ModelScope 命令行工具（modelscope CLI）完整使用指南：登录、模型下载、模型管理与 Pipeline 脚手架-开发者社区

ModelScope 命令行工具（modelscope CLI）完整使用指南：登录、模型下载、模型管理与 Pipeline 脚手架

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

本指南以 ModelScope 开源仓库中的官方命令文档 docs/source/command.md 为主体，系统讲解modelscope命令行工具的核心用法：从获取 Access Token 登录、按文件粒度下载模型、创建并上传模型仓库，到用模板脚手架生成自定义 Pipeline 代码。读完本文，你将能熟练地在终端中完成 ModelScope 模型生命周期管理中的大多数日常操作，并结合仓库源码理解每个命令背后的实现原理。

支持的命令总览

在终端中执行modelscope --help，可以看到当前版本支持的顶层命令：

modelscope --help usage: modelscope <command> [<args>] positional arguments: {download,plugin,pipeline,modelcard,model,server,login} modelscope commands helpers options: -h, --help show this help message and exit

命令说明：

命令	用途
`login`	使用 Access Token 登录 ModelScope，获取访问凭证
`download`	按模型 ID 下载模型文件，支持单文件/多文件/通配符过滤
`model`（别名`modelcard`）	创建模型仓库、上传模型文件、下载模型
`pipeline`	基于模板生成自定义 Pipeline 的脚手架文件
`plugin`	管理 ModelScope 插件（安装/卸载/列出）
`server`	启动本地推理 HTTP 服务

从源码结构看，这些命令的定义分散在 modelscope/cli 目录下：PipelineCMD位于 modelscope/cli/pipeline.py，ModelCardCMD（注册别名为model）位于 modelscope/cli/modelcard.py，PluginsCMD位于 modelscope/cli/plugins.py，ServerCMD位于 modelscope/cli/server.py。而 modelscope/cli/cli.py 作为python -m modelscope.cli.cli的入口，将命令注册与分发委托给modelscope_hub.cli.main.run_cmd，因此modelscope与ms、modelscope-hub、ms-hub四个控制台脚本共享同一套命令体系。

提示：执行任意子命令时都可通过-h/--help查看该命令的参数说明，例如modelscope download --help。

login：登录并配置访问令牌

modelscope login --help usage: modelscope <command> [<args>] login [-h] --token TOKEN options: -h, --help show this help message and exit --token TOKEN The Access Token for modelscope.

--token是必填参数，传入从 ModelScope 个人页面获取的SDK 令牌（Access Token）。登录成功后，后续涉及上传、创建模型等写操作（以及部分私有资源访问）都会携带该凭证。令牌信息会写入本机凭据文件，默认路径由 modelscope/hub/constants.py 中的DEFAULT_CREDENTIALS_PATH（~/.modelscope/credentials）决定，也可通过环境变量MODELSCOPE_CREDENTIALS_PATH覆盖。

download：模型文件下载

download是使用最频繁的命令，支持按文件粒度、通配符过滤、缓存目录与本地目录等多种下载方式：

modelscope download --help usage: modelscope <command> [<args>] download [-h] --model MODEL [--revision REVISION] [--cache_dir CACHE_DIR] [--local_dir LOCAL_DIR] [--include [INCLUDE ...]] [--exclude [EXCLUDE ...]] [files ...] positional arguments: files Specify relative path to the repository file(s) to download.(e.g 'tokenizer.json', 'onnx/decoder_model.onnx'). options: -h, --help show this help message and exit --model MODEL The model id to be downloaded. --dataset DATASET The dataset id to be downloaded. --revision REVISION Revision of the model. --cache_dir CACHE_DIR Cache directory to save model. --local_dir LOCAL_DIR File will be downloaded to local location specified bylocal_dir, in this case, cache_dir parameter will be ignored. --include [INCLUDE ...] Glob patterns to match files to download.Ignored if file is specified --exclude [EXCLUDE ...] Glob patterns to exclude from files to download.Ignored if file is specified

参数速查：

参数	说明	要点
`files`	位置参数，指定仓库内文件的相对路径	例如`tokenizer.json`、`onnx/decoder_model.onnx`
`--model`	要下载的模型 ID	必填（与`--dataset`二选一）
`--dataset`	要下载的数据集 ID	用于下载数据集
`--revision`	模型的版本号（Revision）	不指定时默认拉取最新版本
`--cache_dir`	模型缓存目录	文件保存在`cache_dir/<模型ID>/`下
`--local_dir`	本地下载目录	指定后文件直接落入该目录，且`cache_dir`会被忽略
`--include`	匹配下载文件的 Glob 通配符	指定具体`files`时被忽略
`--exclude`	排除文件的 Glob 通配符	指定具体`files`时被忽略

