Hub Python 库文档
从 Hub 下载文件
并获得增强的文档体验
开始使用
从 Hub 下载文件
huggingface_hub
库提供了从 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'
# 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 下载
您可以使用终端中的 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 的文件传输。要启用它
- 安装
huggingface_hub
时指定hf_transfer
额外选项(例如pip install huggingface_hub[hf_transfer]
)。 - 将
HF_HUB_ENABLE_HF_TRANSFER=1
设置为环境变量。
hf_transfer
是一个高级用户工具!它经过测试且已投入生产,但它缺少用户友好的功能,例如高级错误处理或代理。有关更多详细信息,请参阅此部分。