# 下载文件

## 下载单个文件

### hf_hub_download[[huggingface_hub.hf_hub_download]]

#### huggingface_hub.hf_hub_download[[huggingface_hub.hf_hub_download]]

```python
huggingface_hub.hf_hub_download(repo_id: str, filename: str, subfolder: str | None = None, repo_type: str | None = None, revision: str | None = None, library_name: str | None = None, library_version: str | None = None, cache_dir: str | pathlib.Path | None = None, local_dir: str | pathlib.Path | None = None, user_agent: dict | str | None = None, force_download: bool = False, etag_timeout: float = 10, token: bool | str | None = None, local_files_only: bool = False, headers: dict[str, str] | None = None, endpoint: str | None = None, tqdm_class: type[tqdm.std.tqdm] | None = None, dry_run: bool = False)
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/file_download.py#L855)

**参数：**

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`, *optional*) : 用于下载的令牌。 - 如果为 `True`，则从 HuggingFace 配置文件夹中读取令牌。 - 如果为字符串，则将其用作身份验证令牌。

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](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.DryRunFileInfo) 对象，其中包含有关将要下载内容的信息。

**返回：** `str` 或 [DryRunFileInfo](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.DryRunFileInfo)

- 如果 `dry_run=False`：文件的本地路径，或者在网络关闭时，磁盘上缓存的文件最后版本。
- 如果 `dry_run=True`：一个包含下载信息的 [DryRunFileInfo](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.DryRunFileInfo) 对象。

**引发：** [RepositoryNotFoundError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.RepositoryNotFoundError) 或 [RevisionNotFoundError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.RevisionNotFoundError) 或 `~utils.RemoteEntryNotFoundError` 或 [LocalEntryNotFoundError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.LocalEntryNotFoundError) 或 ``EnvironmentError`` 或 ``OSError`` 或 ``ValueError``

