ms-swift零基础学习教材

ms-swift 零基础学习教材：从推理到 LoRA 微调与部署

适合刚开始学习 AI 和编程的。你不需要一次看懂全部内容，也不需要死记参数。
第一次只完成“第 0 关 → 第 1 关 → 第 2 关”；成功后再学习自定义数据和参数调节。

本文依据 2026 年 8 月 24 日可见的 ms-swift 4.x 官方文档整理。框架、模型和依赖会更新，若命令失效，请以文末官方文档为准。

0. 先知道自己在做什么

0.1 一句话认识 ms-swift

ms-swift 是 ModelScope 社区提供的大模型训练、微调、推理、评测、量化和部署工具。

你可以把大语言模型想象成一名已经读过很多书的学生：

• 推理（inference）：向这名学生提问，让它回答。
• 监督微调（SFT）：拿“问题—标准答案”练习册继续教它。
• LoRA：不重写整本大脑，只训练一小组“外挂笔记”，花费更少显存。
• 部署（deploy）：把模型变成一个可以由其他程序访问的服务。
• 量化（quantization）：降低数字精度，让模型更小、更省显存，代价可能是少量能力损失。
• checkpoint：训练过程中的存档点，类似游戏存档。

ms-swift 的包名是ms-swift，但安装后使用的命令是swift。它和 Apple 的 Swift 编程语言不是一回事。

0.2 这份教材的学习路线

准备 Python 环境 ↓ 用原始模型聊天（推理） ↓ 准备少量 JSONL 教学数据 ↓ 用 LoRA 做 SFT 微调 ↓ 加载 LoRA 检查效果 ↓ 部署成 OpenAI 兼容接口

0.3 先接受三个现实

1. 大模型很吃硬件。普通电脑能学习命令和运行小模型，但训练较大模型通常需要 NVIDIA GPU 或云 GPU。
2. 第一次成功比第一次完美重要。先用小模型、少量数据、1 个 epoch 跑通全流程。
3. 微调不是给模型灌入百科知识的万能办法。想让模型准确查询大量、经常变化的资料，很多时候 RAG（检索增强生成）比微调更合适。

1. 硬件与系统：先选适合你的路线

路线 A：NVIDIA GPU（最适合训练）

推荐 Linux + NVIDIA GPU。先检查：

nvidia-smi

如果能看到显卡名称、显存和 CUDA 信息，说明驱动基本可用。显存越大，能使用的模型、序列长度和批量越大。

大致理解模型规模：0.6B约为 6 亿参数，4B约为 40 亿参数。参数越多，通常资源需求越大。实际显存还受精度、序列长度、优化器、注意力实现等影响，不能只靠参数量精确计算。

路线 B：Apple 芯片 Mac（适合入门推理和小实验）

PyTorch 可使用 MPS，但 CUDA、flash_attn、vLLM 和部分量化/训练功能是 NVIDIA 路线，不能照搬。建议：

• 先用较小模型做swift infer；
• 训练时从极小模型、短序列和很少数据开始；
• 遇到算子不支持或内存不足时，转到 NVIDIA 云 GPU；
• 不要设置CUDA_VISIBLE_DEVICES。

路线 C：只有 CPU（适合理解流程）

可以安装、查看帮助、处理数据，也可能运行很小的模型，但速度通常很慢，不建议把 CPU 当作正式训练设备。

安全提醒：租云 GPU 会产生费用。设置预算和自动关机；训练结束后停止实例。不要把平台 Token、API Key 写进公开代码或提交到 Git。

2. 创建干净的 Python 环境

官方 4.x 主线要求 Python 至少 3.10，官方当前推荐 Python 3.12。下面二选一。

2.1 使用 Conda

conda create-nms-swift-studypython=3.12-yconda activate ms-swift-study python--version

以后每次打开新终端，都先执行：

conda activate ms-swift-study

2.2 使用 uv

在一个专门的练习文件夹内执行：

mkdirms-swift-studycdms-swift-study uv venv--python3.12source.venv/bin/activate

Windows PowerShell 激活命令是：

.venv\Scripts\Activate.ps1

如果没有uv，可先按 uv 官方说明安装；也可以使用上一节 Conda 路线。

3. 安装 ms-swift 并做体检

3.1 常规安装

python-mpipinstall-Ums-swift

如果正在使用 uv 创建的环境，也可按官方推荐：

uv pipinstall-Ums-swift --torch-backend=auto

不要一开始安装全部可选依赖。需要评测、DeepSpeed、vLLM 时再安装对应组件，可以减少冲突。

