nemo-mbridge-recipe-recommender

Auto Recipe — 配方索引与推荐

此技能会为所有已发布的配方建立索引，并帮助用户选择合适的起始配置、调整并行度以及避免常见问题。

如何使用此技能

1. 向用户询问：模型名称/规模、GPU 数量与类型、训练目标 （预训练 / SFT / PEFT），以及序列长度（如果不是默认值）。
2. 在下方索引中查找最匹配的配方。
3. 推荐配方函数名称和入口命令。
4. 提供调整建议（调整并行度、调节批次大小、规避问题）。

首次回答检查清单

推荐配方时，在提供详细索引之前，务必说明以下区别：

1. src/megatron/bridge/recipes/ 下的库配方用于功能训练，并使用 scripts/training/run_recipe.py。
2. scripts/performance/ 下的性能配方用于测量吞吐量上限。它们使用模拟数据，不应作为生产训练配方推荐。
3. 首次进行 Bridge 冒烟测试时，建议使用 llama3_8b_sft_config，并通过 --dataset llm-pretrain-mock 使用模拟数据。除非用户明确需要 SFT 数据路径，否则不要在仅用于测试配置的试运行中使用 llm-finetune。
4. 常规 SFT 推荐使用 --dataset llm-finetune；预训练和模拟验证推荐使用 --dataset llm-pretrain-mock。
5. 给出配方和数据集后，说明必要的调整规则：TP 必须能整除 num_key_value_heads；除非使用 NVL72 级别的互连，否则 TP 应限制在单个节点内；TP > 1 时启用 SP；长上下文需配置 CP；DP 为隐式配置；遇到 OOM 时先减小 micro_batch_size。

---

入口

库配方（功能训练）

# Pretrain with mock data
uv run python -m torch.distributed.run --nproc_per_node=8 scripts/training/run_recipe.py \
    --recipe <recipe_function_name> \
    --dataset llm-pretrain-mock

# SFT with SQuAD
uv run python -m torch.distributed.run --nproc_per_node=8 scripts/training/run_recipe.py \
    --recipe <recipe_function_name> \
    --dataset llm-finetune

# Override any field via CLI
uv run python -m torch.distributed.run --nproc_per_node=8 scripts/training/run_recipe.py \
    --recipe llama3_8b_pretrain_config \
    --dataset llm-pretrain-mock \
    'model.tensor_model_parallel_size=2' \
    'training.global_batch_size=64'

性能配方（吞吐量基准测试）

python scripts/performance/run_script.py \
    --recipe <model_family> \
    --gpu_type h100 \
    --num_gpus 64 \
    --data mock

在将这些配方用于吞吐量基准测试以外的用途之前，请参阅性能配方索引中的重要注意事项。

---

配方统一（即将推出 — PR #2803）

PR #2803 正在将性能配方统一为与库配方相同的 Python 函数格式。主要变更：

• 性能配方从 scripts/performance/configs/ 移至 src/megatron/bridge/recipes/<family>/<model>_perf.py
• 每个性能配方都将成为一个独立的 Python 函数（例如 llama3_8b_h100_bf16_pretrain_config()）
• 移除旧的 WorkloadBaseConfig → set_workload_base_configs → get_perf_optimized_recipe 流程
• 共享辅助函数：_benchmark_common()（50 次迭代、计时、TE RNG）、_perf_precision()（bf16 / fp8_cs / fp8_mx / nvfp4）

为什么用 Python，而不是 YAML？ 之前基于 YAML 的方案存在一些问题： 配方逻辑分散在多个间接层中，配置并非独立完整，而且两级流程让维护和调试 变得困难。Python 函数清晰明确、便于搜索，也易于组合。

#2803 合并后，库配方和性能配方都将通过相同的 run_recipe.py 入口运行。

---

库配方索引

所有配方均位于 src/megatron/bridge/recipes/ 下。每个函数都会返回一个 ConfigContainer，其中包含模型、训练、优化器和数据设置。

Llama

