Reuse a whole recipe via $import, deprecate recipe_type, and backfill the recipes behind NVIDIA's published checkpoints

[shengliangxu]

What does this PR do?

Type of change: new feature (recipe loading + model recipes) with two bug fixes

Two things, the second built on the first:

1. A recipe can now reuse another recipe whole. A top-level $import brings in the imported recipe's entire body; keys given alongside it override the imported ones. metadata.recipe_type becomes optional and is deprecated along the way.
2. modelopt_recipes/models/ backfills the recipes behind already-published checkpoints — the NVIDIA-Nemotron-3 releases, plus three aliases for releases an existing general recipe already covers. Nothing here proposes a new quantization scheme: each entry records, in the repo, the scheme a checkpoint NVIDIA has already shipped was built with, so it is reachable from that checkpoint's hub path.

This is the first of several backfill batches. It carries the loader and doc changes plus the checkpoints whose source model is NVIDIA's own. The rest follow one source-model org per PR — Qwen, deepseek-ai, meta-llama, google, moonshotai, zai-org, microsoft, MiniMaxAI, mistralai, meta-models — so each set of recipes can be validated on its own rather than in one 160-file review.

Declaring what kind of recipe a file is

load_recipe read metadata.recipe_type out of the raw YAML before resolving imports, because it needs the schema class to hand to load_config. That made the field impossible to inherit, so a recipe reusing another had to restate a line it could only have copied.

It is now optional, and the loader takes the first of these that answers:

1. a # modelopt-schema: comment naming the recipe's schema class,
2. metadata.recipe_type — deprecated; still read and still honoured, so a recipe outside this repo keeps working unchanged,
3. the recipe it delegates to via a top-level $import.

Whatever a recipe does state must be true, in both directions. A schema comment contradicting a recipe_type is rejected, and so is a recipe importing a different kind of recipe — that used to surface as whatever pydantic made of, say, an eagle section spliced into a PTQ schema.

The concrete recipe classes carry a RECIPE_TYPE ClassVar as the single source of truth and fill metadata.recipe_type in from it, so load_config validates a recipe identically with or without an explicit schema_type.

Only a recipe that another file imports needs the schema comment — that is what $import resolution requires to validate the payload. A recipe nothing imports needs nothing. Since recipe_type is now deprecated, the sweep here drops it from all 77 shipped recipes that carried it and gives 72 of them the schema comment instead (5 already had one), so nothing in-tree depends on the deprecated field.

How the backfilled recipes were derived

Each release's hf_quant_config.json gives the quantized-module list and the formats; two things it cannot express were read out of the published weights directly:

• Cast vs. calibrated KV cache. hf_quant_config.json records only FP8. use_constant_amax pins amax to the E4M3 max, so a cast KV cache exports k_scale == 1.0 exactly — sampling one k_scale is what separates kv_fp8_cast from kv_fp8, and it is how both Nemotron KV mismatches below surfaced.
• Layers the model class never builds. A checkpoint declaring num_hidden_layers: 61 with num_nextn_predict_layers: 1 ships model.layers.61, the MTP block, which the HF class does not instantiate. Those tensors are outside the quantized model, so they say nothing about what a recipe should match.

Two limits on what this can establish. It says nothing about calibration — hf_quant_config.json does not record whether a release used max, MSE, or something else, so the calibration in each backfilled recipe below reflects what the recipe is meant to do, not a property recovered from the checkpoint. And a checkpoint's tensor names are not the loaded model's module names: transformers/conversion_mapping.py rewrites keys on load, so each pattern below was checked against the modeling code rather than against the checkpoint. nemotron_h's rules (backbone. → model., per-expert up_proj/down_proj fused into 3-D parameters) leave the *mixer.* patterns intact, and the omni-modal releases load through trust_remote_code, where no rewriting applies.

Recipes backfilled

• NVIDIA-Nemotron-3-Nano-30B-A3B-BF16/ptq/fp8_moe_mamba-kv_fp8_cast — MoE experts and the Mamba in_proj/out_proj quantized, except on layers 4, 11, 18, 25, 32 and 41: the Mamba layer immediately preceding each of the six attention layers, which the release leaves BF16. There is deliberately no NVFP4 sibling — see below.
• NVIDIA-Nemotron-3-Super-120B-A12B-BF16/ptq/fp8_moe_mamba-kv_fp8_cast — the FP8 sibling of the existing NVFP4 mirrors; uniform, with no per-layer carve-out.
• Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16/ptq/{fp8-kv_fp8_cast,nvfp4_experts-fp8_rest-kv_fp8_cast} — the omni-modal releases. The NVFP4 one is mixed: routed experts NVFP4, shared experts / Mamba in-out / attention o_proj only FP8, q/k/v BF16. Both add explicit disables for the RADIO vision tower, the Conformer sound encoder and the modality projectors, none of which match a standard exclusion.
• Three aliases for the Llama-Nemotron FP8 releases (Llama-3_1-Nemotron-Ultra-253B-v1, Llama-3_3-Nemotron-Super-49B-v1, -v1_5). Those releases are uniform FP8 W8A8 with an FP8 KV cache and exclude only lm_head, which general/ptq/fp8_default-kv_fp8_cast already covers, so each is a five-line delegation to it rather than a copied body.

What the model cards say about method