下载单个文件

modelscope download --model 'AI-ModelScope/gpt2' 64.tflite

下载多个指定文件

modelscope download --model 'AI-ModelScope/gpt2' 64.tflite config.json

按通配符筛选下载（include）

modelscope download --model 'AI-ModelScope/gpt2' --include 'onnx/*' '*.tflite'

上述命令会匹配仓库中所有onnx/目录下的文件以及所有*.tflite文件。--include可传多个 Glob 模式，彼此是并集关系。

按通配符排除文件（exclude）

modelscope download --model 'AI-ModelScope/gpt2' --exclude 'onnx/*' '*.tflite'

与--include相反，--exclude用于排除onnx/目录与*.tflite文件，其余文件全部下载。--include与--exclude均可与位置参数files混用，但一旦显式指定了具体文件路径，这两个通配符参数即被忽略（见上文 help 中的 "Ignored if file is specified"）。

指定缓存目录下载

modelscope download --model 'AI-ModelScope/gpt2' --include '*.json' --cache_dir './cache_dir'

模型文件会下载到cache_dir/AI-ModelScope/gpt2/，即以「缓存目录 + 模型 ID」作为最终落盘路径。这一目录约定与仓库内 modelscope/hub/snapshot_download.py 的缓存根目录逻辑一致，方便多个项目共享同一份模型缓存。

指定本地目录下载

modelscope download --model 'AI-ModelScope/gpt2' --include '*.json' --local_dir './local_dir'

模型文件会直接下载到./local_dir，不再按模型 ID 生成子目录。当同时指定--local_dir与--cache_dir时，--local_dir优先生效，--cache_dir被忽略。这一行为适合需要把模型精确放到指定工程目录（如部署目录）的场景。

下载底层由 modelscope/hub/snapshot_download.py 提供快照下载能力，支持断点续传与并发下载；并发数与阈值可通过 modelscope/hub/constants.py 中的环境变量MODELSCOPE_PARALLEL_DOWNLOAD_THRESHOLD_MB与MODELSCOPE_DOWNLOAD_PARALLELS调节。此外modelscope model -act download内部也复用了snapshot_download（见下文）。

model / modelcard：模型仓库管理

model是modelcard的别名（注册源码见 modelscope/cli/modelcard.py），用于创建模型与上传模型文件：

modelscope model --help usage: modelscope <command> [<args>] modelcard [-h] [-tk ACCESS_TOKEN] -act {create,upload,download} [-gid GROUP_ID] -mid MODEL_ID [-vis VISIBILITY] [-lic LICENSE] [-ch CHINESE_NAME] [-md MODEL_DIR] [-vt VERSION_TAG] [-vi VERSION_INFO] options: -h, --help show this help message and exit -tk ACCESS_TOKEN, --access_token ACCESS_TOKEN the certification of visit ModelScope -act {create,upload,download}, --action {create,upload,download} the action of api ModelScope[create, upload] -gid GROUP_ID, --group_id GROUP_ID the group name of ModelScope, eg, damo -mid MODEL_ID, --model_id MODEL_ID the model name of ModelScope -vis VISIBILITY, --visibility VISIBILITY the visibility of ModelScope[PRIVATE: 1, INTERNAL:3, PUBLIC:5] -lic LICENSE, --license LICENSE the license of visit ModelScope[Apache License 2.0|GPL-2.0|GPL-3.0|LGPL-2.1|LGPL-3.0|AFL-3.0|ECL-2.0|MIT] -ch CHINESE_NAME, --chinese_name CHINESE_NAME the chinese name of ModelScope -md MODEL_DIR, --model_dir MODEL_DIR the model_dir of configuration.json -vt VERSION_TAG, --version_tag VERSION_TAG the tag of uploaded model -vi VERSION_INFO, --version_info VERSION_INFO the info of uploaded model

关键参数详解：