Recipe	Mode	TP	PP	CP	SP	GPUs (min)	Seq Len
llama2_7b_pretrain_config	Pretrain	2	1	—	—	2	4K
llama3_8b_pretrain_config	Pretrain	2	1	—	✓	2	8K
llama3_8b_16k_pretrain_config	Pretrain	2	1	2	✓	4	16K
llama3_8b_64k_pretrain_config	Pretrain	2	1	4	✓	8	64K
llama3_8b_128k_pretrain_config	Pretrain	2	1	8	✓	16	128K
llama3_70b_pretrain_config	Pretrain	8	4	—	✓	32	8K
llama3_70b_16k_pretrain_config	Pretrain	8	4	2	✓	64	16K
llama3_70b_64k_pretrain_config	Pretrain	8	4	4	✓	128	64K
llama31_405b_pretrain_config	Pretrain	8	16	—	✓	128	8K
llama3_8b_sft_config	SFT	2	1	—	✓	2	8K
llama3_70b_sft_config	SFT	4	4	—	✓	16	8K
llama31_405b_sft_config	SFT	8	8	—	✓	64	8K
llama3_8b_peft_config	PEFT	1	1	—	—	1	8K
llama3_70b_peft_config	PEFT	2	4	—	✓	8	8K
llama31_405b_peft_config	PEFT	4	8	—	✓	32	8K

Qwen2 / Qwen2.5

Recipe	Mode	TP	PP	Sizes
qwen2_*_{pretrain,sft,peft}_config	All	1–8	1–4	500M, 1.5B, 7B, 14B, 32B, 72B
qwen25_*_{pretrain,sft,peft}_config	All	1–8	1–4	500M, 1.5B, 3B, 7B, 14B, 32B, 72B

Qwen3 (Dense)

Recipe	Mode	TP	PP	CP	Sizes
qwen3_*_pretrain_config	Pretrain	1–8	1–2	—	600M–32B
qwen3_*_sft_config	SFT	1–8	1–2	—	600M–32B
qwen3_600m_sft_128k_config	SFT	1	1	8	600M (128K seq)
qwen3_*_peft_config	PEFT	1	1	—	600M–32B

Qwen3 MoE

Recipe	Mode	TP	PP	EP	CP	GPUs
qwen3_30b_a3b_pretrain_config	Pretrain	1	1	8	—	8
qwen3_30b_a3b_sft_config	SFT	1	1	8	—	8
qwen3_30b_a3b_peft_config	PEFT	1	1	1	—	1
qwen3_235b_a22b_pretrain_config	Pretrain	4	16	8	2	512+
qwen3_235b_a22b_sft_config	SFT	4	8	8	—	256
qwen3_235b_a22b_peft_config	PEFT	1	4	4	—	16

Qwen3-Next

Recipe	Mode	TP	PP	EP
qwen3_next_80b_a3b_pretrain_config	Pretrain	1	4	8
qwen3_next_80b_a3b_sft_config	SFT	1	2	8
qwen3_next_80b_a3b_peft_config	PEFT	1	1	4

DeepSeek

Recipe	Mode	TP	PP	EP	GPUs
deepseek_v2_lite_pretrain_config	Pretrain	1	1	8	8
deepseek_v2_pretrain_config	Pretrain	1	4	32	128
deepseek_v3_pretrain_config	Pretrain	2	16	64	2048
deepseek_v3_pretrain_config_32nodes	Pretrain	2	8	32	256

GLM-4.5

Recipe	Mode	TP	PP	EP	GPUs
glm45_355b_pretrain_config	Pretrain	2	8	16	256
glm45_air_106b_pretrain_config	Pretrain	1	4	8	32
glm45_355b_sft_config	SFT	2	8	16	256
glm45_air_106b_sft_config	SFT	1	4	8	32
glm45_355b_peft_config	PEFT	2	4	4	32
glm45_air_106b_peft_config	PEFT	1	2	4	8

Gemma

Recipe	Mode	TP	PP	Sizes
gemma2_*_{pretrain,sft,peft}_config	All	2–8	1–2	2B, 9B, 27B
gemma3_1b_{pretrain,sft,peft}_config	All	1	1	1B (32K seq)

NemotronH / Nemotron

配方	模式	TP	PP	EP	备注
nemotronh_{4b,8b,47b,56b}_*_config	P/S/PEFT	1–8	1–4	—	稠密 SSM 混合架构
nemotron_3_nano_*_config	P/S/PEFT	不定	1	8	MoE + Mamba
nemotron_3_super_*_config	P/S/PEFT	4	1	8	MoE + Mamba，CUDA graph 性能提升约 40%
nemotron_nano_{9b,12b}_v2_*_config	P/S/PEFT	不定	1	—	稠密

