從 Hub 下載檔案

huggingface_hub 庫提供了從 Hub 上的倉庫下載檔案的函式。您可以獨立使用這些函式，也可以將其整合到自己的庫中，從而更方便使用者與 Hub 進行互動。本指南將向您展示如何：

• 下載並快取單個檔案。
• 下載並快取整個倉庫。
• 將檔案下載到本地資料夾。

下載單個檔案

hf_hub_download() 函式是用於從 Hub 下載檔案的主要函式。它下載遠端檔案，將其快取到磁碟（以版本感知的方式），並返回其本地檔案路徑。

從最新版本

使用 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/ 資料夾，可以安全地將其刪除。但是請注意，如果在沒有此資料夾的情況下重新執行指令碼，可能會導致更長的恢復時間，因為元資料將丟失。請放心，您的本地資料將保持完整且不受影響。

從 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 指南。

更快的下載

有兩種方法可以加快下載速度。兩者都涉及安裝用 Rust 編寫的 Python 包。

• hf_xet 較新，使用 Xet 儲存後端進行上傳/下載。Xet 儲存是所有新 Hub 使用者和組織的預設設定，並且正在向所有使用者推出。如果您無法訪問，請加入候補名單，使 Xet 成為您所有倉庫的預設設定！
• hf_transfer 是一個強大的工具，用於下載和上傳到我們的 LFS 儲存後端（注意：這不如 Xet 具有前瞻性）。它經過徹底測試，並已投入生產很長時間，但它有一些限制。

hf_xet

透過 hf_xet 享受更快的下載速度，它是 xet-core 庫的 Python 繫結，可實現基於塊的重複資料刪除，從而加快下載和上傳速度。 hf_xet 與 huggingface_hub 無縫整合，但使用 Rust xet-core 庫和 Xet 儲存，而不是 LFS。

hf_xet 使用 Xet 儲存系統，該系統將檔案分解成不可變的塊，將這些塊的集合（稱為塊或 xorbs）遠端儲存，並在請求時檢索它們以重新組裝檔案。下載時，在確認使用者有權訪問檔案後，hf_xet 將使用此檔案的 LFS SHA256 雜湊查詢 Xet 內容可定址服務 (CAS)，以接收重建元資料（xorbs 中的範圍）以組裝這些檔案，以及直接下載 xorbs 的預簽名 URL。然後 hf_xet 將有效地下載必要的 xorb 範圍，並將檔案寫入磁碟。 hf_xet 使用本地磁碟快取僅下載一次塊，在基於塊的快取 (Xet) 部分了解更多資訊。

要啟用它，只需安裝最新版本的 huggingface_hub

pip install -U "huggingface_hub"

從 huggingface_hub 0.32.0 開始，這將同時安裝 hf_xet。

注意：hf_xet 僅在下載的檔案使用 Xet 儲存時才會使用。

所有其他 huggingface_hub API 將繼續工作，無需任何修改。要了解有關 Xet 儲存和 hf_xet 優勢的更多資訊，請參閱此部分。

hf_transfer

如果您在高頻寬機器上執行，您可以使用 hf_transfer 提高下載速度，這是一個基於 Rust 的庫，旨在加快與 Hub 的檔案傳輸。要啟用它

1. 安裝 huggingface_hub 時指定 hf_transfer 額外選項（例如 pip install huggingface_hub[hf_transfer]）。
2. 將 HF_HUB_ENABLE_HF_TRANSFER=1 設定為環境變數。