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")注意：使用提交雜湊值（commit hash）時，必須使用完整長度的雜湊值，而不是 7 個字元的簡短雜湊值。
建構下載連結
如果您想建構用於從儲存庫下載檔案的連結，可以使用 hf_hub_url()，它會回傳一個 URL。請注意，此函式在內部被 hf_hub_download() 所使用。
下載整個儲存庫
snapshot_download() 可下載指定修訂版本（revision）的整個儲存庫。它在內部使用 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 patterns），記錄在此處。模式比對基於 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您可以一次下載多個檔案，這會顯示進度列並回傳檔案所在的快照（snapshot）路徑。
>>> 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）模式
在某些情況下，您希望在實際下載之前確認會下載哪些檔案。您可以使用 --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 利用更快速的下載，它是 xet-core 程式庫的 Python 綁定，支援基於區塊的去重功能，從而實現更快速的下載和上傳。hf_xet 可與 huggingface_hub 無縫整合，但它使用 Rust 撰寫的 xet-core 程式庫與 Xet 儲存，而非 LFS。
hf_xet 使用 Xet 儲存系統，該系統將檔案分解為不可變的區塊，將這些區塊的集合（稱為 blocks 或 xorbs）儲存在遠端，並在需要時檢索它們以重新組裝檔案。下載時，在確認使用者有權存取這些檔案後，hf_xet 會使用該檔案的 LFS SHA256 雜湊值查詢 Xet 內容定址服務 (CAS)，以接收用於組裝這些檔案的重建元數據（xorb 內的範圍），以及用於直接下載 xorbs 的預簽名連結。然後，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。