其他模型

配方	模式	备注
moonlight_16b_{pretrain,sft,peft}_config	全部	MoE EP=8
olmoe_7b_{pretrain,sft,peft}_config	全部	MoE EP=8
ministral3_{3b,8b,14b}_{sft,peft}_config	SFT/PEFT	稠密
gpt_oss_20b_*_config	全部	MoE + FP8/MXFP8 变体
gpt_oss_120b_*_config	全部	MoE
vanilla_gpt_pretrain_config	预训练	MLM/Bridge 对齐基线
gpt3_175b_pretrain_config	预训练	TP=4，PP=8，VP=6
kimi_k2_pretrain_config	预训练	1T MoE，TP=2 PP=16 EP=32

VLM 配方

配方	模式	TP	PP	EP	GPU 数量
gemma3_vl_{4b,12b,27b}_{sft,peft}_config	SFT/PEFT	1–8	1–2	—	1–16
qwen25_vl_{3b,7b,32b,72b}_{sft,peft}_config	SFT/PEFT	1–8	1–4	—	1–32
qwen3_vl_{8b,30b_a3b,235b_a22b}_{sft,peft}_config	SFT/PEFT	1–4	1–8	1–32	1–512
qwen35_vl_*_{sft,peft}_config	SFT/PEFT	不定	不定	不定	不定
glm_45v_{sft,peft}_config	SFT/PEFT	1	8	4–16	64–512
nemotron_nano_v2_vl_12b_{sft,peft}_config	SFT/PEFT	2–4	1	—	8

Diffusion 配方

配方	模式	TP	CP
wan_1_3B_{pretrain,sft}_config	P/SFT	1	8
wan_14B_{pretrain,sft}_config	P/SFT	2	4
flux_12b_{pretrain,sft}_config	P/SFT	2	1

---

性能配方索引

所有性能配方都位于 scripts/performance/ 下。通过 run_script.py 调用，并根据 GPU 类型使用 WorkloadBaseConfig 预设。

重要： 性能配方用于上限吞吐量基准测试， 而非生产训练。默认情况下，它们会使用模拟数据运行 50 次迭代。 吞吐量数值是期望目标，不是经过验证的收敛配置。

Llama 3 / 3.1

模型	GPU 数量	GPU 类型	主要特性
Llama 3 8B	8	H100、B200、B300、GB200、GB300、R100	CUDA graphs（本地），GB 变体上使用 FSDP
Llama 3 70B	64	H100、B200、B300、GB200、GB300	TP 通信重叠（userbuffers）、FSDP、CUDA graphs
Llama 3.1 405B	128–1024	H100、B200、B300、GB200、GB300	TP+CP 通信重叠（userbuffers）、FSDP、大规模 PP/VP

也有 SFT/LoRA 变体（例如，使用打包序列的 8B SFT、在 32 个 GPU 上运行的 70B SFT）。

DeepSeek V3

模型	GPU 数量	GPU 类型	主要特性
DeepSeek V3（671B MoE）	256–1024	H100、B200、B300、GB200、GB300	HybridEP 分发器、MLA 重计算、CUDA graphs（TE 作用域）

Qwen3 MoE

模型	GPU 数量	GPU 类型	主要特性
Qwen3 30B-A3B	8–16	H100、B200、B300、GB200、GB300	MoE alltoall/flex 分发器
Qwen3 235B-A22B	64–256	H100、B200、B300、GB200、GB300	TP 通信重叠、CUDA graphs、MoE a2a 重叠
Qwen3-Next 80B-A3B	64–128	H100、B200、B300、GB200、GB300	EP 64–128

Qwen3-VL

模型	GPU 数量	GPU 类型	主要特性
Qwen3-VL 30B-A3B	8–16	H100、B200、B300、GB200、GB300	VLM + MoE
Qwen3-VL 235B-A22B	64–256	H100、B200、B300、GB200、GB300	VLM + MoE、TP 通信重叠

Kimi K2

