nemo-mbridge-recipe-recommender

Auto Recipe — 配方索引与推荐

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

如何使用此技能

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

首次回答检查清单

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

1. src/megatron/bridge/recipes/ 下的库配方用于功能性训练，并使用 scripts/training/run_recipe.py。
2. src/megatron/bridge/perf_recipes/ 下的基准测试配方用于测试吞吐量上限。它们自带规范的基准数据和设置，不应作为生产训练配方进行推荐。
3. 首次进行 Bridge 冒烟测试时，建议使用 llama3_8b_pretrain_config，并通过 --dataset mock 使用模拟数据。
4. 常规 SFT 推荐应选择微调预设，例如 --dataset squad 或 --dataset tulu3；预训练和模拟验证推荐应使用 --dataset mock。不要将仅用于预训练的 mock 预设与 SFT 或 PEFT 模式搭配使用。
5. 指定配方和数据集后，给出必需的调整规则：TP 必须整除 num_key_value_heads；除非使用 NVL72 级互连，否则 TP 应限制在单个节点内；TP > 1 时启用 SP；长上下文需配置 CP；DP 为隐式设置；发生 OOM 时先减小 micro_batch_size。
6. 说明每项建议的覆盖设置是否会改变收敛约定，还是只改变执行／性能映射。不要为了提高吞吐量而改变收敛语义，却不明确说明这是一次新的实验。

配置层与变更控制

在推荐或调优配方之前，先将训练语义与其硬件映射分开。

收敛配置包括起始检查点和可训练参数；数据集／修订版本／划分／顺序／随机种子；分词器、掩码、截断和打包；序列长度；全局批次和 token 预算；目标函数和损失系数；自然或强制 MoE 路由以及 token 丢弃策略；优化器、学习率、调度、预热、beta、epsilon、权重衰减、梯度裁剪和 dropout；算术运算与优化器状态精度；以及 PEFT 适配器设置。更改其中任一项都会产生一项新的收敛实验。

执行／性能配置包括硬件数量和拓扑；TP／PP／VP／CP／EP／ETP／DP／SP；重计算和卸载；分布式优化器／FSDP；通信重叠；融合和注意力后端；CUDA 图和编译；检查点 I/O；以及在路由策略不变时，通过 all-to-all、DeepEP 或 HybridEP 进行的 MoE 传输。这些设置应保留目标函数和有效更新，但浮点归约顺序可能导致轻微的数值漂移，仍需验证。

将微批次大小和梯度累积视为执行指纹。只有在全局批次大小、全局批次成员／顺序、归一化、优化器边界和 token 预算固定的情况下才能调优，并针对每种布局验证新的损失哨兵。打包、精度、强制 MoE 负载均衡、token 丢弃／容量以及路由器／辅助损失变更，绝不是纯性能调节项。

将模拟数据、强制均衡、禁用正确性检查和仅用于计时的调度视为仅限基准测试的捷径。这些做法可能适用于 perf_recipes，但其损失和检查点不能作为收敛证据。

对于可比的模型验证配方，应在调优性能之前选择一个适用于整个队列的收敛约定。在架构允许的范围内，保持有界数据选择、预处理、序列长度、全局批次、优化器／调度、精度、随机种子、路由策略、优化器步数上限和已处理 token 检查点一致。记录任何必要的模型特定偏差，并且不要将该结果作为同类对比的收敛证据。不同架构或分词器的绝对损失不可直接排序；应在相同 token 数量下比较稳定性和趋势。

当配方的批次设置与所选收敛约定不一致时，应单独修改并验证库配方。声明的有界验证协议可以明确规定，在整个队列中统一应用相同的学习率、调度、序列和数据覆盖设置，但不要仅为提高吞吐量而单独更改收敛配置。相反，优化适配或吞吐量时，应优先尝试 TP／PP／CP／EP、重计算／卸载、分发器传输、通信重叠、融合和 CUDA 图。

---

入口

库配方（功能性训练）

# 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 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 squad

# 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 mock \
    'model.tensor_model_parallel_size=2' \
    'train.global_batch_size=64'

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

./scripts/training/train.sh \
    --nodes 2 --gpus-per-node 8 \
    --account ACCOUNT --partition PARTITION --container-image IMAGE \
    --recipe qwen3_30b_a3b_pretrain_16gpu_h100_bf16_config \
    --mode pretrain

GPU 分配总数必须与配方名称中编码的数量一致。用户选择节点规格，所选分区必须提供所需硬件。启动器不会注入基准测试离线默认值或特定集群的启动策略。使用 --env NAME 设置导出的离线或 NCCL 网络设置，并使用重复的 --srun-arg=ARG 选项传递给 srun。 通过目标集群集成配置 CPU/NUMA 包装器和 Slurm 分段大小；或者，在需要兼容性策略时使用 scripts/performance/setup_experiment.py。统一 启动器支持精确导出的文本预训练、文本 SFT/PEFT、Qwen-VL 预训练和 Wan 预训练配方，并会推断其前向步数。文本 SFT/PEFT 文本基准测试配方保留扁平运行器的模拟数据默认设置； Qwen-VL 和 Wan 则保留其特定于模型的数据集。导出的基准测试 PEFT 配方是固定的 LoRA 配置；如需使用 DoRA，请使用可配置的库配方。 支持在末尾添加 KEY=VALUE 覆盖项，但覆盖基准测试配方后，它便不再代表其规范基准测试配置。对于基于选择器的调用、 数据集替换、拓扑调整大小和专用基准测试控制，请使用 scripts/performance/setup_experiment.py。

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

