【笔记】解决部署国产AI Agent 开源项目 MiniMax-M1时 Hugging Face 模型下载缓存占满 C 盘问题：更改缓存位置全流程
一、发生背景
MiniMax-AI/MiniMax-M1：MiniMax-M1，世界上第一个开放权重、大规模的混合注意力推理模型。
在本地部署 MiniMax-M1 开源项目时，执行 huggingface-cli download MiniMaxAI/MiniMax-M1-80k 下载模型的命令后，C 盘空间持续被占用，甚至出现 “磁盘空间不足” 提示。查看发现 C:\Users\用户名\.cache\huggingface 文件夹占用超 400GB，严重挤压系统盘空间，急需将缓存迁移到空闲的磁盘分区（ 例如我的 G 盘）。
二、原因分析
Hugging Face 工具（如 huggingface-cli、Transformers 库 ）默认会将模型、缓存文件存储在系统盘（C 盘）的用户缓存目录（C:\Users\用户名\.cache\huggingface ）。当下载大模型（如 MiniMax-M1 相关模型）时，大量模型权重文件、中间缓存会不断写入该目录，若未及时干预，极易占满 C 盘，导致系统运行卡顿甚至报错。
三、排查与解决过程
（一）确认缓存路径与占用
- 定位缓存文件夹：通过文件资源管理器找到
C:\Users\love\.cache\huggingface，查看属性确认其占用空间（超 400GB ），明确空间爆满的 “罪魁祸首”。 - 关联系统存储统计：在 Windows 设置 “系统> 存储 > 其他” 中，看到
C:\Users\love\.cache占用大量空间，进一步验证缓存位置与问题关联。
（二）规划新缓存路径
在空闲的磁盘（比如 G 盘）创建专门的缓存文件夹 G:\huggingface_cache，用于存放 Hugging Face 相关缓存，为后续迁移做准备。
（三）设置环境变量（关键步骤）
Hugging Face 通过环境变量控制缓存路径，需设置以下核心变量（以 Windows 系统为例 ）：
- 打开系统环境变量设置：右键 “此电脑”→“属性”→“高级系统设置”→“环境变量”。
- 新建系统变量：
HUGGINGFACE_HUB_CACHE：变量名填HUGGINGFACE_HUB_CACHE，变量值填G:\huggingface_cache，控制huggingface-cli等工具的通用缓存路径。
变量名：HUGGINGFACE_HUB_CACHE
变量值：G:\huggingface_cache
HF_HOME：变量名填HF_HOME，变量值填G:\huggingface_cache，作为 Hugging Face 缓存的 “根目录”，增强路径控制优先级。
变量名：HF_HOME
变量值：G:\huggingface_cache
- 保存生效：点击 “确定” 保存变量，关闭环境变量设置窗口。
（四）验证环境变量与缓存迁移
- 重启终端 / 环境：关闭当前 Conda 环境（
MiniMax-M1）终端，重新打开并激活环境，执行echo %HUGGINGFACE_HUB_CACHE%和echo %HF_HOME%，输出G:\huggingface_cache则变量设置生效。 - 测试缓存迁移：重新执行
huggingface-cli download相关命令（如下载小模型测试 ），查看G:\huggingface_cache目录是否生成新缓存文件。确认新缓存正常写入 G 盘后，删除 C 盘原.cache\huggingface目录，释放系统盘空间。
huggingface-cli download MiniMaxAI/MiniMax-M1-80k 
可以看到缓存位置更改成功了。
四、总结与注意事项
（一）流程回顾
- 发现问题：C 盘因 Hugging Face 缓存爆满，定位到
C:\Users\用户名\.cache\huggingface路径。 - 解决思路：通过设置系统环境变量，将缓存路径重定向到空闲磁盘（G 盘 ）。
- 验证收尾：重启终端确认变量生效，测试下载验证新缓存路径，清理旧缓存释放空间。
（二）注意事项
- 环境变量生效时机：修改系统环境变量后，需重启终端 / 应用（如 Conda 环境 ），确保变量重新加载。
- 文件夹权限：新缓存路径（
G:\huggingface_cache）需保证当前用户有 “写入” 权限，避免因权限不足导致缓存写入失败。 - 工具特殊配置：若使用 vLLM、SGLang 等推理框架，需额外检查框架自身缓存路径设置，确保全流程缓存迁移到位。
- 原有下载失效问题：更改缓存位置，会导致原有已下载的模型不可用，所以建议完整迁移或者按实际情况重新下载。
- 部署顺序：建议有预见性地先更改 Hugging Face 的缓存位置，避免部署受阻。
通过以上步骤，成功解决 Hugging Face 缓存占满 C 盘问题，既释放系统盘空间，又规范了缓存存储位置，为后续大模型本地部署与运行扫清存储障碍 。
下一篇预告：
关于模型下载失败的恢复下载或修复方法