Hugging Face's logo

Hub Python Library documentation

下载文件

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

下载文件

下载单个文件

hf_hub_download

huggingface_hub.hf_hub_download

< >

( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = Noneuser_agent: dict | str | None = Noneforce_download: bool = Falseetag_timeout: float = 10token: bool | str | None = Nonelocal_files_only: bool = Falseheaders: dict[str, str] | None = Noneendpoint: str | None = Nonetqdm_class: type[tqdm.std.tqdm] | None = Nonedry_run: bool = False ) → str or DryRunFileInfo

参数

  • repo_id (str) — 由/分隔的用户或组织名称以及仓库名称。
  • filename (str) — 仓库中文件的名称。
  • subfolder (str, 可选) — 对应于模型仓库内部某个文件夹的可选值。
  • repo_type (str, 可选) — 如果从数据集、空间或内核仓库下载，请设置为 "dataset"、"space" 或 "kernel"； 如果从模型下载，请设置为 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) — 即使文件已存在于本地缓存中，是否仍应下载该文件。
  • etag_timeout (float, 可选, 默认为 10) — 获取 ETag 时，等待服务器发送数据的超时秒数，超时后放弃请求。该值会传递给 httpx2.request。
  • token (str, bool, 可选) — 用于下载的 token。如果为 True，则从 HuggingFace 配置文件夹中读取 token。如果为字符串，则将其用作身份验证 token。
    • 如果 True，则从 HuggingFace 配置文件夹中读取该 token。
    • 如果为字符串，则用作身份验证令牌。
  • local_files_only (bool，可选，默认为 False) — 如果为 True，则避免下载文件，并在本地缓存文件存在时返回其路径。
  • headers（dict，可选）— 随请求一起发送的附加请求头。
  • endpoint (str, 可选) — 发送请求的 Hub 端点。默认为 HF_ENDPOINT 的值。
  • tqdm_class (tqdm, 可选) — 如果提供，将覆盖进度条的默认行为。传入的参数必须继承自 tqdm.auto.tqdm 或至少模拟其行为。 默认使用自定义的 HF 进度条，可通过设置 HF_HUB_DISABLE_PROGRESS_BARS 环境变量来禁用。
  • dry_run (bool，可选，默认为 False) — 如果为 True，则执行试运行，而不会实际下载文件。返回一个 DryRunFileInfo 对象，其中包含有关将要下载内容的信息。

返回值

str 或 DryRunFileInfo

  • 如果 dry_run=False：文件的本地路径，或者在网络关闭时，磁盘上缓存的文件最后版本。
  • 如果 dry_run=True：一个包含下载信息的 DryRunFileInfo 对象。

引发

RepositoryNotFoundError 或 RevisionNotFoundError 或 ~utils.RemoteEntryNotFoundError 或 LocalEntryNotFoundError 或 EnvironmentError 或 OSError 或 ValueError

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

如果本地缓存中不存在指定文件，则下载该文件。

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

  • 缓存目录中每个 repo_id 都有一个子文件夹（按仓库类型进行命名空间划分）
  • 在每个仓库文件夹内：
    • refs 是最新已知修订版本 => commit_hash 对的列表
    • blobs 包含实际的存储对象（根据其是否为 LFS 文件，分别通过 git-sha 或 sha256 进行标识）
    • 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: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Noneendpoint: str | None = None )

参数

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

根据给定信息构造文件的 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。

参考文献：

下载仓库的快照

huggingface_hub.snapshot_download

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneetag_timeout: float = 10force_download: bool = Falsetoken: bool | str | None = Nonelocal_files_only: bool = Falseallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonemax_workers: int = 8tqdm_class: type[tqdm.asyncio.tqdm_asyncio] | None = Noneheaders: dict[str, str] | None = Noneendpoint: str | None = Nonedry_run: bool = False ) → str or list of DryRunFileInfo

