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.pyModelCardCMD注册别名为model位于 modelscope/cli/modelcard.pyPluginsCMD位于 modelscope/cli/plugins.pyServerCMD位于 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按通配符筛选下载includemodelscope download --model AI-ModelScope/gpt2 --include onnx/* *.tflite上述命令会匹配仓库中所有onnx/目录下的文件以及所有*.tflite文件。--include可传多个 Glob 模式彼此是并集关系。按通配符排除文件excludemodelscope 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_tokenModelScope 访问凭证与login命令的令牌同源从源码看modelscope/cli/modelcard.py传入后会自动执行HubApi.login(access_token)。-act/--action动作类型可选create创建模型仓库、upload上传模型文件、download下载模型。-gid/--group_id所属群组/组织名如damo默认值为damo。注意ModelCardCMD在初始化时会把group_id/model_id拼接成完整的模型 IDmodelscope/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_pathtemplate.tpl选用的模板文件-s/--save_file_path./生成文件的保存目录./表示当前工作目录-f/--filenamems_wrapper.py生成的主文件名必须以.py结尾否则报错-t/--task_name无必填全局唯一的任务名-m/--model_nameMyCustomModel模型类名-p/--preprocessor_nameMyCustomPreprocessor预处理器类名-pp/--pipeline_nameMyCustomPipelinePipeline 类名-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_namemy-custom-model)装饰的${model_name}(TorchModel)提供forward与init_model两个可重写方法init_model默认返回恒等函数lambda x: x预处理器类PREPROCESSORS.register_module(${task_name}, module_namemy-custom-preprocessor)装饰的${preprocessor_name}(Preprocessor)通过__call__与init_preprocessor实现数据预处理Pipeline 类PIPELINES.register_module(${task_name}, module_namemy-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}, modelusr_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），仅供参考