大家好，本篇基于 MS-Swift 3.12 官方 Megatron-SWIFT 命令行参数文档 整理，聚焦 3.12 稳定版核心特性，把最常用、最容易踩坑、最关键的参数全部讲明白，给出标准用法 + 实战示例，不管是 SFT 微调、RLHF 对齐、模型导出、量化、部署，都能直接照着用。

---

一、MS-Swift 3.12 参数整体结构（官方定义）

MS-Swift 3.12 参数分为 4 层，层级逻辑与 4.x 一致，但核心参数更聚焦稳定性：

1. 基本参数（通用核心，所有命令共享）
2. 原子参数（训练器底层，一般无需修改）
3. 集成参数（最终实际使用，重点关注）
4. 特定模型参数（Megatron 大模型/多模态/Qwen 专属）

所有命令最终使用的都是 集成参数，日常训练只需关注 带🔥的重要参数 即可，无需深入底层原子参数。

---

二、参数传入格式

• list 传入：用空格分隔（多数据集/多路径场景）

--dataset data1 data2 data3

• dict 传入：用 JSON 字符串（模型额外配置）

--model_kwargs '{"FPS_MAX_FRAMES": 12, "use_flash_attention": true}'

• bool 传入：true / false（大小写敏感，不可简写）

--load_in_4bit true  # 正确
--load_in_4bit True  # 错误（3.12 不兼容）

---

三、🔥 核心模块参数详

1. 基本参数

参数	说明	常用值	3.12 版本说明
train_type	微调类型（替代 4.x tuner_type）	lora（默认）/ full / adalora / vera	3.12 核心参数，不可用 tuner_type
tuner_backend	LoRA 后端	peft（默认）/ unsloth	3.12 仅支持这两种，无新增后端
adapters	LoRA 路径	断点续训目录/推理权重路径	自动读取 args.json，无需重复传模型参数
model	模型ID/本地路径	Qwen/Qwen2.5-7B-Instruct / 本地路径	必传，支持 ModelScope/HF 模型ID
model_type	模型类型	qwen / qwen2_vl / llama3 / internlm3	3.12 新增对 Qwen2.5、Llama3 稳定支持
use_hf	是否使用 HuggingFace	false（默认 ModelScope）	国内用户建议保持 false，下载更快
hub_token	ModelScope 上传令牌	个人访问令牌（https://modelscope.cn/my/accesskey）	推送模型时必传
seed	随机种子	42（默认）/ 1024	保证训练可复现，推荐固定

示例：

--model_type qwen \
--model Qwen/Qwen2.5-1_8B-Chat \
--train_type lora \  # 3.12 关键：用 train_type 而非 tuner_type
--seed 42 \
--use_hf false

---

2. 模型参数

参数	说明	常用值	3.12 版本特性
torch_dtype	训练精度	bf16（推荐）/ fp16 / float32	3.12 对 bf16 支持更稳定，A10/T4 可用
device_map	设备分配	auto（默认）/ cpu / 手动指定	多卡自动均衡分配，无需手动配置
max_memory	单卡最大显存限制	{‘0’: ‘14GB’, ‘1’: ‘14GB’}	多卡场景避免显存溢出，JSON 字符串格式
rope_scaling	长度外推策略	linear / dynamic / yarn	3.12 新增 yarn 策略，支持更长文本
max_model_len	模型最大长度	2048 / 4096 / 8192	需与 rope_scaling 配合，Qwen2.5 支持 8192
attn_impl	Attention 实现	flash_attention_2（推荐）/ auto	3.12 仅支持 flash_attention_2，无新增实现

示例：

--torch_dtype bfloat16 \
--device_map auto \
--max_model_len 4096 \
--rope_scaling linear \
--attn_impl flash_attention_2 \
--max_memory '{"0": "14GB", "1": "14GB"}'

---

3. 数据参数

