使用 Megatron Bridge 执行 Qwen3-30B-A3B SFT
本文支持的开源 Megatron Bridge 版本是 v0.6.2。TrainingSuite v2.2.0 镜像依赖的 Megatron Bridge 版本为 0.4.2,但 0.4.2 不能替代本文所需的 v0.6.2,两者不能混用,也不能因为镜像内已有 0.4.2 就跳过 v0.6.2 的安装和检查。
本文流程按照官方 v0.6.2 源码执行,并在训练前确认 importlib.metadata.version("megatron-bridge") 输出 0.6.2。
1. 流程范围
本文使用 training-musa-adaptor/examples/megatron_bridge/qwen3_sft,在 MUSA 环境完成 Qwen3-30B-A3B 的文本 SFT:
tulu-3-sft-mixture 原始数据
↓
文本占位符、截断和全 mask 样本清洗
↓
Qwen3-30B-A3B Hugging Face 权重
↓
Megatron Bridge 0.6.2 + Megatron Core
↓
training-musa-adaptor MUSA 适配
↓
单机或双机 SFT
这条流程使用 tulu3 纯文本数据和 qwen3_sft 示例,与 Megatron Bridge 预训练与 SFT SOP 中的 Qwen 多模态 LLaVA 流程不同。
2. 版本基线
| 组件 | 本文要求 |
|---|---|
| Megatron Bridge 开源版本 | v0.6.2 |
| TrainingSuite 镜像依赖的 Bridge 版本 | 0.4.2,不可替代本文的 v0.6.2 |
| Python | 本文验证环境使用 Python 3.12 |
| GPU | MTT S5000 |
| 训练数据 | allenai/tulu-3-sft-mixture |
| 模型 | Qwen/Qwen3-30B-A3B |
| MUSA 适配 | training-musa-adaptor 中的 qwen3_sft 示例 |
开始前在容器内检查实际版本:
python3 - <<'PY'
import sys
from importlib.metadata import PackageNotFoundError, version
print("Python:", sys.version)
for package in ("megatron-bridge", "megatron-core", "training-musa-adaptor"):
try:
print(package, version(package))
except PackageNotFoundError:
print(package, "not installed")
PY
安装 v0.6.2 前,如果输出显示镜像自带 megatron-bridge 0.4.2,直接继续会混淆两个版本。本文按第 3 节从官方 v0.6.2 源码重新安装,并再次检查版本。
3. 准备运行环境
3.1 启动容器
使用包含 MUSA、PyTorch、Transformer Engine 和 Python 3.12 依赖的 TrainingSuite v2.2.0 训练环境。公网镜像标签以正式发布仓库为准:
docker run -it -d \
--ipc host \
--net host \
--shm-size 100g \
--privileged \
-v /ipfs:/ipfs \
-v /data:/data \
--name mbridge-qwen3-sft \
registry.mthreads.com/mcconline/training-suite:v2.2.0 \
bash
docker exec -it mbridge-qwen3-sft bash
如果当前镜像不是 Python 3.12,或缺少本文所需的 MUSA 组件,请切换到对应的兼容训练环境。不要在同一容器中混用多个 Python 解释器安装的 Bridge 和 PyTorch 包。
3.2 设置目录
export ADAPTOR_SRC=/data/software/training-musa-adaptor
export EXAMPLE_DIR="$ADAPTOR_SRC/examples/megatron_bridge/qwen3_sft"
export WORKSPACE_ROOT=/data/workspace/qwen3-30b-a3b-sft
export BRIDGE_HOME="$WORKSPACE_ROOT/Megatron-Bridge"
mkdir -p "$WORKSPACE_ROOT"
cd "$WORKSPACE_ROOT"
ADAPTOR_SRC 指向与当前 TrainingSuite 版本配套的 training-musa-adaptor 源码。该目录需要包含 examples/megatron_bridge/qwen3_sft。
3.3 安装 training-musa-adaptor
python3 -m pip install \
--no-deps \
--no-build-isolation \
-e "$ADAPTOR_SRC"
4. 安装 Megatron Bridge v0.6.2
从 NVIDIA 官方仓库获取 v0.6.2:
cd "$WORKSPACE_ROOT"
git clone \
--branch v0.6.2 \
--depth 1 \
https://github.com/NVIDIA-NeMo/Megatron-Bridge.git \
"$BRIDGE_HOME"
如果 python3 -m pip show megatron-bridge 显示镜像自带的是 0.4.2,继续使用 v0.6.2 源码安装,让当前 Python 环境切换到目标版本:
python3 -m pip install \
--no-deps \
--no-build-isolation \
-e "$BRIDGE_HOME"
检查实际版本:
python3 - <<'PY'
import os
from importlib.metadata import version
bridge_version = version("megatron-bridge")
print("megatron-bridge:", bridge_version)
print("training-musa-adaptor:", version("training-musa-adaptor"))
print("BRIDGE_HOME:", os.environ.get("BRIDGE_HOME"))
assert bridge_version == "0.6.2", bridge_version
PY
只有输出 megatron-bridge: 0.6.2 后,才继续后续步骤。镜像中的 0.4.2 不满足本文要求。
5. 补充数据依赖
如果镜像缺少以下数据处理依赖,执行:
python3 -m pip install \
--no-cache-dir \
--no-deps \
-i https://mirrors.aliyun.com/pypi/simple/ \
pyarrow==21.0.0 \
datasets==4.8.5 \
multi-storage-client==1.1.0 \
webdataset==1.0.2 \
braceexpand==0.1.7 \
s3fs==2026.9.0 \
defusedxml==0.7.1 \
xattr==1.3.0 \
pulp==3.3.2
已经具备相同兼容版本的镜像可以跳过本步骤。不要使用普通 CUDA 环境的 PyTorch 或 Torch 包覆盖当前 MUSA 软件栈。
6. 下载模型和数据
在 WORKSPACE_ROOT 下执行:
modelscope download \
--dataset allenai/tulu-3-sft-mixture \
--local_dir data/tulu3-sft-mixture
modelscope download \
Qwen/Qwen3-30B-A3B \
--local_dir /ipfs/models/Qwen3-30B-A3B
确认数据目录、tokenizer 和模型分片完整:
du -sh data/tulu3-sft-mixture
ls -lh /ipfs/models/Qwen3-30B-A3B
7. 清洗 tulu3 数据
原始 tulu3 数据中以下三类样本会导致训练失败或监督无效:
- 含有
<image>、<video>或<audio>占位符的文本样本,会被 Bridge 误判为多模态并触发 VLM collator 错误。 - 超过
seq_length截断后无法构建 assistant mask 的多轮对话。 - 截断后没有任何监督 token 的样本。
执行完整清洗:
cd "$WORKSPACE_ROOT"
NVTE_FRAMEWORK=musa \
PYTHONPATH="$BRIDGE_HOME/src:/home/Megatron-LM" \
python3 "$EXAMPLE_DIR/clean_tulu3_dataset.py" \
--src data/tulu3-sft-mixture \
--dst data/tulu3-sft-mixture-clean \
--tokenizer /ipfs/models/Qwen3-30B-A3B \
--seq-length 4096 \
--workers 16 \
--drop-all-masked
确认输出目录存在且非空:
du -sh data/tulu3-sft-mixture-clean
find data/tulu3-sft-mixture-clean -maxdepth 2 -type f | head
8. 检查训练配置
先设置参数并执行 dry-run:
export MODEL_PATH=/ipfs/models/Qwen3-30B-A3B
export DATA_PATH="$WORKSPACE_ROOT/data/tulu3-sft-mixture-clean"
export OUTPUT_DIR="$WORKSPACE_ROOT/outputs/qwen3-30b-a3b-sft"
export CONFIG_FILE="$EXAMPLE_DIR/conf/qwen3_30b_a3b_sft_adam.yaml"
export DRY_RUN=1
bash "$EXAMPLE_DIR/run_sft_multinodes.sh"
确认展开后的配置使用:
- Bridge 源码路径
BRIDGE_HOME; - Megatron Core 路径
/home/Megatron-LM; - Qwen3-30B-A3B 模型;
- 清洗后的
tulu3-sft-mixture-clean; - 单机 8 卡或当前指定的多机拓扑。
9. 执行单机 SFT
export DRY_RUN=0
export NNODES=1
export NPROC_PER_NODE=8
export OUTPUT_DIR="$WORKSPACE_ROOT/outputs/qwen3-30b-a3b-sft-$(date +%Y%m%d_%H%M%S)"
bash "$EXAMPLE_DIR/run_sft_multinodes.sh"
首次运行使用新的 OUTPUT_DIR,避免自动加载旧目录中的 Adam checkpoint。
需要切换 Muon 配置时:
CONFIG_FILE="$EXAMPLE_DIR/conf/qwen3_30b_a3b_sft_muon.yaml" \
OUTPUT_DIR="$WORKSPACE_ROOT/outputs/qwen3-muon-run1" \
bash "$EXAMPLE_DIR/run_sft_multinodes.sh"
10. 执行多机 SFT
各节点必须共享模型、清洗后的数据和输出目录。如果作业系统已经提供 WORLD_SIZE 和 RANK,脚本分别将其作为 NNODES 和 NODE_RANK;否则显式设置。
节点 0:
NNODES=2 \
NODE_RANK=0 \
MASTER_ADDR=<ip> \
bash "$EXAMPLE_DIR/run_sft_multinodes.sh"
节点 1:
NNODES=2 \
NODE_RANK=1 \
MASTER_ADDR=<ip> \
bash "$EXAMPLE_DIR/run_sft_multinodes.sh"
所有节点同时满足:
- Bridge 版本均为
0.6.2; - Megatron Core、
training-musa-adaptor和其他 Python 依赖一致; - 使用相同模型、数据和输出路径;
MASTER_ADDR和端口可从所有节点访问。
11. 常用环境变量
| 变量 | 默认值或示例 | 作用 |
|---|---|---|
MEGATRON_HOME | /home/Megatron-LM | Megatron Core 源码 |
BRIDGE_HOME | $WORKSPACE_ROOT/Megatron-Bridge | Bridge v0.6.2 源码 |
MODEL_PATH | /ipfs/models/Qwen3-30B-A3B | Hugging Face 模型 |
DATA_PATH | $WORKSPACE_ROOT/data/tulu3-sft-mixture-clean | 清洗后的数据 |
CONFIG_FILE | qwen3_30b_a3b_sft_adam.yaml | Hydra 训练配置 |
OUTPUT_DIR | $WORKSPACE_ROOT/outputs/megatron_bridge_sft | 日志、TensorBoard 和 checkpoint 根目录 |
CKPT_DIR | $OUTPUT_DIR/checkpoints | checkpoint 目录 |
DRY_RUN | 0 | 1 时仅合并并打印配置 |
EXTRA_ARGS | 无 | 追加配置覆盖,例如 train.train_iters=10 |
NPROC_PER_NODE | 8 | 每节点进程数 |
NNODES | 1 | 节点数 |
NODE_RANK | 0 | 当前节点编号 |
MASTER_ADDR | 127.0.0.1 | 主节点地址 |
MASTER_PORT | 29571 | 主节点端口 |
RESUME_STEP | 无 | 指定恢复 step |
脚本在 MUSA 路径上设置:
| 环境变量 | 作用 |
|---|---|
NVTE_FRAMEWORK=musa | Transformer Engine 使用 MUSA 后端 |
TRAINING_MUSA_ADAPTOR_DISABLE=megatron.moe.permutation.unfused-musa | 关闭过期的 MoE permute 补丁 |
USE_DEEPEP_ACE=1 | 启用 DeepEP ACE 通信路径 |
SYNC_DEEPEP_A2AV=1 | 同步 DeepEP all-to-all 路径 |
12. 断点续训
当 CKPT_DIR/latest_checkpointed_iteration.txt 存在时,脚本自动追加 checkpoint、optimizer 和 RNG 恢复参数:
RESUME_STEP=10 \
CKPT_DIR="$OUTPUT_DIR/checkpoints" \
bash "$EXAMPLE_DIR/run_sft_multinodes.sh"
13. 输出与检查
$OUTPUT_DIR/
├── logs/<时间戳>/run-node<rank>.log
├── tf_logs/<时间戳>/
└── checkpoints/iter_XXXXXXX/
检查:
- 日志中没有 Bridge 版本为
0.4.2或 import 路径指向镜像旧版本的记录; - 每个节点均使用同一份 Bridge v0.6.2 和 adaptor 代码;
- 数据清洗没有残留多模态占位符和全 mask 样本;
logs、tf_logs和checkpoints按预期生成;- 多机任务中所有 rank 使用相同的模型、数据和输出路径。
14. 常见问题
14.1 No VLM collate function is registered for processor type 'Qwen2Tokenizer'
原始文本中仍包含 <image>、<video> 或 <audio> 占位符。重新执行数据清洗,并检查清洗输出是否被训练脚本实际引用。
14.2 AssistantMaskBoundaryConfig did not match any loss-contributing spans
截断后的多轮对话无法构建 assistant mask。开启完整清洗流程,并确认 --seq-length 与训练配置中的序列长度一致。
14.3 permute() got an unexpected keyword argument 'tokens_per_expert'
确认脚本设置:
export TRAINING_MUSA_ADAPTOR_DISABLE=megatron.moe.permutation.unfused-musa
同时检查 training-musa-adaptor 是否为当前示例对应版本。
14.4 实际加载的仍是 Megatron Bridge 0.4.2
检查:
python3 -m pip show megatron-bridge
python3 -c 'import megatron.bridge; print(megatron.bridge.__file__)'
echo "$BRIDGE_HOME"
echo "$PYTHONPATH"
确认镜像旧版本已经移除,editable 安装指向 $BRIDGE_HOME,并保证所有节点重新创建了 Python 进程。
15. 相关文档
- Megatron Bridge 入门:Bridge 定位、能力边界和 MUSA 架构;
- Megatron Bridge 预训练与 SFT SOP:Qwen 多模态 LLaVA 训练;
- Megatron Bridge 官方仓库:v0.6.2 源码与发布信息。

