从 Hub 下载文件
huggingface_hub
库提供从 Hub 上存储的仓库下载文件的函数。您可以独立使用这些函数或将它们集成到您自己的库中,从而使您的用户更方便地与 Hub 交互。本指南将向您展示如何
- 下载和缓存单个文件。
- 下载和缓存整个仓库。
- 将文件下载到本地文件夹。
下载单个文件
The 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")
注意:使用提交哈希时,它必须是完整长度的哈希,而不是 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/
文件夹。但是,请注意,在没有此文件夹的情况下重新运行脚本可能会导致更长的恢复时间,因为元数据将丢失。请放心,您的本地数据将保持完整且不受影响。
不要担心将更改提交到 Hub 时.cache/huggingface/
文件夹!此文件夹会自动被git
和upload_folder()忽略。
从 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 指南.
更快的下载速度
如果您在带宽充足的机器上运行,您可以使用 hf_transfer
来提高下载速度,它是一个基于 Rust 的库,专为加快与 Hub 的文件传输而开发。要启用它
- 在安装
huggingface_hub
时指定hf_transfer
扩展(例如pip install huggingface_hub[hf_transfer]
)。 - 将
HF_HUB_ENABLE_HF_TRANSFER=1
设置为环境变量。
hf_transfer
是一款供高级用户使用的工具!它经过测试并可用于生产环境,但它缺乏诸如高级错误处理或代理之类的用户友好功能。有关更多详细信息,请参阅此 部分。