3.2 检查是否成功

swift--helpswift sft--helppython-c"import torch; print('PyTorch:', torch.__version__); print('CUDA可用:', torch.cuda.is_available()); print('MPS可用:', torch.backends.mps.is_available() if hasattr(torch.backends, 'mps') else False)"

看到swift的帮助文字，就说明命令已安装。再记录环境，方便排错：

python--versionpython-mpip show ms-swift torch transformers

3.3 下载来源

ms-swift 默认从 ModelScope 下载模型和数据集。若要从 Hugging Face 下载，在命令后增加：

--use_hftrue

第一次运行会下载模型，可能需要较多时间和磁盘。--model既可以是 Hub 上的模型 ID，也可以是已经下载好的本地模型目录。

4. 第 1 关：先让原始模型回答问题

第一次请选小模型。下面以Qwen/Qwen3-0.6B为学习示例；若官方支持列表或模型页面发生变化，请换成当前受支持的小型指令模型。

NVIDIA 单卡

CUDA_VISIBLE_DEVICES=0swift infer\--modelQwen/Qwen3-0.6B\--infer_backendtransformers\--streamtrue\--temperature0\--max_new_tokens256

Mac 或 CPU

去掉第一行环境变量：

swift infer\--modelQwen/Qwen3-0.6B\--infer_backendtransformers\--streamtrue\--temperature0\--max_new_tokens256

进入交互模式后输入：

请用高中生能理解的语言解释什么是神经网络。

常用交互命令：

• clear：清空对话历史；
• reset-system：重置系统提示词和历史；
• multi-line：进入多行输入模式，以#结束；
• single-line：回到单行模式；
• quit或exit：退出。

参数解释：

• --model：模型 ID 或本地目录；
• --infer_backend transformers：使用兼容性最好的 Transformers 推理后端；
• --stream true：像打字一样逐步输出；
• --temperature 0：回答更稳定；
• --max_new_tokens 256：最多生成 256 个新 token，不等于 256 个汉字。

如果这一步失败，先不要训练。把推理环境解决好再继续。

可选：浏览器聊天界面

swift app\--modelQwen/Qwen3-0.6B\--infer_backendtransformers\--streamtrue\--max_new_tokens256

完整训练 Web UI 可启动：

swift web-ui

命令行更适合学习参数和复现，因此本教材以命令行为主。

5. 第 2 关：认识训练数据

5.1 SFT 数据在教什么

每条数据都像一道带标准答案的题：

{"messages":[{"role":"user","content":"1+1等于几？"},{"role":"assistant","content":"1+1等于2。"}]}

• user：用户说的话；
• assistant：希望模型学习的答案；
• system：可选，规定身份、风格或规则。

5.2 创建data/train.jsonl

JSONL 的规则是：一行一个完整 JSON 对象，不是在最外层套一个大数组。

{"messages":[{"role":"system","content":"你是一名耐心的高中数学助教，分步骤回答。"},{"role":"user","content":"什么是一元二次方程？"},{"role":"assistant","content":"只含一个未知数，并且未知数的最高次数是2的整式方程，叫作一元二次方程。一般形式是 ax²+bx+c=0，其中 a≠0。"}]} {"messages":[{"role":"system","content":"你是一名耐心的高中数学助教，分步骤回答。"},{"role":"user","content":"如何解方程 x²-5x+6=0？"},{"role":"assistant","content":"第1步，因式分解：x²-5x+6=(x-2)(x-3)。第2步，令每个因式为0：x-2=0或x-3=0。因此 x=2 或 x=3。"}]} {"messages":[{"role":"system","content":"你是一名耐心的高中数学助教，分步骤回答。"},{"role":"user","content":"判别式有什么用？"},{"role":"assistant","content":"对 ax²+bx+c=0，判别式 Δ=b²-4ac。Δ>0 时有两个不相等实根；Δ=0 时有两个相等实根；Δ<0 时没有实根。"}]}

真实训练不要只用 3 条；这是检查格式的最小样例。高质量的几十至几百条数据比大量错误、矛盾、机械重复的数据更值得尝试。

5.3 数据检查清单

• 每一行能单独通过 JSON 解析；
• 使用 UTF-8 编码；
• messages存在且是列表；
• 对话角色顺序合理；
• 最后有要学习的assistant答案；
• 答案正确、清晰、风格一致；
• 不含密码、身份证号、私人聊天等敏感信息；
• 训练集和测试问题不要完全重复。

快速检查 JSONL：

