Chapter 01
项目背景与定位
1.1 一句话定位
ms-swift（Scalable lightWeight Infrastructure for Fine-Tuning，又叫 Swift）是阿里巴巴达摩院魔搭社区（ModelScope）官方推出的、主打"200+ 大模型 / 多模态模型 一站式微调与部署"的开源框架。它的目标客户是国内开发者，尤其是已经在使用魔搭 Hub 的人——下载模型、加载数据集、训练、推理、部署，全部走魔搭一条龙。
ms-swift 在魔搭官方教程里被推荐为标准微调工具。它和 LLaMA-Factory 是中文圈最常被并列提到的两个微调框架，定位接近但侧重点不同。
1.2 为什么会有 ms-swift
阿里推 ModelScope 的策略是"中国版 HuggingFace"。但仅有模型下载平台不够，需要配套训练工具，于是有了 ms-swift。它的几个核心动机：
- 打通魔搭 Hub：HF Hub 在国内访问不稳定，魔搭需要自家平替。从 ms-swift 里下载模型，背后调用的就是 ModelScope SDK；
- 配合自家旗舰模型 Qwen：Qwen 系列需要一份"一等公民"待遇的微调框架；
- 覆盖多模态：除了文本，魔搭还在大力推多模态、语音、Agent；
- 国产化与云端集成：阿里云 DSW、PAI、灵积、百炼这些产品都希望有 swift 作为底层训练引擎。
1.3 它和 LLaMA-Factory 的对比
| 维度 | ms-swift | LLaMA-Factory |
|---|---|---|
| 维护方 | 阿里魔搭官方 | 个人 + 社区 |
| 模型 Hub | ModelScope 优先 | HF Hub 优先 |
| Qwen 系适配 | 第一时间 + 深度 | 同样及时但不如官方深度 |
| Web UI | 有，但更偏 CLI | Web UI 是核心入口 |
| 多模态深度 | 强（Qwen-VL 系深度集成） | 强（LLaVA / Qwen-VL 系） |
| 阿里云生态 | 一等公民 | 不深度绑定 |
| 入门难度 | 中（命令行参数多） | 低（WebUI 直观） |
经验法则：用过 ModelScope SDK / 在阿里云做训练 / 想第一时间用最新 Qwen 优化，用 ms-swift；不在乎云平台、想 GUI 入门、做中文行业模型，用 LLaMA-Factory。
1.4 设计哲学：以模型为中心 + 命令行优先
- 仓库里有
swift/llm/model/目录，给每一种支持的模型都注册了ModelType； - 每个模型对应一份对话模板（
Template），处理 prompt 拼接、多模态 token 占位、tool use 格式等； - 调用入口是统一的
swift sft/swift rlhf/swift infer命令行； - 故意把 CLI 设计得很 verbose：一条命令几十个
--xxx，让"所有可调项都是显式的"。这种风格对老练用户友好，对新手稍重。
1.5 它适合用来做什么、不适合做什么
| 判断 | 典型场景 |
|---|---|
| ✅ 适合 | 微调 Qwen 全家桶（Qwen2.5、Qwen3、Qwen2-VL、Qwen-Audio 等） |
| 国内网络下做训练，希望模型与数据集都从魔搭拉 | |
| 多模态微调（视觉 / 语音 / Agent） | |
| 阿里云 DSW / PAI 上做训练任务调度 | |
| 想用命令行写 reproducible 训练脚本而不是 WebUI | |
| ❌ 不适合 | 完全 HF 生态、不想引 ModelScope 依赖 |
| 想用 GUI 拖拽训练 —— LLaMA-Factory 更顺手 | |
| 千亿参数预训练 |
1.6 本书将怎么带你走完这趟旅程
- 第 2-3 章装好环境、跑通第一个
swift sft命令； - 第 4 章讲清楚 ModelType / Template / Dataset 三大核心抽象；
- 第 5 章给出"完整命令行参数地图"；
- 第 6-8 章逐个剖析 SFT、DPO/KTO/GRPO、PEFT 各算法、多模态训练；
- 第 9 章讲 ms-swift 中集成 Megatron 后端、做多机训练；
- 第 10-12 章推理、量化、阿里云部署的实战；
- 第 13 章给出
swiftCLI 调度链的源码地图。
1.7 ms-swift 2024–2026 时间线
本书基线 commit b58b1bd（2026-05-26）。README "🔥 News" 把过去两年的演进交代得很完整：
| 时间 | 特性 | 说明 | 本书章节 |
|---|---|---|---|
| 2026-03 | ms-swift v4.0 | 重大重构，目录扁平化（swift/llm/* → swift/*） | ch13 |
| 2025-11 | Megatron GRPO + mcore-bridge | HF ↔ Megatron 双向转换 | ch09 |
| 2025-10 | Ray 分布式训练（MegatronRayPipeline） | train/rollout 分集群编排 | ch09 / ch12 |
| 2025-09 | CHORD 训练算法 + Ulysses + Ring SP | 无限长 seq 切分；CHORD 新策略 | ch06.10 / ch09.7 |
| 2025-09 | Megatron 多模态训练 | Megatron 路径下 VLM 支持 | ch08 / ch09 |
| 2025-08 | Dynamic Fine-Tuning (DFT) loss | SFT 时按 token-level 动态加权 | ch06.5 |
| 2025-07 | Megatron LoRA | MoE LoRA 训练加速 | ch09.5 |
| 2025-06 | Reranker 微调 + GKD（生成式 KD） | Reranker / 蒸馏一等公民 | ch06.9 |
| 2025-06 | Megatron RLHF | Megatron 后端跑 DPO / PPO / GRPO | ch09.4 |
| 2025-05 | Sequence parallel（pretrain/SFT/DPO/GRPO） | 全栈 SP，长 CoT 必需 | ch09.7 |
| 2025-04 | AAAI 2025 论文录用 | ms-swift 系统论文 | — |
| 2025-03 | 多轮 GRPO（agent 工具调用） | RL 训练 tool-use | ch08.6 |
| 2025-03 | Megatron 5D 并行（TP/PP/CP/EP/VPP）全栈 | v3.16+；MoE 性能跳跃 | ch09.3 |
| 2025-03 | Embedding / Reranker 文本与多模态微调 | — | ch06.8 |
| 2024-12 | ms-swift v3.0 | 架构重构，统一 Pipeline 风格 | — |
| 2024-08 | arXiv 论文（2408.05517）+ EvalScope 集成 | 评测一站式 | ch10.7 |
| 2024-07 | vLLM + LMDeploy 推理 + 多模态偏好对齐 | 5 个 infer engine 雏形 + VLM RLHF | ch10 / ch08.4 |
| 2024-02 | Agent 训练支持 | ReAct / function-calling 模板 | ch08.6 / ch12.4 |
1.8 支持矩阵（700+ LLM / 400+ VLM）
README 公开的官方支持名单（截至本书基线）：
| 类别 | 代表模型 | 数量 |
|---|---|---|
| 纯文本 LLM | Qwen3 / Qwen3.5 / GLM4.5 / DeepSeek-R1 / Llama4 / InternLM3 / Mistral / Yi / Baichuan ... | 600+ |
| 视觉 / 多模态 | Qwen3-VL / Qwen3-Omni / InternVL3.5 / GLM4.5-V / MiniCPM-V-4 / Ovis2.5 / DeepSeek-VL2 / Llava-Next / Llama4-VL ... | 400+ |
| Embedding / Reranker | modern-bert-gte / bge-reranker / Qwen3-VL-Reranker | 10+ |
| Reward Model | internlm2-reward / qwen2-reward / llama3.2-reward | 5+ |
"我的模型 swift 支不支持？" → 先 grep swift/model/constant.py，再查 swift/model/model/<family>.py（每个模型族独立文件注册）。详细机制在 ch04。
1.9 与 verl / TRL / LLaMA-Factory 的关系
ms-swift 在 2025-2026 已经横跨了几乎所有同类工具的能力范围。具体取舍：
| 维度 | ms-swift | LLaMA-Factory | TRL | verl / OpenRLHF |
|---|---|---|---|---|
| 模型注册数 | 700+ LLM / 400+ VLM | 100+ | 跟 transformers | 跟 HF |
| Megatron 后端 | ★★★★（自家 mcore-bridge） | ★★（2025 末刚集成） | — | ★★★★（verl 内嵌） |
| GRPO 算法变种 | ★★★★★（DAPO/GSPO/SAPO/CISPO/CHORD/RLOO/R++） | ★★（EasyR1） | ★★★★（基本款） | ★★★★（PPO/GRPO/REINFORCE++） |
| 多模态 RLHF | ★★★★★（Qwen-VL / Omni 一等） | ★★★★（多 VLM） | ★★★（基础） | ★★★（verl-omni 独立仓） |
| WebUI | 有（7 tab） | 有（LLaMA Board） | 无 | 无 |
| 云生态绑定 | 阿里云 DSW / PAI 一等公民 | 无 | 无 | 火山引擎 / 字节 |