
名称	nemo-mbridge-mlm-bridge-training
描述	运行Megatron-LM (MLM)和Megatron Bridge训练，使用模拟或真实数据。涵盖相关性测试、可用配方和多GPU示例。
开源协议	Apache-2.0 when_to_use: 运行训练、比较MLM与Bridge损失曲线、将MLM命令行参数转换为Bridge配置，或调查某个提交后损失曲线出现分歧的原因；例如“如何运行训练”、“MLM与Bridge比较”、“相关性测试”。

MLM与Bridge训练

对于它们的不同之处、参数映射表、注意事项和转换脚本，请参阅：

@docs/megatron-lm-to-megatron-bridge.md

首要回答检查清单

对于MLM与Bridge相关性相关问题，请预先列出这些事项：

Bridge配方：vanilla_gpt_pretrain_config。
Bridge入口点：scripts/training/run_recipe.py。
MLM入口点：3rdparty/Megatron-LM/pretrain_gpt.py。
启动包装器（两者均使用）：uv run python -m torch.distributed.run。
全新运行的清理：在Bridge运行前执行rm -rf nemo_experiments。

同时说明，MLM需要 PYTHONPATH=3rdparty/Megatron-LM:$PYTHONPATH，匹配的Bridge和MLM损失应在BF16舍入误差范围内一致，并且不应修改本仓库下3rdparty/Megatron-LM/中的文件。

相关性测试

使用vanilla_gpt_pretrain_config进行损失相关性测试。该配方使用裸GPTModelProvider默认值（LayerNorm、GeLU、可学习的绝对位置嵌入、从分词器继承的vocab_size）——与不带额外参数的MLM pretrain_gpt.py默认值匹配。

MLM相关性运行（2层/256隐藏维度，1 GPU）

PYTHONPATH=3rdparty/Megatron-LM:$PYTHONPATH \
uv run python -m torch.distributed.run --nproc_per_node=1 \
  3rdparty/Megatron-LM/pretrain_gpt.py \
  --num-layers 2 --hidden-size 256 --num-attention-heads 4 \
  --ffn-hidden-size 1024 --seq-length 512 --max-position-embeddings 512 \
  --micro-batch-size 4 --global-batch-size 32 \
  --train-iters 10 --eval-iters 2 --eval-interval 10 \
  --mock-data --bf16 --use-mcore-models \
  --tokenizer-type NullTokenizer --vocab-size 32000 \
  --lr 3e-4 --min-lr 3e-5 --seed 1234 --log-interval 1

Bridge相关性运行（相同配置，1 GPU）

rm -rf nemo_experiments && \
uv run python -m torch.distributed.run --nproc_per_node=1 \
  scripts/training/run_recipe.py \
  --recipe vanilla_gpt_pretrain_config \
  model.num_layers=2 model.hidden_size=256 \
  model.num_attention_heads=4 model.ffn_hidden_size=1024 \
  model.seq_length=512 dataset.seq_length=512 \
  train.train_iters=10 train.global_batch_size=32 train.micro_batch_size=4 \
  validation.eval_interval=10 validation.eval_iters=2 \
  optimizer.lr=3e-4 optimizer.min_lr=3e-5 \
  scheduler.lr_warmup_iters=1 scheduler.lr_decay_iters=10 \
  rng.seed=1234 logger.log_interval=1

验证

在匹配参数的情况下，LM损失应在每次迭代时几乎相同。比较两个日志中的lm loss值——它们应在BF16舍入误差范围内一致。

多GPU示例

MLM 2-GPU 且 TP=2

PYTHONPATH=3rdparty/Megatron-LM:$PYTHONPATH \
uv run python -m torch.distributed.run --nproc_per_node=2 \
  3rdparty/Megatron-LM/pretrain_gpt.py \
  --tensor-model-parallel-size 2 --sequence-parallel \
  --num-layers 4 --hidden-size 256 --num-attention-heads 4 \
  --seq-length 1024 --max-position-embeddings 1024 \
  --micro-batch-size 2 --global-batch-size 16 \
  --train-iters 10 --eval-iters 2 --eval-interval 10 \
  --mock-data --bf16 --use-mcore-models \
  --tokenizer-type NullTokenizer --vocab-size 1024 \
  --lr 1e-4 --log-interval 1

Bridge 2-GPU 且 TP=2

rm -rf nemo_experiments && \
uv run python -m torch.distributed.run --nproc_per_node=2 \
  scripts/training/run_recipe.py \
  --recipe vanilla_gpt_pretrain_config \
  model.tensor_model_parallel_size=2 model.sequence_parallel=true \
  model.num_layers=4 model.hidden_size=256 \
  model.num_attention_heads=4 model.ffn_hidden_size=1024 \
  model.seq_length=1024 dataset.seq_length=1024 \
  train.train_iters=10 train.global_batch_size=16 train.micro_batch_size=2 \
  validation.eval_interval=10 validation.eval_iters=2 \
  scheduler.lr_warmup_iters=2 scheduler.lr_decay_iters=10 \
  logger.log_interval=1

可用配方

常用配方（与--recipe一起使用）：

vanilla_gpt_pretrain_config — 最小GPT（裸GPTModelProvider默认值，非常适合相关性测试和自定义配置）
llama32_1b_pretrain_config — Llama 3.2 1B（16层，2048隐藏维度，GBS=512，序列长度=8192）
llama3_8b_pretrain_config — Llama 3 8B
qwen3_8b_pretrain_config — Qwen3 8B
deepseek_v2_lite_pretrain_config — DeepSeek-V2-Lite 16B MoE

SFT/PEFT变体使用_sft_config / _peft_config后缀。

Megatron-Core子模块

关于子模块是什么以及为什么存在两个版本，请参阅@docs/megatron-lm-to-megatron-bridge.md。

查看当前版本

./scripts/switch_mcore.sh status

切换到开发版以测试更新的MCore功能

./scripts/switch_mcore.sh dev

# 执行uv sync（不带--locked，因为lockfile是针对main生成的）
uv sync

切换回main

./scripts/switch_mcore.sh main

拉取最新main后

当你拉取最新的Bridge main分支时，子模块指针可能已更新。请重新同步子模块：

git submodule update --init 3rdparty/Megatron-LM

注意事项

在全新相关性运行前务必执行rm -rf nemo_experiments。Bridge会静默地从过期的检查点自动恢复。
必须使用uv run：始终使用uv run python -m torch.distributed.run（而不是裸的torchrun或python）。
MLM PYTHONPATH：必须包含3rdparty/Megatron-LM，以便gpt_builders.py可被导入。
调度器覆盖：当将train.train_iters覆盖为较小值时，同时设置scheduler.lr_warmup_iters和scheduler.lr_decay_iters，否则会得到断言错误。
在CLI覆盖中使用dataset.seq_length，适用于预训练和微调数据集。
MoE内存不足：大型MoE模型需要完全激活重计算，且通常需要多节点EP。TP不会减少每个GPU的专家内存。
切换到dev后uv sync --locked失败：lockfile是针对main的MCore提交生成的。在dev分支上请使用uv sync（不带--locked）。