python-c"import json; p='data/train.jsonl'; rows=[json.loads(x) for x in open(p, encoding='utf-8') if x.strip()]; print('有效行数:', len(rows)); print(rows[0])"

ms-swift 也能自动识别常见的query/response、Alpaca、ShareGPT 格式，但初学阶段建议统一使用官方标准messages格式。

6. 第 3 关：第一次 LoRA 微调

先做“冒烟测试”：目标只是验证整个流程能跑通，不追求模型立刻变强。

6.1 NVIDIA GPU 入门命令

CUDA_VISIBLE_DEVICES=0swift sft\--modelQwen/Qwen3-0.6B\--tuner_typelora\--datasetdata/train.jsonl\--split_dataset_ratio0.1\--torch_dtypebfloat16\--num_train_epochs1\--per_device_train_batch_size1\--per_device_eval_batch_size1\--gradient_accumulation_steps8\--learning_rate1e-4\--lora_rank8\--lora_alpha32\--lora_dropout0.05\--target_modulesall-linear\--max_length512\--warmup_ratio0.05\--logging_steps1\--eval_steps10\--save_steps10\--save_total_limit2\--output_diroutput/qwen3-0_6b-math-lora

如果显卡不支持 BF16，把：

--torch_dtypebfloat16

换成：

--torch_dtypefloat16

6.2 极小数据的注意事项

只有 3 条数据时，--split_dataset_ratio 0.1可能无法得到有意义的验证集。冒烟测试可以暂时改为：

--split_dataset_ratio0

并删除--per_device_eval_batch_size、--eval_steps。正式实验建议准备足够数据，或用独立文件：

--datasetdata/train.jsonl\--val_datasetdata/val.jsonl

验证集用来检查模型是否只会背训练题。它不参与参数更新。

6.3 训练结束后去哪里找结果

output/qwen3-0_6b-math-lora下通常会出现一次运行目录和若干checkpoint-数字目录。日志会打印实际路径。

LoRA checkpoint 主要保存“增量适配器”，不是一份完整基础模型。不要随便移动其中的args.json等文件；ms-swift 推理时会用它们恢复训练配置。

7. 第 4 关：加载训练结果并比较

把下面路径换成你的真实 checkpoint：

swift infer\--adaptersoutput/qwen3-0_6b-math-lora/vx-xxx/checkpoint-xxx\--infer_backendtransformers\--streamtrue\--temperature0\--max_new_tokens256

--adapters指向 LoRA checkpoint。因为目录里有args.json，通常不用重复写--model。若不想自动加载保存的参数，可显式设置--load_args false，但初学时不建议。

请用完全相同的问题比较：

1. 原始基础模型；
2. 微调后的模型；
3. 训练集中没出现过、但类型相似的问题。

不要只凭“感觉不错”判断。准备固定测试题并记录：正确性、格式、是否啰嗦、是否编造、响应速度。

8. 最常用参数：意思、影响和建议

8.1 模型与数据

Hub 数据集还支持：

--dataset'数据集ID:子集#采样数'

例如#500表示采样 500 条，适合冒烟测试。多个数据集可在--dataset后依次写多个值。

8.2 训练规模与显存

SFT 中常用的有效总 batch size：

总 batch size = 每卡 batch size × 梯度累积步数 × GPU 数量

例：1 × 8 × 1 = 8。显存不足时，通常先保持每卡 batch 为 1，再用梯度累积获得更大的有效 batch。

8.3 学习过程

学习率过大，loss 可能剧烈震荡、出现 NaN 或能力被破坏；过小则几乎学不到。一次只改变一个关键参数，并记录结果。

8.4 LoRA 参数

不要把rank理解成“越大越好”。rank 太大意味着更多可训练参数、更多显存，也可能让小数据更容易过拟合。

8.5 日志、验证与保存

如果总训练只有 8 step，却设置save_steps=100，中途当然不会出现第 100 步存档。先观察日志中的总 step 数。

8.6 推理生成参数

max_length多用于限制输入/训练样本长度；max_new_tokens限制新生成内容长度。两者不要混淆。

9. 显存不足（CUDA out of memory）怎么处理

按照这个顺序，每改一项就重试：

1. 降低--max_length，例如2048 → 1024 → 512；
2. 把--per_device_train_batch_size设为 1；
3. 适当增加--gradient_accumulation_steps保持有效 batch；
4. 换更小的模型；
5. 使用 LoRA，不要全参数训练；
6. 确认没有其他程序占用 GPU（用nvidia-smi查看）；
7. 在理解兼容性后再学习 QLoRA、DeepSpeed、FlashAttention、序列打包。

