下载文件

下载单个文件

hf_hub_download

huggingface_hub.hf_hub_download

( repo_id: str filename: str subfolder: typing.Optional[str] = None repo_type: typing.Optional[str] = None revision: typing.Optional[str] = None library_name: typing.Optional[str] = None library_version: typing.Optional[str] = None cache_dir: typing.Union[str, pathlib.Path, NoneType] = None local_dir: typing.Union[str, pathlib.Path, NoneType] = None user_agent: typing.Union[typing.Dict, str, NoneType] = None force_download: bool = False proxies: typing.Optional[typing.Dict] = None etag_timeout: float = 10 token: typing.Union[bool, str, NoneType] = None local_files_only: bool = False headers: typing.Optional[typing.Dict[str, str]] = None endpoint: typing.Optional[str] = None resume_download: typing.Optional[bool] = None force_filename: typing.Optional[str] = None local_dir_use_symlinks: typing.Union[bool, typing.Literal['auto']] = 'auto' ) → str

参数

repo_id (str) — 用户或组织名称和仓库名称，以 / 分隔。
filename (str) — 仓库中的文件名。
subfolder (str, 可选) — 对应模型仓库内文件夹的可选值。
repo_type (str, 可选) — 如果从数据集或空间下载，则设置为 "dataset" 或 "space"；如果从模型下载，则设置为 None 或 "model"。默认为 None。
revision (str, 可选) — 可选的 Git 修订 ID，可以是分支名称、标签或提交哈希。
library_name (str, 可选) — 对象所属的库名称。
library_version (str, 可选) — 库的版本。
cache_dir (str, Path, 可选) — 缓存文件存储的文件夹路径。
local_dir (str 或 Path, 可选) — 如果提供，下载的文件将放置在此目录下。
user_agent (dict, str, 可选) — 用户代理信息，可以是字典或字符串形式。
force_download (bool, 可选, 默认为 False) — 即使文件已存在于本地缓存中，是否也应下载该文件。
proxies (dict, 可选) — 映射协议到代理 URL 的字典，传递给 requests.request。
etag_timeout (float, 可选, 默认为 10) — 获取 ETag 时，等待服务器发送数据的时间（秒），传递给 requests.request。
token (str, bool, 可选) — 用于下载的令牌。
- 如果为 True，则从 HuggingFace 配置文件夹读取令牌。
- 如果为字符串，则用作身份验证令牌。
local_files_only (bool, 可选, 默认为 False) — 如果为 True，则避免下载文件，如果文件存在于本地缓存中，则返回其路径。
headers (dict, 可选) — 请求中包含的额外请求头。这些请求头优先于其他请求头。

字符串

文件的本地路径，如果网络已关闭，则是磁盘上缓存的文件的最新版本。

引发

RepositoryNotFoundError 或 RevisionNotFoundError 或 EntryNotFoundError 或 LocalEntryNotFoundError 或 EnvironmentError 或 OSError 或 ValueError

RepositoryNotFoundError — 如果要下载的仓库找不到。这可能是因为仓库不存在，或者因为仓库设置为 private 且您没有访问权限。
RevisionNotFoundError — 如果要下载的修订版本找不到。
EntryNotFoundError — 如果要下载的文件找不到。
LocalEntryNotFoundError — 如果网络禁用或不可用，并且在缓存中找不到文件。
EnvironmentError — 如果 token=True 但找不到令牌。
OSError — 如果无法确定 ETag。
ValueError — 如果某些参数值无效。

如果文件尚未存在于本地缓存中，则下载给定文件。

新的缓存文件布局如下所示：

缓存目录包含每个 repo_id 的一个子文件夹（按仓库类型命名空间）
在每个仓库文件夹内
- refs 是最新已知修订版本 => commit_hash 对的列表
- blobs 包含实际的文件 blob（由其 git-sha 或 sha256 标识，具体取决于它们是否为 LFS 文件）
- snapshots 包含每个提交的一个子文件夹，每个“提交”包含在该特定提交中已解析的文件子集。每个文件名都是指向该特定提交的 blob 的符号链接。

[  96]  .
└── [ 160]  models--julien-c--EsperBERTo-small
    ├── [ 160]  blobs
    │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
    ├── [  96]  refs
    │   └── [  40]  main
    └── [ 128]  snapshots
        ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
        │   ├── [  52]  README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
        │   └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        └── [ 128]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48
            ├── [  52]  README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
            └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd

如果提供了 local_dir，则仓库中的文件结构将在此位置复制。使用此选项时，将不使用 cache_dir，并且将在 local_dir 的根目录创建一个 .cache/huggingface/ 文件夹，用于存储与下载文件相关的某些元数据。虽然此机制不像主缓存系统那样健壮，但它针对定期拉取最新版本的仓库进行了优化。