A backfilled recipe claims only what its released checkpoint's model card supports. Checking all twelve NVIDIA-source releases these recipes target turned up one that a PTQ recipe cannot reproduce: nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-NVFP4, whose card says under Stage 4 that "After PTQ, Quantization-Aware Distillation (QAD) was applied for further accuracy recovery" (arXiv 2601.20088). QAD leaves the quantization layout untouched and retrains the weights, so a PTQ recipe can match every module and format and still not produce the release — and no structural check can detect that. tools/launcher/examples/ agrees: that family ships megatron_lm_qad.yaml and an offline_kd_qad.yaml keyed to the NVFP4 checkpoint itself. So that release is left un-backfilled. The FP8 sibling is kept: its card documents Stage 4 as plain post-training quantization with exactly the selective scope the recipe encodes.

Two releases are confirmed PTQ by their cards (Nano-30B FP8; Lightning-30B NVFP4, whose card names the Four-Over-Six recipe and its 1000-sample/32k calibration set). The remaining cards state no method either way.

One fix

• The Nemotron-3 Super and Ultra NVFP4 recipes quantized the MTP block on the Megatron-Core path, where it is a live model.mtp submodule their broad *mixer.* patterns matched into, contrary to their own descriptions. Hugging Face runs were unaffected — NemotronHPreTrainedModel sets _keys_to_ignore_on_load_unexpected = [r"mtp.*"] and builds no MTP module.

Left for you, not changed here. Those same two recipes also calibrate the KV cache where their releases used a constant amax (published k_scale is exactly 1.0), and a handful of Mamba in_proj / out_proj / latent-proj layers differ from the released map. Altering a validated recipe's numerics is your call, so both are noted rather than edited.

Usage

python examples/hf_ptq/hf_ptq.py \
    --pyt_ckpt_path nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16 \
    --recipe models/nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16/ptq/nvfp4_moe_mamba-kv_fp8_cast \
    --export_path <output>

A recipe that reuses another whole — the shape the aliases and the follow-up batches use:

imports:
  base: general/ptq/nvfp4_default-kv_fp8_cast

$import: base
metadata:
  description: What this checkpoint uses the base recipe for.

Testing

• tests/unit/recipe/test_loader.py — 18 new cases covering every behaviour change: whole-recipe reuse with no metadata at all; kind resolution from each of the three sources, from a delegation chain and from a $import list; a delegation cycle failing with ValueError rather than recursing; peek_declared_schema including a comment placed below the first YAML line; recipe_type being optional, filled per class, and rejected when it contradicts; a directory recipe still requiring it; and delegating across kinds being an error, parametrized over both ways of declaring the kind.
• test_shipped_modelopt_schema_comments_are_in_the_preamble — _parse_modelopt_schema stops at the first non-comment line, so a comment written after metadata: is silently ignored. This catches that shape using the parser's own regex.
• tests/unit/recipe/test_recipe_docs.py — unchanged checks, now also covering the three alias folders, which must be listed in ptq.md like every other models/<org>/<model_id> entry.
• Full tests/unit/recipe/ — 387 passed, 13 failed. The 13 failures are pre-existing and environment-only: they reproduce identically on an unmodified main checkout in the same venv, where a broken transformer_engine .so makes mtq.quantize raise. They are test_glm_5_3_recipe, test_minimax_m3_recipe, test_qwen3_8_recipe, four test_qwen_vision_recipe cases and six test_step3p7_recipes cases.
• pre-commit run --all-files — all hooks pass except Regenerate examples/llm_qat/ARGUMENTS.md, which fails with ModuleNotFoundError: No module named 'torch' in its own hook environment and is untouched here.

Not covered by any of this: numerics. Nothing here asserts accuracy, or that running one of these recipes reproduces a released checkpoint's weights. The recipes were derived from the released quantization layout, but this PR does not claim — and does not test — bit-for-bit reproduction.

Before your PR is "Ready for review"

• Is this change backward compatible?: ✅ — metadata.recipe_type is still read and honoured for recipes outside this repo, the schema comments are inert for direct loads, the loader change only relaxes a check, and the two edits to existing recipes bring them in line with the checkpoints they already claim to mirror.
• If you copied code from any other sources or added a new PIP dependency, did you follow guidance in CONTRIBUTING.md: ✅ — no new dependencies.
• Did you write any new necessary tests?: ✅
• Did you update Changelog?: ✅ — two feature entries, one deprecation, one bug fix under 0.48.0
• Did you get Claude approval on this PR?: ❌ — not yet run

🤖 Generated with Claude Code

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://NVIDIA.github.io/Model-Optimizer/pr-preview/pr-2376/
Built to branch gh-pages at 2026-09-11 20:59 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[codecov]

Codecov Report

❌ Patch coverage is 90.27778% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.99%. Comparing base (c5d1065) to head (33861e0).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
modelopt/recipe/loader.py	86.95%	6 Missing ⚠️
modelopt/recipe/config.py	95.45%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2376      +/-   ##
==========================================
- Coverage   71.29%   70.99%   -0.31%     
==========================================
  Files         590      590              
  Lines       64583    65001     +418     
==========================================
+ Hits        46046    46149     +103     
- Misses      18537    18852     +315     

Flag	Coverage Δ
unit	57.75% <90.27%> (+0.02%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.