ms-swift 部分命令行参数说明

参考链接

swift.readthedocs.io/zh-cn/lates...

chat.qwen.ai/s/b68589f3-...

num_train_epochs

训练的epoch数，默认为3

假设你有 1000 条训练样本，并且设置了：

num_train_epochs = 3

这意味着：

• 模型会完整地遍历这 1000 条数据 3 次。
• 每一次完整的遍历称为一个 epoch 。

为什么需要多个 epoch？

• 在第一个 epoch 中，模型可能还没有学到足够的信息；
• 第二个 epoch 可能会让模型进一步优化参数；
• 第三个 epoch 可能会让模型更准确；
• 但太多 epoch 可能会导致 过拟合（overfitting） ------ 即模型记住训练数据而不是学会泛化。

per_device_train_batch_size

每个设备训练批量大小，在GRPO中，指 completion 的批次大小

假设你设置：

perDeviceTrainBatchSize = 16

• 每次训练时，模型会用 16 个样本 来做一次预测并更新参数；
• 如果你有多个设备（比如多个 GPU），每个设备都会处理 16 个样本；
• 所以总的 batch size = per_device_train_batch_size * num_devices

为什么这个参数重要？

方面	影响
训练速度	越大的 batch size 可能训练更快（利用硬件并行能力）
内存占用	batch size 越大，占用显存越多，太大可能导致 OOM（out of memory）
模型效果	太小可能不稳定（梯度噪声大），太大可能导致泛化能力下降
分布式训练	控制每个设备的负载，便于多设备训练

建议

快速训练	使用尽可能大的 batch size（不超过显存限制）
避免 OOM	从小开始逐步尝试（2 → 4 → 8）
微调大模型	推荐1~8，配合 gradient accumulation
多卡训练	可适当放大 per_device_batch_size
批量归一化（BatchNorm）问题	batch size 不宜过小（否则影响 BN 效果）

learning_rate

学习率，全参数默认为1e-5，LoRA等tuners为1e-4

更通俗的解释

• 在训练神经网络时，我们会计算损失函数（loss）对模型参数的梯度；
• 然后我们用这个梯度来调整模型参数；
• learning_rate 决定了每一步调整的"力度"。

公式大致如下：

newParameter = oldParameter - learningRate * gradient

🔍 学习率的影响：

学习率大小	效果	问题
太大	更新步子大，训练快	容易跳过最优解，导致震荡或发散
太小	更新步子小，稳定但慢	收敛慢，可能陷入局部最小值或耗时太久

建议

1. 图像分类任务（如 CIFAR-10、ImageNet）

• 使用 SGD with momentum 时：

• • 学习率从 0.1 开始，配合学习率衰减策略（如 Step Decay 或 Cosine Annealing）

• 使用 Adam 时：

• • 学习率通常设为 3e-4（即 0.0003）

2. 自然语言处理（NLP）任务

• 使用 Transformer 模型（如 BERT、GPT、InternLM）时：

• • 常用学习率：5e-5（即 0.00005）
  • 有时也使用 3e-5 或 2e-5，特别是在微调阶段

3. 强化学习

• 学习率通常较小，例如：1e-4 到 1e-5

4. 大规模预训练模型微调（Fine-tuning）

• 推荐使用小学习率，如：2e-5 ~ 5e-5
• 因为预训练权重已经很好了，微调时只需轻微调整

warmup_ratio

它表示在整个训练过程中，有多少比例的训练步数（training steps）将被用于"学习率预热"阶段（Warmup Phase）。

通俗地讲：

• 在训练初期，模型权重是随机初始化的，直接使用较大的学习率可能导致不稳定；
• 使用 warmup 阶段可以让学习率从 0（或很小值）逐渐增加到目标学习率；
• 这样可以提高训练稳定性，避免初始阶段的剧烈震荡。

公式解释：

num_warmup_steps = int(warmup_ratio * total_training_steps)

• total_training_steps：整个训练过程中的总步数（通常等于 num_epochs × num_batches_per_epoch）
• warmup_ratio 一般取值在 0.01 ~ 0.2 之间

split_dataset_ratio

它表示训练集和验证集（或测试集）之间的划分比例

通常我们会将一个完整的数据集划分为：

• 训练集（Training Set） ：用于训练模型；
• 验证集（Validation Set） ：用于调参、选择最佳模型；
• （有时也包括）测试集（Test Set） ：用于最终评估模型性能。

假设你有一个包含 1000 条样本的数据集，并设置：

let splitDatasetRatio = 0.8

那么：

• 训练集：1000 × 0.8 = 800 条样本；
• 验证集：1000 × (1 - 0.8) = 200 条样本；

也就是说，这个参数控制了训练集占整个数据集的比例。

lora_rank

lora_rank ****表示 LoRA 中低秩矩阵的秩（rank），它控制了插入到原始模型权重中的适配矩阵的"复杂度"或"表达能力"。

• lora_rank 越小 → 适配矩阵越"简单"，参数越少，节省内存和计算；
• lora_rank 越大 → 适配矩阵越"复杂"，拟合能力越强，但也更容易过拟合；

模型规模	推荐 lora_rank值
小模型（<1B）	8 ~ 64
中等模型（1B~10B）	8 ~ 32
大模型（>10B，如 LLaMA-13B、InternLM-7B）	8 ~ 16

lora_alpha

lora_alpha ****是 LoRA 中用于控制适配矩阵缩放的一个超参数。

数学公式如下：

ΔW =r α ⋅A ⋅B T

其中：

• r ：是 lora_rank
• α ：就是 lora_alpha

假设你设置了：

• lora_rank = 8
• lora_alpha = 16

那么 LoRA 中的缩放因子就是：

16 / 8 = 2

