ModelScope 命令行实战：模型下载、仓库发布与缓存清理的三条最短路径

ModelScope 命令行实战：模型下载、仓库发布与缓存清理的三条最短路径

【免费下载链接】modelscopeModelScope: bring the notion of Model-as-a-Service to life.项目地址: https://gitcode.com/GitHub_Trending/mo/modelscope

ModelScope 的命令行工具（modelscope/ms）把模型下载、仓库创建与上传、本地缓存管理集中在一组子命令里，是模型使用者日常打交道最多的入口。本文不逐条罗列参数，而是按三个高频场景组织：拉取模型文件、发布自己训练的模型、回收磁盘空间。每个场景给出一条最短可行命令链，再附一个常见的排错点。适合已经装了 modelscope 包、准备在终端里干活的个人开发者和团队工程师。

场景一：把模型文件拉到本地，只拿你需要的部分

先花一条命令确认 CLI 能跑

在敲任何下载命令之前，先验证命令行环境本身：

modelscope --version # 输出版本号即安装成功 modelscope --help # 查看当前可用的子命令列表

如果modelscope找不到命令，多半是 pip 安装时把可执行文件装进了没进 PATH 的目录；用python -m modelscope.cli.cli --help也能跑同一套命令，可先顶上。子命令的完整说明也可以直接看仓库内的 docs/source/command.md。

按文件筛选下载，避免拉下不用的大文件

download支持三种缩小范围的方式：直接写文件相对路径、用--include给 glob 模式、用--exclude排除目录。三种方式里指定文件路径优先级最高，会忽略--include。

# 只下配置文件和权重，落到指定本地目录 modelscope download --model 'AI-ModelScope/bert-base-chinese' \ config.json pytorch_model.bin \ --local_dir ./models/bert-base-chinese

指定私有模型或数据集时，在命令后追加--token <你的令牌>；令牌从 ModelScope 平台个人页面的 SDK 令牌入口获取。--cache_dir与--local_dir同时给时，以--local_dir为准，文件直接进你给的目录，不走缓存。

排错点：下载了但没找到文件

文件进的是缓存目录（默认~/.cache/modelscope，可用环境变量MODELSCOPE_CACHE改位置）而不是当前目录，这是最常见的"找不到"。两个对策：要么传--local_dir明确落地位置；要么用modelscope scancache查文件实际存放位置。参数细节以仓库测试 tests/cli/test_download_cmd.py 中的用法为准。

场景二：新建模型仓库，把训练产物传上去打版本标签

先 create 建仓库，再 upload 传文件

发布分两步：model -act create在平台侧建空仓库，model -act upload把本地目录推上去并打版本标签。

# 第一步：建仓库（可见性 1 私有 / 3 内部 / 5 公开） modelscope model -act create -gid 'your-group' -mid 'my-ner-model' \ -vis 3 -lic 'Apache-2.0' -ch '医疗实体识别模型'

仓库建好后上传文件，-vt给版本标签，-vi写清这次改了什么：

# 第二步：上传本地模型目录并打版本 modelscope model -act upload -gid 'your-group' -mid 'my-ner-model' \ -md ./final_model/ -vt v2.1.0 \ -vi '优化实体识别准确率，新增药品名识别'

版本号建议按v主.次.修订走语义化版本，-vi里写功能变更而不是"更新模型"。这样别人下载时用--revision v2.1.0就能锁定版本，不会漂移到你后续上传的默认分支。

排错点：create 报权限或令牌错误

-gid填的是你在平台上的组织/用户名，不是随便起的团队名；令牌不对或权限不足时命令会直接失败。用modelscope login --token <令牌>先做一次身份验证，确认登录成功后再跑 create。可见性参数-vis只认 1、3、5 三个值，写成别的数字会被拒绝。

场景三：磁盘吃紧时，扫一遍缓存再决定删什么

先 scancache 看占用，再 clear-cache 定点删

缓存目录会随下载不断膨胀，但别上来就全删。先用扫描命令看清哪些模型占了多少空间，再按单个模型清理：

# 看缓存占用明细 modelscope scancache # 只清指定模型的缓存（会要求按 Y 确认） modelscope clear-cache --model 'AI-ModelScope/bert-base-chinese'

clear-cache的--model和--dataset互斥，一次只清一类；两个都不传时会请求删除整个缓存目录，确认提示里会明确写着 "entire ModelScope cache"，按 Y 才执行。这个交互确认逻辑可以在 modelscope/cli/clearcache.py 里对照阅读。

排错点：清完发现模型还在

--model后面要填完整的模型 id（含组织名前缀），只写模型短名时可能匹配不到，命令会提示 "Cache for Model xxx not found"。另外如果下载时用过--local_dir，文件根本不在缓存目录里，clear-cache 对它无效，需要手动去对应目录处理。

下一步可以做什么

1. 打开 docs/source/command.md，把model、pipeline、modelcard三个还没用过的子命令过一遍 help。
2. 给团队约定一条规则：所有生产下载都带--revision，禁止依赖默认分支。
3. 把scancache+ 定向clear-cache组合进月度磁盘巡检脚本，替代无差别全量清理。

【免费下载链接】modelscopeModelScope: bring the notion of Model-as-a-Service to life.项目地址: https://gitcode.com/GitHub_Trending/mo/modelscope