不要把几十个优化开关一次全打开，否则失败时很难知道是哪一个造成的。

10. 用 YAML 管理参数：比超长命令更清楚

创建configs/sft_lora.yaml：

model:Qwen/Qwen3-0.6Btuner_type:loradataset:-data/train.jsonlsplit_dataset_ratio:0.1torch_dtype:bfloat16num_train_epochs:1per_device_train_batch_size:1per_device_eval_batch_size:1gradient_accumulation_steps:8learning_rate:0.0001warmup_ratio:0.05max_length:512lora_rank:8lora_alpha:32lora_dropout:0.05target_modules:-all-linearlogging_steps:1eval_steps:10save_steps:10save_total_limit:2output_dir:output/qwen3-0_6b-math-lora

运行：

swift sft configs/sft_lora.yaml

还可以临时覆盖一个值：

swift sft configs/sft_lora.yaml--num_train_epochs2

好习惯：每个实验复制一份配置，文件名写清变化，如sft_rank16.yaml，并记录结果。

11. 部署成一个 API

11.1 兼容性优先的部署

swift deploy\--adaptersoutput/qwen3-0_6b-math-lora/vx-xxx/checkpoint-xxx\--infer_backendtransformers\--served_model_namemath-helper\--host127.0.0.1\--port8000\--temperature0\--max_new_tokens256

这里使用127.0.0.1，只允许本机访问，比直接开放到局域网或公网更安全。若需要对外提供服务，应设置鉴权、防火墙、限流和日志脱敏。

11.2 用 curl 调用

另开一个终端：

curlhttp://127.0.0.1:8000/v1/chat/completions\-H"Content-Type: application/json"\-d'{ "model": "math-helper", "messages": [ {"role": "user", "content": "请分步骤解方程 x²-7x+12=0"} ], "max_tokens": 256, "temperature": 0 }'

服务端参数--max_new_tokens和 OpenAI 兼容请求中的max_tokens都在限制生成长度，具体请求值可以比服务端上限更小。

11.3 vLLM 是什么时候学的

vLLM 能提高吞吐，适合 NVIDIA GPU 部署，但要额外安装，并且对 CUDA、PyTorch、模型和量化方式有兼容要求。初学先用transformers；流程稳定后，再按官方版本表安装 vLLM 并设置：

--infer_backendvllm

QLoRA 适配器不能直接按所有 vLLM LoRA 场景处理；请以当前官方推理后端兼容表为准。

12. 合并、导出与发布

LoRA 可在推理时单独加载，也可以与基础模型合并。官方当前支持在推理时用--merge_lora true，或通过导出流程处理。合并会生成体积更大的完整权重，需要额外磁盘和内存。

发布到 ModelScope 的官方命令形式：

swiftexport\--adaptersoutput/qwen3-0_6b-math-lora/vx-xxx/checkpoint-xxx\--push_to_hubtrue\--hub_model_id'<你的模型ID>'\--hub_token'<你的Token>'\--use_hffalse

安全做法：不要把真实 Token 保存进.md、脚本或 Git 历史。先检查基础模型许可证、数据许可证和隐私要求，再决定是否公开。

13. 进阶地图：现在只需认识名字

• 全参数 SFT：训练所有参数，资源和数据要求更高。
• QLoRA：量化基础模型后训练 LoRA，进一步省显存，但兼容性更复杂。
• DPO/KTO/GRPO 等：偏好学习或强化学习，不是零基础第一课。
• DeepSpeed/FSDP/Megatron：多卡或大规模训练技术。
• vLLM/SGLang/LMDeploy：推理加速后端，各自兼容性不同。
• AWQ/GPTQ/BNB/FP8：不同量化方法。
• EvalScope：模型评测工具。
• 多模态微调：数据还包含images、videos、audios等字段，资源需求更大。

推荐顺序：LoRA SFT → 可靠评测 → 部署 → QLoRA/量化 → 多卡训练 → 偏好或强化学习。

14. 常见报错排查

swift: command not found

可能没激活正确环境，或包装到了另一个 Python：

whichpythonwhichswift python-mpip show ms-swift

Windows 使用：

where python where swift

模型或数据下载失败

• 检查网络和磁盘空间；
• 确认模型 ID 拼写；
• ModelScope 不通时尝试--use_hf true，反之亦然；
• 私有/受限模型需要先在对应平台授权和登录；
• 不要重复中断大文件下载。

CUDA out of memory

按第 9 章的顺序缩小训练配置，并用nvidia-smi查看占用。

BF16 不支持或出现 NaN

