AI 模型缓存怎么管理？用 hf cache 查看占用并预览定向清理

管理 Hugging Face 模型缓存，可以用 hf cache ls 查看仓库和 revision，再用 hf cache rm --dry-run 预览指定目标，确认后清理。先明确缓存路径和目标版本，避免把正在运行或离线还需要的模型一并删掉。

本篇在 Windows、Python 3.11.15、huggingface_hub 1.26.1 中完成了独立演示缓存的下载、列表、预览和删除验证。只在练习目录的 hf-cache-demo 缓存上测试；没有扫描或修改用户默认缓存，也没有以演示文件大小预测真实模型可节省多少空间。官方文档核对日期为 2026 年 10 月 1 日。

先区分两种目录

官方缓存管理说明解释了 Hub 缓存中的 repos、snapshots、blobs 和 refs。多个提交可能引用同一份文件，所以不能把每个 snapshot 目录显示的大小简单相加当作可回收空间。

本篇演示只下载 config.json，因此形成一个不完整的模型缓存，足够练习缓存命令，不能据此离线运行模型。真实离线模型需要完整文件集合，清理之前先记录仍要保留的提交 SHA。

建立独立缓存，避免从默认目录练手

新建空练习目录并进入它，先安装官方客户端。以下为 Windows PowerShell 命令：

py -3.11 -m venv .venv-cache
.\.venv-cache\Scripts\python.exe -m pip install "huggingface_hub==1.26.1"
.\.venv-cache\Scripts\hf.exe cache ls --help
.\.venv-cache\Scripts\hf.exe cache rm --help

如果当前命令没有这些子命令或参数，先核对客户端版本和实际调用的 hf 路径，不把旧命令写法与本篇混用。官方 CLI 指南可作为入口。

保存下面代码为 prepare_cache.py，运行 .\.venv-cache\Scripts\python.exe -X utf8 prepare_cache.py。它只把一个已知小文件写入当前练习目录的 hf-cache-demo。输出的 demo_cache 是后续要核对的绝对路径。

from pathlib import Path
from huggingface_hub import snapshot_download

folder = Path('hf-cache-demo').resolve()
work = Path.cwd().resolve()
if folder.parent != work or folder.name != 'hf-cache-demo':
    raise RuntimeError('演示缓存必须是当前练习目录下的hf-cache-demo')
p = snapshot_download(
    repo_id='hf-internal-testing/tiny-random-bert',
    revision='f171d7baecaf37b5da5a3616d8833b9969753535',
    allow_patterns=['config.json'], cache_dir=folder, token=False,
)
print('demo_cache:', folder)
print('downloaded_config:', Path(p, 'config.json').is_file())

查看版本和占用，再预览删除目标

保持在相同练习目录。下面先确认实际路径，然后查看 revision，再预览删除整个演示仓库；–dry-run 不执行删除。

$demoCachePath = (Resolve-Path -LiteralPath .\hf-cache-demo).Path
Write-Output $demoCachePath
.\.venv-cache\Scripts\hf.exe cache ls --cache-dir $demoCachePath --revisions
.\.venv-cache\Scripts\hf.exe cache rm model/hf-internal-testing/tiny-random-bert --cache-dir $demoCachePath --dry-run

本次列表显示该仓库与提交 f171d7baecaf37b5da5a3616d8833b9969753535；只有 config.json，因此逻辑占用为 548 字节。预览显示将删除 1 个仓库、1 个 revision，预览后 config.json 仍存在。显示格式受终端和版本影响，判断重点是目标、revision、预估范围与文件是否仍在。

清理真实缓存时可以指定完整 revision SHA，而不是整个仓库 ID，预览影响再确认。仓库级删除会删除该缓存中的整个仓库；某个 revision 未被分支或标签引用，也不代表你自己的离线任务一定不再需要它。

确认后删除，并回读列表

确认 $demoCachePath 就是本次专用练习缓存，且预览目标仅为演示仓库后，再执行：

.\.venv-cache\Scripts\hf.exe cache rm model/hf-internal-testing/tiny-random-bert --cache-dir $demoCachePath
.\.venv-cache\Scripts\hf.exe cache ls --cache-dir $demoCachePath --revisions

第一条命令会要求确认；按提示明确确认后才清理。本次实际清理记录为 repos_deleted=1、revisions_deleted=1、freed=548.0，回读 JSON 列表为 []，演示 config.json 已不存在。验证时使用了同一绝对缓存路径；没有用清空目录的通用命令替代客户端管理。

删除后，再次运行 prepare_cache.py 会重新取得该文件，随后可以重复 ls 验证。离线机器无法依赖这一重新下载动作；如果还需要某个版本，先保留完整可运行目录和相应文件记录，再考虑清理。

为什么实际腾出的空间与目录大小可能不同

多个 revision 可共享 blobs，删除一个版本时仍被其他版本引用的数据可能保留；缓存工具按其管理规则计算，文件系统的实际分配空间也有自己的口径。预览范围是决策依据之一，不能把逻辑大小直接当成磁盘必定释放同样容量的承诺。

遇到问题先检查什么

• 列表空但磁盘仍满：先核对扫描的是不是下载实际使用的 cache_dir；local_dir 模型和其他软件缓存不在同一范围。
• 目标找不到：从 ls 输出确认 repo ID 或 revision，检查是否指向另一个缓存根目录。
• 删除被占用或权限失败：先停用引用该缓存的任务并保留报错；不要在失败后报告清理成功。
• 清理后离线加载失败：核对是否删掉仍需的文件。恢复来源是保留副本或重新下载；缓存管理不会自动重建一个完整离线模型。