也就是说，你的低秩矩阵的影响会被放大 2 倍。

推荐值范围：

场景	推荐 lora_alpha值
默认推荐	lora_alpha = 2 × lora_rank
小模型（<1B）	8 ~ 32
大模型（>10B，如 InternLM-7B）	16 ~ 64

常见组合示例：

lora_rank = 8,   lora_alpha = 16
lora_rank = 16,  lora_alpha = 32
lora_rank = 32,  lora_alpha = 64

use_chat_template

决定是否在推理或训练过程中自动应用模型内置的"对话格式模板"来组织输入文本

例如，你传入如下对话历史：

[ {"role": "user", "content": "介绍一下你自己"}, {"role": "assistant", "content": "我是 InternLM，由上海人工智能实验室开发的语言模型..."}, {"role": "user", "content": "你能帮我写一篇关于夏天的文章吗？"}]

如果启用了 use_chat_template = true，系统会自动将这段对话转换为类似下面的字符串：

<|User|>: 介绍一下你自己
<|Assistant|>: 我是 InternLM...
<|User|>: 你能帮我写一篇关于夏天的文章吗？

参数值说明：

值	含义
true	使用模型自带的 chat template 自动格式化对话输入
false	不使用模板，需要手动构造完整的 prompt

target_modules

找不到更多的信息

是用来指定哪些模块将接入 LoRA 或其他 tuner 的核心参数

默认为 all-linear. 在LLM和多模态LLM中，其行为有所不同. 若是LLM则自动寻找除lm_head外的linear并附加tuner，若是多模态LLM，则默认只在LLM上附加tuner，该行为可以被freeze_llm、freeze_vit、freeze_aligner控制。该参数不限于LoRA，可用于其他tuners。

gradient_accumulation_steps

它表示在更新模型参数之前，累计多少个 batch 的梯度后再进行一次参数更新。

通俗地说：

• 通常情况下，每处理一个 batch 就计算梯度并更新一次模型；
• 如果你设置 gradient_accumulation_steps = N，那么会先计算 N 个 batch 的梯度，把它们累加起来，再做一次参数更新；
• 这样可以"模拟"出更大的 batch size，而不会占用过多显存。

假设你设置如下参数：

{
  "per_device_train_batch_size": 4,
  "gradient_accumulation_steps": 8
}

那么：

• 每次只用 4 个样本前向/反向传播；
• 累积 8 次之后才更新一次参数；
• 相当于总 batch size 是 4 × 8 = 32；
• 显存消耗只相当于 batch size = 4，但训练效果接近 batch size = 32。

推荐值范围（根据硬件配置）：

场景	推荐 gradient_accumulation_steps值
单卡 A10 / RTX 3090 / L40（24G 显存）	1 ~ 4（batch 较大时可不累积）
单卡 T4 / V100（16G 显存）	4 ~ 8
单卡 RTX 3060 / 2080（12G 显存）	8 ~ 16
显存非常紧张	可设为 32 或更高（牺牲训练速度）

save_steps

它表示在训练过程中，每隔多少个 step 保存一次模型的当前状态（权重、优化器状态等），默认值 500

通俗地说：

• 每训练一定数量的 batch（即 step），就将模型保存下来；
• 这样即使训练中断，也可以从最近的 checkpoint 继续训练；
• 同时也方便你选择验证效果最好的模型。

假设你设置：

"save_steps": 100

那么：

• 每训练 100 个 step，就会保存一次模型；
• 如果你总共训练 1000 个 step，就会保存 10 次（step_100、step_200、...、step_1000）；

推荐值范围（根据训练规模）：

场景	推荐 save_steps值
小数据集 / 快速实验	50 ~ 100
中等规模训练	500 ~ 1000
大规模预训练任务	1000 ~ 10000
需要频繁备份	设置为较小值（如 50）

save_total_limit

它表示在整个训练过程中最多保留多少个模型检查点（checkpoint），超出部分会被自动删除

通俗地说：

• 每次保存模型时（比如每隔 save_steps 步），都会生成一个 checkpoint；
• 如果你设置了 save_total_limit = 2，那么最多只保留最近的两个模型文件；
• 较早的 checkpoint 会被自动清理掉，以节省磁盘空间；

gradient_checkpointing_kwargs

它用于指定在启用梯度检查点时的一些高级选项，通常是为了进一步节省显存（GPU 内存）占用，默认为 None

🔍 什么是梯度检查点（Gradient Checkpointing）？

这是一个深度学习训练优化技术，它的核心思想是：

• 在前向传播时只保留部分中间激活值；
• 反向传播时重新计算这些激活值，而不是全部保存；
• 这样可以显著减少显存占用，代价是增加了计算时间。

使用建议总结：

目标	建议做法
节省内存（显存不够）	启用gradient_checkpointing
提高训练效率	设置"use_reentrant": false（新版推荐）
兼容老模型	设置"use_reentrant": true
大模型微调（如 LLaMA、InternLM）	强烈建议开启并合理配置

logging_steps

它表示每隔多少个训练步（step），就将当前的训练状态（如 loss、学习率等）打印到控制台或写入日志文件一次， 默认为5

通俗地说：

• 每训练一定数量的 batch，模型会输出一次训练信息；
• 这些信息通常包括：当前 step、loss、学习率、运行时间等；
• 方便你监控训练过程和调试模型表现。

dataloader_num_workers

它表示 PyTorch DataLoader 在加载训练或验证数据时使用的子进程数量。

通俗地说：

• 数据从磁盘读取、预处理、打乱、批处理等操作通常不是由主训练线程完成的；
• 这些工作是由多个"worker"子进程并行完成的；
• dataloader_num_workers 就是用来指定使用多少个这样的子进程来加速数据加载。