引言

本文详细介绍了魔搭（ModelScope）平台的基本概念和使用方法，从环境配置到模型下载、加载和推理的完整流程，并以实际操作为例展示了平台的使用方式。

其实，我对魔搭 ModelScope 是有一些感情在的，因为我的第一次大模型微调经验就是基于魔搭平台，并且凭此获得了数字中国创新大赛的奖项。

有趣的是，出于种种机缘巧合，我既缺乏基础知识，也没有接受过完整的培训，甚至没有经历全流程的使用。

由于当时急于求成，虽然成功完成了训练，却没能深入探索魔搭的强大功能，仅使用了 swift 便捷的训练功能。

所以，这次我打算从”Quick Start”开始，认真学习魔搭的每一个功能。

过程

Quick Start

很奇妙的一点，中英文的教程竟然是不同的，英文版在概念解释上更详细，而中文版在操作流程上更详细。然后，中文版似乎更新更频繁，所以如果是国内用户并以使用优先，建议优先参考中文版，但如果想要更深入的了解模型训练的原理，建议参考英文版。

  1. 魔搭社区
  2. 魔搭社区

哦，对了，如果是打算用的话，建议去直接看文档，他写的真的很好，真的可以让你在 5 分钟内学会使用。

基础概念

首先是一些基础概念：

Task（任务）:
特定领域的具体应用，如图像分类、文本生成等，用户可根据输入输出需求选择合适的模型。

Task refers to a specific application in a certain field, used to complete tasks in specific scenarios. For example, image classification, text generation, speech recognition, etc. You can find the task type suitable for your application scenario based on the input and output of the task, and filter the tasks to find the model you need.

Model（模型）:
包含网络结构和参数的具体模型实例，提供实际的 AI 能力。

Model refers to a specific model instance, including the model network structure and corresponding parameters. ModelScope provides rich model information for users to experience and use.

Modelhub（模型库）:
模型库是模型资源的管理和分发平台，提供丰富的模型资源，帮助用户快速找到合适的模型。

Model library (Modelhub) refers to model services that store, version manage and related operations for models. Models uploaded and shared by users will be stored in ModelScope’s model library. Users can also create their own model storage in Model hub. library, and continue to use the model library management function provided by the platform for model management.

Dataset（数据集）:
用于算法训练、测试的数据集合，支持模型训练和验证。

Dataset refers to a set of data used for model training and evaluation. ModelScope provides rich dataset information for users to experience and use.

Datasethub（数据集库）:
集中管理数据的平台，便于数据访问、管理和共享。

Datasethub is used to centrally manage data and support model training, prediction, etc., making various types of data easy to access, manage, and share.

ModelScope Library（模型库）:
ModelScope 的 Python 框架库，提供简单的代码接口实现模型推理、训练等功能。

ModelScope Library is a set of Python Library frameworks developed by ModelScope. By calling specific methods, users can write just a few lines of code to complete tasks such as model reasoning, training, and evaluation. On this basis, they can also quickly Carry out secondary development and realize your own innovative ideas.

Model Exploration

模型探索：

访问平台网站 https://www.modelscope.cn/models，可以看到平台上的所有公共模型，通过任务或关键词搜索找到感兴趣的模型。

如果需要找到可以在线体验或支持训练和微调的模型，可以通过搜索框右侧的过滤框进行过滤。可以在线体验和训练的模型将不断丰富和扩展，敬请期待。
本文以中文分词模型为例，带你体验使用 ModelScope 的模型。
可以通过过滤任务为 “词性标注” 或搜索关键词 “词性标注” 来检索对应的词性标注模型。在模型卡片右侧，会显示模型的基本信息，包括中文和英文名称、任务类型标签和其他模型标签、模型使用的深度学习框架、模型提供者、下载次数、点赞次数、模型描述等信息，帮助你快速理解模型。

public models on the platform

点击模型进入模型详情页，可以查看模型的具体介绍。模型提供者会在这里介绍模型的具体应用场景、功能描述、技术方法、模型训练和使用、效果评估等信息，供你参考。
在模型卡片右侧，有一个 “在线体验” 功能。可以切换默认示例查看模型效果，或输入适合模型的测试信息测试模型效果。

model details page

事实上并非所有模型都支持在线体验，但是依然是非常实用的功能。

