MT-Megatron 关键特性与参数说明
本文适用于需要在 MUSA 环境中启用高级并行、通信和性能分析能力的开发者。
Megatron-MUSA-Titan 的特性依赖对应的 Megatron、Transformer Engine、DeepEP、Mooncake 和 Titan 集成版本。使用前应在实际容器中核对相关模块、参数和依赖是否存在。
1. 基础环境设置
在每个训练进程启动训练之前,需要在训练进程的启动脚本中设置环境变量,再让 Python 导入训练库。只在启动节点执行 export 不会自动把变量传递到其他节点,也不会自动传入 Ray 工作进程。
export ACCELERATOR_BACKEND=musa
# 在 Megatron-MUSA-Titan 仓库根目录执行时设置。
# 如果 Megatron-LM 位于其他路径,请修改第二个路径。
export PYTHONPATH="$PWD:$PWD/../Megatron-LM${PYTHONPATH:+:$PYTHONPATH}"
| 环境变量 | 示例值 | 作用 |
|---|---|---|
ACCELERATOR_BACKEND | musa | 选择 MUSA 初始化路径,但不会自动安装适配补丁 |
PYTHONPATH | 按实际目录设置 | 让 Python 能够导入 Megatron-MUSA-Titan 和对应的 Megatron-LM 源码 |
仅设置 ACCELERATOR_BACKEND=musa 不会启用预训练适配。预训练入口必须在导入 Megatron 之前显式调用 apply_pretrain_patch():
import os
if os.getenv("ACCELERATOR_BACKEND", "musa") == "musa":
from musa_titan import apply_pretrain_patch
apply_pretrain_patch()
示例启动脚本可能会覆盖已经导出的环境变量。遇到配置没有生效时,应检查每个训练进程实际执行的启动脚本,而不能只检查控制节点上的命令行环境。
2. 块级 FP8 训练
块级 FP8 训练通过 Transformer Engine 执行, 需要增加以下 Megatron 参数:
--transformer-impl transformer_engine
--fp8-format e4m3
--fp8-param-gather
--fp8-recipe mxfp8
MT-TransformerEngine 会将 MXFP8BlockScaling 映射到 MUSA 实现 MTFP8BlockScaling。使用前应确认容器中的 MT-TransformerEngine 包含该实现,并确认模型和硬件配置支持对应精度。
3. 通过 ACE 使用 DeepEP
需要在每个训练进程中设置:
export USE_DEEPEP_ACE=1
同时增加以下 Megatron 参数:
--moe-token-dispatcher-type flex
--moe-enable-deepep
| 环境变量 | 示例值 | 作用 |
|---|---|---|
USE_DEEPEP_ACE | 1 | 启用面向 ACE 的 DeepEP token 分发适配 |
该功能要求 DeepEP 构建版本支持 ACE,并提供 get_ace_combine_buffer 接口。
4. EP 通信与计算重叠
在已经启用基于 ACE 的 DeepEP 的基础上,增加:
--overlap-moe-expert-parallel-comm
该参数在虚拟流水线并行(VPP)下启用批次级专家并行(EP)通信与计算重叠。Titan 没有额外的 EP 重叠环境 变量,单独设置 USE_DEEPEP_ACE=1 不会自动开启 EP 重叠。
--delay-wgrad-compute 是可选配套参数,不是启用 EP 重叠的前置条件。使用该参数时,需要同时启用 EP 重叠,并确保当前实现支持非旧版的分组矩阵乘(Grouped GEMM)路径。
5. 结合 VPP 与 1F1B 的激活卸载
激活卸载通过以下 Megatron 参数启用:
--offload-moe-fc1-input
--offload-moe-fused-swiglu-input
--offload-moe-fc1-input:卸载路由专家 FC1 的输入激活。--offload-moe-fused-swiglu-input:卸载融合 SwiGLU 的输入激活。
当前 Titan 配置要求流水线并行度(PP)大于或等于 3。该能力没有独立的 Titan 环境变量开关。
6. 基于 RDMA 后端的 PP 通信重叠
该能 力使用 Mooncake 点对点 RDMA,在虚拟流水线并行(VPP)下将流水线并行的激活和梯度传输与其他虚拟阶段的计算重叠。
每个训练进程的启动脚本需要设置:
export PP_USE_MOONCAKE=1
export MOONCAKE_P2P_SLOT_SIZE_BYTES=134217728
export MC_WORKERS_PER_CTX=2
export MC_SLICE_SIZE=65536
| 环境变量 | 示例值 | 作用 |
|---|---|---|
PP_USE_MOONCAKE | 1 | 启用 Mooncake P2P RDMA 后端 |
MOONCAKE_P2P_SLOT_SIZE_BYTES | 134217728 | 单次 P2P 传输槽位大小,示例为 128 MiB |
MC_WORKERS_PER_CTX | 2 | 每个上下文的 Mooncake 工作进程数量 |
MC_SLICE_SIZE | 65536 | Mooncake 数据传输分片大小 |
使用该能力还需要:
- 使用支持 Mooncake 的 Megatron 集成;
- 训练节点之间具备可用的 RDMA 连接;
- 配置有效的 VPP 布局和对应 P2P 重叠参数。
只设置 PP_USE_MOONCAKE=1 不会自动启用调度重叠。MOONCAKE_P2P_SLOT_SIZE_BYTES 的 128 MiB 只是示例值,应根据流水线配置中最大的激活或梯度传输量调整。
7. 分布式整体执行轨迹分析
Megatron-MUSA-Titan 提供两类互补的性能分析能力。
7.1 单 GPU PyTorch 调用栈分析
该工具从 GPU 执行轨迹中重建 PyTorch 算子调用栈,将执行开销关联到对 应的 Python 代码。它适用于任意 PyTorch 程序,不限于 Megatron,也不依赖特定加速器后端。
采集执行轨迹时,需要在 torch.profiler.profile(...) 中设置 with_stack=True:
with torch.profiler.profile(..., with_stack=True) as prof:
# 执行需要分析的训练步骤
pass
7.2 大规模分布式 Megatron 执行轨迹分析
该工具分析多个训练进程的执行轨迹,用于定位:
- 高耗时算子;
- 通信瓶颈;
- 流水线气泡;
- 滞后节点;
- 可优先优化的大规模训练问题。
该分析能力也可以用于其他加速器后端的 Megatron 训练。相关工具可参考 Distributed Holistic Trace Analysis。
8. 使用建议
- 先在单个训练进程中确认环境变量、源码路径和
apply_pretrain_patch()均已生效,再启动多卡或多机任务。 - 首次启用 FP8、DeepEP、EP 重叠、激活卸载或 Mooncake PP 重叠时,先缩小模型和训练步数,确认依赖及参数组合可用。
- 多机任务应逐节点核对训练进程的运行环境,不要只检查启动节点。
- Mooncake PP 重叠和 EP 重叠都需要额外的并行配置与运行条件,单独设置环境变量不足以启用完整能力。
- 性能分析前先确认训练流程稳定,再将执行轨迹中的高耗时算子、通信等待、流水线气泡和慢节点作为优化依据。

