Hugging Face's logo

Hub Python Library documentation

下载文件

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v2.4.0).
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 与序列化方法→