跳到主要内容

MT-Megatron 0.19.0 训练参数参考

本文按模型结构、MoE、训练控制、优化器和数据配置分组列出 MT-Megatron 常用参数。使用参数前,请确认容器内的 MT-Megatron 版本和启动脚本支持该参数。

1. 模型结构参数​

参数作用
--num-layersTransformer Block 数量。
--hidden-size每个 token 的隐藏表示维度。
--num-attention-heads多头注意力头数;示例配置使用 128。
--seq-length单次训练的输入序列长度。
--max-position-embeddings模型支持的最大位置编码数量。
--norm-epsilon归一化操作的数值稳定项;示例为 1e-6。
--attention-dropoutAttention dropout 比例;0.0 表示不使用 dropout。
--hidden-dropout隐藏层 dropout 比例;0.0 表示不使用 dropout。
--disable-bias-linear禁用线性层的 bias。
--vocab-sizetokenizer 词表大小。
--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-typetoken 分发方式;示例使用 alltoall,DeepEP 示例使用 flex。
--moe-router-score-functionRouter 分数函数;示例使用 softmax。
--moe-router-num-groupsRouter 分组数量。
--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-coefftoken 级负载均衡辅助损失权重;示例为 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-freqMoE 层插入频率;例如 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-rankQuery 投影矩阵的 LoRA 秩。
--kv-lora-rankKey 和 Value 投影矩阵的 LoRA 秩。
--qk-head-dimQuery 和 Key 的单头维度;示例为 128。
--qk-pos-emb-head-dimQuery 和 Key 位置编码子空间维度;示例为 64。
--v-head-dimValue 的单头维度;示例为 128。
--rotary-scaling-factorRoPE 缩放因子,用于调整长序列位置编码。
--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-layersPipeline 首阶段包含的层数。
--decoder-last-pipeline-num-layersPipeline 末阶段包含的层数。
--wait-after-ckptcheckpoint 写入后的等待秒数。
--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-decayL2 正则化系数;示例为 0.1。
--adam-beta1Adam 一阶矩估计的衰减系数;示例为 0.9。
--adam-beta2Adam 二阶矩估计的衰减系数;示例为 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-sizeTensor Parallel 并行度(TP)。
--pipeline-model-parallel-sizePipeline Parallel 并行度(PP)。
--expert-model-parallel-sizeExpert 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-typetokenizer 类型;Hugging Face 模型示例使用 HuggingFaceTokenizer。
--tokenizer-modeltokenizer 名称或本地模型路径。
--split训练集和验证集划分;示例 1 表示只使用训练集。

数据参数需要与 tokenization 阶段使用的 tokenizer 保持一致。更换 tokenizer 或词表后,重新生成二进制数据。

9. 相关文档​