网站导航
> 技术文档 > Windows 如何更改 ModelScope 的模型下载缓存位置？

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

网友: 技术文档 2025-07-26 20:27:09

💾 如何更改 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（永久生效）

这是最推荐的方式，一次设置，永久有效 。

步骤如下：
  1. 打开 控制面板 > 系统和安全 > 系统 > 高级系统设置
  2. 点击 环境变量
  3. 在“用户变量”区域点击 新建
    • 变量名 ：MODELSCOPE_CACHE 
      MODELSCOPE_CACHE
    • 变量值 ：D:\\modelscope_cache（可自定义路径） 
      D:\\modelscope_cache
  4. 点击确定保存
  5. 重启终端或 IDE（如 PyCharm、VS Code、Jupyter）

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

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

手动创建：

D:\\modelscope_cache

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

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

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

# pythonimport osos.environ[\'MODELSCOPE_CACHE\'] = \'D:\\\\modelscope_cache\' # 注意双反斜杠from modelscope import snapshot_downloadmodel_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 参数直接指定路径（推荐）

# 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 installgit 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\\qwen3git lfs pull --include=\"model.bin\"

🔁 三种方式对比（Windows 用户专属建议）

方法

是否支持自定义路径

是否需改系统

适合场景

MODELSCOPE_CACHE环境变量

✅ 是（全局）

✅ 是（一次）

所有下载统一管理

--local_dir命令行参数

✅ 是（单次）

❌ 否

快速下载单文件

cache_dirSDK 参数

✅ 是（灵活）

❌ 否

项目开发、自动化

Git +clone到指定路径

✅ 是

❌ 否

版本管理、CI/CD

 

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

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

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

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

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

  1. 首选方案 ：
    设置 MODELSCOPE_CACHE = D:\\modelscope_cache，一劳永逸。

  2. 项目专用路径 ：
    使用 snapshot_download(cache_dir=...) 为每个项目独立管理模型。

  3. 避免 C 盘爆满 ：
    不要让 .modelscope 文件夹留在 C 盘！

  4. 调试技巧 ：
    下载后打印 model_dir，确认路径是否正确：

    # pythonprint(f\"模型路径：{model_dir}\")

  5. 离线部署 ：
    使用 local_files_only=True 防止意外联网。

📚 参考文档

  • ModelScope 官网
  • ModelScope CLI 文档
  • Git LFS 安装指南

📝 总结：一句话记住怎么改缓存位置

✅ Windows 用户只需两步 ：

  1. 设置环境变量：MODELSCOPE_CACHE = D:\\your_path
  2. 重启终端，开始下载

或者在代码中指定路径，使用：snapshot_download(..., cache_dir=\'D:\\\\models\')

📌 延伸阅读

Hugging Face 模型下载缓存位置更改：

【笔记】解决部署国产AI Agent 开源项目 MiniMax-M1时 Hugging Face 模型下载缓存占满 C 盘问题：更改缓存位置全流程_minimax agent本地部署-CSDN博客

网络标签：

相关问题