【AI翻译】从 HuggingFace Hub 下载文件官方文档

原文：https://huggingface.co/docs/huggingface_hub/main/en/guides/download

从 Hub 下载文件

huggingface_hub 库提供了从 Hugging Face 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'

# 从数据集下载
>>> 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 参数：

# 从 `v1.0` 标签下载
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0")

# 从 `test-branch` 分支下载
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch")

# 从 Pull Request #3 下载
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3")

# 从特定提交哈希下载
>>> 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'

# 或下载数据集
>>> snapshot_download(repo_id="google/fleurs", repo_type="dataset")
'/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34'

默认下载最新版本。若需特定版本，使用 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。

例如，仅下载 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 下载文件。你可以通过 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 指南。

加速下载

有两种方式可加速下载，均涉及安装基于 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。

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

所有其他 huggingface_hub API 将继续无修改运行。有关 Xet 存储和 hf_xet 的更多信息，请参阅此 部分。

hf_transfer

若你运行在高带宽机器上，可通过 hf_transfer 提高下载速度，这是一个为 Hub 文件传输加速而开发的基于 Rust 的库。启用方法：

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

hf_transfer 是高级用户工具！它经过测试并已投入生产，但缺少高级错误处理或代理等用户友好功能。更多详情，请查看此 部分。