Hugging Face 的标志

Hub Python 库文档

正在下载文件

Hugging Face's logo
加入 Hugging Face 社区

并访问增强的文档体验

开始使用

下载文件

下载单个文件

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, 可选) — 如果从数据集或 Space 下载，则设置为 "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, optional, defaults to False) — 如果为 True，则避免下载文件，并在本地缓存中存在该文件时返回本地缓存文件的路径。
  • headers (dict, optional) — 要随请求一起发送的附加标头。

返回 (Returns)

str

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

引发 (Raises)

RepositoryNotFoundError 或 RevisionNotFoundError 或 EntryNotFoundError 或 LocalEntryNotFoundError 或 EnvironmentError 或 OSError 或 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, optional) — 仓库内文件夹的可选值。
  • repo_type (str, optional) — 如果从数据集或 Space 下载，则设置为 "dataset" 或 "space"，如果从模型下载，则设置为 None 或 "model"。默认为 None。
  • revision (str, optional) — 可选的 Git 版本 ID，可以是分支名称、标签或提交哈希值。

从给定信息构造文件的 URL。

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

示例 (Example)

>>> 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'

注释 (Notes)

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

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

关于来自此库的客户端缓存，我们的缓存基于对象的实体标签 (ETag)，它是资源特定版本的标识符 [1] _。对象的 ETag 是：如果存储在 git 中，则为其 git-sha1；如果存储在 git-lfs 中，则为其 sha256。

参考 (References)

下载仓库的快照 (Download a snapshot of the repo)

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[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, optional) — 如果从数据集或 Space 下载，则设置为 "dataset" 或 "space"，如果从模型下载，则设置为 None 或 "model"。默认为 None。
  • revision (str, optional) — 可选的 Git 版本 ID，可以是分支名称、标签或提交哈希值。
  • cache_dir (str, Path, optional) — 缓存文件存储在其中的文件夹的路径。
  • local_dir (str 或 Path, optional) — 如果提供，下载的文件将放置在此目录下。
  • library_name (str, optional) — 对象对应的库的名称。
  • library_version (str, optional) — 库的版本。
  • user_agent (str, dict, optional) — 用户代理信息，可以是字典或字符串形式。
  • proxies (dict, optional) — 字典，将协议映射到传递给 requests.request 的代理 URL。
  • etag_timeout (float, optional, defaults to 10) — 获取 ETag 时，等待服务器发送数据多少秒后放弃，该值会传递给 requests.request。
  • force_download (bool, optional, defaults to False) — 是否应下载文件，即使该文件已存在于本地缓存中。
  • token (str, bool, optional) — 用于下载的令牌。
    • 如果为 True，则从 HuggingFace 配置文件夹中读取令牌。
    • 如果为字符串，则将其用作身份验证令牌。
  • headers (dict, optional) — 要包含在请求中的附加标头。这些标头的优先级高于其他标头。
  • local_files_only (bool, 可选, 默认为 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 环境变量来禁用。

返回 (Returns)

str

仓库快照的文件夹路径。

引发 (Raises)

RepositoryNotFoundError 或 RevisionNotFoundError 或 EnvironmentError 或 OSError 或 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: 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 )

参数

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

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

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 上版本控制的文件的信息的数据结构。

由 get_hf_file_metadata() 基于 URL 返回。

缓存

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

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

< > 在 GitHub 上更新

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