ms-swift新手福音：命令行参数傻瓜式说明
1. 为什么你需要这份参数指南
你是不是也遇到过这些情况？
- 看到
swift sft命令后面跟着一长串参数，眼睛发花，不知道从哪下手 - 想微调一个模型，但卡在
--target_modules all-linear这种术语上，查文档又太慢 - 复制粘贴别人给的命令，改了模型ID却报错“找不到dataset”，折腾半小时没跑通
- 明明只想要个能用的LoRA微调，结果被
--deepspeed zero2、--vllm_mode colocate这些词绕晕
别担心——这不是你的问题。ms-swift功能强大，但它的命令行参数设计本意是服务工程师，不是为刚接触大模型的新手准备的。而这篇指南，就是专为你写的“翻译器”：把技术参数变成你能听懂的人话，把配置逻辑变成你脑中清晰的流程图。
不讲原理，不堆术语，不列全部300+参数。只聚焦你真正会用到的50个核心参数，按使用频率排序，用生活化类比+真实错误场景+一句话作用说明，让你10分钟看懂、30分钟上手、1小时跑通第一个微调任务。
我们不假设你懂分布式训练，不默认你知道LoRA和QLoRA的区别，甚至不预设你装好了vLLM——所有前提都给你补全，所有坑都提前标好。
现在，深呼吸，打开终端，我们开始。
2. 命令行结构：先看懂这一行到底在干什么
所有ms-swift命令都长这样：
swift <子命令> [通用参数] [子命令专属参数]2.1 三大子命令：你90%的时间都在用它们
| 子命令 | 全称 | 你什么时候需要它 | 小白一句话理解 |
|---|---|---|---|
sft | Supervised Fine-Tuning（监督微调） | 想让模型学会新技能，比如写合同、答客服、说方言 | “教模型做一件事” |
infer | Inference（推理） | 训练完想试试效果，或者直接用别人训好的模型 | “让模型回答问题” |
rlhf | Reinforcement Learning from Human Feedback（人类反馈强化学习） | 模型已经能答，但答得不够好、不够安全、不够有帮助 | “给模型打分，让它越答越好” |
新手建议：先死磕
sft，把它玩熟了再碰rlhf。就像学开车，先练直行和转弯，再学漂移。
2.2 通用参数：所有子命令都认的“普通话”
这些参数出现在任何swift xxx命令里，作用全局有效：
| 参数 | 作用（人话版） | 常见值举例 | 新手避坑提醒 |
|---|---|---|---|
--model | 告诉swift：“我要用哪个模型？” | Qwen/Qwen2.5-7B-Instruct、./my-local-model | 支持ModelScope ID或本地路径 别写 Qwen2.5-7B-Instruct（缺命名空间会报错） |
--torch_dtype | 设定计算精度，影响速度和显存 | bfloat16（推荐）、float16、auto | bfloat16在A100/H100上最稳；RTX3090用float16更兼容 |
--output_dir | 指定“作业本放哪”——所有训练中间文件、最终模型都存这里 | ./output-qwen-lora | 路径不存在会自动创建 别用空格或中文路径（如 ./我的模型） |
--seed | 控制随机性，让结果可复现 | 42、1234 | 同一参数+同一seed=每次结果一样 建议固定为 42，省心 |
关键认知：
--model不是“模型名字”，而是“模型身份证”。它必须精确到作者/模型名格式（如Qwen/Qwen2.5-7B-Instruct），就像快递单号不能少一位。
3. sft微调参数：手把手带你配出第一个可用命令
sft是新手最高频的命令。我们拆解它最常被问的12个参数，每个都配一个“小白能抄”的最小可行命令。
3.1 必填三件套：没有它们，命令直接报错
| 参数 | 为什么必须填？ | 怎么填才不踩坑 | 实例（可直接复制） |
|---|---|---|---|
--dataset | 没数据=没老师，模型学不会 | 支持ModelScope ID（AI-ModelScope/alpaca-gpt4-data-zh）或本地JSONL路径（./data.jsonl）不要加引号包裹多个数据集（错： "a b c"） | --dataset AI-ModelScope/alpaca-gpt4-data-zh#500（ #500表示只取前500条，新手调试必备） |
--train_type | 告诉swift：“你是想重造汽车，还是给汽车换个轮胎？” | full（全参数训练，需A100×8）lora（推荐！只训小模块，3090单卡就能跑）qlora（QLoRA，显存杀手，7B模型9GB搞定） | --train_type lora |
--max_length | 设定“作文纸有多长”——输入+输出总token数上限 | 2048（Qwen系推荐）、4096（长文本任务）、8192（需开启flash-attn） | --max_length 2048 |
新手黄金组合：
swift sft \ --model Qwen/Qwen2.5-7B-Instruct \ --dataset AI-ModelScope/alpaca-gpt4-data-zh#200 \ --train_type lora \ --max_length 2048 \ --output_dir ./quick-test
3.2 LoRA专项参数：搞懂这4个，LoRA就入门了
LoRA是新手最该掌握的技术——它像给大模型“装插件”，不动原模型，只训几个小矩阵。这4个参数决定插件好不好用：
| 参数 | 类比解释 | 推荐值（7B模型） | 错误示范 |
|---|---|---|---|
--lora_rank | 插件的“宽度”——越大能力越强，但也越吃显存 | 8（平衡之选）、16（效果更好）、4（显存紧张时） | --lora_rank 64（7B模型单卡3090必OOM） |
--lora_alpha | 插件的“放大倍数”——控制LoRA权重对原模型的影响强度 | 32（常用）、16（保守）、64（激进） | --lora_alpha 1（效果微弱，几乎没提升） |
--target_modules | 指定“给模型哪些部位装插件” | all-linear（全自动识别，新手首选）q_proj,v_proj（手动指定，高级用） | --target_modules q_proj（只装一个，效果不完整） |
--lora_dropout | 插件的“防过拟合开关”——训练时随机关闭部分插件 | 0.1（推荐）、0（关闭） | --lora_dropout 0.5（过度抑制，学不会） |
记忆口诀：
rank管大小，alpha管力度，target管位置，dropout管稳定。
3.3 训练节奏控制器：让模型学得又快又好
这些参数不决定“学什么”，而决定“怎么学”，直接影响训练是否成功：
| 参数 | 人话作用 | 新手安全值 | 为什么重要 |
|---|---|---|---|
--per_device_train_batch_size | 每张卡一次喂多少条数据 | 1（3090/4090）、2（A100） | 太大会显存爆炸，太小收敛慢 |
--gradient_accumulation_steps | “攒够几批再更新一次参数”——显存不够时的救命稻草 | 16（配batch_size=1）、8（配batch_size=2） | 单卡模拟大batch，效果接近多卡 |
--learning_rate | 学习步子迈多大 | 1e-4（LoRA常用）、2e-4（QLoRA）、5e-5（全参） | 1e-2会直接训飞（loss乱跳） |
--num_train_epochs | 总共学几轮 | 1（快速验证）、3（正式训练） | 数据少时别设太高，易过拟合 |
显存紧张者必用组合：
--per_device_train_batch_size 1 --gradient_accumulation_steps 16
相当于每步用16条数据更新，但只占1条的显存。
3.4 其他高频实用参数：解决你实际会遇到的问题
| 参数 | 解决什么问题 | 示例 | 备注 |
|---|---|---|---|
--system | 给模型设定“人设”，比如“你是个严谨的律师” | --system "You are a helpful, respectful assistant." | 中文模型建议用中文system，如--system "你是一个专业的医疗助手" |
--save_steps/--eval_steps | 每训多少步存一次模型/测一次效果 | --save_steps 50 --eval_steps 50 | 新手建议设小点，早发现问题 |
--logging_steps | 每几步打印一次loss，看训练是否正常 | --logging_steps 5 | loss应平稳下降，若剧烈波动需调learning_rate |
--dataloader_num_workers | 加载数据的“工人数量”，加快数据供给 | --dataloader_num_workers 4 | Linux设4-8，Windows建议≤2（避免卡死） |
4. infer推理参数：训完模型，怎么让它开口说话？
训完模型，下一步就是测试效果。infer命令比sft简单得多，但新手常卡在这3个地方：
4.1 最容易错：--adaptersvs--model
| 场景 | 正确写法 | 错误写法 | 为什么？ |
|---|---|---|---|
| 用原始模型（没微调过） | --model Qwen/Qwen2.5-7B-Instruct | --adapters ... | --adapters只用于加载LoRA权重，原始模型不用它 |
| 用LoRA微调后模型 | --adapters ./output/checkpoint-100 | --model ./output/checkpoint-100 | LoRA权重只是“补丁”，必须挂载在原模型上 |
正确姿势：
# LoRA模型推理（必须同时指定原模型 + adapters） swift infer \ --model Qwen/Qwen2.5-7B-Instruct \ --adapters ./output/checkpoint-100 \ --stream true
4.2 推理体验优化参数：让回答更自然
| 参数 | 作用 | 推荐值 | 效果对比 |
|---|---|---|---|
--temperature | 控制“发挥想象力”的程度 | 0.7（平衡）、0（确定性最强，答案唯一） | 0→答案刻板但准确；1.0→天马行空但可能胡说 |
--top_p | 只从“概率最高的候选词”里选，过滤低质答案 | 0.8（推荐）、0.95（更开放） | 防止模型瞎编，比temperature更可控 |
--max_new_tokens | 限制模型最多生成多少字 | 512（短回答）、2048（长文生成） | 设太大可能卡住，新手从512起步 |
4.3 加速选项：让推理快10倍的秘诀
| 参数 | 作用 | 是否推荐新手用 | 备注 |
|---|---|---|---|
--infer_backend pt | 用PyTorch原生推理 | 是（最稳，兼容所有模型） | 默认值，无需指定 |
--infer_backend vllm | 用vLLM加速引擎 | 建议等vLLM装好再用 | 需pip install vllm，速度提升3-10倍 |
--merge_lora true | 把LoRA权重“缝进”原模型，变回单个文件 | 强烈推荐！ | 合并后可用任意推理工具，不再依赖ms-swift |
合并LoRA并用vLLM推理（生产级）：
swift infer \ --model Qwen/Qwen2.5-7B-Instruct \ --adapters ./output/checkpoint-100 \ --merge_lora true \ --infer_backend vllm \ --vllm_max_model_len 8192
5. rlhf强化学习参数：当你需要模型“越答越好”
RLHF是进阶玩法，但ms-swift把它简化到了极致。新手只需关注这3个核心参数：
5.1 入门三参数：定义你的强化学习任务
| 参数 | 作用 | 常见值 | 小白理解 |
|---|---|---|---|
--rlhf_type | 选哪种强化学习算法 | dpo（最简单）、kto（更稳定）、simpo（新锐） | dpo是新手第一站，资料最多 |
--dataset | 强化学习需要“好坏答案对”，数据集格式不同 | hjh0119/shareAI-Llama3-DPO-zh-en-emoji（DPO专用） | ❗ 必须用DPO/KTO等专用数据集，普通SFT数据集无效 |
--reward_model | （可选）指定一个打分模型，给回答打分 | internlm/internlm2-7b-reward | 新手可先不设，用内置默认打分 |
DPO微调最小命令：
swift rlhf \ --rlhf_type dpo \ --model Qwen/Qwen2.5-7B-Instruct \ --dataset hjh0119/shareAI-Llama3-DPO-zh-en-emoji#200 \ --train_type lora \ --output_dir ./dpo-output
6. 常见报错与速查解决方案
别再为报错抓狂。这里整理了新手前10大报错，按出现频率排序，附带10秒定位法和30秒修复法：
| 报错信息关键词 | 可能原因 | 10秒定位法 | 30秒修复法 |
|---|---|---|---|
OSError: Can't load tokenizer | 模型路径错/网络问题 | 检查--model是否拼错，能否在ModelScope网页打开 | 加--use_hf true换HuggingFace源，或确认ID全称 |
CUDA out of memory | 显存爆了 | 看报错前最后一行batch size和gradient accumulation | 立即降--per_device_train_batch_size到1，升--gradient_accumulation_steps到16 |
ValueError: Dataset not found | 数据集ID错或没权限 | 复制--dataset值，粘贴到ModelScope搜索框 | 换公开数据集如AI-ModelScope/alpaca-gpt4-data-zh，或检查私有数据集权限 |
KeyError: 'q_proj' | --target_modules指定的模块名不存在 | 运行swift sft --model xxx --help看支持模块 | 改用--target_modules all-linear（全自动识别） |
FileNotFoundError: args.json | --adapters路径不对 | ls ./your-path/看是否存在args.json | 用find . -name "args.json"找对路径，或确认checkpoint是否完整 |
TypeError: expected str, bytes or os.PathLike object | 路径含中文或空格 | 看报错行里的路径字符串 | 全部改用英文路径，如./output/而非./我的输出/ |
RuntimeError: Expected all tensors to be on the same device | 混用了CPU和GPU | 检查是否漏了CUDA_VISIBLE_DEVICES=0 | 在命令最前面加CUDA_VISIBLE_DEVICES=0 |
ValueError: max_length must be greater than 0 | --max_length设为0或负数 | 检查该参数值 | 改为--max_length 2048（Qwen系安全值） |
ModuleNotFoundError: No module named 'vllm' | 想用vLLM但没装 | 运行python -c "import vllm" | pip install vllm（A100/H100用户强烈建议） |
Permission denied: './output' | 输出目录权限不足 | ls -ld ./output看权限 | chmod 755 ./output或换--output_dir ./tmp-output |
终极心法：90%的报错，都是路径、ID、显存三者之一出了问题。先查这三项，再看报错全文。
7. 总结：你的第一个ms-swift工作流
现在，你已经拥有了从零到一的完整能力。下面是一份新手第一天实操清单，照着做，保证跑通：
7.1 第一步：环境准备（5分钟）
# 安装ms-swift（确保pip最新） pip install --upgrade pip pip install ms-swift # 安装vLLM（可选，但强烈推荐） pip install vllm # 创建干净工作目录 mkdir my-swift-project && cd my-swift-project7.2 第二步：跑通第一个微调（10分钟）
# 单卡3090，5分钟内完成微调（只训200条数据） swift sft \ --model Qwen/Qwen2.5-7B-Instruct \ --dataset AI-ModelScope/alpaca-gpt4-data-zh#200 \ --train_type lora \ --lora_rank 8 \ --lora_alpha 32 \ --target_modules all-linear \ --per_device_train_batch_size 1 \ --gradient_accumulation_steps 16 \ --learning_rate 1e-4 \ --num_train_epochs 1 \ --max_length 2048 \ --output_dir ./qwen-lora-test \ --logging_steps 5 \ --save_steps 20 \ --eval_steps 207.3 第三步：立刻测试效果（2分钟）
# 用刚训好的模型推理 swift infer \ --model Qwen/Qwen2.5-7B-Instruct \ --adapters ./qwen-lora-test/checkpoint-20 \ --stream true \ --temperature 0.7 \ --max_new_tokens 512输入
你好，你是谁？，看它是否用你设定的--system人设回答。
7.4 第四步：导出为通用模型（3分钟）
# 合并LoRA，生成标准HuggingFace格式模型 swift export \ --model Qwen/Qwen2.5-7B-Instruct \ --adapters ./qwen-lora-test/checkpoint-20 \ --merge_lora true \ --output_dir ./qwen-lora-merged现在
./qwen-lora-merged文件夹可直接用transformers、llama.cpp等任何工具加载！
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