---

基准测试配方布局

基准测试配方采用与库配方相同的Python 函数格式，但位于用于吞吐量基准测试的专用命名空间中：

• 基准测试配方位于 src/megatron/bridge/perf_recipes/<family>/<hardware>/<model>.py
• 每个基准测试配方都是一个自包含的 Python 函数（例如 llama3_8b_pretrain_8gpu_h100_bf16_config()）
• 配方名称编码了模型、任务、GPU 数量、硬件、精度和可选变体
• scripts/performance/utils/utils.py 从扁平配方本身派生兼容的 WorkloadBaseConfig 视图
• 共享辅助函数：_benchmark_common()（50 次迭代、计时、TE RNG）、_perf_precision()（bf16 / fp8_cs / fp8_mx / nvfp4）

为什么使用 Python，而不是 YAML？ 以往基于 YAML 的方法存在一些问题： 配方逻辑分散在多个间接层中，配置并非自包含，而且两级流水线使维护和调试 变得困难。Python 函数清晰明确、便于搜索，也易于组合。

训练启动器根据完整导出函数名称发现库配方和基准测试配方。五个旧版重复名称会选择基准测试定义；对于这些功能性工作负载，请使用相应的通用别名。新配方名称在这两个包中都应保持唯一。

---

配方索引（库与基准测试）

每个系列的完整配方表——包括所有已发布的库配方 （src/megatron/bridge/recipes/）和基准测试配方 （src/megatron/bridge/perf_recipes/），以及并行度、最低 GPU 数量和硬件覆盖范围——均收录在专门的参考文件中，以便本技能保持简洁：

→ 请参阅 references/recipe-index.md — 库 配方索引（Llama、Qwen2/2.5/3、Qwen3-MoE、Qwen3-Next、DeepSeek、GLM-4.5、 Gemma、Nemotron、VLM、Diffusion）和基准测试配方索引（按硬件划分的 吞吐量配置）。

加载该文件以查找确切的配方函数名称或其默认并行度；下文将说明应查阅哪个条目。

---

推荐决策树

User wants to train a model
│
├─ Know the model name?
│   ├─ Yes → Look up in references/recipe-index.md
│   │   ├─ 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 benchmark recipes (src/megatron/bridge/perf_recipes/)
│   │   ├─ Exact exported recipe → scripts/training/train.sh --recipe <exact function name>
│   │   └─ Selector/specialized workflow → scripts/performance/setup_experiment.py
│   └─ 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 无法容纳模型时才增加 PP。使用 VP（虚拟流水线）来缓解气泡开销。
4. **EP 不会减少稠密层的内存占用。**只有专家参数会通过 EP 分片。共享注意力层和嵌入层会被复制。对于“MoE 发生 OOM”，应先增加 EP，而不是 TP。
5. **当 TP > 1 时，SP 应设为 True。**它可消除冗余的激活副本，且几乎没有开销。
6. **CP 需要全对全或环形注意力。**检查 cp_comm_type。对于 GQA 模型，a2a+p2p 分层 CP 允许 CP > num_kv_heads。
7. **稠密网格和专家网格会重叠。**不要将 TP 和 EP 相乘。MoE 的最小 world size 为 PP × max(TP × CP, EP × ETP)。稠密 DP 为 world_size / (TP × PP × CP)，专家 EDP 为 world_size / (PP × EP × ETP)；两个商都必须是整数，且专家数量必须能被 EP 整除。

批大小调优

• 从配方的 micro_batch_size 开始。如果发生 OOM，则减至 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 过低	专家参数导致 OOM	增加 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”	禁用重新计算，或切换到 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	激活导致 OOM	添加 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 mock

# Run the native 4-GPU Qwen3-MoE 30B PEFT topology
uv run python -m torch.distributed.run --nproc_per_node=4 scripts/training/run_recipe.py \
    --recipe qwen3_30b_a3b_peft_config \
    --dataset tulu3

# 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 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 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_pretrain_config + 模拟数据	2
微调 7-8B 模型	llama3_8b_sft_config 或 qwen3_8b_sft_config	2–4
在 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	16
训练大型 MoE（235B+）	qwen3_235b_a22b_pretrain_config	256–512
对文本预训练吞吐量进行基准测试	通过 train.sh --recipe <exact name> 使用基准测试配方	配方中指定的确切数量
长上下文训练	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

---

Code Anchors

What	Path
Library recipes root	src/megatron/bridge/recipes/
Recipe __init__.py (all exports)	src/megatron/bridge/recipes/__init__.py
Common recipe helpers	src/megatron/bridge/recipes/common.py
Training entry point	scripts/training/run_recipe.py
Training Slurm launcher	scripts/training/train.sh
Benchmark recipes root	src/megatron/bridge/perf_recipes/
Benchmark compatibility launcher	scripts/performance/setup_experiment.py
Benchmark recipe helpers	scripts/performance/utils/utils.py
Benchmark overrides	scripts/performance/utils/overrides.py

Last signature refresh: 2026-08-03.