Hub Python 庫文件
從 Hub 下載檔案
並獲得增強的文件體驗
開始使用
從 Hub 下載檔案
huggingface_hub 庫提供了從 Hub 上儲存的倉庫下載檔案的功能。您可以獨立使用這些函式，也可以將它們整合到您自己的庫中，從而方便您的使用者與 Hub 進行互動。本指南將向您展示如何
- 下載並快取單個檔案。
- 下載並快取整個倉庫。
- 將檔案下載到本地資料夾。
下載單個檔案
hf_hub_download() 函式是從 Hub 下載檔案的主要函式。它會下載遠端檔案，在磁碟上進行快取（以版本感知的方式），並返回其本地檔案路徑。
返回的檔案路徑是指向 HF 本地快取的指標。因此，重要的是不要修改檔案，以免快取損壞。如果您想了解更多關於檔案如何快取的資訊，請參閱我們的快取指南。
來自最新版本
使用 repo_id、repo_type 和 filename 引數選擇要下載的檔案。預設情況下，檔案將被視為 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'來自特定版本
預設情況下，會下載 main 分支的最新版本。但是，在某些情況下，您可能希望下載特定版本的某個檔案（例如，從特定分支、PR、標籤或提交雜湊下載）。為此，請使用 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")注意：使用提交雜湊時，必須使用完整長度的雜湊，而不是 7 個字元的提交雜湊。
構建下載 URL
如果您想構建從倉庫下載檔案的 URL，可以使用 hf_hub_url()，它會返回一個 URL。請注意，它在內部由 hf_hub_download() 使用。
下載整個倉庫
snapshot_download() 會下載指定修訂版本下的整個倉庫。它內部使用了 hf_hub_download()，這意味著所有下載的檔案也會被快取到您的本地磁碟。下載是併發進行的，以加快速度。
要下載整個倉庫，只需傳入 repo_id 和 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() 預設下載最新版本。如果您需要特定倉庫版本，請使用 revision 引數。
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1")過濾要下載的檔案
snapshot_download() 提供了一種方便的方式來下載倉庫。但是，您不總是想要下載倉庫的全部內容。例如，如果您知道只會使用 .safetensors 權重，您可能希望阻止下載所有 .bin 檔案。您可以使用 allow_patterns 和 ignore_patterns 引數來實現此目的。
這些引數可以接受單個模式或模式列表。模式是標準萬用字元（globbing 模式），文件參考 此處。模式匹配基於 fnmatch。
例如，您可以使用 allow_patterns 只下載 JSON 配置檔案。
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json")另一方面，ignore_patterns 可以排除某些檔案不被下載。以下示例將忽略 .msgpack 和 .h5 副檔名。
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"])最後，您可以組合使用兩者來精確過濾您的下載。以下示例將下載所有 json 和 markdown 檔案，但排除 vocab.json。
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json")將檔案下載到本地資料夾
預設情況下，我們建議使用 快取系統 從 Hub 下載檔案。您可以透過在 hf_hub_download() 和 snapshot_download() 中指定 cache_dir 引數，或者透過設定 HF_HOME 環境變數來指定自定義快取位置。
但是，如果您需要將檔案下載到特定資料夾，可以將 local_dir 引數傳遞給下載函式。這有助於使工作流更接近 git 命令提供的功能。下載的檔案將在指定資料夾內保持其原始檔案結構。例如，如果 filename="data/train.csv" 且 local_dir="path/to/folder"，則結果檔案路徑將是 "path/to/folder/data/train.csv"。
在本地目錄的根目錄中會建立一個 .cache/huggingface/ 資料夾，其中包含有關下載檔案的元資料。這可以防止在檔案已是最新時重新下載。如果元資料發生更改，則會下載新版本的檔案。這使得 local_dir 針對僅拉取最新更改進行了最佳化。
下載完成後，您可以安全地刪除 .cache/huggingface/ 資料夾（如果您不再需要它）。但是，請注意，在沒有此資料夾的情況下重新執行指令碼可能會導致恢復時間變長，因為元資料將丟失。請放心，您的本地資料將保持不變，不受影響。
在將更改提交到 Hub 時，請不要擔心
.cache/huggingface/資料夾！git和 upload_folder() 都會自動忽略此資料夾。
從 CLI 下載
您可以使用終端中的 hf download 命令直接從 Hub 下載檔案。它在內部使用了上面描述的相同 hf_hub_download() 和 snapshot_download() 助手，並將返回的路徑列印到終端。
>>> hf download gpt2 config.json /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json
您可以一次下載多個檔案，這將顯示進度條並返回檔案所在的快照路徑。
>>> 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
有關 CLI 下載命令的更多詳細資訊，請參閱 CLI 指南。
試執行模式
在某些情況下，您可能希望在實際下載檔案之前先檢查會下載哪些檔案。您可以使用 --dry-run 引數來檢查。它會列出倉庫中所有要下載的檔案，並檢查它們是否已下載。這可以給您一個關於需要下載多少檔案及其大小的概念。
這是一個例子，檢查單個檔案。
>>> 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
如果檔案已快取。
>>> 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 -
您也可以對整個倉庫執行試執行。
>>> 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 -
以及檔案過濾。
>>> 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 -最後，您也可以透過將 dry_run=True 傳遞給 hf_hub_download() 和 snapshot_download() 來以程式設計方式執行試執行。它將返回一個 DryRunFileInfo（或一系列 DryRunFileInfo），其中包含每個檔案的提交雜湊、檔名和檔案大小，以及檔案是否已快取以及是否將下載該檔案。實際上，如果檔案未快取或傳遞了 force_download=True，則會下載該檔案。
更快的下載
透過 hf_xet 利用更快的下載速度，hf_xet 是 xet-core 庫的 Python 繫結，它支援基於塊的去重，以實現更快的下載和上傳。hf_xet 與 huggingface_hub 無縫整合，但使用 Rust xet-core 庫和 Xet 儲存而不是 LFS。
hf_xet 使用 Xet 儲存系統，該系統將檔案分解為不可變的塊，遠端儲存這些塊的集合（稱為塊或 xorb），並在請求時檢索它們以重新組裝檔案。下載時，在確認使用者有權訪問檔案後，hf_xet 將使用檔案的 LFS SHA256 雜湊值查詢 Xet 內容可定址服務（CAS）以接收重組元資料（xorb 內的範圍），並提供用於直接下載 xorb 的預簽名 URL。然後 hf_xet 將高效地下載必要的 xorb 範圍，並將檔案寫入磁碟。
要啟用它，只需安裝最新版本的 huggingface_hub。
pip install -U "huggingface_hub"從 huggingface_hub 0.32.0 開始，這將同時安裝 hf_xet。
所有其他 huggingface_hub API 將繼續按原樣工作。要了解有關 Xet 儲存和 hf_xet 的優勢的更多資訊，請參閱此 部分。
注意：hf_transfer 以前用於 LFS 儲存後端，現在已棄用；請改用 hf_xet。