hf_hub_url

huggingface_hub.hf_hub_url

< 来源 >

( repo_id: str filename: str subfolder: typing.Optional[str] = None repo_type: typing.Optional[str] = None revision: typing.Optional[str] = None endpoint: typing.Optional[str] = None )

参数

repo_id (str) — 命名空间（用户或组织）名称和仓库名称，以 / 分隔。
filename (str) — 仓库中的文件名。
subfolder (str, 可选) — 对应仓库内文件夹的可选值。
repo_type (str, 可选) — 如果从数据集或空间下载，则设置为 "dataset" 或 "space"；如果从模型下载，则设置为 None 或 "model"。默认为 None。
revision (str, 可选) — 可选的 Git 修订 ID，可以是分支名称、标签或提交哈希。

从给定信息构造文件 URL。

解析后的地址可以是 huggingface.co 托管的 URL，也可以是 Cloudfront（内容分发网络或 CDN）的链接，用于几 MB 以上的大文件。

示例

>>> from huggingface_hub import hf_hub_url

>>> hf_hub_url(
...     repo_id="julien-c/EsperBERTo-small", filename="pytorch_model.bin"
... )
'https://huggingface.co/julien-c/EsperBERTo-small/resolve/main/pytorch_model.bin'

备注

Cloudfront 在全球范围内复制，因此最终用户的下载速度更快（也降低了我们的带宽成本）。

Cloudfront 默认情况下会积极缓存文件（默认 TTL 为 24 小时），但这在这里不是问题，因为我们在 huggingface.co 上实现了基于 git 的版本控制系统，这意味着我们以内容可寻址的方式（即文件名是其哈希值）将文件存储在 S3/Cloudfront 上。使用内容可寻址的文件名意味着缓存永远不会过时。

就此库的客户端缓存而言，我们基于对象的实体标签（ETag）进行缓存，实体标签是资源特定版本的标识符 [1]_。对象的 ETag 是：如果存储在 git 中，则为其 git-sha1；如果存储在 git-lfs 中，则为其 sha256。

参考文献

[1] https://mdn.org.cn/zh-CN/docs/Web/HTTP/Headers/ETag

下载仓库快照

huggingface_hub.snapshot_download

< 来源 >

( repo_id: str repo_type: typing.Optional[str] = None revision: typing.Optional[str] = None cache_dir: typing.Union[str, pathlib.Path, NoneType] = None local_dir: typing.Union[str, pathlib.Path, NoneType] = None library_name: typing.Optional[str] = None library_version: typing.Optional[str] = None user_agent: typing.Union[typing.Dict, str, NoneType] = None proxies: typing.Optional[typing.Dict] = None etag_timeout: float = 10 force_download: bool = False token: typing.Union[bool, str, NoneType] = None local_files_only: bool = False allow_patterns: typing.Union[typing.List[str], str, NoneType] = None ignore_patterns: typing.Union[typing.List[str], str, NoneType] = None max_workers: int = 8 tqdm_class: typing.Optional[typing.Type[tqdm.asyncio.tqdm_asyncio]] = None headers: typing.Optional[typing.Dict[str, str]] = None endpoint: typing.Optional[str] = None local_dir_use_symlinks: typing.Union[bool, typing.Literal['auto']] = 'auto' resume_download: typing.Optional[bool] = None ) → str

参数

repo_id (str) — 用户或组织名称以及以 / 分隔的仓库名称。
repo_type (str, 可选) — 如果从数据集或空间下载，则设置为 "dataset" 或 "space"；如果从模型下载，则设置为 None 或 "model"。默认为 None。
revision (str, 可选) — 可选的 Git 修订 ID，可以是分支名称、标签或提交哈希。
cache_dir (str, Path, 可选) — 缓存文件存储的文件夹路径。
local_dir (str 或 Path, 可选) — 如果提供，下载的文件将放置在此目录下。
library_name (str, 可选) — 对象所属的库名称。
library_version (str, 可选) — 库的版本。
user_agent (str, dict, 可选) — 用户代理信息，可以是字典或字符串形式。
proxies (dict, 可选) — 映射协议到代理 URL 的字典，传递给 requests.request。
etag_timeout (float, 可选, 默认为 10) — 获取 ETag 时，等待服务器发送数据的时间（秒），传递给 requests.request。
force_download (bool, 可选, 默认为 False) — 即使文件已存在于本地缓存中，是否也应下载该文件。
token (str, bool, 可选) — 用于下载的令牌。
- 如果为 True，则从 HuggingFace 配置文件夹读取令牌。
- 如果为字符串，则用作身份验证令牌。
headers (dict, 可选) — 请求中包含的额外请求头。这些请求头优先于其他请求头。
local_files_only (bool, optional,默认为 False) — 如果为 True，则避免下载文件，如果本地缓存文件存在，则返回其路径。
allow_patterns (List[str] 或 str, 可选) — 如果提供，则只下载至少匹配一个模式的文件。
ignore_patterns (List[str] 或 str, 可选) — 如果提供，则不下载匹配任何模式的文件。
max_workers (int, 可选) — 下载文件的并发线程数 (1 线程 = 1 文件下载)。默认为 8。
tqdm_class (tqdm, 可选) — 如果提供，则覆盖进度条的默认行为。传递的参数必须继承自 tqdm.auto.tqdm 或至少模仿其行为。请注意，tqdm_class 不会传递给每个单独的下载。默认为自定义的 HF 进度条，可以通过设置 HF_HUB_DISABLE_PROGRESS_BARS 环境变量来禁用。

