# 缓存系统参考

缓存系统在 v0.8.0 中进行了更新，成为依赖 Hub 的各库共享的核心缓存系统。有关 HF 缓存机制的详细说明，请参阅[缓存系统指南](../guides/manage-cache)。

## 辅助函数

### try_to_load_from_cache[[huggingface_hub.try_to_load_from_cache]]

#### huggingface_hub.try_to_load_from_cache[[huggingface_hub.try_to_load_from_cache]]

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

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

**参数：**

cache_dir (`str` 或 `os.PathLike`) : 缓存文件所在的文件夹。

repo_id (`str`) : huggingface.co 上仓库的 ID。

filename (`str`) : 要在 `repo_id` 中查找的文件名。

revision (`str`, *可选*) : 要使用的特定模型版本。如果未提供此参数且也未提供 `commit_hash`，则默认使用 `"main"`。

repo_type (`str`, *可选*) : 仓库的类型。默认值为 `"model"`。

**返回：** `Optional[str]` 或 `_CACHED_NO_EXIST`

如果文件未被缓存，则返回 `None`。否则：
- 如果在缓存中找到该文件，则返回其确切路径
- 如果文件在指定的提交哈希中不存在，且该事实已被缓存，则返回特殊值 `_CACHED_NO_EXIST`。

探索缓存，如果找到，则返回给定修订版本的最新缓存文件。

如果文件未缓存，此函数不会引发任何异常。

示例：

```python
from huggingface_hub import try_to_load_from_cache, _CACHED_NO_EXIST

filepath = try_to_load_from_cache()
if isinstance(filepath, str):
    # file exists and is cached
    ...
elif filepath is _CACHED_NO_EXIST:
    # non-existence of file is cached
    ...
else:
    # file is not cached
    ...
```

### cached_assets_path[[huggingface_hub.cached_assets_path]]

#### huggingface_hub.cached_assets_path[[huggingface_hub.cached_assets_path]]

```python
huggingface_hub.cached_assets_path(library_name: str, namespace: str = 'default', subfolder: str = 'default', assets_dir: str | pathlib.Path | None = None)
```

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

**参数：**

library_name (`str`) : 将管理缓存文件夹的库的名称。示例：`"dataset"`。

namespace (`str`，*可选*，默认为 "default")：数据所属的命名空间。示例：`"SQuAD"`。

subfolder (`str`，*可选*，默认为 "default")：用于存储数据的子文件夹。示例：`extracted`。

assets_dir (`str`, `Path`, *可选*) : 用于缓存资产的文件夹路径。此路径不能与 Hub 文件的缓存文件夹相同。如果未提供，则默认为 `HF_HOME / "assets"`。也可以通过 `HF_ASSETS_CACHE` 环境变量进行设置。

**返回：**

缓存文件夹的路径（`Path`）。

返回一个用于缓存任意文件的文件夹路径。

`huggingface_hub` 提供了一个用于存储资产的规范文件夹路径。这是下游库集成缓存的推荐方式，因为它可以利用内置工具来正确扫描和删除缓存。

