Megatron Bridge 预训练与 SFT 示例
本文使用镜像依赖的 Megatron Bridge 0.4.2、Megatron Core 0.19 和 training-musa-adaptor 示例,在单机 8 × MTT S5000 上拉起 Qwen 多模态训练。流程覆盖加载 Hugging Face 权重继续训练/SFT,以及随机初始化从头预训练。
1. 前置条件
| 项目 | 要求 |
|---|---|
| GPU | 单机 8 × MTT S5000,训练前确认目标卡空闲 |
| 镜像 | 已包含 MUSA PyTorch、MATE、Transformer Engine、FlashAttention 和 MCCL 的 v2.2.0 训练环境 |
| Python | 3.12;安装、检查和训练必须使用同一个解释器 |
| Bridge / Core | Megatron Bridge 0.4.2 / Megatron Core 0.19 |
| MUSA 适配 | 包含 Bridge 0.4.2 适配的 training-musa-adaptor |
| 模型 | 完整的 Hugging Face 配置、tokenizer/processor、权重索引和全部分片 |
| 数据 | LLaVA-Pretrain conversation JSON 及标注引用的全部图片 |
| 存储 | 模型、数据和输出目录挂载到容器内,并预留充足的 checkpoint 与缓存空间 |
通用 v2.2.0 镜像是否预装 Bridge 需要以实际容器为准。先执行:
mthreads-gmi
python3 -m pip show megatron-bridge megatron-core training-musa-adaptor
python3 - <<'PY'
import torch
import torch_musa
print("PyTorch:", torch.__version__)
print("torch_musa:", torch_musa.__version__)
print("MUSA available:", torch.musa.is_available())
print("MUSA device count:", torch.musa.device_count())
PY
预期 torch.musa.is_available() 为 True,设备数为 8。
2. 准备目录与运行环境
先设置本文统一使用的路径。ADAPTOR 指向包含 Bridge 示例和 0.4.2 适配的交付目录:
export WORKDIR=/data/software
export ADAPTOR=/data/software/training-musa-adaptor
export MODEL_ROOT=/data/models
export DATASET_ROOT=/data/datasets/LLaVA-Pretrain
export RUN_ROOT=/data/outputs/megatron_bridge
test -d "$ADAPTOR/examples/megatron_bridge"
mkdir -p "$MODEL_ROOT" "$DATASET_ROOT" "$RUN_ROOT"
如果 Bridge 和 Megatron Core 尚未安装,在已配置好 MUSA 基础栈的同一个 Python 环境中准备:
git clone --depth 1 --branch core_v0.19.0 \
https://github.com/NVIDIA/Megatron-LM.git "$WORKDIR/Megatron-LM"
python3 -m pip install --no-deps --no-build-isolation -e "$WORKDIR/Megatron-LM"
python3 -m pip install --no-deps megatron-bridge==0.4.2
python3 -m pip install --no-build-isolation -e "$ADAPTOR"
本文实测依赖还包括:
| 包 | 验证版本 |
|---|---|
| NumPy | 1.26.1 |
| Transformers / tokenizers / huggingface-hub | 5.16.1 / 0.23.3 / 1.33.0 |
| Megatron Energon | 6.0.1 |
| Flash Linear Attention / fla-core | 0.5.2 / 0.5.2 |
| qwen-vl-utils | 0.0.14 |
| OmegaConf / Hydra Core | 2.3.1 / 1.3.8 |
这些版本必须与镜像中的 PyTorch ABI 和 MUSA 算子匹配。不要直接从普通 CUDA 环境复制依赖,也不要用 PyPI 安装普通 Torch 覆盖厂商构建的 torch_musa。
当前普通 Qwen 训练路径不使用 ModelOpt。若基础镜像预装 nvidia-modelopt 并导致导入失败,可在该训练环境中显式卸载:
python3 -m pip uninstall -y nvidia-modelopt
需要蒸馏、量化或恢复带 ModelOpt 状态的 checkpoint 时,应另行准备完整兼容环境,不能复用这里的缺包路径。
3. 准备模型和数据
前三个模型和 LLaVA-Pretrain 数据可从 ModelScope 获取:
modelscope download --model Qwen/Qwen3-VL-32B-Instruct \
--local_dir "$MODEL_ROOT/Qwen3-VL-32B-Instruct"
modelscope download --model Qwen/Qwen3.5-4B \
--local_dir "$MODEL_ROOT/Qwen3.5-4B"
modelscope download --model Qwen/Qwen3.5-35B-A3B \
--local_dir "$MODEL_ROOT/Qwen3.5-35B-A3B"
modelscope download --dataset AI-ModelScope/LLaVA-Pretrain \
--local_dir "$DATASET_ROOT"
Qwen3.8-27B 使用模型发布方授权的完整模型快照。公开资料中没有可与前三个模型并列引用的 ModelScope 地址时,不要下载 同名前缀的其他权重替代。
数据目录应至少包含:
/data/datasets/LLaVA-Pretrain/
├── blip_laion_cc_sbu_558k.json
└── <JSON 中 image 字段引用的图片>
启动前检查模型权重分片、processor/tokenizer 和数据样本:
python3 - <<'PY'
import json
from pathlib import Path
from PIL import Image
from transformers import AutoProcessor
models = {
"Qwen3-VL-32B-Instruct": "/data/models/Qwen3-VL-32B-Instruct",
"Qwen3.5-4B": "/data/models/Qwen3.5-4B",
"Qwen3.5-35B-A3B": "/data/models/Qwen3.5-35B-A3B",
}
for name, value in models.items():
root = Path(value)
index = json.loads((root / "model.safetensors.index.json").read_text())
shards = sorted(set(index["weight_map"].values()))
missing = [shard for shard in shards if not (root / shard).is_file()]
assert not missing, (name, missing)
AutoProcessor.from_pretrained(root, trust_remote_code=True, local_files_only=True)
print(name, "shards:", len(shards), "OK")
root = Path("/data/datasets/LLaVA-Pretrain")
samples = json.loads((root / "blip_laion_cc_sbu_558k.json").read_text())
sample = next(row for row in samples if row.get("image"))
image = root / sample["image"]
assert image.is_file(), image
with Image.open(image) as handle:
handle.verify()
print("LLaVA samples:", len(samples), "image:", image)
PY
Bridge 0.4.2 会在输出目录中把 LLaVA JSON 转换为 canonical conversation JSONL,不在原数据目录生成派生文件。
4. 设置训练模式
4.1 加载 HF 权重继续训练或 SFT
不追加 --load-hf-weights false 时,示例加载 MODEL_PATH 中的 Hugging Face 权重。数据通过 DirectHFSFTDatasetConfig 组织为 conversation 格式,loss 只计算 assistant token。
该路径适合:
- 从已有 Hugging Face 权重开始多模态监督训练;
- 验证模型、processor、数据模板和 MUSA 训练链路;
- 执行短步数 loss 和每步耗时验收。
短程运行不能证明最终任务效果或长时间收敛。
4.2 随机初始化从头预训练
在任一模型命令后追加:
--load-hf-weights false \
--lr 1e-4 \
--min-lr 1e-5 \
--lr-warmup-iters 10
随机初始化时仍使用新的 OUT。如果输出目录已有 checkpoint,Bridge 会尝试续训,不会自动因为 --load-hf-weights false 清空历史状态。
5. 拉起训练
所有命令均在单机 8 卡上运行,默认使用 BF16、GBS 64、micro batch 2、序列长度 2048 和 flash attention。
5.1 Qwen3-VL-32B-Instruct
MODEL_PATH=/data/models/Qwen3-VL-32B-Instruct \
DATASET_ROOT=/data/datasets/LLaVA-Pretrain \
OUT=/data/outputs/megatron_bridge/qwen3vl_32b_20steps \
TRAIN_ITERS=20 \
GLOBAL_BATCH_SIZE=64 \
bash "$ADAPTOR/examples/megatron_bridge/qwen3_vl/run_qwen3_vl_bridge.sh"
固定并行配置为 TP1 / PP8,首层 4、末层 6,optimizer CPU offload 0.6。
5.2 Qwen3.5-4B
MODEL_PATH=/data/models/Qwen3.5-4B \
DATASET_ROOT=/data/datasets/LLaVA-Pretrain \
OUT=/data/outputs/megatron_bridge/qwen35_4b_20steps \
TRAIN_ITERS=20 \
GLOBAL_BATCH_SIZE=64 \
bash "$ADAPTOR/examples/megatron_bridge/qwen35_vl/run_qwen35_vl_bridge.sh"
默认并行配置为 TP2 / PP1 / DP4,optimizer CPU offload 0.4。
5.3 Qwen3.5-35B-A3B
MODEL_PATH=/data/models/Qwen3.5-35B-A3B \
DATASET_ROOT=/data/datasets/LLaVA-Pretrain \
OUT=/data/outputs/megatron_bridge/qwen35_35b_a3b_20steps \
TRAIN_ITERS=20 \
GLOBAL_BATCH_SIZE=64 \
bash "$ADAPTOR/examples/megatron_bridge/qwen35_vl/run_qwen35_vl_bridge.sh" \
--tp 1 --pp 1 --optimizer-offload-fraction 1.0 \
model.expert_model_parallel_size=8 \
model.expert_tensor_parallel_size=1
对应 TP1 / PP1 / EP8 / ETP1 / DP8。optimizer offload 必须使用 1.0;使用 0.6 时曾出现显存余量不足。
5.4 Qwen3.8-27B
MODEL_PATH=/data/models/Qwen3.8-27B \
DATASET_ROOT=/data/datasets/LLaVA-Pretrain \
OUT=/data/outputs/megatron_bridge/qwen38_27b_20steps \
TRAIN_ITERS=20 \
GLOBAL_BATCH_SIZE=64 \
bash "$ADAPTOR/examples/megatron_bridge/qwen35_vl/run_qwen35_vl_bridge.sh" \
--tp 1 --pp 8 --first-pp-layers 4 --last-pp-layers 6 \
--optimizer-offload-fraction 0.6
对应 TP1 / PP8 / DP1。optimizer offload 使用 0.6;0.4 会在第 2 步 MTP FP32 logits 分配时 OOM。该模型当前没有修复 output_gate_type=swish 的语义差异。
5.5 后台运行和退出码
短程验收可以直接运行命令。长任务建议写入明确的退出码:
export MODEL_PATH=/data/models/Qwen3.5-4B
export OUT=/data/outputs/megatron_bridge/qwen35_4b_bg_$(date +%Y%m%d_%H%M%S)
export TRAIN_ITERS=1000
export GLOBAL_BATCH_SIZE=64
mkdir -p "$OUT"
nohup bash -c '
bash "$ADAPTOR/examples/megatron_bridge/qwen35_vl/run_qwen35_vl_bridge.sh"
rc=$?
printf "%s\n" "$rc" > "$OUT/train.exit_code"
exit "$rc"
' > "$OUT/launcher.log" 2>&1 < /dev/null &
printf "%s\n" "$!" > "$OUT/launcher.pid"
tail -20 "$OUT/launcher.log"
Bridge 启动脚本最后强制 checkpoint.save=null。上述 SOP 不保存 checkpoint,不能用于断点恢复验收。
6. 验收 loss 与每步耗时
训练开始后检查 iteration 是否推进以及是否出现原始异常:
LOG="$OUT/train.log"
grep 'iteration ' "$LOG" | tail -30
grep -nE 'Traceback|OutOfMemoryError|out of memory|Assertion.*failed|SIGABRT' "$LOG" || true
grep '\[after training is done\]' "$LOG"
cat "$OUT/train.exit_code"
成功运行的判定至少包括:
train.exit_code为 0;- 日志出现预期步数或
[after training is done]; - LM loss、MTP loss 和 grad norm 为有限值;
- skipped 和 NaN 计数为 0;
- 日志中没有未处理的 traceback。
6.1 加载 HF 权重的实测结果
下表来自 Bridge 0.4.2、8 × MTT S5000、GBS 64、micro batch 2、序列长度 2048、BF16、flash attention 的 20 步运行。稳态耗时取第 11–20 步中位数,首步包含首次执行和缓存/编译影响。
| 模型 | 并行 / offload | 首步时间 | 稳态中位数(11 –20) | 稳态范围(11–20) | 首步 → 第 20 步 LM loss |
|---|---|---|---|---|---|
| Qwen3.5-4B | TP2/PP1/DP4;0.4 | 35.603 s | 5.933 s | 5.880–6.024 s | 3.058109 → 2.041883 |
| Qwen3.5-35B-A3B | TP1/PP1/EP8/ETP1/DP8;1.0 | 50.582 s | 17.512 s | 17.381–17.806 s | 3.567537 → 2.139151 |
| Qwen3-VL-32B-Instruct | TP1/PP8;0.6 | 128.267 s | 25.579 s | 25.265–26.003 s | 6.047277 → 3.649220 |
| Qwen3.8-27B(历史) | TP1/PP8;0.6 | 487.5 s | 33.389 s | 未记录 | 4.025290 → 2.113969 |
前三行来自 2026-11-04 的 0.4.2 日志。Qwen3.8-27B 来自 2026-11-03 的另一节点,本轮没有复测,不能与前三个模型合并解释为同一次实验。
6.2 随机初始化预训练参考 loss
以下历史结果使用学习率 1e-4、最小学习率 1e-5、warmup 10 步、GBS 64 和 100 步训练,仅用于判断随机初始化是否合理:
| 模型 | 首步 LM loss | 第 100 步 LM loss |
|---|---|---|
| Qwen3-VL-32B-Instruct | 13.06 | 7.91 |
| Qwen3.5-4B | 13.05 | 7.24 |
| Qwen3.8-27B | 13.49 | 7.47 |
| Qwen3.5-35B-A3B | 12.77 | 7.35 |
随机初始化首步 LM loss 约为 ln(V) + σ²/2。不同模型词表大小和初始化标准差不同,不应要求四个模型的首步 loss 完全相同。warmup 结束前后 loss 可能短暂上冲,再开始下降。
7. 结果解释与限制
- 首步耗时受算子编译、TileLang 缓存、权重加载和节点状态影响,不能拿单次首步直接比较模型性能。
- 稳态耗时只适用于表中的模型、并行、batch、序列长度、镜像、节点和 attention backend。
- 20 步 loss 下降只证明指定链路可以执行和产生有限梯度,不证明收敛、最终精度或任务效果。
- 启动脚本不保存 checkpoint;未验证 model、optimizer、dataloader 和 RNG 恢复。
- 未验证 HF 数值逐值等价。Qwen3.8-27B 的
output_gate_type=swish还会进一步限制语义对齐结论。 - 扩大训练范围时,需要重新验收并行配置、收敛、保存恢复和数值正确性。
8. 常见问题
8.1 Numpy is not available
检查 NumPy 与 Torch 的 ABI 是否兼容。本文验证栈使用 NumPy 1.26.1;NumPy 2.x 可能导致 tensor.numpy() 和 all_gather_object() 失败。
8.2 No module named omegaconf 或 qwen_vl_utils is required
确认 Bridge、依赖和训练进程使用同一个 Python 解释器。Bridge 使用 --no-deps 安装时,不会自动补齐 OmegaConf、Hydra 和 qwen-vl-utils。
8.3 FLA 版本约束冲突
flash-linear-attention 与 fla-core 必须成对使用同一版本。本文实测组合为 0.5.2;不要只升级其中一个,也不要让依赖解析器混入 0.6.0 的其中一个包。
8.4 ModelOpt 导入失败
普通训练不依赖 ModelOpt。确认当前环境已卸载 nvidia-modelopt;不要为了消除一个可选导入错误而安装不完整的量化依赖组合。
8.5 首步长时间没有新日志
首步可能正在编译内核、生成 TileLang 缓存或加载权重。先检查进程和 GPU 状态,再看 iteration 是否推进;不要仅因为短时间没有日志就判定 hang。
8.6 Qwen3.8-27B 第 2 步 OOM
确认 optimizer offload fraction 为 0.6,PP 为 8,首层 4、末层 6。使用 0.4 时曾因 MTP FP32 logits 分配而 OOM。
8.7 Qwen3.5-35B-A3B 显存余量不足
确认 optimizer_offload_fraction=1.0、expert_model_parallel_size=8 和 expert_tensor_parallel_size=1。仅替换 MODEL_PATH 不会自动选择大模型所需并行配置。
8.8 训练结束但没有 checkpoint
示例启动脚本明确传入 checkpoint.save=null。这是当前 SOP 的预期行为;需要保存和恢复时,应修改脚本并重新验收保存、optimizer 状态、dataloader 与 RNG 的恢复。
9. 数据口径
本文命令、默认参数、模型范围和限制依据 training-musa-adaptor revision 1d94ecc(2026-11-05)中的 examples/megatron_bridge/qwen3_vl、examples/megatron_bridge/qwen35_vl 和 Bridge 0.4.2 验证记录。前三组 20 步 loss/耗时来自 2026-11-04 日志;Qwen3.8-27B 数据来自 2026-11-03 历史日志。发布前如示例脚本或环境 revision 改变,应重新核对默认参数并重新生成测试数据。

