💾 如何更改 ModelScope 的模型下载缓存位置？Windows 完整指南（2025）
适用人群 ：使用 Windows 系统下载大模型的开发者、科研人员、AI 爱好者
解决痛点 ：避免模型默认下载到 C 盘，导致磁盘空间不足
支持方式：命令行、SDK、Git 全覆盖，含自定义路径实操
🚨 为什么需要改缓存位置？
ModelScope 默认将模型缓存到用户目录下：
C:\Users\你的用户名\.modelscope\
而像 Qwen3、百川、ChatGLM 等大模型动辄几十 GB，极易占满 C 盘空间，影响系统运行。
✅ 解决方案：通过以下三种方式，把模型下载到 D 盘或其他大容量磁盘！
🔧 第一步：安装 ModelScope SDK
无论使用哪种方法，先安装官方工具包：
pip install modelscope
💡 推荐使用本地虚拟环境（.venv 如 poetry /virtualenv /pipenv /uv /hatch 或 conda 等）
✅ 方法一：设置全局缓存路径（推荐！一劳永逸）
方式 1.1：通过环境变量 MODELSCOPE_CACHE（永久生效）
这是最推荐的方式，一次设置，永久有效。
步骤如下：
-
打开 控制面板 > 系统和安全 > 系统 > 高级系统设置
-
点击 环境变量
-
在"用户变量"区域点击 新建
-
变量名 ：
MODELSCOPE_CACHEMODELSCOPE_CACHE -
变量值 ：
D:\modelscope_cache（可自定义路径）D:\modelscope_cache
-
-
点击确定保存
-
重启终端或 IDE（如 PyCharm、VS Code、Jupyter）
✅ 效果：所有后续通过
modelscope download或 SDK 下载的模型都会自动保存到该目录。
📁 创建目标文件夹（建议）
手动创建：
D:\modelscope_cache避免路径不存在导致报错。
方式 1.2：在代码中临时设置（适合调试）
如果你不想改系统设置，可以在 Python 脚本开头设置：
# python
import os
os.environ['MODELSCOPE_CACHE'] = 'D:\\modelscope_cache' # 注意双反斜杠
from modelscope import snapshot_download
model_dir = snapshot_download('Qwen/Qwen3-Coder-480B-A35B-Instruct')
print(f"模型已下载至：{model_dir}")⚠️ 必须在
import modelscope之前设置！否则无效！
💻 方法二：命令行下载 + 指定本地目录（灵活快捷）
使用 ModelScope 提供的 CLI 工具，支持直接指定下载路径。
下载整个模型到指定目录
modelscope download --model Qwen/Qwen3-Coder-480B-A35B-Instruct --local_dir D:\models\qwen3--local_dir：指定本地保存路径- 不依赖环境变量，适合一次性任务
下载单个文件（如 README.md）
modelscope download --model Qwen/Qwen3-Coder-480B-A35B-Instruct README.md --local_dir ./docs📌 场景：只想看文档、配置文件，无需下载完整模型。
批量下载多个小文件
modelscope download --model Qwen/Qwen3-Coder-480B-A35B-Instruct config.json tokenizer.json --local_dir D:\models\qwen_config
modelscope 官方使用说明
🧩 方法三：SDK 编程下载（项目集成首选）
适合写入训练/推理脚本中，支持更多参数控制。
使用 cache_dir 参数直接指定路径（推荐）
# python
from modelscope import snapshot_download
model_dir = snapshot_download(
'Qwen/Qwen3-Coder-480B-A35B-Instruct',
cache_dir='D:\\models\\qwen3' # 直接指定路径
)
print(f"模型路径：{model_dir}")✅ 优势：
- 不依赖环境变量
- 可为不同模型设置不同路径
- 支持
revision、ignore_file_pattern等高级参数
常用参数说明
| 参数 | 说明 |
|---|---|
cache_dir |
自定义缓存路径（优先级最高） |
revision='v1.0.0' |
指定模型版本 |
ignore_file_pattern=['*.bin'] |
忽略某些大文件（如仅下载结构） |
local_files_only=True |
仅使用本地缓存（离线模式） |
🌐 方法四：Git 下载（适合高级用户）
适用于需要版本控制或 CI/CD 的场景。
完整下载（含 LFS 大文件）
git lfs install
git clone https://www.modelscope.cn/Qwen/Qwen3-Coder-480B-A35B-Instruct.git D:\models\qwen3⚠️ 需提前安装 Git LFS
跳过大文件下载（快速获取结构）
GIT_LFS_SKIP_SMUDGE=1 git clone https://www.modelscope.cn/Qwen/Qwen3-Coder-480B-A35B-Instruct.git D:\models\qwen3后续按需拉取：
cd D:\models\qwen3
git lfs pull --include="model.bin"🔁 三种方式对比（Windows 用户专属建议）
| 方法 | 是否支持自定义路径 | 是否需改系统 | 适合场景 |
|---|---|---|---|
MODELSCOPE_CACHE环境变量 |
✅ 是（全局） | ✅ 是（一次） | 所有下载统一管理 |
--local_dir命令行参数 |
✅ 是（单次） | ❌ 否 | 快速下载单文件 |
cache_dirSDK 参数 |
✅ 是（灵活） | ❌ 否 | 项目开发、自动化 |
Git +clone到指定路径 |
✅ 是 | ❌ 否 | 版本管理、CI/CD |
🧹 清理旧缓存（释放 C 盘空间）
删除默认缓存目录以释放空间：
C:\Users\你的用户名\.modelscope\💡 建议迁移后删除，避免重复下载。
✅ 最佳实践建议（Windows 用户必看）
-
首选方案 ：
设置
MODELSCOPE_CACHE = D:\modelscope_cache，一劳永逸。 -
项目专用路径 ：
使用
snapshot_download(cache_dir=...)为每个项目独立管理模型。 -
避免 C 盘爆满 ：
不要让
.modelscope文件夹留在 C 盘！ -
调试技巧 ：
下载后打印
model_dir，确认路径是否正确：# python print(f"模型路径：{model_dir}") -
离线部署 ：
使用
local_files_only=True防止意外联网。
📚 参考文档
📝 总结：一句话记住怎么改缓存位置
✅ Windows 用户只需两步：
- 设置环境变量：
MODELSCOPE_CACHE = D:\your_path- 重启终端，开始下载
或者在代码中指定路径，使用：
snapshot_download(..., cache_dir='D:\\models')
📌 延伸阅读
Hugging Face 模型下载缓存位置更改：
【笔记】解决部署国产AI Agent 开源项目 MiniMax-M1时 Hugging Face 模型下载缓存占满 C 盘问题：更改缓存位置全流程_minimax agent本地部署-CSDN博客