-tk/--access_token：ModelScope 访问凭证，与login命令的令牌同源；从源码看（modelscope/cli/modelcard.py），传入后会自动执行HubApi.login(access_token)。
-act/--action：动作类型，可选create（创建模型仓库）、upload（上传模型文件）、download（下载模型）。
-gid/--group_id：所属群组/组织名，如damo，默认值为damo。注意ModelCardCMD在初始化时会把group_id/model_id拼接成完整的模型 ID（modelscope/cli/modelcard.py），若model_id本身已包含/则直接使用。
-mid/--model_id：模型名，必填。
-vis/--visibility：可见性，取值PRIVATE: 1、INTERNAL: 3、PUBLIC: 5，默认5。这些取值与 modelscope/hub/constants.py 中ModelVisibility枚举一致；源码在创建前会做合法性校验，非法值会抛出异常（modelscope/cli/modelcard.py）。
-lic/--license：许可证，默认Apache License 2.0，可选值全集见 modelscope/hub/constants.py 的Licenses类：Apache License 2.0、GPL-2.0、GPL-3.0、LGPL-2.1、LGPL-3.0、AFL-3.0、ECL-2.0、MIT。
-ch/--chinese_name：模型中文名，默认这是我的第一个模型。
-md/--model_dir：包含configuration.json的模型目录，默认当前目录.。
-vt/--version_tag与-vi/--version_info：上传模型的版本标签与版本说明；两者需同时给出才会走打 tag 的逻辑。

创建模型仓库

modelscope model -act create -gid 'YOUR_GROUP_ID' -mid 'THE_MODEL_ID' -vis 1 -lic 'MIT' -ch '中文名字'

该命令会在 ModelScope 平台上创建名为THE_MODEL_ID的模型仓库。从源码看（modelscope/cli/modelcard.py），执行逻辑为：先通过HubApi.get_model探测模型是否已存在，若不存在则调用HubApi.create_model创建，随后输出模型 Git 地址、页面地址与模型 ID 三个访问入口（pprint方法，modelscope/cli/modelcard.py）。

上传模型文件

modelscope model -act upload -gid 'YOUR_GROUP_ID' -mid 'THE_MODEL_ID' -md modelfiles/ -vt 'v0.0.1' -vi 'upload model files'

上传时会将-md指定的目录（如modelfiles/，需包含configuration.json）推送到远端仓库，并通过-vt/-vi打上v0.0.1版本标签。源码实现（modelscope/cli/modelcard.py）分为两条路径：

当同时指定-vt与-vi时，先通过 modelscope/hub/repository.py 的Repository克隆远端仓库，再调用tag_and_push打标签推送；
未指定版本参数时，若本地model_dir下没有README.md，会自动用 modelscope/cli/template/readme.tpl 模板生成默认模型卡片（内含许可证 front-matter 与git clone指引），然后调用HubApi.push_model完成上传。

pipeline：生成自定义 Pipeline 脚手架

pipeline命令用于生成自定义 Pipeline 所需的模板文件，把「模型类 + 预处理器类 + Pipeline 类 + 配置」一次性以代码文件形式产出，是接入 ModelScope 自定义任务最快捷的方式：

modelscope pipeline --help usage: modelscope <command> [<args>] pipeline [-h] -act {create} [-tpl TPL_FILE_PATH] [-s SAVE_FILE_PATH] [-f FILENAME] -t TASK_NAME [-m MODEL_NAME] [-p PREPROCESSOR_NAME] [-pp PIPELINE_NAME] [-config CONFIGURATION_PATH] options: -h, --help show this help message and exit -act {create}, --action {create} the action of command pipeline[create] -tpl TPL_FILE_PATH, --tpl_file_path TPL_FILE_PATH the template be selected for ModelScope[template.tpl] -s SAVE_FILE_PATH, --save_file_path SAVE_FILE_PATH the name of custom template be saved for ModelScope -f FILENAME, --filename FILENAME the init name of custom template be saved for ModelScope -m MODEL_NAME, --model_name MODEL_NAME the class of model name for ModelScope -p PREPROCESSOR_NAME, --preprocessor_name PREPROCESSOR_NAME the class of preprocessor name for ModelScope -pp PIPELINE_NAME, --pipeline_name PIPELINE_NAME the class of pipeline name for ModelScope -config CONFIGURATION_PATH, --configuration_path CONFIGURATION_PATH the path of configuration.json for ModelScope

参数默认值（与 modelscope/cli/pipeline.py 中的register定义一致）：

参数	默认值	说明
`-act/--action`	无（必填）	目前仅支持`create`
`-tpl/--tpl_file_path`	`template.tpl`	选用的模板文件
`-s/--save_file_path`	`./`	生成文件的保存目录，`./`表示当前工作目录
`-f/--filename`	`ms_wrapper.py`	生成的主文件名，必须以`.py`结尾（否则报错）
`-t/--task_name`	无（必填）	全局唯一的任务名
`-m/--model_name`	`MyCustomModel`	模型类名
`-p/--preprocessor_name`	`MyCustomPreprocessor`	预处理器类名
`-pp/--pipeline_name`	`MyCustomPipeline`	Pipeline 类名
`-config/--configuration_path`	`./`	`configuration.json`的生成路径