在开始在线体验之前，请仔细阅读并理解相关的免责声明，合法合规地使用在线体验模块的功能。
除了模型体验，你还可以查看和下载模型的具体文件。（目前支持通过 git 和 Python SDK 下载。更多信息请参见模型下载）
如果你对模型效果满意，想要了解更多并进行代码验证，可以点击 “快速使用” 查看具体的代码示例方法。平台提供了两种下载模型的方式：

  1. Install and download through ModelScope Library
  2. Pull the repository through git
    这些方法都可以在本地运行模型。但是，你需要先安装 ModelScope Library 才能运行代码。详情请参见步骤 [环境准备] - [本地开发环境安装]。

环境准备

本地开发环境安装

如果你需要运行模型，你需要进行相应的环境安装准备，包括：

  • 安装 python 环境。支持 python3，但不支持 python2。推荐使用 Anaconda 安装。
  • 安装深度学习框架。ModelScope Library 目前支持两大深度学习框架，Tensorflow 和 Pytorch，用于模型训练和推理。你可以根据模型所需的框架选择合适的框架进行安装。
  • 安装 ModelScope Library。我们提供了两种安装方法，你可以根据需要选择合适的安装方法。
    • pip 安装。ModelScope 根据不同领域提供了安装包，你可以根据对应的模型选择所需的安装包。
    • 从源码安装。

魔搭社区提供了预安装好的 Notebook 环境来使用魔搭社区模型，并为新用户提供了 100 小时的免费 GPU 算力和不限时长的免费 CPU 算力，并预安装了大部分模型可运行的环境依赖。

Python 环境安装配置

首先，参考文档 安装配置 Anaconda 环境。安装完成后，执行如下命令为 ModelScope library 创建对应的 Python 环境。

1
2
conda create -n modelscope python=3.10
conda activate modelscope

ModelScope Library 安装

ModelScope Library 由核心 hub 支持，框架，以及不同领域模型的对接组件组成。根据您实际使用的场景，可以选择不同的安装选项。

如果只需要通过 ModelScope SDK，或者 ModelScope 命令行工具来下载模型，可以只最轻量化的安装 ModelScope 的核心 hub 支持：

1
pip install modelscope

如果需要更完整的使用 ModelScope 平台上的一系列框架能力，包括数据集的加载，外部模型的使用等，则推荐使用”framework”的安装选项，也就是：

1
pip install modelscope[framework]

以上两种方法，都不涉及 ModelScope 上原生模型的集成。要使用 ModelScope 来实现各种领域模型的使用，包括基于 NLP、CV、语音、多模态，等不同领域的模型，来进行模型推理以及模型训练、微调等能力，则需要根据具体领域，通过安装选项，来安装额外的依赖。同时也涉及对应的 PyTorch,Tensorflow 等机器学习框架的安装。

同时社区推荐安装 Git 和 Git LFS，这是模型管理包括上传所必须的工具。

其他

以下部分的内容建议参考文档，因为文档写的真的很好。

  • 深度学习框架依赖的安装
  • 分领域 ModelScope 模型依赖的安装
  • 安装验证

实际流程

因为我这次是为了体验 cv 领域的模型，所以选择了安装modelscope[cv]。

1
2
pip install torch
pip install "modelscope[cv]" -f https://modelscope.oss-cn-beijing.aliyuncs.com/releases/repo.html

模型下载

如果您在高带宽的机器上运行，推荐使用 ModelScope 命令行工具下载模型。该方法支持断点续传和模型高速下载，例如可以通过如下命令，将 Qwen2.5-0.5B-Instruct 模型，下载到当前路径下的”model-dir”目录。

1
modelscope download --model Qwen/Qwen2.5-0.5B-Instruct --local_dir ./model-dir

这里有个插曲是当时我发现文档中代码无法实际使用，然后提了 issue, 然后过来不久开发团队就回复了问题并更新了文档。

谢谢指出。
这里主要是 typo，把后面一个引号的位置写错了。事实上对于下载模型，以下 3 种写法都支持

1
2
3
>modelscope download --model="Qwen/Qwen2.5-0.5B-Instruct" --local_dir ./model-dir
>modelscope download --model "Qwen/Qwen2.5-0.5B-Instruct" --local_dir ./model-dir
>modelscope download "Qwen/Qwen2.5-0.5B-Instruct" --local_dir ./model-dir

文档中已经修复引号的位置。

您也可以使用 ModelScope Python SDK 下载模型，该方法支持断点续传和模型高速下载：

1
2
from modelscope import snapshot_download
model_dir = snapshot_download("Qwen/Qwen2.5-0.5B-Instruct")

由于模型都是通过 Git 存储，所以也可以在安装 Git LFS 后，通过 git clone 的方式在本地下载模型，例如：

1
2
git lfs install
git clone https://www.modelscope.cn/Qwen/Qwen2.5-0.5B-Instruct.git