参数	说明	常用值	3.12 避坑点
dataset	训练数据集	本地路径 / ModelScope 数据集ID#采样数	支持 JSON/JSONL/CSV，多数据集空格分隔
val_dataset	验证集	单独数据集路径 / 空	未指定则按 split_dataset_ratio 拆分
custom_dataset_info	自定义数据集配置	dataset_info.json 路径	3.12 完全兼容 4.x 格式，无需修改
split_dataset_ratio	训练集切分验证集比例	0.05（默认）/ 0.1	比例过大可能导致训练数据不足
dataset_num_proc	预处理进程数	4 / 8（根据CPU核心数）	3.12 优化多进程稳定性，避免数据错乱
columns	字段映射	{“messages”: “conversation”} / {“prompt”: “instruction”}	自定义数据集必传，格式为 JSON 字符串
strict	是否严格检查数据	false（推荐）/ true	false 自动跳过坏数据，避免训练中断

示例：

--dataset med-disc med-self-cog \
--custom_dataset_info custom_dataset.json \
--split_dataset_ratio 0.05 \
--dataset_num_proc 4 \
--columns '{"messages": "conversation"}' \  # JSON 字符串格式
--strict false

---

4. 模板参数

参数	说明	常用值	3.12 版本限制
template	对话模板	auto（默认）/ qwen / llama3	自动匹配模型，无需手动指定
system	系统提示词	医疗/教育/客服专属提示词	全局生效，优先级高于数据内 system 字段
max_length	单条样本最大长度	2048 / 4096	需 ≤ max_model_len，否则触发截断
truncation_strategy	超长处理策略	delete（默认）/ left / right	3.12 仅支持这三种，无新增策略
loss_scale	损失计算范围	default / last_round	default：全轮对话计算损失；last_round：仅最后一轮
agent_template	智能体模板	react_en（默认）/ qwen	3.12 无新增模板，仅支持内置两种

示例：

--system "你是专业医疗助手，提供严谨、安全的健康咨询服务，不替代医嘱" \
--max_length 2048 \
--truncation_strategy delete \
--loss_scale default

---

5. 训练参数

参数	说明	常用值	3.12 推荐配置
output_dir	输出目录	本地路径（如 ./output_med）	自动创建，包含 checkpoint、日志、配置文件
num_train_epochs	训练轮数	2~5	1.8B 模型推荐 2 轮，7B 模型推荐 3 轮
per_device_train_batch_size	单卡批次大小	2 / 4 / 8	3.12 显存优化：1.8B+LoRA 单卡可设 4
gradient_accumulation_steps	梯度累积步数	2 / 4 / 8	显存不足时增大，等效提升批次
learning_rate	学习率	1e-4（LoRA 默认）/ 5e-5（full）	3.12 学习率范围与 4.x 一致，无需调整
warmup_ratio	预热比例	0.05（默认）/ 0.1	避免初始学习率过高导致不收敛
gradient_checkpointing	梯度检查点（省显存）	true（推荐）/ false	3.12 对该功能优化，无性能损失
save_steps	保存步数	500（默认）/ 1000	数据量大设 1000，量小设 200
eval_steps	评估步数	500（默认）/ 与 save_steps 一致	每 eval_steps 计算一次验证集损失
save_total_limit	最大保存数	5（默认）/ 3	避免占用过多磁盘空间

示例：

--num_train_epochs 2 \
--per_device_train_batch_size 4 \
--gradient_accumulation_steps 2 \
--learning_rate 1e-4 \
--gradient_checkpointing true \
--save_steps 500 \
--eval_steps 500 \
--save_total_limit 3 \
--output_dir "./output_med_312"

---

6. LoRA 参数

参数	说明	常用值	3.12 最佳实践
lora_rank	秩	8 / 16（推荐）/ 32	1.8B~7B 模型用 16，7B+ 用 32
lora_alpha	缩放系数	32（16×2）/ 16（8×2）/ 64（32×2）	固定为 lora_rank×2，效果最优
lora_dropout	dropout 概率	0.05（默认）/ 0.1	防止过拟合，医疗数据集推荐 0.05
target_modules	目标层	all-linear（默认）/ 具体层名	3.12 对 all-linear 支持更稳定，无需手动指定
use_dora	是否使用 DoRA	true（推荐）/ false	3.12 仅支持 LoRA+DoRA，无新增变体

