MT-Megatron 0.19.0 训练参数参考
本文按模型结构、MoE、训练控制、优化器和数据配置分组列出 MT-Megatron 常用参数。使用参数前,请确认容器内的 MT-Megatron 版本和启动脚本支持该参数。
1. 模型结构参数
| 参数 | 作用 |
|---|---|
--num-layers | Transformer Block 数量。 |
--hidden-size | 每个 token 的隐藏表示维度。 |
--num-attention-heads | 多头注意力头数;示例配置使用 128。 |
--seq-length | 单次训练的输入序列长度。 |
--max-position-embeddings | 模型支持的最大位置编码数量。 |
--norm-epsilon | 归一化操作的数值稳定项;示例为 1e-6。 |
--attention-dropout | Attention dropout 比例;0.0 表示不使用 dropout。 |
--hidden-dropout | 隐藏层 dropout 比例;0.0 表示不使用 dropout。 |
--disable-bias-linear | 禁用线性层的 bias。 |
--vocab-size | tokenizer 词表大小。 |
--ffn-hidden-size | 前馈网络隐藏层维度。 |
--position-embedding-type | 位置编码类型;长文本示例使用 rope。 |
--no-position-embedding | 不创建显式位置编码,通常与 RoPE 配合使用。 |
--swiglu | 使用 SwiGLU 激活函数。 |
--normalization | 选择归一化方法;示例使用 RMSNorm。 |
--untie-embeddings-and-output-weights | 不共享输入词嵌入和输出层权重。 |
模型结构参数必须与 tokenizer、checkpoint 和模型定义一致。Hugging Face 权重转换前,请同时核对 config.json 中的层数、隐藏维度、注意力头数和词表大小。
2. MoE 参数
| 参数 | 作用 |
|---|---|
--num-experts | 每个 MoE 层的专家数量。 |
--expert-model-parallel-size | 专家并行度(EP),控制专家参数在设备间的划分。 |
--moe-token-dispatcher-type | token 分发方式;示例使用 alltoall,DeepEP 示例使用 flex。 |
--moe-router-score-function | Router 分数函数;示例使用 softmax。 |
--moe-router-num-groups | Router 分组数量。 |
--moe-router-group-topk | 每个路由组选择的 top-k 专家数。 |
--moe-router-load-balancing-type | 负载均衡策略;示例使用 seq_aux_loss。 |
--moe-router-topk | 每个 token 选择的专家数,通常为 1 或 2。 |
--moe-router-pre-softmax | 在 softmax 前计算路由分数。 |
--moe-router-topk-scaling-factor | 缩放 top-k 路由分数。 |
--moe-aux-loss-coeff | token 级负载均衡辅助损失权重;示例为 3e-3。 |
--moe-expert-capacity-factor | 每个专家可处理的 token 容量因子。 |
--moe-device-level-capacity | 启用设备级专家容量控制。 |
--moe-device-level-aux-loss-coeff | 设备级负载均衡损失权重;示例为 5e-2。 |
--moe-comm-aux-loss-coeff | 跨设备通信负载均衡损失权重;示例为 2e-2。 |
--moe-ffn-hidden-size | 每个专家的前馈网络隐藏层维度。 |
--moe-shared-expert-intermediate-size | 共享专家的中间层维度。 |
--moe-layer-freq | MoE 层插入频率;例如 2 表示每两层插入一个 MoE 层。 |
--moe-grouped-gemm | 使用 Grouped GEMM 合并专家矩阵计算。 |
--moe-permute-fusion | 融合 token permute 操作;是否支持以当前实现为 准。 |
MoE 参数之间存在依赖关系。配置 --moe-token-dispatcher-type flex 时,还需要安装兼容的 DeepEP 版本;启用 EP 通信重叠时,需要另行添加高级特性页面列出的参数。
2.1 DeepSeek MLA 和 MTP 参数
| 参数 | 作用 |
|---|---|
--q-lora-rank | Query 投影矩阵的 LoRA 秩。 |
--kv-lora-rank | Key 和 Value 投影矩阵的 LoRA 秩。 |
--qk-head-dim | Query 和 Key 的单头维度;示例为 128。 |
--qk-pos-emb-head-dim | Query 和 Key 位置编码子空间维度;示例为 64。 |
--v-head-dim | Value 的单头维度;示例为 128。 |
--rotary-scaling-factor | RoPE 缩放因子,用于调整长序列位置编码。 |
--use-multi-token-prediction | 启用多 token 预测;默认关闭。 |
--mtp-coeff | 多 token 预测损失权重。 |
--mtp-depth | 多 token 预测深度。 |
3. 训练控制参数
| 参数 | 作用 |
|---|---|
--seed | 随机种子;示例为 42。 |
--micro-batch-size | 每张 GPU 的微批次大小。 |
--global-batch-size | 全局批次大小,等于微批次、数据并行度和梯度累积步数的乘积。 |
--train-iters | 总训练迭代步数。 |
--init-method-std | 参数初始化标准差;示例为 0.006。 |
--use-mcore-models | 使用 Megatron Core 模型实现。 |
--no-rope-fusion | 禁用 RoPE 融合。 |
--use-distributed-optimizer | 使用分布式优化器。 |
--use-flash-attn | 使用 FlashAttention。 |
--sequence-parallel | 按序列维度划分激活和计算。 |
--recompute-granularity | 激活重计算粒度;示例为 full。 |
--recompute-method | 重计算方法;示例为 block。 |
--recompute-num-layers | 启用重计算的层数。 |
--distributed-backend | 分布式通信后端;MUSA 使用 MCCL,但兼容参数名仍为 nccl。 |
--multi-latent-attention | 启用多隐变量注意力。 |
--qk-layernorm | 对 Query 和 Key 应用 LayerNorm。 |
--overlap-grad-reduce | 重叠梯度规约与反向传播。 |
--moe-shared-expert-overlap | 重叠 MoE 共享专家参数通信与计算。 |
--train-samples | 指定训练样本数;示例配置未启用。 |
--no-gradient-accumulation-fusion | 禁用梯度累积融合。 |
--no-bias-dropout-fusion | 禁用 bias 与 dropout 融合。 |
--no-bias-swiglu-fusion | 禁用 bias 与 SwiGLU 融合。 |
--no-persist-layer-norm | 禁用持久化 LayerNorm。 |
--num-layers-per-virtual-pipeline-stage | 每个虚拟流水线阶段包含的层数。 |
--decoder-first-pipeline-num-layers | Pipeline 首阶段包含的层数。 |
--decoder-last-pipeline-num-layers | Pipeline 末阶段包含的层数。 |
--wait-after-ckpt | checkpoint 写入后的等待秒数。 |
--overlap-param-gather | 重叠参数收集与前向计算。 |
--tp-comm-overlap | 重叠 Tensor Parallel 通信与计算。 |
--disable-tp-comm-overlap-ag | 禁用 TP 通信与 AllGather 重叠。 |
--no-overlap-p2p-communication | 禁用点对点通信重叠。 |
--micro-batch-size、--global-batch-size、数据并行度和梯度累积步数必须满足一致关系。改变 GPU 数或并行度后,重新计算全局批次。
4. 显存优化参数
4.1 Optimizer offload
| 参数 | 作用 |
|---|---|
--optimizer-cpu-offload | 将优化器状态移至 CPU。 |
--optimizer-offload-fraction | 控制 CPU offload 比例;示例为 1.0。 |
--use-precision-aware-optimizer | 使用精度感知优化器。 |
--overlap-cpu-optimizer-d2h-h2d | 重叠 CPU 优化器与 D2H/H2D 数据传输。 |
4.2 细粒度重计算
| 参数 | 作用 |
|---|---|
--attn-recompute | 仅对 Attention 层启用重计算。 |
--recompute-variance | 重计算方差计算部分。 |
--mlp-recompute | 仅对 MLP 层启用重计算。 |
Offload 和重计算都会降低显存占用,也会增加 CPU、PCIe 或计算开销。调整后应重新测量每步耗时和显存余量。
5. 优化器与学习率参数
| 参数 | 作用 |
|---|---|
--weight-decay | L2 正则化系数;示例为 0.1。 |
--adam-beta1 | Adam 一阶矩估计的衰减系数;示例为 0.9。 |
--adam-beta2 | Adam 二阶矩估计的衰减系数;示例为 0.95。 |
--clip-grad | 梯度裁剪阈值;示例为 1.0。 |
--lr | 初始学习率。 |
--lr-decay-style | 学习率衰减策略;示例为 cosine。 |
--lr-warmup-iters | 学习率预热步数。 |
--min-lr | 学习率衰减下限。 |
--initial-loss-scale | 混合精度训练的初始 loss scale;示例为 65536。 |
--min-loss-scale | 动态 loss scale 的最小值;示例为 1.0。 |
学习率和全局批次通常需要联合调整。扩大数据并行度或改变梯度累积步数后,重新评估 warmup 和总训练步数。
6. 模型并行参数
| 参数 | 作用 |
|---|---|
--tensor-model-parallel-size | Tensor Parallel 并行度(TP)。 |
--pipeline-model-parallel-size | Pipeline Parallel 并行度(PP)。 |
--expert-model-parallel-size | Expert Parallel 并行度(EP),仅用于 MoE。 |
数据并行度通常由总 GPU 数和模型并行度推导。以 TP、PP、EP 和 DP 配置训练前,请确认 TP × PP × DP 或对应 MoE 组合与世界大小一致。
7. 混合精度参数
| 参数 | 作用 |
|---|---|
--bf16 | 使用 bfloat16 训练。 |
--attention-softmax-in-fp32 | 在 FP32 中计算 Attention softmax。 |
--no-masked-softmax-fusion | 禁用 masked softmax 融合。 |
--accumulate-allreduce-grads-in-fp32 | 使用 FP32 累积和规约梯度。 |
精度参数应保持一致组合。启用 FP8 时,还需参考 MT-Megatron 关键特性与参数说明中的 Transformer Engine 参数。
8. 数据参数
| 参数 | 作用 |
|---|---|
--data-path | 训练数据前缀或分片列表。 |
--tokenizer-type | tokenizer 类型;Hugging Face 模型示例使用 HuggingFaceTokenizer。 |
--tokenizer-model | tokenizer 名称或本地模型路径。 |
--split | 训练集和验证集划分;示例 1 表示只使用训练集。 |
数据参数需要与 tokenization 阶段使用的 tokenizer 保持一致。更换 tokenizer 或词表后,重新生成二进制数据。

