Chapter 05
命令行参数地图
📌 commit b58b1bdswift sft 的 200+ 参数按 8 组归类
swift sft --help 输出能滚屏好几页。本章按功能归类，让你知道每组在干什么。
5.1八大参数组
| 组 | 典型字段 | 来源文件 |
|---|
| Model | model / model_type / template / torch_dtype | swift/llm/argument/base_args/model_args.py |
| Data | dataset / split_dataset_ratio / dataset_num_proc / max_length | data_args.py |
| Quant | quant_method / quant_bits / bnb_4bit_* | quant_args.py |
| Tuner | train_type / lora_rank / lora_alpha / target_modules | tuner_args.py |
| Train | num_train_epochs / batch_size / lr / warmup / deepspeed | train_args.py |
| RLHF | rlhf_type / beta / loss_type / num_generations | rlhf_args.py |
| Megatron | tensor_model_parallel_size / pipeline_model_parallel_size | megatron_args.py |
| Infer / Export | adapters / merge_lora / quant_n_samples / output_dir | infer_args.py / export_args.py |
5.2Model 组高频字段
| 字段 | 说明 |
|---|
--model | 必填，模型 ID 或本地路径 |
--model_type | 不填时根据 model 自动识别 |
--template | 不填时跟随 model_type |
--torch_dtype | bfloat16 / float16 / float32 |
--attn_impl | "flash_attn" / "sdpa" / "eager" |
--rope_scaling | 长上下文扩展（linear / dynamic / yarn） |
5.3Data 组
| 字段 | 说明 |
|---|
--dataset | 可以多个，用空格分隔；#N 取前 N 条 |
--val_dataset | 显式 valid 集 |
--split_dataset_ratio | 从 train 切出 valid 的比例，0.01 推荐 |
--dataset_num_proc | tokenize 并行进程数 |
--max_length | 截断长度 |
--packing | 开 packing，节省 padding |
--streaming | 大数据集流式加载 |
--loss_scale | "default" / "all" / "agent" / 自定义 |
5.4Train 组
| 字段 | 建议 |
|---|
--num_train_epochs | 1-3 |
--per_device_train_batch_size | 视显存 |
--gradient_accumulation_steps | 有效 batch / GPU 数 / per_device 计算 |
--learning_rate | 1e-4（LoRA）/ 2e-5（full） |
--warmup_ratio | 0.03 |
--lr_scheduler_type | cosine |
--gradient_checkpointing | 显存紧时 true |
--deepspeed | default-zero2 / zero3 |
--save_steps | 200 |
--save_total_limit | 2-3 避免占盘 |
--logging_steps | 10 |
5.5Tuner 组
| 字段 | 说明 |
|---|
--train_type | full / lora / dora / longlora / galore / lisa / liger / boft |
--lora_rank | 8-64 |
--lora_alpha | 常 = 2× rank |
--target_modules | "all-linear" 起步 |
--lora_dropout | 0.05 |
--use_dora | true 开 DoRA |
--use_rslora | true 开 rsLoRA |
--init_lora_weights | true / pissa / loftq / olora |
5.6Quant 组
| 字段 | 说明 |
|---|
--quant_method | bnb / hqq / eetq / awq / gptq |
--quant_bits | 4 / 8 |
--bnb_4bit_compute_dtype | bfloat16 |
--bnb_4bit_quant_type | nf4 |
--bnb_4bit_use_double_quant | true |
5.7Megatron 组
| 字段 | 说明 |
|---|
--megatron | 切到 Megatron 后端（详见 ch09） |
--tensor_model_parallel_size | TP |
--pipeline_model_parallel_size | PP |
--sequence_parallel | SP（配合 TP） |
--fp8 | 开 FP8（H100/H200） |
5.8Infer 组（推理）
| 字段 | 说明 |
|---|
--adapters | LoRA adapter 路径 |
--merge_lora | true 合并 LoRA 再推理 |
--infer_backend | pt / vllm / lmdeploy |
--stream | 流式输出 |
--max_new_tokens | 256 |
--temperature / top_p | 采样 |
5.9Arguments 真实继承图
v4 之后所有 dataclass 在 swift/arguments/ 下。继承关系比看起来复杂：
SftArguments # swift/arguments/sft_args.py:217
└─ inherits:
├─ TrainingArguments # trainers/arguments.py
│ └─ TrainArgumentsMixin + Seq2SeqTrainingArguments # 继承 HF
├─ TunerArguments # arguments/tuner_args.py
└─ BaseArguments # arguments/base_args/
RLHFArguments # swift/arguments/rlhf_args.py:170
└─ = TeacherModelArguments + GRPOArguments + PPOArguments
+ RewardModelArguments + SftArguments
含义：
SftArguments ≈ "训练参数 + tuner 参数 + 模型/数据 base 参数" 的总和；RLHFArguments = SftArguments + 4 组 RLHF 特化 args（teacher / grpo / ppo / reward），一份 dataclass 装下所有 RLHF 算法的参数；- "
--rlhf_type"字段决定走哪个 trainer，其余 args 共享 namespace。
5.10TrainArgumentsMixin 关键字段
trainers/arguments.py:17–80 的 TrainArgumentsMixin 提供 swift 在 HF Trainer 之外加的字段。最常用：
| 字段 | 含义 |
|---|
tuner_backend | "peft" / "unsloth"，决定 LoRA 实现走哪个库 |
vit_gradient_checkpointing | VLM 时单独控制 vision tower 的 grad ckpt |
router_aux_loss_coef | MoE 路由辅助 loss 权重 |
optimizer | 插件名（optimizers_map 自动 lookup），优先级高于 HF 的 optim 字段 |
loss_type | "ce" / "dft" / "nll" 等，走 swift/loss/loss_map.py |
metric | 评测插件名 |
acc_strategy | "token" / "seq" 选择 accuracy 计算粒度 |
ds3_gather_for_generation | DeepSpeed ZeRO-3 时 generation 前是否 all-gather |
5.11RLHFArguments 9 个 rlhf_type + 多 loss
rlhf_args.py:169–250 的关键字段：
| 字段 | 取值 / 含义 |
|---|
rlhf_type | dpo / orpo / simpo / kto / cpo / rm / ppo / grpo / gkd 九选一 |
beta | KL 强度，每种算法有不同默认值（DPO 0.1，GRPO 0.001 等） |
loss_type | 同一算法内的 loss 变种（如 DPO 下走 ipo / sigmoid / hinge） |
loss_weights | 多损失加权（MPO 模式） |
reward_funcs / reward_weights | GRPO 时多 reward function 列表 + 权重 |
max_completion_length | GRPO / PPO 生成长度上限 |
teacher_model_server | GKD 时教师模型走 API 而不是本地加载 |
5.12YAML / CLI 合并优先级
swift/cli/main.py:38–71：
- 先解析第一个位置参数（如果是
.yaml/.json 就 load）；
- YAML 里支持
env 段，自动 export 到环境变量（line 53–59）；
- YAML 字段 → CLI args（line 61–70）；
- 剩下的命令行 args 再 override YAML。
所以 swift sft my.yaml --learning_rate 5e-5 一定能让 CLI 学习率覆盖 YAML 的。
5.13这章你需要带走的
- 参数 200+ 但分 8 组：Model / Data / Quant / Tuner / Train / RLHF / Megatron / Infer；
- 每组对应一个 args 文件，看 args.json 比看 --help 更全；
- 常用 12 个字段足以覆盖 90% 场景；
- 不确定时跑一次后看
./output/v0-xxx/args.json 把默认值都列出来。