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ữ được lưu trữ trên Hub. Bạn có thể sử dụng các hàm này một cách độc lập hoặc tích hợp chúng vào thư viện của riêng bạn, 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() là hàm chính để tải tệp từ Hub. Nó 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ộ của nó.

Đườ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 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.

>>> 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:

# 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(), hàm này sẽ trả về một URL. Lưu ý rằng hàm này được sử dụng bên trong hf_hub_download().

Tải xuống toàn bộ kho

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(), điều này có nghĩa là 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:

>>> 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() 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:

>>> 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() 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 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 chấp 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. Việc khớp mẫu dựa trên fnmatch.

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:

>>> 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:

>>> 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.

>>> 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 để 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() và snapshot_download(), hoặc bằng cách đặt biến môi trường 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.

Đừ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() 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, nó sử dụng các hàm trợ giúp hf_hub_download() và snapshot_download() được mô tả ở trên và in đường dẫn trả về ra terminal.

>>> 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:

>>> 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://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (xem tham chiếu 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ó:

# 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.

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:

>>> 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:

>>> 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ữ:

>>> 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:

>>> 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() và snapshot_download(). Hàm sẽ trả về một DryRunFileInfo (hoặc một danh sách các 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 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:

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 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ế.