关于模型下载的详细说明，可参考模型下载文档。

同时，如果模型和 ModelScope SDK 绑定，则只需要几行代码即可加载模型，同时 ModelScope 还支持通过 AutoModel 等接口来加载模型。如下是使用 AutoModel 和 pipeline 方式加载模型的示例：

实际操作

我实验的模型是图片生成模型：PAI中文Diffusion模型-美食。

魔搭社区

1
2
# 命令行下载
modelscope download --model PAI/pai-diffusion-food-large-zh --local_dir ./model

模型加载

使用 ModelScope pipeline 加载模型

如果你准备好了环境，可以基于以下代码推理模型。使用 modelscope pipeline 接口只需要两步，以下以词性标注模型（damo/nlp_structbert_word-segmentation_chinese-base）为例进行简要说明：

首先实例化一个基于任务的 pipeline 对象

1
2
from modelscope.pipelines import pipeline
word_segmentation = pipeline('word-segmentation',model='damo/nlp_structbert_word-segmentation_chinese-base')

输入数据并获取输出

1
2
3
input_str = '今天天气不错，适合出去游玩'
print(word_segmentation(input_str))
{'output': '今天 天气 不错，适合 出去 游玩'}

使用 AutoModel 加载模型

1
2
3
4
5
6
7
8
9
10
from modelscope import AutoModelForCausalLM, AutoTokenizer

model_name = "Qwen/Qwen2.5-0.5B-Instruct"

model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype="auto",
    device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained(model_name)

模型推理

pipeline

推理不同模态多种任务，pipeline 是最简单、最快捷的方法。您可以使用开箱即用的 pipeline 执行跨不同模式的多种任务，下面是一个 pipeline 完整的运行示例：

1
2
3
4
5
6
7
8
9
10
from modelscope.pipelines import pipeline
from modelscope.utils.constant import Tasks

inference_pipeline = pipeline(
    task=Tasks.auto_speech_recognition,
    model='iic/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-pytorch',
    model_revision="v2.0.4")

rec_result = inference_pipeline('https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/asr_vad_punc_example.wav')
print(rec_result)

AutoModel 和 AutoTokenizer

ModelScope 兼容了 Transformers 提供的简单而统一的方法来加载预训练实例和 tokenizer。这意味着您可以使用 ModelScope 加载 AutoModel 和 AutoTokenizer 等类。下面是一个大语言模型的完整的运行示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
from modelscope import AutoModelForCausalLM, AutoTokenizer

model_name = "qwen/Qwen2.5-0.5B-Instruct"

model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype="auto",
    device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained(model_name)

prompt = "Give me a short introduction to large language model."
messages = [
    {"role": "system", "content": "You are Qwen, created by Alibaba Cloud. You are a helpful assistant."},
    {"role": "user", "content": prompt}
]
text = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True
)
model_inputs = tokenizer([text], return_tensors="pt").to(model.device)

generated_ids = model.generate(
    **model_inputs,
    max_new_tokens=512
)
generated_ids = [
    output_ids[len(input_ids):] for input_ids, output_ids in zip(model_inputs.input_ids, generated_ids)
]

response = tokenizer.batch_decode[generated_ids, skip_special_tokens=True](0)

其他模型推理

对于暂时未与 ModelScope SDK 做原生集成的模型，可以先从 ModelScope 上下载模型，然后通过其他的主流库实现模型推理，以 SDXL-Turbo 模型为例，完整的模型推理运行示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
from diffusers import AutoPipelineForText2Image
import torch
from modelscope import snapshot_download

model_dir = snapshot_download("AI-ModelScope/sdxl-turbo")

pipe = AutoPipelineForText2Image.from_pretrained(model_dir, torch_dtype=torch.float16, variant="fp16")
pipe.to("cuda")

prompt = "A cinematic shot of a baby racoon wearing an intricate italian priest robe."

image = pipe(prompt=prompt, num_inference_steps=1, guidance_scale=0.0).images[0]
image.save("image.png")

模型推理实际操作

1
2
3
4
5
6
7
from modelscope.pipelines import pipeline
import cv2

p = pipeline('text-to-image-synthesis', 'PAI/pai-diffusion-food-large-zh', model_revision='v1.0.0')
result = p({'text': '红烧狮子头'})
image = result["output_imgs"][0]
cv2.imwrite("image.png", image)

注：可以把模型地址写为刚刚下载的文件夹路径。

结论

受益匪浅，ModelScope 的文档写的真的很好，而且很详细，很适合初学者。