
名称	nemo-mbridge-recipe-recommender
开源协议	Apache-2.0
描述	针对用户的模型、GPU数量、硬件、序列长度以及预训练/SFT/PEFT目标，推荐和定制Megatron Bridge库与基准配方。在选择起始配方、比较库与基准配置、为GPU分配调整并行度，或区分收敛性变更、保持语义的执行调优以及仅基准的快捷方式时使用。

自动配方 — 配方索引与推荐

本技能索引所有已发布的配方，并帮助用户选择正确的起始配置、调整并行度，避免常见陷阱。

如何使用本技能

向用户询问：模型名称/规模、GPU数量与类型、训练目标（预训练 / SFT / PEFT）以及序列长度（若非默认值）。
在下面的索引中查找最匹配的配方。
推荐配方函数名 + 入口命令。
提供调整建议（并行度调整、批大小调优、陷阱）。

首次回答清单

在推荐配方时，务必在展示冗长索引细节之前包含以下区分说明：

src/megatron/bridge/recipes/ 下的库配方用于功能性训练，并使用 scripts/training/run_recipe.py。
src/megatron/bridge/perf_recipes/ 下的基准配方用于上限吞吐量基准测试。它们拥有自己的标准基准数据和设置，不应作为生产训练配方呈现。
对于首次Bridge冒烟测试，推荐 llama3_8b_pretrain_config，并使用 --dataset mock 模拟数据。
对于常规SFT推荐，选择微调预设，如 --dataset squad 或 --dataset tulu3；对于预训练和模拟验证推荐，使用 --dataset mock。不要将仅预训练的 mock 预设与SFT或PEFT模式配对。
在配方和数据集之后，给出必要的调整规则：TP必须整除 num_key_value_heads，除非使用NVL72类互联，否则TP保持在一个节点内；当TP > 1时启用SP；针对长上下文配置CP；DP是隐式的；OOM时优先减小 micro_batch_size。
说明每个提议的覆盖是改变收敛契约，还是仅改变执行/性能映射。不要为了吞吐量而牺牲收敛语义，除非声明这是一个新实验。

配置层与变更控制

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

收敛配置 包括起始检查点和可训练参数；数据集/版本/切分/顺序/种子；分词器、掩码、截断和打包；序列长度；全局批大小与token预算；目标与损失系数；自然或强制的MoE路由和token丢弃策略；优化器、学习率、调度、预热、betas、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数下比较稳定性和趋势。

当配方的批次与所选收敛契约不一致时，单独修改并验证库配方。声明的有界验证协议可以明确地对整个群体应用相同的LR、调度、序列和数据覆盖，但不要仅为了提升吞吐量而进行一次性收敛更改。相反，在优化适配或吞吐量时，首先尝试TP/PP/CP/EP、重计算/卸载、分发器传输、重叠、融合和CUDA图。

入口点

库配方（功能性训练）

# 使用模拟数据进行预训练
uv run python -m torch.distributed.run --nproc_per_node=8 scripts/training/run_recipe.py \
    --recipe <recipe_function_name> \
    --dataset mock

# 使用SQuAD进行SFT
uv run python -m torch.distributed.run --nproc_per_node=8 scripts/training/run_recipe.py \
    --recipe <recipe_function_name> \
    --dataset squad

# 通过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分配必须与配方名称中编码的数量匹配。用户选择节点形状，所选分区必须提供所请求的硬件。启动器不注入基准离线默认值或集群特定的启动策略。对导出的离线或NCCL结构设置使用 --env NAME，对 srun 使用重复的 --srun-arg=ARG 选项。通过目标集群集成配置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）和基准配方索引（每硬件吞吐量配置）。

加载该文件以获取精确的配方函数名或其默认并行度；以下指南告诉您应查找哪个条目。

调整建议（推荐时）

并行度调整规则

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

TP必须整除 num_key_value_heads（GQA约束）。例如，若 num_key_value_heads=8，有效TP = {1, 2, 4, 8}。
TP应保持在一个节点内（NVLink）。TP > 8需要节点间NVLink（如GB200 NVL72）。
PP增加流水线气泡。 尽量减少PP；仅当TP无法容纳模型时增加。使用VP（虚拟流水线）缓解气泡开销。
EP不会减少密集层内存。 只有专家参数随EP分片。共享注意力/嵌入被复制。对于“MoE OOM”，首先增加EP，而非TP。
当TP > 1时，SP应为True。 它消除了冗余激活副本，几乎零成本。
CP需要all-to-all或环状注意力。 检查 cp_comm_type。对于GQA模型，a2a+p2p 分层CP允许CP > num_kv_heads。
密集和专家网格重叠。 不要将TP和EP相乘。最小MoE世界大小为 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个秩上
CUDA图 + 打包序列	断言：“CUDA graph accepts only Tensor inputs”	禁用打包或使用 `local` 全迭代图
CUDA图 + 全重计算	断言：“full recompute only with full iteration CUDA graph”	禁用重计算或切换到 `local` 实现
未设置 `use_te_rng_tracker`	启用CUDA图时提供程序初始化断言	设置 `cfg.model.use_te_rng_tracker = True` 和 `cfg.rng.te_rng_tracker = True`
H100上FSDP + TP > 1	可能的通信瓶颈	在H100上优先使用FSDP且TP=1或TP=2；FSDP在GB/B系列上表现最佳
长上下文未使用CP	激活OOM	添加CP=2/4/8；使用 `_16k`、`_64k` 或 `*_128k` 配方变体
MoE `overlap_grad_reduce` 在H100上	可能损害吞吐量（许多H100预置中为False）	对于H100上的MoE，设置 `overlap_grad_reduce=False`
VLM SFT缺少图像数据	正常运行但产生垃圾	提供实际多模态数据集或使用模拟VLM数据
Qwen35-VL MoE FSDP	仅在Blackwell上测试	可能在H100上无法工作；先验证

配方覆盖示例

# 将Llama3 8B从2 GPU扩展到8 GPU（增加DP）
uv run python -m torch.distributed.run --nproc_per_node=8 scripts/training/run_recipe.py \
    --recipe llama3_8b_pretrain_config \
    --dataset mock

# 运行原生4-GPU Qwen3-MoE 30B PEFT拓扑
uv run python -m torch.distributed.run --nproc_per_node=4 scripts/training/run_recipe.py \
    --recipe qwen3_30b_a3b_peft_config \
    --dataset tulu3

# 为现有配方添加长上下文
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'

# 在任何配方上启用CUDA图
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 <精确名称>` 使用基准配方	精确编码数量
长上下文训练	`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`
训练Slurm启动器	`scripts/training/train.sh`
基准配方根目录	`src/megatron/bridge/perf_recipes/`
基准兼容性启动器	`scripts/performance/setup_experiment.py`
基准配方辅助函数	`scripts/performance/utils/utils.py`
基准覆盖	`scripts/performance/utils/overrides.py`

最后签名刷新：2026-08-03。

Megatron桥接配方推荐器Skill nemo-mbridge-recipe-recommender