Hub Python Library documentation
缓存系统参考
缓存系统参考
缓存系统在 v0.8.0 中进行了更新，成为依赖 Hub 的各库共享的核心缓存系统。有关 HF 缓存机制的详细说明，请参阅缓存系统指南。
辅助函数
try_to_load_from_cache
huggingface_hub.try_to_load_from_cache
< source >( repo_id: strfilename: strcache_dir: str | pathlib.Path | None = Nonerevision: str | None = Nonerepo_type: str | None = None ) → Optional[str] or _CACHED_NO_EXIST
参数
- 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。
探索缓存，如果找到，则返回给定修订版本的最新缓存文件。
如果文件未缓存，此函数不会引发任何异常。
cached_assets_path
huggingface_hub.cached_assets_path
< source >( library_name: strnamespace: str = 'default'subfolder: str = 'default'assets_dir: str | pathlib.Path | None = None )
返回一个用于缓存任意文件的文件夹路径。
huggingface_hub 提供了一个用于存储资产的规范文件夹路径。这是下游库集成缓存的推荐方式，因为它可以利用内置工具来正确扫描和删除缓存。
系统区分了从 Hub 缓存的文件和资产。来自 Hub 的文件以感知 git 的方式缓存，并完全由 huggingface_hub 管理。请参阅 相关文档。下游库缓存的所有其他文件均被视为“资产”（从外部来源下载的文件、从 .tar 归档中提取的文件、为训练而预处理的文件等）。
一旦生成了文件夹路径，即可保证该路径存在且为一个目录。
该路径基于三个层级的深度：库名称、命名空间和子文件夹。这三个层级在允许 huggingface_hub 在扫描或删除资产缓存的部分内容时预期文件夹存在的同时，提供了灵活性。在库内部，预期所有命名空间共享相同的子文件夹名称子集，但这并非强制规则。下游库因此可以完全控制其缓存内采用的文件结构。命名空间和子文件夹是可选的（默认使用 "default/" 子文件夹），但库名称是必需的，因为我们希望每个下游库都管理自己的缓存。
预期树：
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/
└── (...)示例：
>>> 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
< source >( cache_dir: str | pathlib.Path | None = None )
扫描整个 HF 缓存系统并返回一个 ~HFCacheInfo 结构。
使用 scan_cache_dir 以编程方式扫描您的缓存系统。缓存将按仓库逐个扫描。如果某个仓库已损坏，内部会抛出 ~CorruptedCacheException，但会被捕获并返回在 ~HFCacheInfo 结构中。只有有效的仓库才会获得完整的报告。
>>> 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 命令行打印详细报告：
> 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.
引发：
CacheNotFound如果缓存目录不存在。
ValueError如果缓存目录是一个文件而不是目录。
返回：一个 ~HFCacheInfo 对象。
数据结构
所有结构均由 scan_cache_dir() 构建并返回，且不可变。
HFCacheInfo
class huggingface_hub.HFCacheInfo
< source >( size_on_disk: intrepos: frozensetincomplete_files: frozensetwarnings: listcache_dir: pathlib.Path | None = None )
参数
- size_on_disk (
int) — 缓存系统的物理大小（以字节为单位）。跨仓库共享的 blob 仅计算一次，且包含不再被任何仓库引用的仅存储共享 blob。该值可能小于各仓库大小之和。 - repos (
frozenset[CachedRepoInfo]) — 在扫描缓存系统时找到的所有有效缓存仓库的 ~CachedRepoInfo 集合。 - incomplete_files (
frozenset[CachedIncompleteFileInfo]) — 一组 ~CachedIncompleteFileInfo，用于描述由中断的下载遗留下来的孤立*.incomplete文件。 - warnings (
list[CorruptedCacheException]) — 扫描缓存期间发生的 ~CorruptedCacheException 列表。 捕获这些异常以便扫描能够继续。损坏的仓库将被跳过，不参与扫描。 - cache_dir (
Path或None) — 已扫描的缓存目录。
用于保存整个缓存系统信息的冻结数据结构。
此数据结构由 scan_cache_dir() 返回，且不可变。
size_on_disk仅统计 blob，并会跳过损坏的仓库。它是一个物理大小：与CachedRepoInfo.size_on_disk不同（后者会将共享 blob 计入每个引用它的仓库），此处共享的 blob 只计算一次。
准备删除单个缓存文件的策略。
仅删除快照条目。只有当没有其他缓存文件引用某个 blob 时，该 blob 才会被删除，因此与其他修订版本共享的 blob 会被保留。即使快照最终变为空，引用和快照目录也会被保留。若要删除整个修订版本或仓库，请使用 delete_revisions()。
示例：
>>> 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()准备删除一个或多个本地缓存的修订版本的策略。
输入修订版本可以是任意修订版本哈希值。如果在本地缓存中未找到修订版本哈希值，则会抛出警告，但不会引发错误。由于哈希值在不同仓库之间是唯一的，因此修订版本可以来自不同的缓存仓库，
示例：
>>> 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()>>> from huggingface_hub import scan_cache_dir
>>> scan_cache_dir().delete_revisions(
... "81fd1d6e7847c99f5862c9fb81387956d99ec7aa",
... "e2983b237dccf3ab4937c97fa717319a9ca1a96d",
... "6c0e6080953db56375760c0471a8c5f2929baf11",
... ).execute()
delete_revisions返回一个需要执行的 DeleteCacheStrategy 对象。DeleteCacheStrategy 本身不应被修改，但允许在实际执行删除之前进行试运行。
export_as_table
< source >( verbosity: int = 0 ) → str
从 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”。
示例：
>>> 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/150ebc2c4b72291e770f58e6057481c8d2ed331aCachedRepoInfo
类 huggingface_hub.CachedRepoInfo
< source >( repo_id: strrepo_type: typing.Literal['model', 'dataset', 'space', 'kernel']repo_path: Pathsize_on_disk: intnb_files: intrevisions: frozensetlast_accessed: floatlast_modified: float )
参数
- repo_id (
str) — Hub 上仓库的仓库 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 集合，描述仓库中缓存的所有修订版本。 - last_accessed (
float) — 仓库中 blob 文件最后一次被访问的时间戳。 - last_modified (
float) — 仓库中 blob 文件最后一次修改/创建的时间戳。
用于保存缓存仓库信息的冻结数据结构。
size_on_disk不一定等于所有修订版本大小的总和，因为存在重复文件。此外，仅计算 blob 的大小，而不包括（可忽略不计的）文件夹和符号链接的大小。
last_accessed和last_modified的可靠性可能取决于您使用的操作系统。 有关更多详细信息，请参阅 python 文档。
（属性）refs 与修订数据结构之间的映射。
CachedRevisionInfo
类 huggingface_hub.CachedRevisionInfo
< source >( commit_hash: strsnapshot_path: Pathsize_on_disk: intfiles: frozensetrefs: frozensetlast_modified: float )
参数
- commit_hash (
str) — 修订版本的哈希值（唯一）。 示例："9338f7b671827df886678df2bdd7cc7b4f36dffd"。 - snapshot_path (
Path) —snapshots文件夹中修订版本目录的路径。它包含与 Hub 上仓库完全一致的树结构。 - files — (
frozenset[CachedFileInfo]): 一个 ~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）。
last_accessed无法在单个修订版本中正确确定，因为 blob 文件在多个修订版本之间共享。
size_on_disk不一定等于所有文件大小之和，因为可能存在重复文件。此外，仅计算 blob 的大小，而不包括文件夹和符号链接（可忽略不计）的大小。
(property) 该修订版本中的文件总数。
CachedFileInfo
类 huggingface_hub.CachedFileInfo
< source >( file_name: strfile_path: Pathblob_path: Pathsize_on_disk: intblob_last_accessed: floatblob_last_modified: float )
参数
- 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 文件最后一次修改/创建的时间戳。
用于保存单个缓存文件信息的冻结数据结构。
blob_last_accessed和blob_last_modified的可靠性可能取决于您使用的操作系统。有关更多详细信息，请参阅 python 文档。
CachedIncompleteFileInfo
类 huggingface_hub.CachedIncompleteFileInfo
< source >( file_path: Pathsize_on_disk: int )
用于保存单个未完成下载信息的冻结数据结构。
中断的下载会留下 <cache>/<repo>/blobs/<etag>.incomplete 文件。
这些文件不属于任何已提交的修订版本，因此会由 scan_cache_dir() 单独列出。
DeleteCacheStrategy
类 huggingface_hub.DeleteCacheStrategy
< source >( expected_freed_size: intblobs: frozensetrefs: frozensetrepos: frozensetsnapshots: frozensetfiles: frozenset = frozenset()cache_dir: pathlib.Path | None = None )
参数
- 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() 或 delete_files() 返回。有关使用示例，请参阅文档。
异常
CorruptedCacheException
Huggingface 缓存系统中任何意外结构的异常。