# Windows 上的 Hugging Face 缓存，如何检查、清理和迁移

Hugging Face 下载可能通过多个模型版本、数据集和中断的下载占满 Windows 磁盘。先从下载这些内容的那个环境里的缓存工具入手。随意删除一个 `blobs` 文件夹可能破坏仍共享这些文件的版本，而删除整个 `HF_HOME` 还会移除认证状态。

## 找到应用实际使用的缓存

通常的 Hub 缓存是 `%USERPROFILE%\.cache\huggingface\hub`，但应用也可能使用其他账户、环境变量或显式指定的缓存目录。[环境变量参考](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables)区分了 `HF_HOME`、`HF_HUB_CACHE` 和 `HF_XET_CACHE`。`HF_HOME` 的范围比模型缓存更广，还包含保存的认证令牌。

打开该 AI 应用所用的终端或 Python 环境，检查它安装的命令：

```
hf cache --help
hf cache ls
hf cache ls --revisions
```

这些是清点命令。如果 `hf` 或某个子命令不可用，检查该环境中 `huggingface_hub` 的版本以及该工具支持的升级方式。升级全局 Python 环境，不一定会改变应用自带的 Python 环境。

如果 Hub 缓存配置在其他位置，用 `--cache-dir` 传入实际路径。默认位置的列表不能证明更大的自定义位置是空的。

## 先确认命令来自哪里、缓存存在哪里

在 PowerShell 中，这些检查显示正在调用哪个可执行文件，以及当前进程设置的缓存路径。这些命令不会读取认证令牌：

```powershell
Get-Command hf | Select-Object Source
$env:HF_HOME
$env:HF_HUB_CACHE
$env:HF_XET_CACHE
```

输出为空行表示该变量在当前 PowerShell 进程中未设置。这不能证明桌面启动器、虚拟环境或服务没有单独设置缓存路径。请将上述结果与执行下载的应用程序进行对照，尤其是在存在多个 Python 安装时。

如果缓存存到了其他盘，查看清单和预览删除时都要指定同一个路径：

```powershell
hf cache ls --cache-dir "D:\AI\huggingface\hub" --revisions
hf cache rm model/OWNER/REPOSITORY --cache-dir "D:\AI\huggingface\hub" --dry-run
```

将路径和仓库 ID 替换为在电脑上找到的值。如果已安装的命令拒绝某个选项，请停止并阅读其帮助信息。不要因语法错误就改为手动删除文件夹。在刚输入的路径下列出零个条目，也不能证明实际缓存为空。

## 理解为什么多个版本在 Windows 上可能占用更多空间

Hugging Face 的[缓存说明](https://huggingface.co/docs/huggingface_hub/guides/manage-cache)介绍了共享 blob 和版本快照。在不支持符号链接的 Windows 上，文件可能直接存放在快照中，因此同一文件可能在不同版本间多次占用空间。

如果电脑的管理策略允许，开发者模式可以启用更高效的符号链接行为。隐藏符号链接警告既不会启用符号链接，也不会追溯去重旧下载。不要仅仅为了消除那条消息而把整个 AI 应用以管理员身份运行。

还要区分 Hub 缓存和复制到应用自己文件夹中的模型文件。缓存命令不会清点电脑上的每一个 `.safetensors` 或 GGUF 文件。

## 避免重复计算共享模型文件

当前的缓存文档说明，共享不仅存在于不同修订版本之间，对于支持这种共享方式的 Xet 下载，也跨仓库共享。仓库报告的大小可能是逻辑大小，而缓存整体的物理大小会对共享文件只计一次。因此，将每个仓库的大小相加，可能高估删除这些仓库后能释放的空间。

当两个模型名称显示的大小相同时，这一点很重要。根据下载方式和文件系统，它们可能包含不同的权重、共享文件或各自独立的副本。应用兼容的缓存工具计算删除方案，而不是假设列出的每个 GB 都是独立的。

同一份文档还警告，较旧的客户端不一定都能正确管理较新的共享存储。如果缓存由比即将用于删除操作的工具更新的库创建，请在清理前检查应用程序支持的版本。保留原有环境，确需更换工具时先确认版本兼容且仍受维护；不要盲目更新应用程序锁定的依赖项。

Hub 缓存只是一个位置。Xet 数据、数据集处理输出以及显式下载到本地模型目录的文件，可能位于其他地方。如果 Hub 预览只占磁盘使用量的一小部分，请查明那些其他占用来源，而不是把 Hub 的删除范围扩大。

## 预览删除一个已知仓库

停止使用目标缓存的下载、训练和推理。确认一个不再需要的仓库，并确认如果以后需要恢复，它的确切版本仍可获取。受限访问、上游文件被删除和离线使用都可能让原本能够下载的模型变得难以替换。

当前的[CLI 指南](https://huggingface.co/docs/huggingface_hub/guides/cli)支持预览：

```
hf cache rm model/OWNER/REPOSITORY --dry-run
```

把 `model/OWNER/REPOSITORY` 替换为列表中确切的 ID。阅读受影响的版本和大小。只有在这项检查之后，才运行同一条不含 `--dry-run` 的命令并回答它的确认提示。这是删除，不是移到回收站。

要清理未被引用的缓存内容，单独预览已安装工具的计划：

```
hf cache prune --dry-run
```

缓存中未被分支或标签引用的版本，仍可能被指定了提交版本的脚本使用。在接受清理之前检查那些项目。不要用笼统的确认标志绕过这项检查。

## 用真实项目检验清理方案

缓存中的分支或标签引用并不能完整反映项目所需内容。脚本可能指定了不再作为缓存分支最新提交的精确修订哈希。确认清理方案前，请在活跃项目的配置中搜索模型 ID 和锁定修订版本，并为离线或可复现工作所需的任何内容保留副本。

当前 CLI 文档还说明，清理行为会包含被中断的 `.incomplete` 下载。在查看方案前，请先完成或停止发起该下载的进程。被中断的下载留下的部分文件，与另一个正在运行的进程仍在写入的文件不同。

完成一次经审核的删除后，用同一个缓存路径重新查看清单，并比较同一盘上的可用空间。然后运行一个能代表日常用途的小任务。如果它立即再次下载大型模型，说明该工作负载仍需要被删除的数据；重复清理只会用下载时间换取磁盘空间。

如需移动缓存，除非有意迁移身份验证状态，否则不要将其纳入操作。只把 `HF_HUB_CACHE` 指向其他盘，比移动整个 `HF_HOME` 的影响范围更小。更改前记录旧值，重启所属应用，并检查其下一次实际下载出现在哪里。如果应用仍使用旧目录，请先调查其显式缓存路径，再删除任一副本。

## 迁移后续下载而不混淆位置

要把 Hub 缓存放到另一个盘，为使用缓存的应用配置 `HF_HUB_CACHE`，然后完全重启该应用。环境变更必须在库导入之前生效。应用专用的 `cache_dir` 仍可能指向别处，所以要验证下一次下载的实际目标位置。

更改变量不会移动旧文件。在新位置经过测试并且需要保留且只有本地副本的内容得到保留之前，保留旧缓存。如果旧目录仍然很大，用缓存工具及其路径明确检查它。

清理后，测试一个重要工作负载，并比较同一宗卷上的可用空间。对于 Ollama 单独的模型存储，使用 [Ollama 迁移指南](/zh/windows/blog/move-ollama-models-windows)。围绕 AI 的共享品牌并不意味着这些工具共享一个缓存或一条安全的删除命令。


Canonical: https://mole.fit/zh/windows/blog/huggingface-cache-windows