Hugging Face 的标志

Hub Python 库文档

下载文件

Hugging Face's logo
加入 Hugging Face 社区

并获得增强型文档体验

开始使用

下载文件

下载单个文件

hf_hub_download

huggingface_hub.hf_hub_download

< >

( repo_id: str filename: str subfolder: Optional = None repo_type: Optional = None revision: Optional = None library_name: Optional = None library_version: Optional = None cache_dir: Union = None local_dir: Union = None user_agent: Union = None force_download: bool = False proxies: Optional = None etag_timeout: float = 10 token: Union = None local_files_only: bool = False headers: Optional = None endpoint: Optional = None resume_download: Optional = None force_filename: Optional = None local_dir_use_symlinks: Union = '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, 可选) — 将协议映射到传递给 requests.request 的代理 URL 的字典。
  • etag_timeout (float, 可选, 默认值 10) — 获取 ETag 时，在放弃之前等待服务器发送数据的时间（以秒为单位），传递给 requests.request。
  • token (str, bool, 可选) — 用于下载的令牌。
    • 如果为 True，则从 HuggingFace 配置文件夹中读取令牌。
    • 如果为字符串，则用作身份验证令牌。
  • local_files_only (bool, 可选, 默认值 False) — 如果为 True，则避免下载文件，如果本地缓存中存在文件，则返回本地缓存文件的路径。
  • headers (dict, 可选) — 要与请求一起发送的额外标头。

返回

str

文件的本地路径，或者如果网络关闭，则为磁盘上缓存的最后一个版本文件的路径。

引发

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

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

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

  • 缓存目录包含每个 repo_id 的一个子文件夹（按仓库类型命名空间）
  • 在每个仓库文件夹内
    • refs 是已知最新版本的列表 => commit_hash 对
    • blobs 包含实际的文件块（根据它们是 LFS 文件还是非 LFS 文件，由它们的 git-sha 或 sha256 标识）
    • snapshots 包含每个提交的一个子文件夹，每个“提交”包含在该特定提交时已解析的文件子集。每个文件名都是指向该特定提交的块的符号链接。
[  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: Optional = None repo_type: Optional = None revision: Optional = None endpoint: Optional = 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）的链接，用于超过几兆字节的大文件。

示例

>>> 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: str repo_type: Optional = None revision: Optional = None cache_dir: Union = None local_dir: Union = None library_name: Optional = None library_version: Optional = None user_agent: Union = None proxies: Optional = None etag_timeout: float = 10 force_download: bool = False token: Union = None local_files_only: bool = False allow_patterns: Union = None ignore_patterns: Union = None max_workers: int = 8 tqdm_class: Optional = None headers: Optional = None endpoint: Optional = None local_dir_use_symlinks: Union = 'auto' resume_download: Optional = 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, 可选) — 用户代理信息，以字典或字符串的形式。
  • 代理 (dict, 可选) — 将协议映射到传递给 requests.request 的代理 URL 的字典。
  • ETag 超时 (float, 可选, 默认值为 10) — 获取 ETag 时，等待服务器发送数据的时间（以秒为单位），超过该时间将放弃，该时间传递给 requests.request。
  • 强制下载 (bool, 可选, 默认值为 False) — 是否应即使文件已存在于本地缓存中也下载文件。
  • 令牌 (str, bool, 可选) — 用于下载的令牌。
    • 如果为 True，则从 HuggingFace 配置文件夹中读取令牌。
    • 如果为字符串，则用作身份验证令牌。
  • 标头 (dict, 可选) — 要包含在请求中的其他标头。这些标头优先于其他标头。
  • 仅限本地文件 (bool, 可选, 默认值为 False) — 如果为 True，则避免下载文件，如果本地缓存中存在文件，则返回本地缓存文件的路径。
  • 允许模式 (List[str] 或 str, 可选) — 如果提供，则仅下载与至少一种模式匹配的文件。
  • 忽略模式 (List[str] 或 str, 可选) — 如果提供，则不下载与任何模式匹配的文件。
  • 最大工作线程数 (int, 可选) — 用于下载文件的并发线程数（1 个线程 = 1 个文件下载）。默认值为 8。
  • 进度条类 (tqdm, 可选) — 如果提供，将覆盖进度条的默认行为。传递的参数必须继承自 tqdm.auto.tqdm 或至少模仿其行为。请注意，tqdm_class 不会传递给每个单独的下载。默认情况下，使用自定义的 HF 进度条，可以通过设置 HF_HUB_DISABLE_PROGRESS_BARS 环境变量来禁用该进度条。

返回

str

存储库快照的文件夹路径。

引发

RepositoryNotFoundError 或 RevisionNotFoundError 或 EnvironmentError 或 OSError 或 ValueError

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

下载存储库文件。

在指定版本处下载存储库文件的整个快照。当您需要存储库中的所有文件但事先不知道需要哪些文件时，这很有用。所有文件都嵌套在文件夹中，以便保持它们相对于该文件夹的实际文件名。您还可以使用 allow_patterns 和 ignore_patterns 过滤要下载的文件。

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

另一种方法是克隆存储库，但这需要安装并正确配置 git 和 git-lfs。使用 git 克隆存储库时，也不可能过滤要下载的文件。

获取有关文件的元数据

get_hf_file_metadata

huggingface_hub.get_hf_file_metadata

< >

( url: str token: Union = None proxies: Optional = None timeout: Optional = 10 library_name: Optional = None library_version: Optional = None user_agent: Union = None headers: Optional = None )

参数

  • url (str) — 文件 URL，例如由 hf_hub_url() 返回。
  • token (str 或 bool, 可选) — 用于下载的令牌。
    • 如果为 True，则从 HuggingFace 配置文件夹读取令牌。
    • 如果为 False 或 None，则不提供令牌。
    • 如果为字符串，则用作身份验证令牌。
  • proxies (dict, 可选) — 将协议映射到传递给 requests.request 的代理 URL 的字典。
  • timeout (float, 可选，默认值为 10) — 在放弃之前等待服务器发送元数据的秒数。
  • library_name (str, 可选) — 与该对象相对应的库的名称。
  • library_version (str, 可选) — 库的版本。
  • user_agent (dict, str, 可选) — 以字典或字符串形式的用户代理信息。
  • headers (dict, optional) — 请求时要发送的额外头信息。

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

HfFileMetadata

class huggingface_hub.HfFileMetadata

< >

( commit_hash: Optional etag: Optional location: str size: Optional )

参数

  • commit_hash (str, optional) — 与文件相关的 commit_hash。
  • etag (str, optional) — 文件在服务器上的 Etag。
  • location (str) — 下载文件的地址。可以是 Hub URL 或其他地址（CDN）。
  • size (size) — 文件的大小。如果是 LFS 文件，包含实际 LFS 文件的大小，而不是指针的大小。

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

由 get_hf_file_metadata() 基于 URL 返回。

缓存

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

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

< > 在 GitHub 上更新

←Hugging Face Hub API 混合类 & 序列化方法→