参数

  • repo_id (str) — 由/分隔的用户或组织名称以及仓库名称。
  • repo_type (str, 可选) — 如果从数据集、空间或内核仓库下载，请设置为 "dataset"、"space" 或 "kernel"； 如果从模型下载，请设置为 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, 可选) — 以字典或字符串形式表示的用户代理信息。
  • etag_timeout (float, 可选, 默认为 10) — 获取 ETag 时，等待服务器发送数据的超时秒数，超时后放弃请求。该值会传递给 httpx2.request。
  • force_download (bool，可选，默认为 False) — 即使文件已存在于本地缓存中，是否仍应下载该文件。
  • token (str, bool, 可选) — 用于下载的 token。如果为 True，则从 HuggingFace 配置文件夹中读取 token。如果为字符串，则将其用作身份验证 token。
    • 如果 True，则从 HuggingFace 配置文件夹中读取该 token。
    • 如果为字符串，则用作身份验证令牌。
  • headers（dict，可选）— 请求中要包含的额外请求头。这些请求头的优先级高于其他请求头。
  • endpoint (str, 可选) — 发送请求的 Hub 端点。默认为 HF_ENDPOINT 的值。
  • local_files_only (bool，可选，默认为 False) — 如果为 True，即使文件不在 cache_dir 或 local_dir 中，也不下载任何文件。
  • 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 来禁用。
  • dry_run (bool，可选，默认为 False) — 如果为 True，则执行试运行，而不会实际下载文件。返回一个包含 DryRunFileInfo 对象的列表，其中包含有关将下载内容的信息。

返回值

str 或 DryRunFileInfo 列表

  • 如果 dry_run=False：本地快照路径。
  • 如果 dry_run=True：一个包含下载信息的 DryRunFileInfo 对象列表。

引发

RepositoryNotFoundError 或 RevisionNotFoundError 或 IncompleteSnapshotError 或 EnvironmentError 或 OSError 或 ValueError

  • RepositoryNotFoundError — 如果找不到要下载的仓库。这可能是因为它不存在，或者它被设置为 private 且您没有访问权限。
  • RevisionNotFoundError — 如果找不到要下载的 revision。
  • IncompleteSnapshotError — 如果无法连接到 Hub（离线、连接问题或 local_files_only=True），并且缓存的快照缺少部分请求的文件。
  • EnvironmentError — 如果 token=True 且找不到令牌。
  • OSError — 如果无法确定 ETag。
  • ValueError — 如果某些参数值无效。

下载仓库文件。

下载指定修订版本中仓库文件的完整快照。当您不确定事先需要哪些文件时，此功能非常有用，因为您可以获取仓库中的所有文件。所有文件都嵌套在一个文件夹中，以保持相对于该文件夹的路径和文件名。您还可以使用 allow_patterns 和 ignore_patterns 来筛选要下载的文件。

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

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

读取缓存的仓库树

huggingface_hub.get_cached_repo_tree

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = None ) → list[RepoFile]

参数

  • repo_id (str) — 由/分隔的用户或组织名称以及仓库名称。
  • repo_type (str, 可选) — 如果从数据集、空间或内核仓库中列出，请设置为 "dataset"、"space" 或 "kernel"； 如果从模型中列出，请设置为 None 或 "model"。默认值为 None。
  • revision (str, 可选) — 可选的 Git 修订版本 ID，可以是分支名称、标签或提交哈希。默认值为默认分支。分支/标签名称会通过本地缓存（refs/）解析为提交哈希。
  • cache_dir (str, Path, 可选) — 用于存储缓存文件的文件夹路径。默认值为 HF_HUB_CACHE 的值。
  • local_dir (str 或 Path，可选) — 如果提供，则从 local_dir 下载时缓存的树列表（位于 local_dir/.cache/huggingface/）中读取，而不是从主缓存中读取。分支/标签修订版本仍会使用主缓存（cache_dir）解析为提交哈希。

返回值

list[RepoFile]

为此修订版本缓存的 RepoFile 对象列表。

引发

CachedRepoTreeNotFoundError

  • CachedRepoTreeNotFoundError — 如果请求的修订版本没有缓存的树列表（例如，该仓库从未在此修订版本下下载过）。

返回指定修订版本的仓库的缓存树列表，无需任何网络调用。

树列表是某个仓库在特定提交下的文件集合（包含其下载元数据）。它作为 snapshot_download() 的副作用写入磁盘（参见 trees/<commit_hash>.json 缓存文件），并用于在后续下载中跳过网络请求。此函数直接暴露了该缓存。

如果您需要获取 Hub 上某个仓库的当前树列表，请改用 list_repo_tree()。

示例：