示例：

--lora_rank 16 \
--lora_alpha 32 \  # 16×2 黄金比例
--lora_dropout 0.05 \
--target_modules all-linear \
--use_dora true

---

7. 量化参数

参数	说明	常用值	3.12 支持范围
quant_method	量化方法	bnb（训练）/ awq / gptq（导出）	3.12 训练仅支持 bnb，导出支持 awq/gptq
quant_bits	量化位数	4（推荐）/ 8	4bit 省显存，8bit 平衡效果与性能
bnb_4bit_quant_type	4bit 量化类型	nf4（推荐）/ fp4	3.12 仅支持这两种，nf4 效果更优
load_in_4bit / load_in_8bit	是否加载时量化	true / false	训练时省显存，推荐单卡 8G 用 load_in_4bit

示例（训练时量化省显存）：

--quant_method bnb \
--quant_bits 4 \
--bnb_4bit_quant_type nf4 \
--load_in_4bit true  # 3.12 关键：加载模型时量化，省显存

---

8. RLHF 对齐参数

参数	说明	常用值	3.12 版本限制
rlhf_type	对齐类型	orpo（推荐）/ dpo / simpo / kto	3.12 不支持 4.x 新增的部分方法，聚焦稳定款
beta	偏差系数	0.1（ORPO）/ 0.5（DPO）/ 1.0	医疗模型推荐偏小，避免过度对齐
max_completion_length	最大生成长度	512 / 1024	需 ≤ max_model_len - 输入长度
ref_model	参考模型	同 base_model / 空	3.12 支持自动用 base_model 作为参考，无需额外指定

示例（ORPO 对齐医疗模型）：

--rlhf_type orpo \
--beta 0.1 \  # 医疗场景：温和对齐，保证专业性
--max_completion_length 512 \
--ref_model Qwen/Qwen2.5-1_8B-Chat

---

9. 推理 & 部署参数

参数	说明	常用值	3.12 版本特性
infer_backend	推理引擎	transformers（默认）/ vllm / lmdeploy / sglang	3.12 支持 vllm0.13.0，无 sglang 新增功能
max_new_tokens	最大生成长度	1024 / 2048	医疗对话推荐 1024，足够覆盖回答
temperature	随机性	0.3（推荐）/ 0.1~0.7	越低越严谨，医疗场景避免超过 0.7
stream	流式输出	true（推荐）/ false	3.12 流式输出无卡顿，适合交互场景
host	部署 IP	0.0.0.0（默认）	允许外部访问，本地测试用 127.0.0.1
port	部署端口	8000（默认）/ 8080	避免端口占用，可自定义
vllm_max_model_len	vLLM 最大长度	8192 / 4096	需与训练时 max_model_len 一致

示例（vLLM 加速医疗模型推理）：

--infer_backend vllm \
--max_new_tokens 1024 \
--temperature 0.3 \
--stream true \
--vllm_max_model_len 4096 \
--host 0.0.0.0 \
--port 8000

---

10. 导出 & 推送参数

参数	说明	常用值	3.12 注意事项
merge_lora	是否合并 LoRA 权重	true（推荐）/ false	导出部署必须设为 true，生成完整模型
push_to_hub	是否推送到 ModelScope	true / false	3.12 仅支持推送到 ModelScope，不支持 HF
hub_model_id	模型ID	用户名/模型名（如：zhangsan/qwen2.5-med-1.8b）	需符合 ModelScope 命名规范，不可重复
quant_method	导出量化方法	awq（推荐）/ gptq / bnb	3.12 导出 awq 更稳定，部署速度更快
quantization_bit	导出量化位数	4（推荐）/ 8	4bit 适合部署，8bit 效果更接近原始模型
use_hf	导出为 HF 格式	false（默认）/ true	国内部署建议保持 false，适配 ModelScope

示例（合并+4bit AWQ量化+推送）：

