从ModelScope上下载模型

一、安装

pip install -U modelscope
#（可选）按领域安装：modelscope[nlp] / [cv] / [audio] / [multi-modal]

官方 README 也推荐这样装。

二、命令行下载（CLI）

适合“拉整库/拉单个文件到指定目录”，简单直观。

1.	拉整库到默认缓存（~/.cache/modelscope）

modelscope download --model Qwen/Qwen3-Omni-30B-A3B-Instruct

示例模型来自 Qwen 官方仓库家族。
2. 拉整库到指定目录

modelscope download --model Qwen/Qwen3-Omni-30B-A3B-Instruct --local_dir ./models/qwen3-omni-30b

（多家模型 README 也给出同样的 CLI 用法。）
3. 只拉某个文件到目标目录（你给的例子完全正确）

modelscope download --model Qwen/Qwen3-Omni-30B-A3B-Instruct README.md --local_dir ./dir

4.	下载数据集而非模型（命令相同，参数换成 –dataset）

modelscope download --dataset open-thoughts/OpenThoughts-114k --local_dir ./data/OpenThoughts-114k

（社区 issue 中也用的这个法子。）

参考：ModelScope 文档“Download Model”页（含更多 CLI 选项与 Git 下载指引）。 

三、Python SDK 下载（snapshot_download）

适合写脚本、可控缓存目录、后续程序直接引用。

最常用 3 行：

from modelscope import snapshot_download
model_dir = snapshot_download('Qwen/Qwen3-Omni-30B-A3B-Instruct', cache_dir='./models/qwen3-omni-30b')
print(model_dir)  # 返回实际落盘目录

（ModelScope 官方/生态文档都用这个函数示例。）

访问私有/受限模型（SDK）

from modelscope.hub.api import HubApi
api = HubApi()
api.login('YOUR_MODELSCOPE_TOKEN')     # 个人中心-Access Token
from modelscope import snapshot_download
snapshot_download('your-org/private-model', cache_dir='./models/private')

（HubApi.login 用法可见官方/社区讨论。）

四、私有模型 & Git 下载（另一种姿势）

有些场景你可能更偏爱 Git（尤其想精确控版本 / 分支）：
1. 在 ModelScope 网站登录 → 个人中心 → Access Token，复制 Git Token。 
2. 装好 Git LFS，然后：

git lfs install

# 用 token 直连（示例，不要泄露 token）
git clone https://<YOUR_TOKEN>@www.modelscope.cn/api/v1/models/Qwen/Qwen3-Omni-30B-A3B-Instruct.git

（ModelScope 官方下载页也写了 Git 方式。）

五、缓存与目录管理（强烈推荐）
• 默认缓存：~/.cache/modelscope。
• 改缓存位置（系统级）：
• Linux/macOS:

export MODELSCOPE_CACHE=/data/ms-cache

•	Windows（PowerShell）：

setx MODELSCOPE_CACHE "D:\ms-cache"

（官方 FAQ 推荐用 MODELSCOPE_CACHE 或在 SDK 里用 cache_dir。）

六、离线/内网环境搬运（稳定可复用）

在有网机器下载好后，打包带走：

# 有网机
modelscope download --model Qwen/Qwen3-Omni-30B-A3B-Instruct --local_dir ./models/qwen3-omni-30b
tar -czf qwen3-omni-30b.tgz -C ./models qwen3-omni-30b

# 传到离线机（示例）
scp qwen3-omni-30b.tgz user@offline-host:/data/models/
ssh user@offline-host
mkdir -p /data/models && tar -xzf /data/models/qwen3-omni-30b.tgz -C /data/models

离线加载时，直接把本地路径喂给你的框架/推理服务（比如 Transformers/VLLM/自研服务），无需再联网；SDK 脚本也用 cache_dir=‘/data/models/qwen3-omni-30b’ 即可。

七、常见问题（踩坑提示）
• 拉大文件校验失败 / 中断：网络抖动时可能出现完整性校验失败，常见解决是重试（必要时换网络/代理）。 
• 权限 401/403：确认 Access Token 是否有效；私有仓库需要先 HubApi().login(token)（SDK）或使用 Git Token（Git 方式）。 
• 空间不够：提前把 MODELSCOPE_CACHE 指到大盘，或 SDK 里用 cache_dir 指向大盘。 
• 要精确控制版本：优先 Git（选分支/tag），或在 SDK/CLI 里加 --revision <tag/commit>（见官方下载文档）。 

⸻

一键可用的最小命令清单

# 1) 安装
pip install -U modelscope

# 2) CLI：整库到指定目录
modelscope download --model Qwen/Qwen3-Omni-30B-A3B-Instruct --local_dir ./models/qwen3-omni-30b

# 3) CLI：只下一个文件
modelscope download --model Qwen/Qwen3-Omni-30B-A3B-Instruct README.md --local_dir ./dir

# 4) SDK：脚本里拉到本地目录
python - << 'PY'
from modelscope import snapshot_download
snapshot_download('Qwen/Qwen3-Omni-30B-A3B-Instruct', cache_dir='./models/qwen3-omni-30b')
PY

# 5) SDK（私有库）：先登录再下
python - << 'PY'
from modelscope.hub.api import HubApi
from modelscope import snapshot_download
api = HubApi(); api.login('YOUR_MODELSCOPE_TOKEN')
snapshot_download('your-org/private-model', cache_dir='./models/private')
PY