当前位置：首页 > news >正文

Windows 如何更改 ModelScope 的模型下载缓存位置？

news 2025/7/27 1:06:07

💾 如何更改 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_CACHE
```
MODELSCOPE_CACHE
```
- 变量值 ：D:\modelscope_cache（可自定义路径）
```
D:\modelscope_cache
```
点击确定保存
重启终端或 IDE（如 PyCharm、VS Code、Jupyter）

✅ 效果：所有后续通过 modelscope download 或 SDK 下载的模型都会自动保存到该目录。

📁 创建目标文件夹（建议）

手动创建：

D:\modelscope_cache

避免路径不存在导致报错。

方式 1.2：在代码中临时设置（适合调试）

如果你不想改系统设置，可以在 Python 脚本开头设置：

#  pythonimport 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

🧩 方法三：SDK 编程下载（项目集成首选）

适合写入训练/推理脚本中，支持更多参数控制。

使用 `cache_dir` 参数直接指定路径（推荐）

# pythonfrom modelscope import snapshot_downloadmodel_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_dir`SDK 参数	✅ 是（灵活）	❌ 否	项目开发、自动化
Git +`clone`到指定路径	✅ 是	❌ 否	版本管理、CI/CD

🧹 清理旧缓存（释放 C 盘空间）

删除默认缓存目录以释放空间：

C:\Users\你的用户名\.modelscope\

💡 建议迁移后删除，避免重复下载。

✅ 最佳实践建议（Windows 用户必看）

首选方案 ：
设置 MODELSCOPE_CACHE = D:\modelscope_cache，一劳永逸。
项目专用路径 ：
使用 snapshot_download(cache_dir=...) 为每个项目独立管理模型。
避免 C 盘爆满 ：
不要让 .modelscope 文件夹留在 C 盘！
调试技巧 ：
下载后打印 model_dir，确认路径是否正确：
```
#  pythonprint(f"模型路径：{model_dir}")
```
离线部署 ：
使用 local_files_only=True 防止意外联网。