模型	GPU 数量	GPU 类型	主要特性
Kimi K2（1T MoE）	256–1024	H100、B200、B300、GB200、GB300	Muon/Adam 优化器、HybridEP、流水线布局辅助工具

NemotronH

模型	GPU 数量	GPU 类型	主要特性
Nemotron 3 Nano (30B MoE+Mamba)	8–16	H100, B200, B300, GB200, GB300	TE CUDA graphs (attn+mamba+moe)、HybridEP
Nemotron 3 Super	64	H100, B200, B300, GB200, GB300	TE CUDA graphs、EP=64
NemotronH 56B	64	H100, B200, B300	TP=2–8、TE graphs (mamba+attn)

GPT-OSS

模型	GPU 数量	GPU 类型	主要特性
GPT-OSS 120B	64	H100, B200, GB200	EP=64、GB200 上使用 HybridEP

---

推荐决策树

User wants to train a model
│
├─ Know the model name?
│   ├─ Yes → Look up in Library Recipe Index above
│   │   ├─ Has a recipe for their size + mode? → Use it directly
│   │   └─ No exact match? → Use closest size, adjust parallelism
│   └─ No → Ask for model name, size, and HF model ID
│
├─ What's the training goal?
│   ├─ Pretrain → Use *_pretrain_config
│   ├─ SFT (full fine-tune) → Use *_sft_config
│   └─ PEFT (LoRA/DoRA) → Use *_peft_config (lowest GPU requirement)
│
├─ How many GPUs?
│   ├─ 1 GPU → Only PEFT recipes work (TP=1, PP=1)
│   ├─ 8 GPUs (1 node) → Most 8B–16B models, small MoE (EP=8)
│   ├─ 16–64 GPUs → 70B dense, medium MoE
│   └─ 128+ GPUs → 405B+, large MoE (DeepSeek V3, Kimi K2)
│
├─ Want throughput benchmarks?
│   ├─ Yes → Use perf recipes (scripts/performance/)
│   │   └─ ⚠️ These run on mock data for upper-bound perf only
│   └─ No → Use library recipes (scripts/training/run_recipe.py)
│
└─ Long context?
    ├─ > 8K → Need CP (context parallelism), check *_16k / *_64k / *_128k variants
    └─ ≤ 8K → Default recipes work

---

调整建议（推荐时）

并行度调整规则

当用户的 GPU 数量与配方默认值不同时：

1. TP 必须能整除 num_key_value_heads（GQA 限制）。例如，如果 num_key_value_heads=8，有效的 TP = {1, 2, 4, 8}。
2. TP 应限制在单个节点内（NVLink）。TP > 8 需要节点间 NVLink（例如 GB200 NVL72）。
3. PP 会产生流水线气泡。 尽量减少 PP；仅在单靠 TP 无法容纳模型时才增加。 使用 VP（虚拟流水线）来缓解气泡开销。
4. EP 不会减少稠密层的内存占用。 只有专家参数会通过 EP 分片。共享注意力层/嵌入层会被复制。对于“MoE 显存溢出”，应先增加 EP，而不是 TP。
5. 只要 TP > 1，SP 就应为 True。 它可以消除冗余的激活副本，且几乎没有额外开销。
6. CP 需要全互联或环形注意力。 检查 cp_comm_type。对于 GQA 模型，a2a+p2p 分层 CP 允许 CP > num_kv_heads。
7. world_size = DP × TP × PP × CP × EP。 DP 是隐式的。确保显式并行度的乘积能整除 GPU 总数。

批次大小调优

• 从配方的 micro_batch_size 开始。如果显存溢出，将其减小到 1。
• global_batch_size 决定学习动态。按 DP 缩放： GBS = micro_batch_size × DP × gradient_accumulation_steps。
• 对于 MoE，大规模训练时通常将 micro_batch_size=1。

需要提醒的常见陷阱

