从 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 模式），如此处记录here。模式匹配基于 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 下载

您可以使用终端中的 huggingface-cli download 命令直接从 Hub 下载文件。在内部，它使用上面描述的相同的 hf_hub_download() 和 snapshot_download() 助手，并将返回的路径打印到终端。

>>> huggingface-cli download gpt2 config.json
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json

您可以一次下载多个文件，这会显示一个进度条，并返回文件所在的快照路径

>>> huggingface-cli 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 存储后端进行上传/下载。它已在生产环境中可用，但正在向所有用户推广，因此请加入 候补名单 以尽快加入！
• hf_transfer 是一个强大的工具，用于下载和上传到我们的 LFS 存储后端（注意：这不如 Xet 更具未来性）。它经过了彻底的测试，并在生产环境中使用了很长时间，但它有一些限制。

hf_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 使用本地磁盘缓存仅下载块一次，在 Chunk-based caching(Xet) 部分了解更多信息。

要启用它，请在安装 huggingface_hub 时指定 hf_xet 包

pip install -U huggingface_hub[hf_xet]

注意： 仅当要下载的文件存储在 Xet Storage 中时，才会使用 hf_xet。

所有其他 huggingface_hub API 将继续工作，无需任何修改。要了解更多关于 Xet 存储和 hf_xet 的好处，请参阅此 section。

hf_transfer

如果您在具有高带宽的机器上运行，您可以使用 hf_transfer 来提高您的下载速度，hf_transfer 是一个基于 Rust 的库，旨在加速与 Hub 的文件传输。要启用它

1. 在安装 huggingface_hub 时指定 hf_transfer extra（例如 pip install huggingface_hub[hf_transfer]）。
2. 将 HF_HUB_ENABLE_HF_TRANSFER=1 设置为环境变量。