# Tải tệp từ Hub Thư viện `huggingface_hub` cung cấp các hàm để tải xuống các tệp từ các kho lưu trữ trên Hub. Bạn có thể sử dụng các hàm này độc lập hoặc tích hợp chúng vào thư viện của riêng mình, giúp người dùng của bạn tương tác với Hub thuận tiện hơn. Hướng dẫn này sẽ cho bạn thấy cách: * Tải xuống và lưu vào bộ nhớ đệm một tệp duy nhất. * Tải xuống và lưu trữ bộ nhớ đệm toàn bộ kho lưu trữ. * Tải tệp xuống thư mục cục bộ. ## Tải xuống một tệp duy nhất Hàm [hf_hub_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.hf_hub_download) là hàm chính để tải tệp từ Hub. Hàm này tải tệp từ xa, lưu vào bộ nhớ đệm trên đĩa (theo cách nhận biết phiên bản) và trả về đường dẫn tệp cục bộ. > [!TIP] > Đường dẫn tệp được trả về là một con trỏ đến bộ đệm cục bộ của HF. Do đó, việc không chỉnh sửa tệp là rất quan trọng để tránh làm hỏng bộ đệm. Nếu bạn muốn tìm hiểu thêm về cách các tệp được lưu trong bộ đệm, hãy tham khảo [hướng dẫn về bộ đệm](./manage-cache) của chúng tôi. ### Từ phiên bản mới nhất Chọn tệp để tải xuống bằng các tham số `repo_id`, `repo_type` và `filename`. Mặc định, tệp sẽ được coi là một phần của kho `model`. ```python >>> from huggingface_hub import hf_hub_download >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json") '/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json' # Download from a dataset >>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset") '/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py' ``` ### Từ phiên bản cụ thể Mặc định, phiên bản mới nhất từ nhánh `main` sẽ được tải xuống. Tuy nhiên, trong một số trường hợp, bạn muốn tải xuống một tệp ở một phiên bản cụ thể (ví dụ: từ một nhánh nhất định, một PR, một tag hoặc một commit hash). Để làm điều này, hãy sử dụng tham số `revision`: ```python # Download from the `v1.0` tag >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0") # Download from the `test-branch` branch >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch") # Download from Pull Request #3 >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3") # Download from a specific commit hash >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a") ``` **Lưu ý:** Khi sử dụng commit hash, nó phải là hash có độ dài đầy đủ thay vì commit hash 7 ký tự. ### Xây dựng URL tải xuống Nếu bạn muốn xây dựng URL được dùng để tải xuống một tệp từ một repo, bạn có thể sử dụng [hf_hub_url()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.hf_hub_url), hàm này trả về một URL. Lưu ý rằng nó được dùng bên trong [hf_hub_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.hf_hub_download). ## Tải xuống toàn bộ kho [snapshot_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.snapshot_download) tải toàn bộ một kho lưu trữ tại một phiên bản (revision) được chỉ định. Hàm này sử dụng bên trong [hf_hub_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.hf_hub_download), do đó tất cả các tệp được tải xuống cũng sẽ được lưu vào bộ nhớ đệm trên ổ đĩa cục bộ của bạn. Các thao tác tải được thực hiện đồng thời để tăng tốc quá trình. Để tải xuống toàn bộ một kho lưu trữ, chỉ cần truyền `repo_id` và `repo_type`: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp") '/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade' # Or from a dataset >>> snapshot_download(repo_id="google/fleurs", repo_type="dataset") '/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34' ``` [snapshot_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.snapshot_download) tải bản sửa đổi mới nhất theo mặc định. Nếu bạn muốn một bản sửa đổi cụ thể của kho, hãy sử dụng tham số `revision`: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1") ``` ### Lọc tệp để tải xuống [snapshot_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.snapshot_download) cung cấp cách dễ dàng để tải xuống một kho lưu trữ. Tuy nhiên, bạn không phải lúc nào cũng muốn tải xuống toàn bộ nội dung của một kho lưu trữ. Ví dụ, bạn có thể muốn ngăn tải xuống tất cả các tệp `.bin` nếu bạn biết mình chỉ sử dụng trọng số `.safetensors`. Bạn có thể làm điều đó bằng cách sử dụng các tham số `allow_patterns` và `ignore_patterns`. Các tham số này nhận một mẫu duy nhất hoặc một danh sách các mẫu. Các mẫu là Standard Wildcards (mẫu globbing) như được tài liệu hóa [tại đây](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). Việc khớp mẫu dựa trên [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). Ví dụ, bạn có thể sử dụng `allow_patterns` để chỉ tải xuống các tệp cấu hình JSON: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json") ``` Mặt khác, `ignore_patterns` có thể loại trừ một số tệp khỏi việc tải xuống. Ví dụ sau bỏ qua các phần mở rộng tệp `.msgpack` và `.h5`: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"]) ``` Cuối cùng, bạn có thể kết hợp cả hai để lọc chính xác tệp tải xuống. Dưới đây là một ví dụ để tải xuống tất cả các tệp json và markdown ngoại trừ `vocab.json`. ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json") ``` ## Tải tệp xuống thư mục cục bộ Mặc định, chúng tôi khuyến nghị sử dụng [hệ thống cache](./manage-cache) để tải tệp từ Hub. Bạn có thể chỉ định vị trí cache tùy chỉnh bằng tham số `cache_dir` trong [hf_hub_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.hf_hub_download) và [snapshot_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.snapshot_download), hoặc bằng cách đặt biến môi trường [`HF_HOME`](../package_reference/environment_variables#hf_home). Tuy nhiên, nếu bạn cần tải tệp xuống một thư mục cụ thể, bạn có thể truyền tham số `local_dir` cho hàm tải xuống. Điều này hữu ích để đưa quy trình làm việc gần hơn với những gì lệnh `git` cung cấp. Các tệp được tải xuống sẽ giữ nguyên cấu trúc tệp gốc bên trong thư mục được chỉ định. Ví dụ, nếu `filename="data/train.csv"` và `local_dir="path/to/folder"`, đường dẫn tệp kết quả sẽ là `"path/to/folder/data/train.csv"`. Một thư mục `.cache/huggingface/` được tạo tại gốc của thư mục cục bộ, chứa các siêu dữ liệu về các tệp đã tải xuống. Điều này ngăn việc tải lại các tệp nếu chúng đã ở phiên bản mới nhất. Nếu siêu dữ liệu đã thay đổi, phiên bản tệp mới sẽ được tải xuống. Nhờ đó, `local_dir` được tối ưu hóa để chỉ lấy các thay đổi mới nhất. Sau khi hoàn tất việc tải xuống, bạn có thể an toàn xóa thư mục `.cache/huggingface/` nếu không còn cần đến nó. Tuy nhiên, hãy lưu ý rằng việc chạy lại script mà không có thư mục này có thể dẫn đến thời gian khôi phục lâu hơn, do dữ liệu mô tả (metadata) sẽ bị mất. Bạn có thể yên tâm rằng dữ liệu cục bộ của bạn sẽ vẫn nguyên vẹn và không bị ảnh hưởng. > [!TIP] > Đừng lo lắng về thư mục `.cache/huggingface/` khi cam kết các thay đổi lên Hub! Thư mục này được cả `git` và [upload_folder()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) tự động bỏ qua. ## Tải xuống từ CLI Bạn có thể sử dụng lệnh `hf download` từ terminal để tải trực tiếp các tệp từ Hub. Bên trong, lệnh này sử dụng các hàm trợ giúp [hf_hub_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.hf_hub_download) và [snapshot_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.snapshot_download) đã mô tả ở trên và in đường dẫn được trả về ra terminal. ```bash >>> hf download gpt2 config.json /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` Bạn có thể tải xuống nhiều tệp cùng lúc, thao tác này sẽ hiển thị thanh tiến trình và trả về đường dẫn snapshot chứa các tệp: ```bash >>> hf download gpt2 config.json model.safetensors Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s] /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 ``` Bạn cũng có thể trỏ đến kho (và tùy chọn một phiên bản và tệp) bằng cách sử dụng một URI `hf://` duy nhất. URI tuân theo ngữ pháp `hf://[/][@][/]` (xem [tham chiếu HF URIs](../package_reference/hf_uris) để biết cú pháp đầy đủ) và thay thế các tùy chọn `--repo-type` và `--revision`, những tùy chọn không thể được đặt cùng với nó: ```bash # Download a single file from a dataset at a given revision >>> hf download hf://datasets/google/fleurs@refs/pr/1/fleurs.py # Download a subfolder (note the trailing slash) >>> hf download hf://datasets/google/fleurs/data/ # Download an entire repo >>> hf download hf://datasets/google/fleurs ``` Để biết thêm chi tiết về lệnh tải xuống CLI, vui lòng tham khảo [hướng dẫn CLI](./cli#hf-download). ## Chế độ chạy thử Trong một số trường hợp, bạn có thể muốn kiểm tra các tệp sẽ được tải xuống trước khi thực sự tải chúng. Bạn có thể kiểm tra điều này bằng tham số `--dry-run`. Tham số này liệt kê tất cả các tệp cần tải xuống trong repo và kiểm tra xem chúng đã được tải xuống hay chưa. Điều này giúp bạn có cái nhìn tổng quan về số lượng tệp cần tải xuống và kích thước của chúng. Dưới đây là một ví dụ, kiểm tra trên một tệp duy nhất: ```sh >>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run [dry-run] Will download 1 files (out of 1) totalling 655.2M File Bytes to download ------------------------------ ----------------- onnx/decoder_model_merged.onnx 655.2M ``` Và nếu tệp đã được lưu trong bộ nhớ đệm: ```sh >>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run [dry-run] Will download 0 files (out of 1) totalling 0.0. File Bytes to download ------------------------------ ----------------- onnx/decoder_model_merged.onnx - ``` Bạn cũng có thể thực hiện chạy thử (dry-run) trên toàn bộ kho lưu trữ: ```sh >>> hf download openai-community/gpt2 --dry-run [dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00, 6.26it/s] [dry-run] Will download 11 files (out of 26) totalling 5.6G. File Bytes to download --------------------------------- ----------------- .gitattributes - 64-8bits.tflite 125.2M 64-fp16.tflite 248.3M 64.tflite 495.8M README.md - config.json - flax_model.msgpack 497.8M generation_config.json - merges.txt - model.safetensors 548.1M onnx/config.json - onnx/decoder_model.onnx 653.7M onnx/decoder_model_merged.onnx 655.2M onnx/decoder_with_past_model.onnx 653.7M onnx/generation_config.json - onnx/merges.txt - onnx/special_tokens_map.json - onnx/tokenizer.json - onnx/tokenizer_config.json - onnx/vocab.json - pytorch_model.bin 548.1M rust_model.ot 702.5M tf_model.h5 497.9M tokenizer.json - tokenizer_config.json - vocab.json - ``` Và với bộ lọc tệp: ```sh >>> hf download openai-community/gpt2 --include "*.json" --dry-run [dry-run] Fetching 11 files: 100%|█████████████| 11/11 [00:00<00:00, 80518.92it/s] [dry-run] Will download 0 files (out of 11) totalling 0.0. File Bytes to download ---------------------------- ----------------- config.json - generation_config.json - onnx/config.json - onnx/generation_config.json - onnx/special_tokens_map.json - onnx/tokenizer.json - onnx/tokenizer_config.json - onnx/vocab.json - tokenizer.json - tokenizer_config.json - vocab.json - ``` Cuối cùng, bạn cũng có thể thực hiện dry-run theo cách lập trình bằng cách truyền `dry_run=True` vào [hf_hub_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.hf_hub_download) và [snapshot_download()](/docs/huggingface_hub/v2.4.0/vi/package_reference/file_download#huggingface_hub.snapshot_download). Hàm sẽ trả về một [DryRunFileInfo](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.DryRunFileInfo) (hoặc một danh sách các [DryRunFileInfo](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.DryRunFileInfo)) chứa cho mỗi tệp: commit hash, tên tệp và kích thước tệp, tệp có được cache hay không và tệp có sẽ được tải xuống hay không. Trên thực tế, tệp sẽ được tải xuống nếu chưa được cache hoặc nếu `force_download=True` được truyền vào. ## Tải xuống nhanh hơn Tận dụng tốc độ tải xuống nhanh hơn thông qua `hf_xet`, bản liên kết Python của thư viện [`xet-core`](https://github.com/huggingface/xet-core) cho phép khử trùng lặp dựa trên chunk để tải xuống và tải lên nhanh hơn. `hf_xet` tích hợp liền mạch với `huggingface_hub`, nhưng sử dụng thư viện Rust `xet-core` và bộ nhớ Xet thay vì LFS. `hf_xet` sử dụng hệ thống lưu trữ Xet, hệ thống này chia nhỏ các tệp thành các khối (chunks) bất biến, lưu trữ các tập hợp của những khối này (gọi là blocks hoặc xorbs) từ xa và truy xuất chúng để lắp ráp lại tệp khi có yêu cầu. Khi tải xuống, sau khi xác nhận người dùng được cấp quyền truy cập vào các tệp, `hf_xet` sẽ truy vấn dịch vụ CAS (content-addressable service) của Xet bằng hash LFS SHA256 của tệp này để nhận metadata tái tạo (các khoảng trong xorbs) nhằm lắp ráp các tệp này, cùng với các URL presigned để tải trực tiếp các xorbs. Sau đó, `hf_xet` sẽ tải xuống hiệu quả các khoảng xorb cần thiết và ghi các tệp ra đĩa. Để bật tính năng này, chỉ cần cài đặt phiên bản mới nhất của `huggingface_hub`: ```bash pip install -U "huggingface_hub" ``` Bắt đầu từ `huggingface_hub` 0.32.0, điều này cũng sẽ cài đặt `hf_xet`. Tất cả các API khác của `huggingface_hub` sẽ tiếp tục hoạt động mà không cần bất kỳ thay đổi nào. Để tìm hiểu thêm về các lợi ích của lưu trữ Xet và `hf_xet`, hãy tham khảo [phần](https://huggingface.co/docs/hub/xet/index) này. Lưu ý: `hf_transfer` trước đây được sử dụng với backend lưu trữ LFS và hiện đã bị ngừng hỗ trợ; hãy sử dụng `hf_xet` thay thế.