换成--torch_dtype float16，或使用支持 BF16 的 GPU。若仍出现 NaN，再检查学习率、数据异常和依赖版本。

数据被丢弃或提示格式错误

先用 2～3 条数据测试，并增加：

--stricttrue

它会让错误样本直接报错，便于找到坏行。检查 JSON、角色顺序、空答案和超长样本。默认truncation_strategy=delete时，超过max_length的训练样本可能被删除。

训练没有明显效果

• 数据太少或答案质量低；
• 训练问题与测试问题差别太大；
• 学习率太低或训练步数太少；
• 模型太小，任务超过其能力；
• 只测试了训练原题，误把背诵当泛化；
• 生成参数不同，比较不公平。

训练后能力变差

• 数据单一、错误或相互矛盾；
• 学习率过大；
• epoch 太多导致过拟合；
• 训练模板或模型类型不匹配；
• 没有保留通用能力相关的数据。

15. 怎样做一次像样的小实验

准备一张实验记录表：

科学实验的核心是：

1. 固定一组测试题；
2. 每次只改一个主要变量；
3. 保存配置、日志和 checkpoint；
4. 同时记录成功与失败；
5. 不用训练集原题冒充测试集成绩。

15.1 loss 怎么看

loss 是模型答案与标准答案差距的数学度量。通常训练 loss 下降说明正在拟合数据，但它不是最终成绩：

• 训练 loss 下降、验证效果也提高：通常是好现象；
• 训练 loss 继续下降、验证效果变差：可能过拟合；
• loss 不动：检查数据、可训练参数、学习率；
• loss 突然 NaN：检查精度、学习率、异常数据和依赖。

不要比较不同数据、不同模板下 loss 的绝对数值后直接下结论。

16. 一周入门计划

第 1 天：终端与环境

• 学会cd、ls、pwd；
• 创建 Python 环境；
• 成功运行swift --help。

第 2 天：模型推理

• 跑通一个小模型；
• 理解 model、token、temperature、max_new_tokens。

第 3 天：数据

• 手写 10 条 JSONL；
• 用 Python 检查解析；
• 区分训练集与验证集。

第 4 天：LoRA

• 用 10～50 条数据跑冒烟测试；
• 找到 checkpoint；
• 看懂 loss 和 step。

第 5 天：比较

• 准备 20 个固定问题；
• 比较原始模型和微调模型；
• 记录失败案例。

第 6 天：参数实验

• 只改变 epoch 或 learning_rate；
• 使用 YAML 保存配置；
• 比较实验结果。

第 7 天：部署

• 启动本地 API；
• 用 curl 调用；
• 写一页学习总结。

17. 最小速查表

# 安装python-mpipinstall-Ums-swift# 看帮助（这是查当前版本参数最可靠的方法之一）swift--helpswift sft--helpswift infer--helpswift deploy--help# 原始模型推理swift infer--modelQwen/Qwen3-0.6B--infer_backendtransformers# LoRA 微调swift sft\--modelQwen/Qwen3-0.6B\--tuner_typelora\--datasetdata/train.jsonl\--max_length512\--per_device_train_batch_size1\--gradient_accumulation_steps8\--learning_rate1e-4\--lora_rank8\--lora_alpha32\--target_modulesall-linear\--num_train_epochs1\--output_diroutput/my-first-lora# LoRA 推理（替换真实路径）swift infer--adaptersoutput/.../checkpoint-...--temperature0# 本地部署（替换真实路径）swift deploy\--adaptersoutput/.../checkpoint-...\--infer_backendtransformers\--host127.0.0.1\--port8000

18. 官方资料与继续学习

优先看官方资料，因为命令和默认值会变化：

• ms-swift GitHub 与官方 README
• ms-swift 中文文档首页
• 安装说明
• 快速开始
• 命令行参数
• 自定义数据集
• 预训练与微调
• 推理与部署
• 支持的模型与数据集
• 官方 examples 目录

遇到问题时，提问要附上：操作系统、GPU 型号与显存、python --version、pip show ms-swift torch transformers、完整命令、报错最后 50 行、最小数据样例。不要附 Token 或隐私数据。

结语

学习 AI 不是智力竞赛，而是把大问题拆成小问题、不断得到反馈的过程。你第一次的目标只有四个：

1. swift --help能运行；
2. 小模型能回答一句话；
3. 3 条 JSONL 能被正确读取；
4. LoRA 冒烟测试能生成 checkpoint。

做到这四点，你已经完成了一个真实的大模型微调闭环。接下来不是“我会不会”，而只是“我准备把哪一步练得更熟”。