ModelScope 模型下载

本文介绍在 ModelScope 社区下载模型的三种方式：

1. 使用命令行工具下载
2. 使用 SDK 下载
3. 通过 Git 下载

模型下载默认存放地址#

无论是使用命令行还是ModelScope SDK，模型会下载到~/.cache/modelscope/hub默认路径下。如果需要修改 cache 目录，可以手动设置环境变量：MODELSCOPE_CACHE，完成设置后，模型将下载到该环境变量指定的目录中。

使用命令行工具下载#

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. --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

使用示例#

命令示例（以Qwen2-7B）模型为例

下载整个模型repo（到默认cache地址）#

modelscope download --model 'Qwen/Qwen2-7b'

下载整个模型repo到指定目录#

modelscope download --model 'Qwen/Qwen2-7b' --local_dir 'path/to/dir'

指定下载单个文件(以'tokenizer.json'文件为例)#

modelscope download --model 'Qwen/Qwen2-7b' tokenizer.json

指定下载多个个文件#

modelscope download --model 'Qwen/Qwen2-7b' tokenizer.json config.json

指定下载某些文件#

modelscope download --model 'Qwen/Qwen2-7b' --include '*.safetensors'

过滤指定文件#

modelscope download --model 'Qwen/Qwen2-7b' --exclude '*.safetensors'

指定下载cache_dir#

modelscope download --model 'Qwen/Qwen2-7b' --include '*.json' --cache_dir './cache_dir'

模型文件将被下载到'cache_dir/Qwen/Qwen2-7b'。

指定下载local_dir#

modelscope download --model 'Qwen/Qwen2-7b' --include '*.json' --local_dir './local_dir'

模型文件将被下载到'./local_dir'。

如果cache_dir和local_dir参数同时被指定，local_dir优先级高，cache_dir将被忽略。

下载私有模型需要登录#

通过login命令#

当下载私有模型时，您需要先登陆。通过 CLI 方式登陆的命令为modelscope login，详细使用说明如下：

usage: modelscope <command> [<args>] login [-h] --token TOKEN

options:
  -h, --help     show this help message and exit
  --token TOKEN  The Access Token for modelscope.

  modelscope login --token YOUR_MODELSCOPE_SDK_TOKEN

您可以在我的访问令牌页面获取SDK 令牌。

使用 ModelScope SDK 下载#

下载整个模型仓库#

您可以使用snapshot_download下载整个模型仓库，示例如下：

from modelscope.hub.snapshot_download import snapshot_download model_dir = snapshot_download('iic/nlp_xlmr_named-entity-recognition_viet-ecommerce-title')

参数说明

字段名	必填	类型	描述
model_id	是	str	模型ID
revision	否	str	模型的Git版本，分支名或tag
cache_dir	否	str,Path	指定模型本次下载缓存目录，给定后下载的具体模型文件将会被存储在cache_dir/model_id/THE_MODEL_FILES
allow_patterns	否	str,List	指定要下载的文件模式，如文件名或文件扩展名
ignore_patterns	否	str,List	指定要忽略下载的文件模式，如文件名或文件扩展名
local_dir	否	str	指定模型的下载存放目录，给定后本次下载的模型文件将会被存储在local_dir/THE_MODEL_FILES

如果cache_dir和local_dir参数同时被指定，local_dir优先级高，cache_dir将被忽略；更多参数使用说明可以参见开源代码的接口文档。如需指定下载或过滤下载某种/某类文件模式，可以使用 allow_patterns或ignore_patterns参数，示例如下：

• 指定下载某些文件

以指定下载Qwen/QwQ-32B-GGUF中q4_k_m量化版本到path/to/local/dir目录下为例。

from modelscope.hub.snapshot_download import snapshot_download model_dir = snapshot_download('Qwen/QwQ-32B-GGUF',allow_patterns='qwq-32b-q4_k_m.gguf',local_dir='path/to/local/dir')

• 过滤指定文件

以将deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B仓库除figures子目录外的所有文件下载到指定的path/to/local/dir目录为例。

from modelscope.hub.snapshot_download import snapshot_download model_dir = snapshot_download('deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B',ignore_patterns='figures/',local_dir='path/to/local/dir')

下载模型指定文件#

您也可以使用model_file_download下载模型指定文件。示例如下：

from modelscope.hub.file_download import model_file_download model_dir = model_file_download(model_id='Qwen/QwQ-32B-GGUF',file_path='qwq-32b-q4_k_m.gguf')

参数说明

字段名	必填	类型	描述
model_id	是	str	模型ID
file_path	是	str	待下载文件在远程模型仓库的相对路径
revision	否	str	模型的Git版本，分支名或tag
cache_dir	否	str,Path	指定模型本次下载缓存目录，给定后下载的具体模型文件将会被存储在cache_dir/models/model_id/THE_MODEL_FILES
local_dir	否	str	指定模型的下载存放目录，给定后本次下载的模型文件将会被存储在local_dir/THE_MODEL_FILES

如果cache_dir和local_dir参数同时被指定，local_dir优先级高，cache_dir将被忽略；更多参数使用说明可以参见开源代码的接口文档。

下载私有模型#

当下载非公开模型及申请制模型时，您需要先登陆，然后可参考前述文档步骤下载模型。此处以通过 snapshot_download 下载非公开模型为例：

from modelscope import HubApi from modelscope import snapshot_download # login to ModelScope api=HubApi() api.login('YOUR_MODELSCOPE_SDK_ACCESS_TOKEN') # download your model, the model_path is downloaded model path. model_path =snapshot_download(model_id='the_model_id')

ModelScope SDK提供了多种登陆方式，您也可以通过命令行等其他方式完成登陆。

通过加载模型触发下载#

除了直接下载模型文件外，当使用ModelScope SDK加载模型时，也会自动触发模型下载。如果模型和ModelScope SDK绑定，则只需要几行代码即可加载模型，同时 ModelScope 还支持通过 AutoModel 等接口来加载模型。此处以使用 Model 加载模型为例：

from modelscope.models import Model model = Model.from_pretrained('iic/nlp_xlmr_named-entity-recognition_viet-ecommerce-title', revision='v1.0.1') # revision为可选参数，不指定版本会取模型默认版本，默认版本，默认版本为ModelScope library发布前最后一个版本 # 如何得到发布时间 import modelscope print(modelscope.version.__release_datetime__)

使用 GIT 下载模型#

ModelScope服务端的模型都是通过Git存储，所以也可以在安装Git LFS后，通过git clone的方式在本地下载模型。

# 公开模型下载 git lfs install git clone https://www.modelscope.cn/<owner_name>/<model-name>.git # 例如: git clone https://www.modelscope.cn/iic/ofa_image-caption_coco_large_en.git # 私有模型下载，前提是您有响应模型权限 方法1 git lfs install git clone http://oauth2:your_git_token@www.modelscope.cn/<owner_name>/<model-name>.git # 方法2 git clone http://your_user_name@www.modelscope.cn/<owner_name>/<model-name>.git # Password for 'http://your_user_name@modelscope.cn': # input git token

如果希望跳过LFS大文件的下载，可以在git clone命令前添加GIT_LFS_SKIP_SMUDGE=1，来只获取LFS指针，而不下载实际的大文件：

GIT_LFS_SKIP_SMUDGE=1 https://www.modelscope.cn/<namespace>/<model-name>.git

如何获取git token#

用您的账号登录https://www.modelscope.cn ，在个人中心->访问令牌，拷贝git token.