ms-swift零基础学习教材

ms-swift 零基础学习教材从推理到 LoRA 微调与部署适合刚开始学习 AI 和编程的。你不需要一次看懂全部内容也不需要死记参数。第一次只完成“第 0 关 → 第 1 关 → 第 2 关”成功后再学习自定义数据和参数调节。本文依据 2026 年 8 月 24 日可见的 ms-swift 4.x 官方文档整理。框架、模型和依赖会更新若命令失效请以文末官方文档为准。0. 先知道自己在做什么0.1 一句话认识 ms-swiftms-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 先接受三个现实大模型很吃硬件。普通电脑能学习命令和运行小模型但训练较大模型通常需要 NVIDIA GPU 或云 GPU。第一次成功比第一次完美重要。先用小模型、少量数据、1 个 epoch 跑通全流程。微调不是给模型灌入百科知识的万能办法。想让模型准确查询大量、经常变化的资料很多时候 RAG检索增强生成比微调更合适。1. 硬件与系统先选适合你的路线路线 ANVIDIA GPU最适合训练推荐 Linux NVIDIA GPU。先检查nvidia-smi如果能看到显卡名称、显存和 CUDA 信息说明驱动基本可用。显存越大能使用的模型、序列长度和批量越大。大致理解模型规模0.6B约为 6 亿参数4B约为 40 亿参数。参数越多通常资源需求越大。实际显存还受精度、序列长度、优化器、注意力实现等影响不能只靠参数量精确计算。路线 BApple 芯片 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 使用 Condaconda create-nms-swift-studypython3.12-yconda activate ms-swift-study python--version以后每次打开新终端都先执行conda activate ms-swift-study2.2 使用 uv在一个专门的练习文件夹内执行mkdirms-swift-studycdms-swift-study uv venv--python3.12source.venv/bin/activateWindows PowerShell 激活命令是.venv\Scripts\Activate.ps1如果没有uv可先按 uv 官方说明安装也可以使用上一节 Conda 路线。3. 安装 ms-swift 并做体检3.1 常规安装python-mpipinstall-Ums-swift如果正在使用 uv 创建的环境也可按官方推荐uv pipinstall-Ums-swift --torch-backendauto不要一开始安装全部可选依赖。需要评测、DeepSpeed、vLLM 时再安装对应组件可以减少冲突。3.2 检查是否成功swift--helpswift sft--helppython-cimport 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 transformers3.3 下载来源ms-swift 默认从 ModelScope 下载模型和数据集。若要从 Hugging Face 下载在命令后增加--use_hftrue第一次运行会下载模型可能需要较多时间和磁盘。--model既可以是 Hub 上的模型 ID也可以是已经下载好的本地模型目录。4. 第 1 关先让原始模型回答问题第一次请选小模型。下面以Qwen/Qwen3-0.6B为学习示例若官方支持列表或模型页面发生变化请换成当前受支持的小型指令模型。NVIDIA 单卡CUDA_VISIBLE_DEVICES0swift infer\--modelQwen/Qwen3-0.6B\--infer_backendtransformers\--streamtrue\--temperature0\--max_new_tokens256Mac 或 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:11等于几},{role:assistant,content:11等于2。}]}user用户说的话assistant希望模型学习的答案system可选规定身份、风格或规则。5.2 创建data/train.jsonlJSONL 的规则是一行一个完整 JSON 对象不是在最外层套一个大数组。{messages:[{role:system,content:你是一名耐心的高中数学助教分步骤回答。},{role:user,content:什么是一元二次方程},{role:assistant,content:只含一个未知数并且未知数的最高次数是2的整式方程叫作一元二次方程。一般形式是 ax²bxc0其中 a≠0。}]} {messages:[{role:system,content:你是一名耐心的高中数学助教分步骤回答。},{role:user,content:如何解方程 x²-5x60},{role:assistant,content:第1步因式分解x²-5x6(x-2)(x-3)。第2步令每个因式为0x-20或x-30。因此 x2 或 x3。}]} {messages:[{role:system,content:你是一名耐心的高中数学助教分步骤回答。},{role:user,content:判别式有什么用},{role:assistant,content:对 ax²bxc0判别式 Δb²-4ac。Δ0 时有两个不相等实根Δ0 时有两个相等实根Δ0 时没有实根。}]}真实训练不要只用 3 条这是检查格式的最小样例。高质量的几十至几百条数据比大量错误、矛盾、机械重复的数据更值得尝试。5.3 数据检查清单每一行能单独通过 JSON 解析使用 UTF-8 编码messages存在且是列表对话角色顺序合理最后有要学习的assistant答案答案正确、清晰、风格一致不含密码、身份证号、私人聊天等敏感信息训练集和测试问题不要完全重复。快速检查 JSONLpython-cimport json; pdata/train.jsonl; rows[json.loads(x) for x in open(p, encodingutf-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_DEVICES0swift 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_dtypefloat166.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 关加载训练结果并比较把下面路径换成你的真实 checkpointswift 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但初学时不建议。请用完全相同的问题比较原始基础模型微调后的模型训练集中没出现过、但类型相似的问题。不要只凭“感觉不错”判断。准备固定测试题并记录正确性、格式、是否啰嗦、是否编造、响应速度。8. 最常用参数意思、影响和建议8.1 模型与数据参数作用入门建议--modelHub 模型 ID 或本地模型目录先选 0.5B1.5B 量级的小模型跑通--use_hf true改用 Hugging Face 下载默认 ModelScope 可用时不必加--dataset一个或多个训练数据集 ID/路径自定义数据优先用 JSONL--val_dataset独立验证集正式实验推荐使用--split_dataset_ratio从训练集切出验证集的比例官方当前默认 0可从0.05或0.1开始--dataset_num_proc数据预处理进程数小数据用 1大文本数据可逐渐增加--columns把自定义列名映射到标准列名标准messages格式不需要--system命令行提供系统提示词数据里的 system 优先级更高Hub 数据集还支持--dataset数据集ID:子集#采样数例如#500表示采样 500 条适合冒烟测试。多个数据集可在--dataset后依次写多个值。8.2 训练规模与显存参数作用调大后通常怎样--max_length单条样本编码后的最大 token 数能容纳长文本但显存和计算量明显增加--per_device_train_batch_size每张卡一次放几条样本吞吐可能提高但更吃显存--gradient_accumulation_steps累积多少次小批量再更新少占峰值显存但每次更新等待更久--gradient_checkpointing用额外计算换显存更省显存但训练变慢实际默认行为依模型/版本检查--torch_dtype权重和计算精度BF16 通常更稳定硬件必须支持SFT 中常用的有效总 batch size总 batch size 每卡 batch size × 梯度累积步数 × GPU 数量例1 × 8 × 1 8。显存不足时通常先保持每卡 batch 为 1再用梯度累积获得更大的有效 batch。8.3 学习过程参数作用入门建议--num_train_epochs完整学习训练集几遍先 1再比较 23防止过拟合--learning_rate每次更新参数的步幅LoRA 常从1e-4起全参官方默认更低1e-5--warmup_ratio前多少比例逐渐升高学习率0.030.1示例用0.05--weight_decay对过大权重的惩罚不理解时先用默认值--lr_scheduler_type学习率如何随训练变化默认cosine通常可先保留--seed随机种子固定后更方便复现实验学习率过大loss 可能剧烈震荡、出现 NaN 或能力被破坏过小则几乎学不到。一次只改变一个关键参数并记录结果。8.4 LoRA 参数参数作用入门建议--tuner_type lora启用 LoRA 微调初学首选--target_modules all-linear给模型中的线性层挂 LoRA官方常用通用设置--lora_rankLoRA 容量官方当前默认 8先用 8复杂任务可试 16/32但更吃显存--lora_alphaLoRA 更新的缩放系数rank8 时先用 16 或 32官方示例用 32--lora_dropoutLoRA 分支随机丢弃比例当前默认 0.05小数据可保留 0.05别随意大改--lora_bias是否训练 bias先用默认none不要把rank理解成“越大越好”。rank 太大意味着更多可训练参数、更多显存也可能让小数据更容易过拟合。8.5 日志、验证与保存参数作用入门建议--logging_steps每隔多少 step 打印日志小实验 15大实验可更大--eval_steps每隔多少 step 验证应与总 step 数匹配--save_steps每隔多少 step 保存小实验 1050--save_total_limit最多保留几个 checkpoint23避免磁盘被占满--output_dir输出目录每个实验使用不同名字--report_to记录到 TensorBoard/WB 等当前官方默认 TensorBoard如果总训练只有 8 step却设置save_steps100中途当然不会出现第 100 步存档。先观察日志中的总 step 数。8.6 推理生成参数参数作用常见选择--temperature随机程度事实/数学用 00.2创作用 0.7 左右再观察--top_p只在累计概率较高的候选中采样常与 temperature 配合不必同时乱调--max_new_tokens最多生成多少新 token128、256、512 起步--stream true流式显示聊天时推荐--infer_backend推理后端初学用transformersmax_length多用于限制输入/训练样本长度max_new_tokens限制新生成内容长度。两者不要混淆。9. 显存不足CUDA out of memory怎么处理按照这个顺序每改一项就重试降低--max_length例如2048 → 1024 → 512把--per_device_train_batch_size设为 1适当增加--gradient_accumulation_steps保持有效 batch换更小的模型使用 LoRA不要全参数训练确认没有其他程序占用 GPU用nvidia-smi查看在理解兼容性后再学习 QLoRA、DeepSpeed、FlashAttention、序列打包。不要把几十个优化开关一次全打开否则失败时很难知道是哪一个造成的。10. 用 YAML 管理参数比超长命令更清楚创建configs/sft_lora.yamlmodel: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. 部署成一个 API11.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\-HContent-Type: application/json\-d{ model: math-helper, messages: [ {role: user, content: 请分步骤解方程 x²-7x120} ], max_tokens: 256, temperature: 0 }服务端参数--max_new_tokens和 OpenAI 兼容请求中的max_tokens都在限制生成长度具体请求值可以比服务端上限更小。11.3 vLLM 是什么时候学的vLLM 能提高吞吐适合 NVIDIA GPU 部署但要额外安装并且对 CUDA、PyTorch、模型和量化方式有兼容要求。初学先用transformers流程稳定后再按官方版本表安装 vLLM 并设置--infer_backendvllmQLoRA 适配器不能直接按所有 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可能没激活正确环境或包装到了另一个 Pythonwhichpythonwhichswift python-mpip show ms-swiftWindows 使用where python where swift模型或数据下载失败检查网络和磁盘空间确认模型 ID 拼写ModelScope 不通时尝试--use_hf true反之亦然私有/受限模型需要先在对应平台授权和登录不要重复中断大文件下载。CUDA out of memory按第 9 章的顺序缩小训练配置并用nvidia-smi查看占用。BF16 不支持或出现 NaN换成--torch_dtype float16或使用支持 BF16 的 GPU。若仍出现 NaN再检查学习率、数据异常和依赖版本。数据被丢弃或提示格式错误先用 23 条数据测试并增加--stricttrue它会让错误样本直接报错便于找到坏行。检查 JSON、角色顺序、空答案和超长样本。默认truncation_strategydelete时超过max_length的训练样本可能被删除。训练没有明显效果数据太少或答案质量低训练问题与测试问题差别太大学习率太低或训练步数太少模型太小任务超过其能力只测试了训练原题误把背诵当泛化生成参数不同比较不公平。训练后能力变差数据单一、错误或相互矛盾学习率过大epoch 太多导致过拟合训练模板或模型类型不匹配没有保留通用能力相关的数据。15. 怎样做一次像样的小实验准备一张实验记录表实验模型数据量max_lengthranklrepoch验证结果备注baseline原始模型0----记录 20 道题基线exp01Qwen 小模型10051281e-41待填写首次 LoRAexp02同上10051285e-51待填写只改 lr科学实验的核心是固定一组测试题每次只改一个主要变量保存配置、日志和 checkpoint同时记录成功与失败不用训练集原题冒充测试集成绩。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用 1050 条数据跑冒烟测试找到 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\--port800018. 官方资料与继续学习优先看官方资料因为命令和默认值会变化ms-swift GitHub 与官方 READMEms-swift 中文文档首页安装说明快速开始命令行参数自定义数据集预训练与微调推理与部署支持的模型与数据集官方 examples 目录遇到问题时提问要附上操作系统、GPU 型号与显存、python --version、pip show ms-swift torch transformers、完整命令、报错最后 50 行、最小数据样例。不要附 Token 或隐私数据。结语学习 AI 不是智力竞赛而是把大问题拆成小问题、不断得到反馈的过程。你第一次的目标只有四个swift --help能运行小模型能回答一句话3 条 JSONL 能被正确读取LoRA 冒烟测试能生成 checkpoint。做到这四点你已经完成了一个真实的大模型微调闭环。接下来不是“我会不会”而只是“我准备把哪一步练得更熟”。