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 を 1 ノード内に収めること、TP > 1 の場合は SP を有効にすること、長いコンテキストでは CP を設定すること、DP は暗黙的であること、OOM 時はまず micro_batch_size を減らすこと。
6. 提案する各オーバーライドが収束条件を変更するのか、それとも実行／パフォーマンスのマッピングのみを変更するのかを明記します。収束の意味を犠牲にしてスループットを上げる場合は、新しい実験として明示してください。

構成レイヤーと変更管理

レシピを推奨または調整する前に、学習の意味論とハードウェアへの割り当てを分けます。

収束構成には、開始チェックポイントと学習可能なパラメーター、データセット／リビジョン／分割／順序／シード、トークナイザー、マスキング、切り詰め、パッキング、シーケンス長、グローバルバッチとトークン予算、目的関数と損失係数、自然または強制的な MoE ルーティングとトークン破棄ポリシー、オプティマイザー、LR、スケジュール、ウォームアップ、ベータ、イプシロン、重み減衰、クリッピング、ドロップアウト、演算精度とオプティマイザー状態の精度、PEFT アダプター設定が含まれます。これらのいずれかを変更すると、新しい収束実験になります。

実行／パフォーマンス構成には、ハードウェアの数とトポロジー、TP／PP／VP／CP／EP／ETP／DP／SP、再計算とオフロード、分散オプティマイザー／FSDP、通信オーバーラップ、融合とアテンションバックエンド、CUDA グラフとコンパイル、チェックポイント I/O、ルーティングポリシーを変更しない場合の all-to-all、DeepEP、または HybridEP による MoE 通信が含まれます。これらの設定では目的関数と実効的な更新を維持する必要がありますが、浮動小数点のリダクション順序によって小さな数値のずれが生じることがあり、検証が必要です。

マイクロバッチサイズと勾配累積は、実行のフィンガープリントとして扱います。グローバルバッチサイズ、グローバルバッチの構成メンバーと順序、正規化、オプティマイザーの境界、トークン予算を固定した場合にのみ調整し、各レイアウトで新しい損失センチネルを検証してください。パッキング、精度、強制的な MoE 負荷分散、トークン破棄／容量、ルーター／補助損失の変更は、パフォーマンスのみを調整する設定ではありません。

モックデータ、強制的な負荷分散、正確性チェックの無効化、計測専用のスケジュールは、ベンチマーク専用の近道として扱います。これらは perf_recipes では適切な場合がありますが、その損失とチェックポイントは収束の根拠にはなりません。

モデル検証用のレシピを比較する場合は、パフォーマンスを調整する前に、コホート全体で適用する収束契約を決めます。アーキテクチャ上可能な範囲で、制限付きのデータ選択、前処理、シーケンス長、グローバルバッチ、オプティマイザー／スケジュール、精度、シード、ルーティングポリシー、オプティマイザーステップの上限、処理済みトークンのチェックポイントを揃えます。必要なモデル固有の差異を記録し、その結果を同条件での収束の根拠として提示しないでください。異なるアーキテクチャやトークナイザーの絶対損失は直接比較できません。同じトークン数で安定性と傾向を比較してください。

レシピのバッチサイズが選択した収束契約と一致しない場合は、ライブラリレシピを個別に変更して検証します。宣言された制限付き検証プロトコルでは、コホート全体に同じ LR、スケジュール、シーケンス、データの上書きを明示的に適用できますが、スループットを上げるためだけに個別の収束設定を変更しないでください。逆に、適合性やスループットを最適化する際は、まず 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 の割り当て総数は、レシピ名に含まれる台数と一致させる必要があります。ユーザーがノードの形状を選択し、選択したパーティションが要求されたハードウェアを提供する必要があります。ランチャーは、ベンチマーク用のオフラインのデフォルト設定や、クラスター固有の起動ポリシーを自動で適用しません。オフライン設定または 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）

YAML ではなく Python を使う理由： 以前の YAML ベースの方法には問題がありました。レシピのロジックが複数の間接層に分散し、設定が自己完結しておらず、2 段階のパイプラインによって保守やデバッグが困難になっていました。Python 関数は明示的で、検索しやすく、組み合わせ可能です。

トレーニングランチャーは、エクスポートされた関数名全体からライブラリレシピとベンチマークレシピを検出します。従来の重複名が 5 つあり、それらはベンチマーク定義を選択します。該当するワークロードには、対応する汎用エイリアスを使用してください。新しいレシピ名は、両方のパッケージで一意にしてください。

---

レシピインデックス（ライブラリとベンチマーク）

ファミリーごとの全レシピ表 — 並列処理の次数、最小 GPU 数、対応ハードウェアを含む、提供されているすべてのライブラリレシピ（src/megatron/bridge/recipes/）とベンチマークレシピ（src/megatron/bridge/perf_recipes/）— は、このスキルを簡潔に保つため、専用のリファレンスファイルにまとめられています。

→ 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 だけでは モデルを収容できない場合にのみ増やしてください。バブルのオーバーヘッドを軽減するには、VP（仮想パイプライン）を使用します。
4. EP は密結合層のメモリを削減しません。 EP でシャーディングされるのはエキスパートパラメーターのみです。共有されるアテンション／埋め込みは複製されます。「MoE で OOM」が発生した場合は、TP ではなく、まず EP を増やしてください。
5. TP > 1 の場合、SP は True にしてください。 冗長なアクティベーションのコピーをなくし、実質的にコストはかかりません。
6. CP には all-to-all またはリングアテンションが必要です。 cp_comm_type を確認してください。GQA モデルでは、a2a+p2p による階層型 CP を使うことで、CP を num_kv_heads より大きくできます。
7. 密結合メッシュとエキスパートメッシュは重なります。 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 の約数まで減らす
VP なしの PP	スループットが低い（大きなバブル）	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 では 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.