跳到主要内容

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 训练环境
Python3.12;安装、检查和训练必须使用同一个解释器
Bridge / CoreMegatron 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"

本文实测依赖还包括:

包验证版本
NumPy1.26.1
Transformers / tokenizers / huggingface-hub5.16.1 / 0.23.3 / 1.33.0
Megatron Energon6.0.1
Flash Linear Attention / fla-core0.5.2 / 0.5.2
qwen-vl-utils0.0.14
OmegaConf / Hydra Core2.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-4BTP2/PP1/DP4;0.435.603 s5.933 s5.880–6.024 s3.058109 → 2.041883
Qwen3.5-35B-A3BTP1/PP1/EP8/ETP1/DP8;1.050.582 s17.512 s17.381–17.806 s3.567537 → 2.139151
Qwen3-VL-32B-InstructTP1/PP8;0.6128.267 s25.579 s25.265–26.003 s6.047277 → 3.649220
Qwen3.8-27B(历史)TP1/PP8;0.6487.5 s33.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-Instruct13.067.91
Qwen3.5-4B13.057.24
Qwen3.8-27B13.497.47
Qwen3.5-35B-A3B12.777.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 改变,应重新核对默认参数并重新生成测试数据。