在 ms-swift（ModelScope SWIFT）框架中使用 Megatron 模式 进行大模型 SFT（Supervised Fine-Tuning）训练时，--train-iters、--max_epochs 和 --save_interval 这三个参数是控制训练进度和模型保存的核心配置。它们之间存在明确的优先级关系和计算逻辑，理解清楚能避免很多“训练步数不对”或“checkpoint 没按预期保存”的坑。

下面用一篇通俗的中文博客风格来详细介绍这三个参数的关系和实际使用建议（基于 ms-swift 最新文档和社区 issue 反馈，2025-2026 年版本行为）。

Megatron SFT 训练中，train_iters、max_epochs、save_interval 到底怎么玩？

大家好，我是 Shizheng Li。最近在用 ms-swift + Megatron 微调 Llama-3.2-3B 模型时，经常被 --train-iters、--max_epochs 和 --save_interval 这仨参数搞得头大。明明想跑 5 个 epoch，结果步数对不上；想每 2000 步保存一次，结果最后没保存最终模型……踩坑无数后，终于捋清楚了它们的关系，今天写下来分享给大家。

1. 三个参数的本质含义

• --train-iters：总训练迭代次数（总 steps）。
  这是 Megatron 底层最硬核的控制参数。训练循环就是跑到这个步数（或更早因为其他条件停止）就结束。
  默认：None（不设置的话要靠别的参数推导）。

• --max_epochs：目标训练轮数（epochs）。
  这是大家最习惯的“跑几轮数据”的表达方式。
  默认：None。

• --save_interval：checkpoint 保存间隔（以 step 为单位）。
  每隔多少个 iteration 保存一次模型。
  默认：500。
  重要：训练结束时一定会额外保存一次最终模型，不管是否整除 save_interval。

2. 它们之间的优先级和自动计算逻辑（关键！）

ms-swift 在 Megatron 模式下对这两个“停止条件”有智能处理：

• 当你同时设置了 --train-iters 和 --max_epochs 时：
  优先使用 max_epochs 自动计算的 train_iters（尤其在新版本中）。
  为什么？因为 ms-swift 支持 packing（序列打包）和动态 batch，数据集打包后“有效样本数”会变化，手动算 train_iters 很容易错。

• 当你只设置 --max_epochs（不传 train_iters）：
  最推荐的做法！
  ms-swift 会自动根据以下公式计算总步数：

  一个 epoch 的步数 ≈ ceil(数据集总样本数 / global_batch_size)
  总 train_iters ≈ ceil(一个 epoch 的步数 × max_epochs)
  

  • 如果用了 packing，非流式数据集也能兼容计算。
  • 日志里通常会打印类似：train_iters auto set to: 10850 这样的信息。

• 当你只设置 --train-iters（不传 max_epochs）：
  严格按你指定的总步数跑，不会管 epoch。
  适合你已经精确预估好步数，或者想完全手动控制的情况。

• --save_interval 的行为：
  保存时机完全基于 当前 iteration（从 0 开始计数）：

  • 当 iteration % save_interval == 0 时保存（通常从 save_interval 开始，比如 500、1000…）
  • 训练结束（达到 train_iters 或 max_epochs）时，强制额外保存一次最终 checkpoint（即使不是 save_interval 的倍数）。

3. 实际案例分析（来自我的一次真实训练命令）

命令片段：

--train-iters 10850 \
--max_epochs 5 \
--global_batch_size 16 \
--save_interval 5000 \
--dataset .../train_mixed.jsonl   # 假设约34726条样本

计算过程：

• 数据集 ≈ 34726 条
• global_batch_size = 16 → 一个 epoch ≈ 34726 / 16 ≈ 2170.375 步 → ceil 到 2171 步
• 5 epochs ≈ 2171 × 5 ≈ 10855 步（接近你写的 10850，基本匹配，可能有轻微 rounding）

结果：

• ms-swift 很可能自动把 train_iters 调整为 ≈10850~10855（以 max_epochs 为准）
• 保存点：step 5000、step 10000
• 结束时（~10850 步）额外保存最终模型

如果你日志里 train_iters 被改了，别慌——这就是 max_epochs 在起作用。

4. 推荐的使用姿势（避坑指南）

额外小技巧：

• 想只按 epoch 保存？用 --save_strategy epoch（新版本支持），这时 save_interval 会强制为 1（每个 epoch 都存）。
• 训练中途想看日志确认：搜 train_iters 或 auto set 关键词。

5. 小结

一句话概括 ms-swift Megatron SFT 的逻辑：

“max_epochs 是人性化的入口，train_iters 是底层铁律，save_interval 是基于步数的闹钟，而最终模型永远会额外保存一次。”

用对这三个参数，能让你的训练既高效又可控。希望这篇分享帮到正在调 SWIFT 的朋友～