系统区分了从 Hub 缓存的文件和资产。来自 Hub 的文件以感知 git 的方式缓存，并完全由 `huggingface_hub` 管理。请参阅 [相关文档](https://huggingface.co/docs/huggingface_hub/how-to-cache)。下游库缓存的所有其他文件均被视为“资产”（从外部来源下载的文件、从 .tar 归档中提取的文件、为训练而预处理的文件等）。

一旦生成了文件夹路径，即可保证该路径存在且为一个目录。该路径基于三个层级的深度：库名称、命名空间和子文件夹。这三个层级在允许 `huggingface_hub` 在扫描或删除资产缓存的部分内容时预期文件夹存在的同时，提供了灵活性。在库内部，预期所有命名空间共享相同的子文件夹名称子集，但这并非强制规则。下游库因此可以完全控制其缓存内采用的文件结构。命名空间和子文件夹是可选的（默认会使用 `"default/"` 子文件夹），但库名称是必需的，因为我们希望每个下游库都能管理自己的缓存。

预期树：
```text
    assets/
    └── datasets/
    │   ├── SQuAD/
    │   │   ├── downloaded/
    │   │   ├── extracted/
    │   │   └── processed/
    │   ├── Helsinki-NLP--tatoeba_mt/
    │       ├── downloaded/
    │       ├── extracted/
    │       └── processed/
    └── transformers/
        ├── default/
        │   ├── something/
        ├── bert-base-cased/
        │   ├── default/
        │   └── training/
    hub/
    └── models--julien-c--EsperBERTo-small/
        ├── blobs/
        │   ├── (...)
        │   ├── (...)
        ├── refs/
        │   └── (...)
        └── [ 128]  snapshots/
            ├── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/
            │   ├── (...)
            └── bbc77c8132af1cc5cf678da3f1ddf2de43606d48/
                └── (...)
```

示例：
```py
>>> from huggingface_hub import cached_assets_path

>>> cached_assets_path(library_name="datasets", namespace="SQuAD", subfolder="download")
PosixPath('/home/wauplin/.cache/huggingface/extra/datasets/SQuAD/download')

>>> cached_assets_path(library_name="datasets", namespace="SQuAD", subfolder="extracted")
PosixPath('/home/wauplin/.cache/huggingface/extra/datasets/SQuAD/extracted')

>>> cached_assets_path(library_name="datasets", namespace="Helsinki-NLP/tatoeba_mt")
PosixPath('/home/wauplin/.cache/huggingface/extra/datasets/Helsinki-NLP--tatoeba_mt/default')

>>> cached_assets_path(library_name="datasets", assets_dir="/tmp/tmp123456")
PosixPath('/tmp/tmp123456/datasets/default/default')
```

### scan_cache_dir[[huggingface_hub.scan_cache_dir]]

#### huggingface_hub.scan_cache_dir[[huggingface_hub.scan_cache_dir]]

```python
huggingface_hub.scan_cache_dir(cache_dir: str | pathlib.Path | None = None)
```

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

**参数：**

cache_dir (`str` or `Path`, `optional`) : Cache directory to cache. Defaults to the default HF cache directory.

扫描整个 HF 缓存系统并返回一个 [~HFCacheInfo](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.HFCacheInfo) 结构。

使用 `scan_cache_dir` 以编程方式扫描您的缓存系统。缓存将按仓库逐个扫描。如果某个仓库已损坏，内部会抛出 [~CorruptedCacheException](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.CorruptedCacheException)，但会被捕获并返回在 [~HFCacheInfo](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.HFCacheInfo) 结构中。只有有效的仓库才会获得完整的报告。

```py
>>> from huggingface_hub import scan_cache_dir

>>> hf_cache_info = scan_cache_dir()
HFCacheInfo(
    size_on_disk=3398085269,
    repos=frozenset({
        CachedRepoInfo(
            repo_id='t5-small',
            repo_type='model',
            repo_path=PosixPath(...),
            size_on_disk=970726914,
            nb_files=11,
            revisions=frozenset({
                CachedRevisionInfo(
                    commit_hash='d78aea13fa7ecd06c29e3e46195d6341255065d5',
                    size_on_disk=970726339,
                    snapshot_path=PosixPath(...),
                    files=frozenset({
                        CachedFileInfo(
                            file_name='config.json',
                            size_on_disk=1197
                            file_path=PosixPath(...),
                            blob_path=PosixPath(...),
                        ),
                        CachedFileInfo(...),
                        ...
                    }),
                ),
                CachedRevisionInfo(...),
                ...
            }),
        ),
        CachedRepoInfo(...),
        ...
    }),
    warnings=[
        CorruptedCacheException("Snapshots dir doesn't exist in cached repo: ..."),
        CorruptedCacheException(...),
        ...
    ],
)
```

您也可以使用以下命令直接从 `hf` 命令行打印详细报告：
```text
> hf cache ls
ID                          SIZE     LAST_ACCESSED LAST_MODIFIED REFS
--------------------------- -------- ------------- ------------- -----------
dataset/nyu-mll/glue          157.4M 2 days ago    2 days ago    main script
model/LiquidAI/LFM2-VL-1.6B     3.2G 4 days ago    4 days ago    main
model/microsoft/UserLM-8b      32.1G 4 days ago    4 days ago    main

Done in 0.0s. Scanned 6 repo(s) for a total of 3.4G.
Got 1 warning(s) while scanning. Use -vvv to print details.
```

> [!WARNING]
> 引发：
>
> `CacheNotFound` 如果缓存目录不存在。
>
> [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) 如果缓存目录是一个文件而不是目录。

返回：一个 [~HFCacheInfo](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.HFCacheInfo) 对象。

## 数据结构

所有结构均由 [scan_cache_dir()](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.scan_cache_dir) 构建并返回，且不可变。

### HFCacheInfo[[huggingface_hub.HFCacheInfo]]

#### huggingface_hub.HFCacheInfo[[huggingface_hub.HFCacheInfo]]

```python
huggingface_hub.HFCacheInfo(size_on_disk: int, repos: frozenset, incomplete_files: frozenset, warnings: list, cache_dir: pathlib.Path | None = None)
```

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

**参数：**

size_on_disk (`int`) : 缓存系统的物理大小（以字节为单位）。跨仓库共享的 blob 仅计算一次，且不再被任何仓库引用的仅存储共享 blob 也会被包含在内。该值可能小于各仓库大小之和。

repos (`frozenset[CachedRepoInfo]`) : 一组 [~CachedRepoInfo](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.CachedRepoInfo)，描述在扫描缓存系统时找到的所有有效缓存仓库。

incomplete_files (`frozenset[CachedIncompleteFileInfo]`) : 一组 [~CachedIncompleteFileInfo](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.CachedIncompleteFileInfo)，用于描述由中断的下载遗留下来的孤立 `*.incomplete` 文件。

warnings (`list[CorruptedCacheException]`) : 扫描缓存期间发生的 [~CorruptedCacheException](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.CorruptedCacheException) 列表。捕获这些异常是为了让扫描能够继续。损坏的仓库会被跳过，不参与扫描。

cache_dir (`Path` 或 `None`) : 已扫描的缓存目录。

用于保存整个缓存系统信息的冻结数据结构。

此数据结构由 [scan_cache_dir()](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.scan_cache_dir) 返回，且不可变。

> [!WARNING]
> `size_on_disk` 仅统计 blob，并会跳过损坏的仓库。它是一个物理大小：与 `CachedRepoInfo.size_on_disk` 不同（后者会将共享 blob 计入每个引用它的仓库），此处共享的 blob 只计算一次。

#### delete_files[[huggingface_hub.HFCacheInfo.delete_files]]

```python
delete_files(*files: CachedFileInfo)
```

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

准备删除单个缓存文件的策略。

仅删除快照条目。只有当没有其他缓存文件引用某个 blob 时，该 blob 才会被删除，因此与其他修订版本共享的 blob 会被保留。即使快照最终为空，引用和快照目录也会被保留。若要删除整个修订版本或仓库，请使用 [delete_revisions()](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.HFCacheInfo.delete_revisions)。

示例：
```py
>>> from huggingface_hub import scan_cache_dir
>>> cache_info = scan_cache_dir()
>>> files = [
...     file
...     for repo in cache_info.repos
...     if repo.repo_id == "org/model"
...     for revision in repo.revisions
...     for file in revision.files
...     if file.file_name == "model-Q4_K_M.gguf"
... ]
>>> delete_strategy = cache_info.delete_files(*files)
>>> print(f"Will free {delete_strategy.expected_freed_size_str}.")
Will free 4.9G.
>>> delete_strategy.execute()
```

#### delete_revisions[[huggingface_hub.HFCacheInfo.delete_revisions]]

```python
delete_revisions(*revisions: str)
```

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

准备删除一个或多个本地缓存的修订版本的策略。

输入修订版本可以是任意修订版本哈希值。如果在本地缓存中未找到修订版本哈希值，则会抛出警告，但不会引发错误。由于哈希值在不同仓库之间是唯一的，因此修订版本可以来自不同的缓存仓库，

示例：
```py
>>> from huggingface_hub import scan_cache_dir
>>> cache_info = scan_cache_dir()
>>> delete_strategy = cache_info.delete_revisions(
...     "81fd1d6e7847c99f5862c9fb81387956d99ec7aa"
... )
>>> print(f"Will free {delete_strategy.expected_freed_size_str}.")
Will free 7.9K.
>>> delete_strategy.execute()
```

```py
>>> from huggingface_hub import scan_cache_dir
>>> scan_cache_dir().delete_revisions(
...     "81fd1d6e7847c99f5862c9fb81387956d99ec7aa",
...     "e2983b237dccf3ab4937c97fa717319a9ca1a96d",
...     "6c0e6080953db56375760c0471a8c5f2929baf11",
... ).execute()
```

> [!WARNING]
> `delete_revisions` 返回一个需要执行的 [DeleteCacheStrategy](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.DeleteCacheStrategy) 对象。[DeleteCacheStrategy](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.DeleteCacheStrategy) 本身不应被修改，但允许在实际执行删除之前进行试运行。

#### export_as_table[[huggingface_hub.HFCacheInfo.export_as_table]]

```python
export_as_table(verbosity: int = 0)
```

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

**参数：**

verbosity (`int`, *可选*) : 详细程度级别。默认为 0。

**返回：** `str`

以字符串形式表示的表格。

从 [HFCacheInfo](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.HFCacheInfo) 对象生成表格。

传入 `verbosity=0` 可获取一个表格，其中每个仓库占一行，列包括 "repo_id"、"repo_type"、"size_on_disk"、"nb_files"、"last_accessed"、"last_modified"、"refs" 和 "local_path"。

传入 `verbosity=1` 可获取一个表格，其中每个仓库和修订版本占一行（因此单个仓库可能出现多行），列包括 "repo_id"、"repo_type"、"revision"、"size_on_disk"、"nb_files"、"last_modified"、"refs" 和 "local_path"。

示例：
```py
>>> from huggingface_hub.utils import scan_cache_dir

>>> hf_cache_info = scan_cache_dir()
HFCacheInfo(...)

>>> print(hf_cache_info.export_as_table())
REPO ID                                             REPO TYPE SIZE ON DISK NB FILES LAST_ACCESSED LAST_MODIFIED REFS LOCAL PATH
--------------------------------------------------- --------- ------------ -------- ------------- ------------- ---- --------------------------------------------------------------------------------------------------
roberta-base                                        model             2.7M        5 1 day ago     1 week ago    main ~/.cache/huggingface/hub/models--roberta-base
suno/bark                                           model             8.8K        1 1 week ago    1 week ago    main ~/.cache/huggingface/hub/models--suno--bark
t5-base                                             model           893.8M        4 4 days ago    7 months ago  main ~/.cache/huggingface/hub/models--t5-base
t5-large                                            model             3.0G        4 5 weeks ago   5 months ago  main ~/.cache/huggingface/hub/models--t5-large

>>> print(hf_cache_info.export_as_table(verbosity=1))
REPO ID                                             REPO TYPE REVISION                                 SIZE ON DISK NB FILES LAST_MODIFIED REFS LOCAL PATH
--------------------------------------------------- --------- ---------------------------------------- ------------ -------- ------------- ---- -----------------------------------------------------------------------------------------------------------------------------------------------------
roberta-base                                        model     e2da8e2f811d1448a5b465c236feacd80ffbac7b         2.7M        5 1 week ago    main ~/.cache/huggingface/hub/models--roberta-base/snapshots/e2da8e2f811d1448a5b465c236feacd80ffbac7b
suno/bark                                           model     70a8a7d34168586dc5d028fa9666aceade177992         8.8K        1 1 week ago    main ~/.cache/huggingface/hub/models--suno--bark/snapshots/70a8a7d34168586dc5d028fa9666aceade177992
t5-base                                             model     a9723ea7f1b39c1eae772870f3b547bf6ef7e6c1       893.8M        4 7 months ago  main ~/.cache/huggingface/hub/models--t5-base/snapshots/a9723ea7f1b39c1eae772870f3b547bf6ef7e6c1
t5-large                                            model     150ebc2c4b72291e770f58e6057481c8d2ed331a         3.0G        4 5 months ago  main ~/.cache/huggingface/hub/models--t5-large/snapshots/150ebc2c4b72291e770f58e6057481c8d2ed331a
```

### CachedRepoInfo[[huggingface_hub.CachedRepoInfo]]

#### huggingface_hub.CachedRepoInfo[[huggingface_hub.CachedRepoInfo]]

```python
huggingface_hub.CachedRepoInfo(repo_id: str, repo_type: typing.Literal['model', 'dataset', 'space', 'kernel'], repo_path: Path, size_on_disk: int, nb_files: int, revisions: frozenset, last_accessed: float, last_modified: float)
```

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

**参数：**

repo_id (`str`) : Hub 上仓库的 Repo id。示例：`"google/fleurs"`。

repo_type (`Literal["dataset", "model", "space", "kernel"]`)：缓存仓库的类型。

repo_path (`Path`) : 缓存仓库的本地路径。

size_on_disk (`int`) : 缓存仓库中 blob 文件大小的总和。

nb_files (`int`) : 缓存仓库中 blob 文件的总数。

revisions (`frozenset[CachedRevisionInfo]`) : 描述仓库中所有已缓存修订版本的 [~CachedRevisionInfo](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.CachedRevisionInfo) 集合。

last_accessed (`float`) : 该仓库的 blob 文件最后一次被访问的时间戳。

last_modified (`float`) : 该仓库中 blob 文件最后一次被修改或创建的时间戳。

用于保存缓存仓库信息的冻结数据结构。

> [!WARNING]
> `size_on_disk` 不一定等于所有修订版本大小的总和，因为存在重复文件。此外，仅计算 blob 的大小，而不包括文件夹和符号链接（可忽略不计）的大小。

> [!WARNING]
> `last_accessed` 和 `last_modified` 的可靠性可能取决于您使用的操作系统。有关更多详细信息，请参阅 [python 文档](https://docs.python.org/3/library/os.html#os.stat_result)。

#### size_on_disk_str[[huggingface_hub.CachedRepoInfo.size_on_disk_str]]

```python
size_on_disk_str()
```

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

(property) 以人类可读的字符串形式表示的 blob 文件大小总和。

示例：“42.2K”。

#### 参考文献[[huggingface_hub.CachedRepoInfo.refs]]

```python
refs()
```

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

（属性）`refs` 与修订数据结构之间的映射。

### CachedRevisionInfo[[huggingface_hub.CachedRevisionInfo]]

#### huggingface_hub.CachedRevisionInfo[[huggingface_hub.CachedRevisionInfo]]

```python
huggingface_hub.CachedRevisionInfo(commit_hash: str, snapshot_path: Path, size_on_disk: int, files: frozenset, refs: frozenset, last_modified: float)
```

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

**参数：**

commit_hash (`str`) : 修订版的哈希值（唯一）。示例：`"9338f7b671827df886678df2bdd7cc7b4f36dffd"`。

snapshot_path (`Path`)：`snapshots` 文件夹中修订版本目录的路径。它包含与 Hub 上仓库完全一致的树结构。

files : (`frozenset[CachedFileInfo]`): 描述快照中包含的所有文件的 [~CachedFileInfo](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.CachedFileInfo) 集合。

refs (`frozenset[str]`) : 指向此修订版本的 `refs` 集合。如果该修订版本没有 `refs`，则视为已分离。示例：`{"main", "2.4.0"}` 或 `{"refs/pr/1"}`。

size_on_disk (`int`) : 该修订版本通过符号链接引用的 blob 文件大小之和。

last_modified (`float`) : 该修订版本最近一次创建/修改的时间戳。

用于保存修订版本信息的冻结数据结构。

一个修订版本对应于`snapshots`文件夹中的一个文件夹，其内容具有与 Hub 上仓库完全相同的树结构，但仅包含符号链接。一个修订版本可以被一个或多个`refs`引用，也可以处于“分离”状态（没有 refs）。

> [!WARNING]
> `last_accessed` 无法在单个修订版本中正确确定，因为 blob 文件在多个修订版本之间共享。

> [!WARNING]
> `size_on_disk` 不一定等于所有文件大小之和，因为可能存在重复文件。此外，仅计算 blob 的大小，而不包括文件夹和符号链接（可忽略不计）的大小。

#### size_on_disk_str[[huggingface_hub.CachedRevisionInfo.size_on_disk_str]]

```python
size_on_disk_str()
```

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

(property) 以人类可读的字符串形式表示的 blob 文件大小总和。

示例：“42.2K”。

#### nb_files[[huggingface_hub.CachedRevisionInfo.nb_files]]

```python
nb_files()
```

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

(property) 该修订版本中的文件总数。

### CachedFileInfo[[huggingface_hub.CachedFileInfo]]

#### huggingface_hub.CachedFileInfo[[huggingface_hub.CachedFileInfo]]

```python
huggingface_hub.CachedFileInfo(file_name: str, file_path: Path, blob_path: Path, size_on_disk: int, blob_last_accessed: float, blob_last_modified: float)
```

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

**参数：**

file_name (`str`) : 文件的名称。示例：`config.json`。

file_path (`Path`)：`snapshots` 目录中文件的路径。该文件路径是一个符号链接，指向 `blobs` 文件夹中的一个 blob。

blob_path (`Path`) : `file_path` 所引用的仓库本地 blob 条目的路径。该 blob 条目本身可以是指向缓存级共享 blob 存储的符号链接。

size_on_disk (`int`) : 以字节为单位的 blob 文件大小。

blob_last_accessed (`float`) : 上次访问该 blob 文件的时间戳（来自任意版本）。

blob_last_modified (`float`) : Blob 文件上次修改/创建的时间戳。

用于保存单个缓存文件信息的冻结数据结构。

> [!WARNING]
> `blob_last_accessed` 和 `blob_last_modified` 的可靠性可能取决于您使用的操作系统。有关更多详细信息，请参阅 [python 文档](https://docs.python.org/3/library/os.html#os.stat_result)。

#### size_on_disk_str[[huggingface_hub.CachedFileInfo.size_on_disk_str]]

```python
size_on_disk_str()
```

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

(property) 以人类可读的字符串形式表示的 blob 文件大小。

示例：“42.2K”。

### CachedIncompleteFileInfo[[huggingface_hub.CachedIncompleteFileInfo]]

#### huggingface_hub.CachedIncompleteFileInfo[[huggingface_hub.CachedIncompleteFileInfo]]

```python
huggingface_hub.CachedIncompleteFileInfo(file_path: Path, size_on_disk: int)
```

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

**参数：**

file_path (`Path`)：`blobs` 文件夹中 `.incomplete` 文件的路径。

size_on_disk (`int`) : 部分下载文件的字节大小。

用于保存单个未完成下载信息的冻结数据结构。

中断的下载会留下 `<cache>/<repo>/blobs/<etag>.incomplete` 文件。这些文件不属于任何已提交的修订版本，因此会由 [scan_cache_dir()](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.scan_cache_dir) 单独列出。

### DeleteCacheStrategy[[huggingface_hub.DeleteCacheStrategy]]

#### huggingface_hub.DeleteCacheStrategy[[huggingface_hub.DeleteCacheStrategy]]

```python
huggingface_hub.DeleteCacheStrategy(expected_freed_size: int, blobs: frozenset, refs: frozenset, repos: frozenset, snapshots: frozenset, files: frozenset = frozenset(), cache_dir: pathlib.Path | None = None)
```

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

**参数：**

expected_freed_size (`float`) : 执行策略后预期释放的大小。

blobs (`frozenset[Path]`) : 要删除的 blob 文件路径集合。

refs (`frozenset[Path]`) : 要删除的参考文件路径集合。

repos (`frozenset[Path]`) : 要删除的整个仓库路径集合。

snapshots (`frozenset[Path]`) : 要删除的快照集合（符号链接目录）。

files (`frozenset[Path]`, *可选*) : 要删除的单个快照条目集合。仅当它们的 blob 列在 `blobs` 中时，才会被删除。

cache_dir (`Path` 或 `None`) : 计算该策略时所使用的缓存目录。用于收集被删除操作移除的仓库本地符号链接所引用的共享 blob。

用于删除缓存版本或文件的策略的冻结数据结构。

此对象不用于通过编程方式实例化，而是由 [delete_revisions()](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.HFCacheInfo.delete_revisions) 或 [delete_files()](/docs/huggingface_hub/v2.4.0/zh/package_reference/cache#huggingface_hub.HFCacheInfo.delete_files) 返回。有关使用示例，请参阅文档。

#### expected_freed_size_str[[huggingface_hub.DeleteCacheStrategy.expected_freed_size_str]]

```python
expected_freed_size_str()
```

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

(property) 预期释放的大小，以人类可读的字符串形式表示。

示例：“42.2K”。

## 异常

### CorruptedCacheException[[huggingface_hub.CorruptedCacheException]]

#### huggingface_hub.CorruptedCacheException[[huggingface_hub.CorruptedCacheException]]

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

Huggingface 缓存系统中任何意外结构的异常。