modelscope/ms-cookbook · 上手攻略
- 仓库：modelscope/ms-cookbook
- 链接：https://github.com/modelscope/ms-cookbook
- 分类：agent / 开源模型实战教程（HTML 静态站 + Markdown 章节，Apache-2.0）
- 作者：spark
- 更新：2026-11-02
一、它是什么
魔搭紫皮书（ModelScope Cookbook）是一本面向开发者的开源模型应用实战指南，由魔搭社区（ModelScope）维护。它不是某个工具的代码库，而是一个 39 章、8 大主题的教程仓库 + 配套静态阅读站。
它想解决的痛点非常具体：开源模型让 AI 能力唾手可得，但真动手时一连串问题接踵而来——业务需求该选哪类模型？自己电脑跑不跑得动？数据怎么准备？微完调完到底有没有变好？怎么接进一个真应用？
书的组织方式是把这些问题串成一条完整学习路线：模型选型 → 推理部署 → 数据准备 → 微调评测 → 应用开发，再用 RAG、Agent、AIGC、端侧应用等案例落地。
配套工具链在书中反复出现：EvalScope（评测）、ms-swift（微调）、DiffSynth（图像 LoRA）、Ollama（本地推理）。
二、结构一览
全书 8 篇主题、39 个章节，状态用 ✅ 可读 / 🚧 待更新 / 🤝 共建入口 标注：
| 篇 | 章节范围 | 内容 |
|---|---|---|
| 一、认识开源模型 | 01–04 | 开放程度与许可证、模型库检索与下载、数据准备、免费算力资源 |
| 二、从问题出发 | 05–06 | 业务问题→模型任务转换；先评再选（EvalScope 选型基线） |
| 三、跑得起 | 07–12 | 30 分钟首次推理、服务器选型（显存/参数量）、Ollama 本地推理、云端 Notebook、MiniCPM 手机部署、量化 |
| 四、调得好 | 13–16 | 业务素材→训练样本、ms-swift 轻量微调、偏好对齐、微调前后效果对比 |
| 五、场景篇 | 17–22 | AI 健身教练、智能客服质检、语音助手、企业知识问答（RAG）、手机巡检助手、场景共建入口 |
| 六、AIGC 特别篇 | 23–28 | 10 个 AIGC case、DiffSynth 图像 LoRA、商品营销图、Qwen-Image 教学海报、视频生成（🚧 待更新）、生成理论 |
| 七、Agent 特别篇 | 29–37 | Agent 基础、MCP、Skill、Claude Code 快速上手、PI、DeepSeek Harness、产线巡检 Agent（Penguin Harness）、Mini AI Scientist（Qwen3 4B 做科学发现）、Agent 框架知识 |
| 八、补充内容 | 38–39 | 大模型基础知识、主流 LLM 评测（🤝 共建入口） |
README 还维护了一份"真实任务库"，把可复现的实战案例（健身教练、客服质检、语音助手、知识问答、手机巡检、商品营销图、教学海报、产线巡检）单独摘出来，方便按任务直接切入。
三、快速安装
它其实"不用装"——三种使用方式：
方式 A：在线阅读（最省事）
打开 https://modelscope.cn/active/ms-cookbook 即可，无需安装，站点提供全文搜索、章节导航、学习路线和代码复制。魔搭创空间入口：modelscope.cn/studios/ms-cookbook-team/ms-cookbook。
方式 B：本地阅读
git clone https://github.com/modelscope/ms-cookbook.git
cd ms-cookbook
python3 -m http.server 4173 --bind 127.0.0.1
浏览器打开 http://127.0.0.1:4173/#home。Ctrl+C 停止服务；端口被占用就把命令和访问地址里的端口一并改成 4174。
阅读站只需要 Python 3 + 现代浏览器。 跑各章的模型示例时才需要另外准备依赖、模型文件、访问凭据与算力资源。
方式 C：直接读 GitHub 上的章节 Markdown
章节正文在 content/chapters/chapter-XX.md，例如：
# 在线读某一章
curl -sL https://raw.githubusercontent.com/modelscope/ms-cookbook/main/content/chapters/chapter-09.md | head -50
维护者视角：改内容后重新构建
章节 HTML 源文件在 content/source-html/，GitHub 阅读版 content/chapters/ 与网站数据 assets/content.js 由构建生成，篇章顺序与状态由 content/manifest.json 维护。改完正文后：
python3 scripts/build-content.py # 构建（Python 3）
node scripts/build-content.mjs --check # 校验（需 Node.js 22+）
node scripts/check-site.mjs
要同时提交源文件和生成文件，并预览受影响的桌面与手机页面。站点由 GitHub Actions 工作流（.github/workflows/deploy-modelscope.yml）从 GitHub 同步至魔搭创空间，以 main 为发布源，合入后自动构建部署。
四、核心用法
4.1 第一条路径：30 分钟看到第一个结果（第 07 章）
章节从魔搭 Notebook 入手，点模型库里的 Qwen/Qwen3-ASR-1.7B → "Notebook 快速开发" → "连接运行时"（选 GPU 实例），然后在 notebook 里依次检查环境：
!python3 --version # Python 版本
!pip3 show qwen-asr # 查依赖（缺失则 !pip3 install -U qwen-asr）
!lscpu # CPU 配置
!nvidia-smi # GPU 与显存
!free -h # 内存
!df -h # 磁盘
按模型名直接加载（会自动下载模型文件）：
import torch
from qwen_asr import Qwen3ASRModel
model = Qwen3ASRModel.from_pretrained(
"Qwen/Qwen3-ASR-1.7B",
dtype=torch.bfloat16,
device_map="cuda:0",
# attn_implementation="flash_attention_2",
max_inference_batch_size=32, # Batch size 上限，-1 为不限；调小可避免 OOM
max_new_tokens=256, # 最大生成 token，长音频需调大
)
print("模型加载完成！")
先手动下载模型的话：
!pip3 install modelscope
!modelscope download --model Qwen/Qwen3-ASR-1.7B --local_dir /mnt/workspace/Qwen3-ASR-1.7B
然后把 from_pretrained 的参数换成本地路径即可。最后传入音频：
results = model.transcribe(
audio="https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/asr_en.wav",
language=None, # 设 "English" 可强制语言
)
print(results[0].language)
print(results[0].text)
章节配套代码与文件在魔搭 Gallery：https://www.modelscope.cn/gallery/liucong/54c2ca38-b797-43d1-97ab-4b9f569aaa95
4.2 按目标选路线（README 提供的五条）
| 学习目标 | 推荐顺序 | 学完能做什么 |
|---|---|---|
| 完成第一次模型推理 | 01 认识模型 → 05 定义任务 → 07 首次推理 | 换一份输入，观察输出与适用范围 |
| 让模型适应自己的数据 | 13 数据准备 → 14 轻量微调 → 16 效果评测 | 用同一组测试样本对比微调前后 |
| 搭建知识问答应用 | 05 定义任务 → 07 首次推理 → 20 企业知识问答 | 替换成自己的文档，检查检索与回答准确性 |
| 探索图像生成与定制 | 23 应用案例 → 24 图像 LoRA → 25 商品图 → 26 教学海报 | 为自己的素材设计一套生成/编辑流程 |
| 入门 Agent 应用开发 | 29 Agent 基础 → 30 MCP → 31 Skill → 35 巡检 Agent | 选第 32–34 章补练习，再完成一个小任务 |
4.3 核心方法论：先评再选
第 05 章教"把业务问题转换成模型任务问题"（定义输入输出与评估标准），第 06 章教"用 EvalScope 形成开源模型的第一份报告"。这两章合起来是全书的方法论内核：先定义评测，再选模型，而不是拿排行榜选模型。
4.4 推荐实践节奏
README 给的学习方法很具体，建议按 "检查环境 → 复现示例 → 替换输入 → 对比结果 → 记录问题" 推进——每次阅读都变成一次实践，而不是读完就走。
五、典型适用场景
- 新手系统性入门开源模型：从 01 看到 16，覆盖模型认知 → 选型 → 跑通 → 微调 → 评测的完整闭环。
- 应用工程师排查具体环节：数据不会准备看 13；微调效果差看 14 + 16；RAG 答不准看 20。
- 中文 AIGC 工作流：图像 LoRA 训练（24）、商品图生成与编辑（25）、Qwen-Image 本地部署做教学海报（26）。
- Agent 开发入门与进阶：MCP（30）、Skill（31）讲机制，32–34 讲具体工具上手，35 用 Penguin Harness 做产线巡检 Agent 并通过评测迭代优化，36 用 Qwen3 4B 搭 Mini AI Scientist 跑"提出假设→验证结论"的全流程。
- 端侧部署：第 11 章完整走了一遍"把微调后的 MiniCPM 装进手机"——LoRA 微调 → GGUF 量化 → Android 部署；第 21 章是 MiniCPM-V 手机巡检助手，含端侧图像推理、人工确认与离线同步。
- 贡献内容：勘误、可复现案例、评测对比、英文翻译认领都有明确入口（英文翻译走 Issue 认领流程）。
六、坑与注意
- "能读"不等于"能跑"：39 章里只有 31 章标 ✅ 可读，第 22 / 39 章是 🤝 共建入口（征集素材中），第 27 章（AI 视频）标 🚧 待更新。按路线走时别把待更新章节当成完整教程。
- 阅读与实操是两套依赖：起静态站只要 Python 3 + 浏览器，但每章示例的依赖各不相同——第 07 章明确要求先看模型卡片确认推理依赖（本例是
qwen-asr），漏装就在加载时才炸。 - 显存是隐性门槛：第 07 章的示例直接
device_map="cuda:0"+torch.bfloat16，bf16 与 FlashAttention 对硬件有要求；max_inference_batch_size注释也明说"调小可避免 OOM"。本地没有 N 卡就别硬抄，第 09 章的 Ollama 路线更适合纯 CPU 起步。 - 仓库是「构建生成物 + 源文件」双份：直接改
content/chapters/会被下次构建覆盖。正确改法是改content/source-html/，然后跑三条构建校验命令，并同时提交源文件与生成文件。漏了生成文件，线上站点不更新。 - 校验脚本要求 Node.js 22+：
node scripts/build-content.mjs --check与node scripts/check-site.mjs对 Node 版本有硬要求，低版本会失败（而构建本身只要 Python 3）。 - 示例里的模型/数据集各有各的许可证：仓库本身是 Apache-2.0，但书里引用的模型、数据集、工具适用各自许可证与使用条款，商用前要逐个核。
- 图片与附件的版权不在仓库：README 明确"正文图片和附件的权利归原作者或相应权利人所有"。
- 在线站点与 GitHub 可能短暂不同步：站点由 Actions 从
main同步，"通常需要几分钟"。刚合入的改动在站上可能还没出现，别以为提交失败了。 - 共建者人数是两份名单相加：README 写明"当前 13 + 4 = 17，不跨平台推断同一身份"——这个数字是名单条目数，不是去重人数。
- 第三方依赖各有其许可证：KaTeX（MIT）、Remix Icon（Apache 2.0）、Noto Serif SC（SIL OFL 1.1）、"搭搭"形象（MIT），仓库里都有对应的 LICENSE/NOTICE 文件。
- ⚠️ 待补：本次未逐章核验 39 章正文的具体代码片段与版本号（各章依赖如 ms-swift / EvalScope / DiffSynth 的版本浮动未在 README 汇总表里给出）；第 07 章代码已实读核对，其余章节的 API 与参数请以章节正文与对应工具的官方文档为准。
- ⚠️ 评测口径："主流 LLM 评测"（第 39 章）本身是共建入口状态，且书中的评测结论多在特定模型与任务设定下得出，跨章节引用数字时注意口径与年份标注。
七、与同类对比
| 资源 | 形态 | 覆盖广度 | 深度 | 语言 | 适合谁 |
|---|---|---|---|---|---|
| ms-cookbook（紫皮书） | 教程仓库 + 静态站 | 8 篇 39 章，选型→推理→微调→评测→应用全链路 | 中（章节级示例可复制） | 中文为主（README_EN.md 提供英文版） | 中文开发者、需要体系化学习路径 |
| HF Learn / smol-course | 官方课程 | 偏模型原理与训练 | 中高 | 英文 | 偏原理与训练的研究者 |
| LLaMA-Factory / ms-swift 官方文档 | 单项目文档 | 只覆盖自己的工具 | 高（参数级） | 中/英 | 已经在用某个微调框架 |
| Datawhale 开源教程 | 系列教程 | 按主题分散在多个仓库 | 中高 | 中文 | 需要某一垂直主题的深度笔记 |
| 各模型 README / Model Card | 卡片 | 单模型 | 高（该模型） | 多语 | 已经在用某个具体模型 |
| 官方博客 / 直播课 | 视频与文章 | 碎片化 | 中 | 中文 | 碎片时间学习 |
差异化优势：它是中文世界里少见的"教科书级"完整编排——不是一堆零散笔记，而是有明确学习顺序、有推荐路径表、有从第 01 章到第 39 章的可追踪体系，并且每个场景都落到能复现的真实任务上。配套工具（EvalScope / ms-swift / DiffSynth）也都是魔搭自家生态，读完书顺手就把工具链摸熟了。
八、一句话推荐
想用中文把"开源模型从选型到上线"这条路走通一遍，ms-cookbook 是最省心的入口——但它是教程不是工具，第 27 章仍待更新、各章依赖版本会漂，别把它当可直接调用的 SDK 用。