生成 Pipeline 文件

modelscope pipeline -act 'create' -t 'THE_PIPELINE_TASK' -m 'THE_MODEL_NAME' -pp 'THE_PIPELINE_NAME'

执行后会做以下事情（对应 modelscope/cli/pipeline.py 的create_template方法）：

定位模板：优先使用仓库自带的 modelscope/cli/template/template.tpl，也可用-tpl指定自定义模板路径；
用 Python 的string.Template把task_name、model_name、preprocessor_name、pipeline_name、configuration_path等参数替换进模板占位符（如${model_name}）；
在-s指定目录生成ms_wrapper.py（可用-f改名），并在-config目录生成configuration.json；
终端提示你「打开生成的文件，更新并运行它」。

生成的ms_wrapper.py结构清晰，是理解 ModelScope 注册机制的最佳入口，其核心骨架如下（完整模板见 modelscope/cli/template/template.tpl）：

模型类：@MODELS.register_module('${task_name}', module_name='my-custom-model')装饰的${model_name}(TorchModel)，提供forward与init_model两个可重写方法，init_model默认返回恒等函数lambda x: x；
预处理器类：@PREPROCESSORS.register_module('${task_name}', module_name='my-custom-preprocessor')装饰的${preprocessor_name}(Preprocessor)，通过__call__与init_preprocessor实现数据预处理；
Pipeline 类：@PIPELINES.register_module('${task_name}', module_name='my-custom-pipeline')装饰的${pipeline_name}(Pipeline)，内置_sanitize_parameters、forward、postprocess等可重写方法，docstring 中直接给出了用法示例：
```
>>> from modelscope.pipelines import pipeline >>> input = "Hello, ModelScope!" >>> my_pipeline = pipeline('my-task', 'my-model-id') >>> result = my_pipeline(input)
```
配置生成：末尾用Config自动 dump 出configuration.json，其中包含framework: pytorch、task、model.type、pipeline.type与allow_remote: true等字段；
自测入口：if __name__ == "__main__"中直接以pipeline('${task_name}', model=usr_config_path)的方式跑通一次推理，验证脚手架可用。

@MODELS.register_module、@PREPROCESSORS.register_module、@PIPELINES.register_module分别对应仓库中 modelscope/models/builder.py、modelscope/preprocessors/builder.py、modelscope/pipelines/builder.py 的注册表机制——这也是 ModelScope 通过字符串类型名自动装配模型、预处理器与 Pipeline 的核心。

其他相关命令（plugin / server）

原文档的顶层命令列表中还包含plugin与server两个命令，简要说明如下：

modelscope plugin：管理插件包，子命令为install <package...> [-i/--index_url] [-f/--force_update]、uninstall <package...> [-y/--yes]、list [-a/--all]，底层调用 modelscope/utils/plugins.py 的PluginsManager（命令定义见 modelscope/cli/plugins.py）。
modelscope server：启动本地推理 HTTP 服务，参数与启动逻辑由 modelscope/server/api_server.py 的add_server_args与run_server提供（见 modelscope/cli/server.py），适合将已注册的 Pipeline 以 HTTP 接口形式对外暴露。

实践建议与注意事项

令牌安全：login与model的-tk都涉及 Access Token，建议通过环境变量或凭据文件方式管理，避免明文写入 shell 历史；令牌获取入口为 ModelScope 个人页面中的「SDK 令牌」。
下载路径二选一：--local_dir与--cache_dir同时出现时--local_dir优先生效（原文档明确说明），需要按模型 ID 组织缓存时请只使用--cache_dir。
上传前的目录结构：model -act upload的-md目录应包含configuration.json；缺少README.md时命令会自动生成默认模型卡片，建议随后按模板要求完善后再公开模型。
自定义 Pipeline 的接入链路：用pipeline -act create生成脚手架后，依次实现init_model、init_preprocessor、forward/postprocess，再通过modelscope pipeline生成的configuration.json注册任务，即可用pipeline('<task_name>', model=...)统一调用。

本文所有命令的参数与行为均可在仓库源码中验证：命令注册集中在 modelscope/cli 目录，常量与枚举定义见 modelscope/hub/constants.py，模板文件见 modelscope/cli/template。如需进一步了解模型下载 API、仓库克隆推送等底层能力，可继续阅读 modelscope/hub/snapshot_download.py 与 modelscope/hub/repository.py。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考