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 の初回スモークテストには、--dataset llm-pretrain-mock でモックデータを使用する llama3_8b_sft_config をおすすめします。セットアップのみを試す場合は、ユーザーが SFT のデータパスを明示的に求めない限り、llm-finetune を使用しないでください。
4. 通常の SFT には --dataset llm-finetune を、事前学習およびモック検証には --dataset llm-pretrain-mock を使用しておすすめしてください。
5. レシピとデータセットの後に、必須のサイズ変更ルールを提示します：TP は num_key_value_heads を割り切れる必要があり、NVL72 クラスのインターコネクトを使用しない限り、TP を 1 ノード以内に収めます。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）

なぜ YAML ではなく Python なのか？ 以前の YAML ベースの方法には問題がありました： レシピのロジックが複数の間接レイヤーに分散し、設定が自己完結しておらず、2 段階のパイプラインによって保守やデバッグが困難でした。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グラフで約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

拡散モデルのレシピ

レシピ	モード	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グラフ（ローカル）、GBバリアントでFSDP
Llama 3 70B	64	H100、B200、B300、GB200、GB300	TP通信のオーバーラップ（userbuffers）、FSDP、CUDAグラフ
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グラフ（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グラフ、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 で OOM」が発生した場合は、TP ではなく、まず EP を増やしてください。
5. TP > 1 の場合は、SP を常に True にしてください。 冗長なアクティベーションのコピーをなくし、実質的にコストはかかりません。
6. CP には all-to-all または ring attention が必要です。 cp_comm_type を確認してください。GQA モデルでは、a2a+p2p の階層型 CP により、CP を num_kv_heads より大きくできます。
7. world_size = DP × TP × PP × CP × EP。 DP は暗黙的です。明示的に指定した並列度の積が、GPU の合計数を割り切れることを確認してください。

バッチサイズの調整

• レシピの 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 の約数に減らす
VP なしの PP	スループットの低下（大きなバブル）	virtual_pipeline_model_parallel_size を設定する
大規模 MoE に対して EP が小さすぎる	エキスパートのパラメーターで OOM	EP を増やす。各エキスパートは EP/num_experts 個のランクに配置される
CUDA graphs とパック済みシーケンスの併用	アサーション：「CUDA graph accepts only Tensor inputs」	パッキングを無効にするか、local の全イテレーショングラフを使用する
CUDA graphs と完全な再計算の併用	アサーション：「full recompute only with full iteration CUDA graph」	再計算を無効にするか、local 実装に切り替える
use_te_rng_tracker が未設定	CUDA graphs 有効時、プロバイダーの初期化でアサーション	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 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 経由で Perf レシピを実行する	環境によって異なります
長いコンテキストで学習する	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
Perf レシピのルート	scripts/performance/
Perf のエントリーポイント	scripts/performance/run_script.py
Perf ワークロード設定	scripts/performance/configs/<family>/
Perf オーバーライド（ベンチマークのデフォルト値）	scripts/performance/utils/overrides.py