【Hugging Face】如何从hub中下载文件

huggingface_hub库提供了从存储在Hub上的仓库中下载文件的功能。您可以独立使用这些函数或将它们集成到您自己的库中，使您的用户更方便地与Hub交互。本指南将向您展示如何：

下载并缓存单个文件。
下载并缓存整个代码库。
将文件下载到本地文件夹。

下载单个文件

【hf_hub_download()】函数是从Hub下载文件的主要函数。它会下载远程文件，在磁盘上以版本感知的方式缓存它，并返回其本地文件路径。

返回的文件路径是指向HF本地缓存的指针。因此，重要的是不要修改文件，以避免缓存损坏。如果您想了解更多有关如何缓存文件的信息，请参阅我们的缓存指南。

从上个版本

使用repo_id、repo_type和filename参数选择要下载的文件。默认情况下，该文件将被视为模型存储库的一部分。

from huggingface_hub import hf_hub_download
hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")

hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset")

从特定版本

默认情况下，会下载主分支的最新版本。然而，在某些情况下，您可能想要下载特定版本的文件（例如，从特定分支、PR、标签或提交哈希）。为此，请使用修订参数。

hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0")

hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch")

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")

snapshot_download(repo_id="google/fleurs", repo_type="dataset")

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"])

下载文件到本地文件夹。

推荐（也是默认的）从Hub下载文件的方法是使用缓存系统。您可以通过设置【cache_dir】参数（在hf_hub_download（）和snapshot_download（）中均可）来定义缓存位置。
但是，在某些情况下，您希望下载文件并将它们移动到特定文件夹。这对于让工作流程更接近git命令提供的内容非常有用。您可以使用local_dir和local_dir_use_symlinks参数来实现这一点：
local_dir必须是系统上文件夹的路径。下载的文件将保持与存储库中相同的文件结构。例如，如果filename =“data / train.csv”并且local_dir =“path / to / folder”，则返回的文件路径将为“path / to / folder / data / train.csv”。
local_dir_use_symlinks定义了如何将文件保存在本地文件夹中。默认行为（“auto”）是复制小文件（<5MB），并对大文件使用符号链接。符号链接允许优化带宽和磁盘使用率。但是手动编辑符号链接的文件可能会损坏缓存，因此对于小文件进行复制。可以使用HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD环境变量来配置5MB阈值。
如果设置local_dir_use_symlinks = True，则所有文件都将链接到最佳磁盘空间优化。例如，在下载具有数千个小文件的巨大数据集时非常有用。
最后，如果您根本不想使用符号链接，则可以禁用它们（local_dir_use_symlinks = False）。仍将使用缓存目录来检查文件是否已缓存。如果已经缓存，则从缓存中复制文件（即节省带宽但增加磁盘使用）。如果文件尚未缓存，则会直接下载并移动到本地目录。这意味着如果您需要稍后在其他地方重用它，它将被重新下载。
以下是一张表格，总结了不同的选项，以帮助您选择最适合您使用情况的参数。

注意：如果您使用的是Windows机器，您需要启用开发人员模式或以管理员身份运行huggingface_hub以启用符号链接。请查看缓存限制部分以了解更多细节。

从CLI下载

你可以使用huggingface-cli下载命令直接从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 login）将被使用。如果您想显式地进行身份验证，请使用 --token 选项：

 huggingface-cli download gpt2 config.json --token=hf_****
/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

如果您想要静音进度条和潜在的警告，请使用 --quiet 选项。如果您想要将输出传递给脚本中的另一个命令，这将证明非常有用。

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

默认情况下，文件将被下载到由HF_HOME环境变量定义的缓存目录中（如果未指定，则为~/.cache/huggingface/hub）。您可以通过使用--cache-dir选项来覆盖此设置。

huggingface-cli download gpt2 config.json --cache-dir=./cache
./cache/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json

如果您想将文件下载到本地文件夹，而不带缓存目录结构，则可以使用--local-dir。将文件下载到本地文件夹会带来一些限制，这些限制列在此表中。

huggingface-cli download gpt2 config.json --local-dir=./models/gpt2
./models/gpt2/config.json

有更多的参数可以指定不同类型的仓库或版本来下载，并使用glob模式包含/排除要下载的文件：

huggingface-cli download bigcode/the-stack --repo-type=dataset --revision=v1.2 --include="data/python/*" --exclu
de="*.json" --exclude="*.zip"
Fetching 206 files:   100%|████████████████████████████████████████████| 206/206 [02:31<2:31, ?it/s]
/home/wauplin/.cache/huggingface/hub/datasets--bigcode--the-stack/snapshots/9ca8fa6acdbc8ce920a0cb58adcdafc495818ae7

对于所有的参数列表，您可以运行：

huggingface-cli download --help

快速下载

如果你正在使用带宽较高的计算机，你可以使用【hf_transfer】来增加你的下载速度。hf_transfer是一个基于Rust开发的库，用于加速与Hub的文件传输。要启用它，请安装该包（pip install hf_transfer）并将HF_HUB_ENABLE_HF_TRANSFER=1设置为环境变量。