MS-Swift 命令行参数最全通关指南（新手到实战）

一篇看懂训练、推理、对齐、量化、部署全参数

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

---

一、MS-Swift 参数整体结构

MS-Swift 参数分为 4 层：

1. 基本参数（通用核心）
2. 原子参数（训练器底层）
3. 集成参数（最终实际使用）
4. 特定模型参数（多模态/Qwen等专属）

所有命令最终使用的都是 集成参数，我们日常训练只需要关注 带🔥的重要参数 即可。

---

二、参数传入格式（必看！不然必报错）

• list 传入：用空格分隔

--dataset data1 data2 data3

• dict 传入：用 JSON 字符串

--model_kwargs '{"FPS_MAX_FRAMES": 12}'

• bool 传入：true / false

--load_in_4bit true

---

三、🔥 核心模块参数详解（实战版）

1. 基本参数（所有命令通用）

参数	说明	常用值
tuner_type	微调类型	lora（默认）/ full / adalora / vera
tuner_backend	LoRA 后端	peft / unsloth
adapters	LoRA 路径	断点续训/推理用
model	模型ID/路径	必传
model_type	模型类型	qwen / qwen2_vl 等
use_hf	使用 HuggingFace	false（默认用 ModelScope）
hub_token	上传 ModelScope 令牌	推送模型用
seed	随机种子	42

示例：

--model_type qwen \
--model Qwen/Qwen-1_8B-Chat \
--tuner_type lora \
--seed 42

---

2. 模型参数

参数	说明
torch_dtype	精度
device_map	设备分配
max_memory	显存分配
rope_scaling	长度外推
max_model_len	模型最大长度
attn_impl	attention

示例：

--bf16 true \
--device_map auto \
--max_model_len 2048 \
--attn_impl flash_attention_2

---

3. 数据参数（最容易错）

参数	说明
dataset	训练数据集
val_dataset	验证集
custom_dataset_info	自定义 dataset_info.json
split_dataset_ratio	训练集切分验证
dataset_num_proc	预处理进程
columns	字段映射
strict	是否严格检查

示例：

--dataset med-disc med-self-cog \
--custom_dataset_info custom_dataset.json \
--split_dataset_ratio 0.05 \
--dataset_num_proc 4

---

4. 模板参数（对话格式）

参数	说明
template	对话模板
system	系统提示词
max_length	单条最大长度
truncation_strategy	超长策略
loss_scale	损失计算范围
agent_template	智能体模板

示例：

--system "你是专业医疗助手，提供严谨安全的健康咨询" \
--max_length 2048 \
--loss_scale default

---

5. 训练参数（SFT / DPO / ORPO）

参数	说明
output_dir	输出目录
num_train_epochs	训练轮数
per_device_train_batch_size	批次
gradient_accumulation_steps	梯度累积
learning_rate	学习率
warmup_ratio	预热
gradient_checkpointing	省显存
save_steps	保存步数
eval_steps	评估步数
save_total_limit	最大保存数

示例：

--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 5

---

6. LoRA 参数（最常用）

参数	说明
lora_rank	秩
lora_alpha	缩放
lora_dropout	dropout
target_modules	目标层
use_dora	使用 DoRA

示例：

--lora_rank 16 \
--lora_alpha 32 \
--lora_dropout 0.05 \
--target_modules all-linear

---

7. 量化参数（训练省显存）

参数	说明
quant_method	量化方法
quant_bits	量化位数
bnb_4bit_quant_type	nf4（推荐）

示例：

--quant_method bnb \
--quant_bits 4 \
--bnb_4bit_quant_type nf4

---

8. RLHF 对齐参数（DPO/ORPO/SimPO/KTO）

参数	说明
rlhf_type	对齐类型
beta	偏差系数
max_completion_length	最大生成长度

示例：

--rlhf_type orpo \
--beta 0.1 \
--max_completion_length 512

---

9. 推理 & 部署参数

参数	说明
infer_backend	推理引擎
max_new_tokens	最大生成长度
temperature	随机性
stream	流式输出
host	部署IP
port	端口

示例：

--infer_backend vllm \
--max_new_tokens 1024 \
--temperature 0.3 \
--stream true

---

10. 导出 & 推送参数（合并+量化+上传）

参数	说明
merge_lora	合并LoRA
push_to_hub	推送到 ModelScope
hub_model_id	模型ID
quant_method	导出量化
quantization_bit	导出位数

示例：

--merge_lora true \
--push_to_hub true \
--hub_model_id myname/qwen-med-1.8b \
--quant_method awq \
--quantization_bit 4

---

四、最常用实战命令（直接复制）

1）SFT 训练命令（医疗微调）

CUDA_VISIBLE_DEVICES=0,1 NPROC_PER_NODE=2 swift sft \
    --model_type qwen \
    --model "./Qwen-1_8B-Chat" \
    --train_type lora \
    --custom_dataset_info "custom_dataset.json" \
    --dataset med-disc med-self-cog \
    --bf16 true \
    --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_length 2048 \
    --system "你是专业医疗助手" \
    --output_dir "./output"

2）ORPO 对齐命令

swift dpo \
    --model_type qwen \
    --model "./output/checkpoint-xxx" \
    --rlhf_type orpo \
    --dataset med-disc \
    --output_dir "./output_orpo"

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

swift export \
    --model_type qwen \
    --model "./output_orpo/checkpoint-xxx" \
    --merge_lora true \
    --push_to_hub true \
    --hub_model_id myname/med-model \
    --quant_method awq \
    --quantization_bit 4

---

五、参数避坑指南（高频错误）

1. dataset 写错路径 → 找不到文件
2. columns 映射错误 → 格式不匹配
3. max_length 太小 → 样本被截断
4. quant_bits=4 但不支持 → 换成 bnb
5. LoRA 训练用 full 学习率 → 不收敛
6. 推送模型忘记填 hub_token

---

六、总结

MS-Swift 命令行参数虽然多，但真正高频使用的不到 30 个。
只要掌握：

• 模型参数
• 数据参数
• 训练参数
• LoRA 参数
• 量化/导出参数

就能完成 SFT → RLHF → 量化 → 部署 → 推送 ModelScope 全流程。