如何安全清理 Hugging Face 缓存

删除任何内容前，使用当前 hf cache 命令检查缓存。用 hf cache rm 删除已知仓库或修订版；对不再被引用的修订版使用 hf cache prune。不要把缓存目录视为一堆独立文件——多个快照可以共享同一批数据块。

为什么手动删除看似简单，实则危险

Hub 缓存旨在避免重复下载相同内容。在 hub 缓存下，一个仓库通常包含 refs、snapshots 和 blobs。快照把修订版呈现为可用目录，而其文件可能链接回 blobs 中的共享内容。因此，两个修订版看似各自包含同一个大型权重文件，但不一定占用两份完整空间。

该布局效率很高，但这意味着“删除看起来最大的文件夹”并不是好规则。手动删除一个仍在使用的数据块可能破坏多个快照。删除一个快照释放的空间可能远小于其表面大小，因为其他修订版仍引用相同内容。

测量你实际使用的缓存

首先找到正在使用的Hugging Face 缓存目录。HF_HOME、HF_HUB_CACHE 和相关变量可能已将其移出默认位置。然后通过 CLI 查看缓存：

hf cache ls
hf cache ls --revisions

第一个命令列出缓存仓库；第二个显示各个修订版。列表很长时，请使用当前 CLI 提供的筛选或排序功能。你需要决定的并非简单的“哪些内容旧了？”，而是“哪个确切仓库或修订版可以重新获取，哪个仍支撑当前工作？”

有意删除某个仓库或修订版

如果你知道整个缓存仓库都可以丢弃，请将其缓存标识符传给 hf cache rm。当前文档使用如下仓库标识符：

hf cache rm model/gpt2

若要进行更精细的清理，请选择 hf cache ls --revisions 报告的特定修订标识符。仔细阅读预览和确认内容。CLI 可以计算哪些内容会失去引用；文件系统选择无法解释这些关系。

修剪已分离的修订版，而不是工作集

hf cache prune 以不再被引用的修订版为目标。它适合清理分支或标签引用变化后留下的旧修订数据，但并不承诺每个你已忘记的旧模型都会消失。请在检查拟删除内容后运行它，不要把它当作每次会话结束时的自动反射动作。

hf cache prune

如果缓存由多个用户、容器或计划任务管理，请先停止正在进行的下载。即使缓存机制支持恢复，在另一个进程正在生成快照时执行清理也会造成不必要的歧义。

验证保留的内容

1. 再次运行 hf cache ls 并记录新大小。
2. 对你关心且要保留的仓库使用 hf cache verify <repo>。
3. 启动一个会加载所保留模型的真实工作流程。
4. 留意新的下载：悄然重新获取的模型此前并未完整保存在本地。

重新下载并不总是失败——缓存就是缓存——但当你离线工作、固定特定修订版，或依赖可能消失的上游文件时，它会很重要。

缓存清理与长期保留解决不同问题

Hub 缓存针对重复使用和重新获取进行了优化。它不是用于记录模型、分词器、配置或适配器为何应当归为一组的精选目录。在清理难以重现的修订版前，请确定使用它所需的完整模型系列。对于 PEFT 适配器，这可能包括兼容的基础模型和配置；对于训练结果，可能不只是权重。

Tensor Archive 属于这条界线中需要深思熟虑的一侧。保留一个已完成的本地模型系列，验证归档并证实可以精确恢复。然后，缓存可以重新成为可丢弃的基础设施，而不是意外形成的博物馆。

相关指南

如果当前缓存只是位于错误的硬盘上，请按照单独指南更改 Hugging Face 缓存目录。如果模型库横跨多个运行时，请在判断哪些只是可替换的缓存状态前使用保留清单。