>>> from huggingface_hub import get_cached_repo_tree
>>> files = get_cached_repo_tree("openai-community/gpt2")
>>> [f.path for f in files]
['.gitattributes', 'config.json', 'model.safetensors', ...]

解析修订版本

将分支/标签名称解析为提交哈希值一次，然后将结果传递到各处，以便将所有下载固定到同一提交。请参阅 HfApi.resolve_revision() 和 缓存系统指南。

ResolvedRevision

类 huggingface_hub.ResolvedRevision

< >

( resolved: strinitial: str | None = Nonerepo_id: str | None = Nonerepo_type: str | None = None )

参数

  • initial (str 或 None) — 用户最初请求的版本。如果为 None，则字符串值默认为 "main"。
  • resolved (str) — initial 解析到的提交哈希值。

已解析为提交哈希值的 git 修订版本。

ResolvedRevision 是 str 的子类，因此可以传递给任何接受 revision 参数的 huggingface_hub 方法。其字符串值为用户最初请求的 revision（例如 "main"、"refs/pr/4"），这使 URL 和错误消息保持可读性，而 .resolved 则保存其所指向的 commit hash。

实例由 HfApi.resolve_revision() 构建，该方法还会将 revision -> commit hash 的映射缓存到本地缓存（refs/ 文件夹）中。

提交哈希值仅在其所解析的仓库中具有意义，因此实例还会记住该仓库。针对另一个仓库重新解析它并不会报错：最初请求的修订版本会被再次解析（参见 HfApi.resolve_revision()）。

示例：

>>> from huggingface_hub import resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')
>>> revision == "main"  # it's a string
True
>>> revision.resolved
'607a30d783dfa663caf39e06633721c8d4cfcd7e'

获取文件的元数据

get_hf_file_metadata

huggingface_hub.get_hf_file_metadata

< >

( url: strtoken: bool | str | None = Nonetimeout: float | None = 10library_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneheaders: dict[str, str] | None = Noneendpoint: str | None = Noneretry_on_errors: bool = False )

参数

  • url (str) — 文件 URL，例如由 hf_hub_url() 返回。
  • token (str 或 bool, 可选) — 用于下载的 token。如果为 True，则从 HuggingFace 配置文件夹中读取 token。如果为 False 或 None，则不提供 token。如果为字符串，则将其用作身份验证 token。
    • 如果 True，则从 HuggingFace 配置文件夹中读取该 token。
    • 如果为 False 或 None，则不提供任何标记。
    • 如果为字符串，则用作身份验证令牌。
  • timeout (float，可选，默认为 10) — 在放弃之前，等待服务器发送元数据的秒数。
  • library_name (str, 可选) — 该对象所对应的库的名称。
  • library_version (str, 可选) — 库的版本。
  • user_agent (dict, str, 可选) — 以字典或字符串形式表示的用户代理信息。
  • headers（dict，可选）— 随请求一起发送的附加请求头。
  • endpoint (str，可选) — Hub 的端点。默认为 https://huggingface.co。
  • retry_on_errors (bool，可选，默认为 False) — 是否在遇到错误（429、5xx、超时、网络错误）时重试。 如果为 False，则不重试，以便快速回退到本地缓存。

获取 Hub 上给定 url 的文件版本的元数据。

HfFileMetadata

class huggingface_hub.HfFileMetadata

< >

( commit_hash: str | Noneetag: str | Nonelocation: strsize: int | Nonexet_file_data: huggingface_hub.utils._xet.XetFileData | None )

参数

  • commit_hash (str, 可选) — 与该文件相关的 commit_hash。
  • etag (str, 可选) — 服务器上该文件的 Etag。
  • location (str) — 下载文件的位置。可以是 Hub 网址，也可以不是（CDN）。
  • size (size) — 文件大小。对于 LFS 文件，包含实际 LFS 文件的大小，而非指针的大小。
  • xet_file_data (XetFileData，可选) — 该文件的 Xet 信息。仅当文件使用 Xet 存储时才会设置此值。

包含在 Hub 上版本化文件信息的数据结构。

根据 URL 由 get_hf_file_metadata() 返回。

缓存

上述显示的方法旨在与一个缓存系统配合使用，该系统可防止重复下载文件。该缓存系统在 v0.8.0 中进行了更新，成为依赖 Hub 的各个库之间共享的中央缓存系统。

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

Update on GitHub

←CLI Mixins 与序列化方法→