字符串

仓库快照的文件夹路径。

引发

RepositoryNotFoundError 或 RevisionNotFoundError 或 EnvironmentError 或 OSError 或 ValueError

RepositoryNotFoundError — 如果要下载的仓库找不到。这可能是因为仓库不存在，或者因为仓库设置为 private 且您没有访问权限。
RevisionNotFoundError — 如果要下载的修订版本找不到。
EnvironmentError — 如果 token=True 但找不到令牌。
OSError — 如果无法确定 ETag。
ValueError — 如果某些参数值无效。

下载仓库文件。

下载指定修订版仓库文件的完整快照。当您需要仓库中的所有文件，因为您事先不知道需要哪些文件时，这非常有用。所有文件都嵌套在一个文件夹中，以保持其相对于该文件夹的实际文件名。您还可以使用 allow_patterns 和 ignore_patterns 筛选要下载的文件。

另一种方法是克隆仓库，但这需要安装和正确配置 git 和 git-lfs。使用 git 克隆仓库时也无法筛选要下载的文件。

获取文件元数据

get_hf_file_metadata

huggingface_hub.get_hf_file_metadata

< 源 >

( url: str token: typing.Union[bool, str, NoneType] = None proxies: typing.Optional[typing.Dict] = None timeout: typing.Optional[float] = 10 library_name: typing.Optional[str] = None library_version: typing.Optional[str] = None user_agent: typing.Union[typing.Dict, str, NoneType] = None headers: typing.Optional[typing.Dict[str, str]] = None endpoint: typing.Optional[str] = None )

参数

url (str) — 文件 URL，例如由 hf_hub_url() 返回。
token (str 或 bool, 可选) — 用于下载的令牌。
- 如果为 True，则从 HuggingFace 配置文件夹中读取令牌。
- 如果为 False 或 None，则不提供令牌。
- 如果为字符串，则用作身份验证令牌。
proxies (dict, 可选) — 映射协议到代理 URL 的字典，传递给 requests.request。
timeout (float, 可选, 默认为 10) — 等待服务器发送元数据的时间，单位为秒。
library_name (str, 可选) — 对象对应的库名称。
library_version (str, 可选) — 库的版本。
user_agent (dict, str, 可选) — 用户代理信息，以字典或字符串形式提供。
headers (dict, 可选) — 请求附带的附加头部。
endpoint (str, 可选) — Hub 的端点。默认为 https://huggingface.co。

获取 Hub 上版本化文件的元数据，针对给定 URL。

HfFileMetadata

class huggingface_hub.HfFileMetadata

< 源 >

( commit_hash: typing.Optional[str] etag: typing.Optional[str] location: str size: typing.Optional[int] xet_file_data: typing.Optional[huggingface_hub.utils._xet.XetFileData] )

参数

commit_hash (str, 可选) — 与文件相关的 commit_hash。
etag (str, 可选) — 服务器上文件的 Etag。
location (str) — 下载文件的位置。可以是 Hub URL 或其他（CDN）。
size (size) — 文件大小。如果是 LFS 文件，则包含实际 LFS 文件的大小，而不是指针的大小。
xet_file_data (XetFileData, 可选) — 文件的 Xet 信息。仅当文件使用 Xet 存储时设置。

包含 Hub 上文件版本信息的 Data structure。

由 get_hf_file_metadata() 基于 URL 返回。

缓存

上述方法旨在配合缓存系统，防止文件重复下载。缓存系统在 v0.8.0 中进行了更新，成为所有依赖于 Hub 的库共享的中心缓存系统。

阅读缓存系统指南，了解 HF 缓存的详细介绍。

< > 在 GitHub 上更新

Hub Python 库