陷阱	症状	修复方法
TP > num_kv_heads	崩溃：“TP must divide num_query_groups”	将 TP 降低到 num_kv_heads 的因数
PP 未使用 VP	吞吐量差（气泡较大）	设置 virtual_pipeline_model_parallel_size
大型 MoE 的 EP 过低	专家参数导致显存溢出	增加 EP；每个专家分布在 EP/num_experts 个 rank 上
CUDA graphs + packed sequences	断言：“CUDA graph accepts only Tensor inputs”	禁用打包，或使用 local 全迭代图
CUDA graphs + full recompute	断言：“full recompute only with full iteration CUDA graph”	禁用 recompute，或切换到 local 实现
未设置 use_te_rng_tracker	启用 CUDA graphs 时，provider 初始化触发断言	设置 cfg.model.use_te_rng_tracker = True 和 cfg.rng.te_rng_tracker = True
H100 上 FSDP + TP > 1	可能出现通信瓶颈	H100 上优先使用 TP=1 或 TP=2 的 FSDP；FSDP 在 GB/B 系列上效果更好
长上下文但未使用 CP	激活值导致显存溢出	添加 CP=2/4/8；使用 *_16k、*_64k 或 *_128k 配方变体
H100 上 MoE 的 overlap_grad_reduce	可能影响性能（许多 H100 预设中为 False）	在 H100 上训练 MoE 时设置 overlap_grad_reduce=False
VLM SFT 缺少图像数据	可以运行，但生成结果毫无意义	提供实际的多模态数据集，或使用模拟 VLM 数据
Qwen35-VL MoE FSDP	仅在 Blackwell 上测试过	可能无法在 H100 上运行；请先验证

配方覆盖示例

# Scale Llama3 8B from 2 GPUs to 8 GPUs (increase DP)
uv run python -m torch.distributed.run --nproc_per_node=8 scripts/training/run_recipe.py \
    --recipe llama3_8b_pretrain_config \
    --dataset llm-pretrain-mock

# Reduce parallelism for Qwen3-MoE 30B to fit on 4 GPUs
uv run python -m torch.distributed.run --nproc_per_node=4 scripts/training/run_recipe.py \
    --recipe qwen3_30b_a3b_sft_config \
    --dataset llm-finetune \
    'model.expert_model_parallel_size=4'

# Add long context to an existing recipe
uv run python -m torch.distributed.run --nproc_per_node=8 scripts/training/run_recipe.py \
    --recipe llama3_8b_pretrain_config \
    --dataset llm-pretrain-mock \
    'model.seq_length=32768' \
    'model.context_parallel_size=4'

# Enable CUDA graphs on any recipe
uv run python -m torch.distributed.run --nproc_per_node=8 scripts/training/run_recipe.py \
    --recipe qwen3_30b_a3b_pretrain_config \
    --dataset llm-pretrain-mock \
    'model.cuda_graph_impl=transformer_engine' \
    'model.cuda_graph_scope=[attn,moe_router,moe_preprocess]' \
    'model.use_te_rng_tracker=True' \
    'rng.te_rng_tracker=True'

---

快速参考：我的情况适合哪种配置？

我想要……	从以下配置开始	所需 GPU 数量
首次试用 Bridge	llama3_8b_sft_config + 模拟数据	2
微调 7–8B 模型	llama3_8b_sft_config 或 qwen3_8b_sft_config	2–8
在 1 个 GPU 上使用 LoRA	llama3_8b_peft_config 或 qwen3_8b_peft_config	1
预训练稠密型 70B 模型	llama3_70b_pretrain_config	32–64
训练小型 MoE	qwen3_30b_a3b_pretrain_config	8
训练大型 MoE（235B 以上）	qwen3_235b_a22b_pretrain_config	256–512
对吞吐量进行基准测试	通过 run_script.py 使用性能配置	不定
进行长上下文训练	llama3_8b_128k_pretrain_config 或添加 CP 覆盖配置	16 以上
微调 VLM	qwen3_vl_8b_sft_config 或 gemma3_vl_*_sft_config	4–8
进行扩散模型训练	wan_1_3B_pretrain_config 或 flux_12b_pretrain_config	8

---

代码索引

内容	路径
库配置根目录	src/megatron/bridge/recipes/
配置 __init__.py（所有导出项）	src/megatron/bridge/recipes/__init__.py
通用配置辅助项	src/megatron/bridge/recipes/common.py
训练入口	scripts/training/run_recipe.py
性能配置根目录	scripts/performance/
性能入口	scripts/performance/run_script.py
性能工作负载配置	scripts/performance/configs/<family>/
性能覆盖配置（基准默认值）	scripts/performance/utils/overrides.py