- [RepositoryNotFoundError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.RepositoryNotFoundError) -- 如果找不到要下载的仓库。这可能是因为它不存在，或者它被设置为 `private` 且您没有访问权限。
- [RevisionNotFoundError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.RevisionNotFoundError) -- 如果找不到要下载的修订版本。
- `~utils.RemoteEntryNotFoundError` -- 如果找不到要下载的文件。
- [LocalEntryNotFoundError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.LocalEntryNotFoundError) -- 如果网络被禁用或不可用，且缓存中未找到该文件。
- [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError) -- 如果 `token=True` 但找不到令牌。
- [`OSError`](https://docs.python.org/3/library/exceptions.html#OSError) -- 如果无法确定 ETag。
- [`ValueError`](https://docs.python.org/3/library/exceptions.html#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]]

#### huggingface_hub.hf_hub_url[[huggingface_hub.hf_hub_url]]

```python
huggingface_hub.hf_hub_url(repo_id: str, filename: str, subfolder: str | None = None, repo_type: str | None = None, revision: str | None = None, endpoint: str | None = None)
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/file_download.py#L210)

**参数：**

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，也可以是针对大于几 MB 的大文件指向 Cloudfront（内容分发网络，即 CDN）的链接。

示例：

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

> [!TIP]
> 注意事项：
>
> Cloudfront 在全球范围内进行了复制，因此终端用户的下载速度会快得多（同时也能降低我们的带宽成本）。
>
> Cloudfront 默认会积极缓存文件（默认 TTL 为 24 小时），但在这里这不是问题，因为我们在 huggingface.co 上实现了基于 git 的版本控制系统，这意味着我们以内容可寻址的方式（即文件名为其哈希值）在 S3/Cloudfront 上存储文件。使用内容可寻址的文件名意味着缓存永远不会过期。
>
> 就本库的客户端缓存而言，我们的缓存基于对象的实体标签（`ETag`），它是特定版本资源的标识符 [1]_。对象的 ETag 为：若存储在 git 中，则为其 git-sha1；若存储在 git-lfs 中，则为其 sha256。

参考文献：

-  https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag

## 下载仓库的快照[[huggingface_hub.snapshot_download]]

#### huggingface_hub.snapshot_download[[huggingface_hub.snapshot_download]]

```python
huggingface_hub.snapshot_download(repo_id: str, repo_type: str | None = None, revision: str | None = None, cache_dir: str | pathlib.Path | None = None, local_dir: str | pathlib.Path | None = None, library_name: str | None = None, library_version: str | None = None, user_agent: dict | str | None = None, etag_timeout: float = 10, force_download: bool = False, token: bool | str | None = None, local_files_only: bool = False, allow_patterns: list[str] | str | None = None, ignore_patterns: list[str] | str | None = None, max_workers: int = 8, tqdm_class: type[tqdm.asyncio.tqdm_asyncio] | None = None, headers: dict[str, str] | None = None, endpoint: str | None = None, dry_run: bool = False)
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_snapshot_download.py#L121)

**参数：**

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`, *optional*) : 用于下载的令牌。 - 如果为 `True`，则从 HuggingFace 配置文件夹中读取令牌。 - 如果为字符串，则将其用作身份验证令牌。

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](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.DryRunFileInfo) 对象的列表，其中包含有关将下载内容的信息。

**返回：** `str` 或 [DryRunFileInfo](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.DryRunFileInfo) 列表

- 如果 `dry_run=False`：本地快照路径。
- 如果 `dry_run=True`：一个包含下载信息的 [DryRunFileInfo](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.DryRunFileInfo) 对象列表。

**引发：** [RepositoryNotFoundError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.RepositoryNotFoundError) 或 [RevisionNotFoundError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.RevisionNotFoundError) 或 [IncompleteSnapshotError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.IncompleteSnapshotError) 或 ``EnvironmentError`` 或 ``OSError`` 或 ``ValueError``

- [RepositoryNotFoundError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.RepositoryNotFoundError) -- 如果找不到要下载的仓库。这可能是因为它不存在，或者它被设置为 `private` 且您没有访问权限。
- [RevisionNotFoundError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.RevisionNotFoundError) -- 如果找不到要下载的修订版本。
- [IncompleteSnapshotError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.IncompleteSnapshotError) -- 如果无法连接到 Hub（离线、连接问题或 `local_files_only=True`），并且缓存的快照缺少部分请求的文件。
- [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError) -- 如果 `token=True` 且未找到令牌。
- [`OSError`](https://docs.python.org/3/library/exceptions.html#OSError) -- 如果无法确定 ETag。
- [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) -- 如果某些参数值无效。

下载仓库文件。

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

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

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

## 读取缓存的仓库树[[huggingface_hub.get_cached_repo_tree]]

#### huggingface_hub.get_cached_repo_tree[[huggingface_hub.get_cached_repo_tree]]

```python
huggingface_hub.get_cached_repo_tree(repo_id: str, repo_type: str | None = None, revision: str | None = None, cache_dir: str | pathlib.Path | None = None, local_dir: str | pathlib.Path | None = None)
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_snapshot_download.py#L603)

**参数：**

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](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.RepoFile) 对象列表。

**引发：** [CachedRepoTreeNotFoundError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.CachedRepoTreeNotFoundError)

- [CachedRepoTreeNotFoundError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.CachedRepoTreeNotFoundError) -- 如果请求的修订版本没有缓存的树列表（例如，该仓库从未在此修订版本下下载过）。

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

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

如果您需要获取 Hub 上某个仓库的当前树列表，请改用 [list_repo_tree()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.list_repo_tree)。

示例：
```py
>>> 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()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision) 和 [缓存系统指南](../guides/manage-cache#pin-a-revision-advanced)。

### ResolvedRevision[[huggingface_hub.ResolvedRevision]]

#### huggingface_hub.ResolvedRevision[[huggingface_hub.ResolvedRevision]]

```python
huggingface_hub.ResolvedRevision(resolved: str, initial: str | None = None, repo_id: str | None = None, repo_type: str | None = None)
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_revision.py#L4)

**参数：**

initial (`str` 或 `None`) : 用户最初请求的版本。如果为 `None`，则字符串值默认为 `"main"`。

resolved (`str`) : `initial` 所解析到的提交哈希值。

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

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

实例由 [HfApi.resolve_revision()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision) 构建，该方法还会将 `revision` -> `commit hash` 的映射缓存到本地缓存（`refs/` 文件夹）中。

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

示例：
```python
>>> 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]]

#### huggingface_hub.get_hf_file_metadata[[huggingface_hub.get_hf_file_metadata]]

```python
huggingface_hub.get_hf_file_metadata(url: str, token: bool | str | None = None, timeout: float | None = 10, library_name: str | None = None, library_version: str | None = None, user_agent: dict | str | None = None, headers: dict[str, str] | None = None, endpoint: str | None = None, retry_on_errors: bool = False)
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/file_download.py#L1617)

**参数：**

url (`str`) : 文件 URL，例如由 [hf_hub_url()](/docs/huggingface_hub/v2.4.0/zh/package_reference/file_download#huggingface_hub.hf_hub_url) 返回。

token (`str` 或 `bool`，*可选*)：用于下载的令牌。- 如果为 `True`，则从 HuggingFace 配置文件夹中读取令牌。- 如果为 `False` 或 `None`，则不提供令牌。- 如果为字符串，则将其用作身份验证令牌。

timeout (`float`, *可选*，默认为 10) : 在放弃之前，等待服务器发送元数据的秒数。

library_name (`str`, *可选*) : 该对象所对应的库的名称。

library_version (`str`, *可选*) : 库的版本。

user_agent (`dict`、`str`、*可选*)：以字典或字符串形式表示的用户代理信息。

headers (`dict`, *可选*) : 随请求一起发送的附加请求头。

endpoint (`str`, *可选*) : Hub 的端点。默认为 。

retry_on_errors (`bool`，*可选*，默认为 `False`)：是否在遇到错误（429、5xx、超时、网络错误）时重试。如果为 False，则不重试，以便快速回退到本地缓存。

**返回：**

包含位置、etag、大小和 commit_hash 等元数据的 [HfFileMetadata](/docs/huggingface_hub/v2.4.0/zh/package_reference/file_download#huggingface_hub.HfFileMetadata) 对象。

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

### HfFileMetadata[[huggingface_hub.HfFileMetadata]]

#### huggingface_hub.HfFileMetadata[[huggingface_hub.HfFileMetadata]]

```python
huggingface_hub.HfFileMetadata(commit_hash: str | None, etag: str | None, location: str, size: int | None, xet_file_data: huggingface_hub.utils._xet.XetFileData | None)
```

[源代码](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/file_download.py#L155)

**参数：**

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()](/docs/huggingface_hub/v2.4.0/zh/package_reference/file_download#huggingface_hub.get_hf_file_metadata) 返回。

## 缓存

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

阅读[缓存系统指南](../guides/manage-cache)，详细了解 HF 的缓存机制。