--merge_lora true \
--push_to_hub true \
--hub_model_id zhangsan/qwen2.5-med-1.8b \
--hub_token 你的token \
--quant_method awq \
--quantization_bit 4 \
--use_hf false

---

四、使用ms-swift-3.12 版本实战命令（

1）SFT 训练命令（医疗微调，单卡/多卡）

# 双卡训练（3.12 稳定版）
CUDA_VISIBLE_DEVICES=0,1 NPROC_PER_NODE=2 swift sft \
    --model_type qwen \
    --model "./Qwen2.5-1_8B-Chat" \
    --train_type lora \  # 3.12 关键参数
    --custom_dataset_info "custom_dataset.json" \
    --dataset med-disc med-self-cog \
    --torch_dtype bfloat16 \
    --load_in_4bit true \  # 省显存，单卡8G可用
    --num_train_epochs 2 \
    --per_device_train_batch_size 4 \
    --gradient_accumulation_steps 2 \
    --learning_rate 1e-4 \
    --lora_rank 16 \
    --lora_alpha 32 \
    --target_modules all-linear \
    --max_model_len 2048 \
    --max_length 2048 \
    --system "你是专业医疗助手，提供严谨安全的健康咨询，不替代医嘱" \
    --gradient_checkpointing true \
    --save_steps 500 \
    --eval_steps 500 \
    --output_dir "./output_med_312"

2）ORPO 对齐命令

swift dpo \
    --model_type qwen \
    --model "./output_med_312/checkpoint-1000" \  # SFT 输出目录
    --train_type lora \
    --rlhf_type orpo \
    --beta 0.1 \
    --dataset med-disc \
    --num_train_epochs 1 \
    --per_device_train_batch_size 2 \
    --learning_rate 5e-5 \
    --max_completion_length 512 \
    --output_dir "./output_orpo_312"

3）合并 + 量化 + 推送到 ModelScope

swift export \
    --model_type qwen \
    --model "./output_orpo_312/checkpoint-500" \
    --merge_lora true \
    --push_to_hub true \
    --hub_model_id "你的用户名/qwen2.5-med-1.8b-orpo" \
    --hub_token "你的ModelScope令牌" \
    --quant_method awq \
    --quantization_bit 4 \
    --use_hf false

---

五、3.12 版本避坑指南（高频错误）

1. 用 tuner_type 而非 train_type → 报错
   3.12 核心差异：--train_type lora 是正确写法，4.x 的 tuner_type 完全不可用。
2. quant_method 训练时用 awq → 报错
   3.12 训练仅支持 bnb 量化，awq/gptq 仅用于导出。
3. load_in_4bit 小写 true → 正确
   3.12 对 bool 值大小写敏感，必须写 true/false，不能写 True/False。
4. 数据集路径用相对路径 → 找不到文件
   3.12 建议用绝对路径，或确保命令执行目录与数据集目录一致。
5. 推送模型忘记传 hub_token → 权限错误
   必须在 ModelScope 官网获取令牌，否则无法上传。
6. max_length 超过 max_model_len → 截断异常
   3.12 中 max_length 必须 ≤ max_model_len，否则会强制截断对话。

---

六、3.12 版本总结

MS-Swift 3.12 作为稳定分支，命令行参数的核心特点是：

• 兼容优先：大部分参数与 4.x 一致，仅核心微调类型参数改名（tuner_type → train_type）
• 稳定为王：去除实验性参数，聚焦生产环境常用功能
• 适配优化：对 Qwen2.5、Llama3 等主流模型支持更完善，显存控制更优

日常训练只需掌握 5 类核心参数：

• 基本参数（train_type、model、use_hf）
• 训练参数（batch_size、learning_rate、epochs）
• LoRA 参数（lora_rank、lora_alpha、target_modules）
• 量化参数（load_in_4bit、quant_method）
• 导出参数（merge_lora、push_to_hub）

即可流畅完成 SFT → RLHF → 量化 → 部署 → 推送 全流程，适合新手与生产环境使用。

---

标签

#MS-Swift312 #大模型微调 #命令行参数 #LoRA #医疗大模型 #模型部署 #ModelScope