跳到主要内容

使用 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
GPUMTT 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 数据中以下三类样本会导致训练失败或监督无效:

  1. 含有 <image>、<video> 或 <audio> 占位符的文本样本,会被 Bridge 误判为多模态并触发 VLM collator 错误。
  2. 超过 seq_length 截断后无法构建 assistant mask 的多轮对话。
  3. 截断后没有任何监督 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-LMMegatron Core 源码
BRIDGE_HOME$WORKSPACE_ROOT/Megatron-BridgeBridge v0.6.2 源码
MODEL_PATH/ipfs/models/Qwen3-30B-A3BHugging Face 模型
DATA_PATH$WORKSPACE_ROOT/data/tulu3-sft-mixture-clean清洗后的数据
CONFIG_FILEqwen3_30b_a3b_sft_adam.yamlHydra 训练配置
OUTPUT_DIR$WORKSPACE_ROOT/outputs/megatron_bridge_sft日志、TensorBoard 和 checkpoint 根目录
CKPT_DIR$OUTPUT_DIR/checkpointscheckpoint 目录
DRY_RUN01 时仅合并并打印配置
EXTRA_ARGS无追加配置覆盖,例如 train.train_iters=10
NPROC_PER_NODE8每节点进程数
NNODES1节点数
NODE_RANK0当前节点编号
MASTER_ADDR127.0.0.1主节点地址
MASTER_PORT29571主节点端口
RESUME_STEP无指定恢复 step

脚本在 MUSA 路径上设置:

环境变量作用
NVTE_FRAMEWORK=musaTransformer 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. 相关文档​