Nemo Mbridge Recipe Recommender

Auto Recipe — Recipe Index & Recommendation

This skill indexes every shipped recipe and helps users pick the right starting config, adjust parallelism, and avoid common pitfalls.

How to Use This Skill

1. Ask the user for: model name/size, GPU count & type, training goal (pretrain / SFT / PEFT), and sequence length (if non-default).
2. Look up the best-match recipe in the index below.
3. Recommend the recipe function name + entry-point command.
4. Provide adjustment advice (parallelism resizing, batch tuning, pitfalls).

First Answer Checklist

When recommending recipes, always include these distinctions before the long index details:

1. Library recipes under src/megatron/bridge/recipes/ are for functional training and use scripts/training/run_recipe.py.
2. Benchmark recipes under src/megatron/bridge/perf_recipes/ are for upper-bound throughput benchmarks. They own their canonical benchmark data and settings and should not be presented as production training recipes.
3. For a first-time Bridge smoke test, recommend llama3_8b_pretrain_config with mock data via --dataset mock.
4. For normal SFT recommendations, select a finetuning preset such as --dataset squad or --dataset tulu3; for pretrain and mock validation recommendations, use --dataset mock. Do not pair the pretraining-only mock preset with an SFT or PEFT mode.
5. After the recipe and dataset, give the required resizing rules: TP must divide num_key_value_heads, keep TP within one node unless using NVL72-class interconnect, enable SP when TP > 1, configure CP for long context, DP is implicit, and reduce micro_batch_size first on OOM.
6. State whether each proposed override changes the convergence contract or only the execution/performance mapping. Do not trade convergence semantics for throughput without calling it a new experiment.

Configuration Layers and Change Control

Separate training semantics from their hardware mapping before recommending or tuning a recipe.

Convergence configuration includes the starting checkpoint and trainable parameters; dataset/revision/split/order/seeds; tokenizer, masking, truncation, and packing; sequence length; global batch and token budget; objective and loss coefficients; natural or forced MoE routing and token-dropping policy; optimizer, LR, schedule, warmup, betas, epsilon, weight decay, clipping, and dropout; arithmetic and optimizer-state precision; and PEFT adapter settings. Changing one of these creates a new convergence experiment.

Execution/performance configuration includes hardware count and topology; TP/PP/VP/CP/EP/ETP/DP/SP; recompute and offload; distributed optimizer/FSDP; communication overlap; fusions and attention backends; CUDA graphs and compilation; checkpoint I/O; and MoE transport through all-to-all, DeepEP, or HybridEP when the routing policy is unchanged. These settings should preserve the objective and effective updates, although floating-point reduction order can produce small numerical drift that still needs validation.

Treat micro batch size and gradient accumulation as execution fingerprints. Tune them only with fixed global batch size, global batch membership/order, normalization, optimizer boundaries, and token budget, and validate fresh loss sentinels for each layout. Packing, precision, forced MoE load balancing, token dropping/capacity, and router/auxiliary loss changes are never performance-only knobs.

Treat mock data, forced balancing, disabled correctness checks, and timing-only schedules as benchmark-only shortcuts. They may be appropriate in perf_recipes, but their losses and checkpoints are not convergence evidence.

For comparable model-verification recipes, choose a cohort-wide convergence contract before tuning performance. Keep the same bounded data selection, preprocessing, sequence length, global batch, optimizer/schedule, precision, seeds, routing policy, optimizer-step horizon, and processed-token checkpoints where the architectures permit. Record any necessary model-specific deviation and do not present that result as apples-to-apples convergence evidence. Absolute losses from different architectures or tokenizers are not directly rankable; compare stability and trend at equal token counts.

When a recipe's batch disagrees with the chosen convergence contract, modify and validate the library recipe separately. A declared bounded-verification protocol may explicitly apply the same LR, schedule, sequence, and data overrides across a cohort, but do not make one-off convergence changes merely to improve throughput. Conversely, first try TP/PP/CP/EP, recompute/offload, dispatcher transport, overlap, fusion, and CUDA graphs when optimizing fit or throughput.

Entry Points

Library recipes (functional training)

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

Benchmark recipes (throughput benchmarks)

./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

The total GPU allocation must match the count encoded in the recipe name. The user selects the node shape, and the selected partition must provide the requested hardware. The launcher does not inject benchmark offline defaults or cluster-specific launch policy. Use --env NAME for exported offline or NCCL fabric settings and repeated --srun-arg=ARG options for srun. Configure CPU/NUMA wrappers and Slurm segment sizing through the target cluster integration, or use scripts/performance/setup_experiment.py when its compatibility policies are required. The unified launcher supports exact exported text pretraining, text SFT/PEFT, Qwen-VL pretraining, and Wan pretraining recipes and infers their forward step. Text SFT/PEFT text benchmark recipes retain the flat runner's mock-data default; Qwen-VL and Wan retain their model-specific datasets. Exported benchmark PEFT recipes are fixed LoRA configs; use a configurable library recipe for DoRA. Trailing KEY=VALUE overrides are accepted, but an overridden benchmark recipe no longer represents its canonical benchmark configuration. Use scripts/performance/setup_experiment.py for selector-based invocation, dataset replacement, topology resizing, and specialized benchmark controls.

See the Benchmark Recipe Index for important caveats before using these for anything beyond throughput benchmarking.

Benchmark Recipe Layout

Benchmark recipes use the same Python function format as library recipes, but live in a dedicated namespace for throughput benchmarking:

• Benchmark recipes live in src/megatron/bridge/perf_recipes/<family>/<hardware>/<model>.py
• Each benchmark recipe is a self-contained Python function (e.g. llama3_8b_pretrain_8gpu_h100_bf16_config())
• Recipe names encode model, task, GPU count, hardware, precision, and optional variant
• scripts/performance/utils/utils.py derives compatibility WorkloadBaseConfig views from the flat recipe itself
• Shared helpers: _benchmark_common() (50 iters, timing, TE RNG), _perf_precision() (bf16 / fp8_cs / fp8_mx / nvfp4)

Why Python, not YAML? Previous YAML-based approaches had problems: recipe logic was split across multiple indirection layers, configs were not self-contained, and the two-level pipeline made maintenance and debugging difficult. Python functions are explicit, greppable, and composable.

The training launcher discovers library and benchmark recipes from the complete exported function name. Five legacy duplicate names select the benchmark definition; use the corresponding generic alias for those functional workloads. New recipe names should be unique across both packages.