Normalize calibrated ONNX request contracts

[ajrasane]

What does this PR do?

Type of change: new feature

Normalize the public ONNX quantization contract for calibrated INT8 and FP8 modes. Quantization now accepts only the exact int8, fp8, and int4 mode names, applies mode-specific default calibration methods, rejects unsupported methods, and requires exactly one explicit calibration source.

Remove calibration-cache inputs from the Python and CLI interfaces with migration-facing errors. Collection inputs are copied before lower layers can mutate them, while existing passes=None and INT4 behavior remain supported.

Usage

import modelopt.onnx.quantization as moq

moq.quantize(
    "model.onnx",
    quantize_mode="fp8",
    calibration_data={"input": calibration_batches},
)

Testing

• Changed-file pre-commit checks passed.
• Relevant ONNX quantization suites passed in the documented TensorRT container: 40 passed, 8 expected xfails.

Before your PR is "Ready for review"

Make sure you read and follow Contributor guidelines and your commits are signed (git commit -s -S).

Make sure you read and follow the Security Best Practices (e.g. avoiding hardcoded trust_remote_code=True, torch.load(..., weights_only=False), pickle, etc.).

• Is this change backward compatible?: ❌ — calibration-cache inputs and implicit random calibration were removed, and mode names are now exact.
• If you copied code from any other sources or added a new PIP dependency, did you follow guidance in CONTRIBUTING.md: N/A
• Did you write any new necessary tests?: ✅
• Did you update Changelog?: ✅
• Did you get Claude approval on this PR?: N/A

Additional Information

Characterization coverage was introduced in #2457.

Summary by CodeRabbit

• New Features

  • ONNX quantization now supports only int8, fp8, and int4 modes.
  • INT8 and FP8 quantization require exactly one calibration data source.
  • Default calibration methods are now entropy for INT8 and max for FP8.

• Bug Fixes

  • Improved validation and CLI guidance for calibration methods and inputs.

• Breaking Changes

  • Calibration cache options and implicit random calibration are no longer supported.

[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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: c0e8a44d-f36d-46c8-908e-557d9a79d35d

📥 Commits

Reviewing files that changed from the base of the PR and between 76c04df and 849239c.

📒 Files selected for processing (12)

• CHANGELOG.rst
• modelopt/onnx/quantization/__main__.py
• modelopt/onnx/quantization/calib_utils.py
• modelopt/onnx/quantization/fp8.py
• modelopt/onnx/quantization/int8.py
• modelopt/onnx/quantization/qdq_utils.py
• modelopt/onnx/quantization/quantize.py
• tests/unit/onnx/quantization/test_calibrated_quantization.py
• tests/unit/onnx/quantization/test_convtranspose_qdq.py
• tests/unit/onnx/quantization/test_qdq_rules_int8.py
• tests/unit/onnx/quantization/test_quantize_api.py
• tests/unit/onnx/quantization/test_quantize_int8.py

💤 Files with no reviewable changes (2)

• modelopt/onnx/quantization/calib_utils.py
• modelopt/onnx/quantization/qdq_utils.py

Included review availability: Your plan provides up to 12 included reviews per hour; 10 remain after this review.

---

📝 Walkthrough

Walkthrough

Changes

ONNX quantization calibration

Layer / File(s)	Summary
Calibration contract and validation modelopt/onnx/quantization/quantize.py, tests/unit/onnx/quantization/test_calibrated_quantization.py, CHANGELOG.rst	quantize accepts only int8, fp8, and int4. INT8 and FP8 require exactly one calibration source. Their default methods are entropy and max.
Calibration-cache removal modelopt/onnx/quantization/int8.py, modelopt/onnx/quantization/fp8.py, modelopt/onnx/quantization/calib_utils.py, modelopt/onnx/quantization/qdq_utils.py	Calibration-cache parameters, cache parsing, cached-scale application, and related helpers were removed. Removed arguments now raise TypeError.
CLI wiring and test migration modelopt/onnx/quantization/__main__.py, tests/unit/onnx/quantization/*	The CLI rejects --calibration_cache_path and documents required calibration data. Tests now provide calibration inputs for INT8 and FP8 paths and verify the new validation rules.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Suggested reviewers: kevalmorabia97

Merge Risk: ⚪ Minimal · up to 84923

The revised calibration contract has no identified actionable regression and is ready to merge.

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 27 functions across 9 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: standardizing calibrated ONNX quantization request contracts, including calibration requirements and removed cache inputs.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Security Anti-Patterns	✅ Passed	No listed security anti-pattern was introduced. The authoritative diff changes six modelopt Python files and no examples or dependency metadata. Added-line and structural searches found no torch.load(…

Full details: Docstring Coverage

Explanation

Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 27 functions across 9 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

_{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-2476/
Built to branch gh-pages at 2026-09-18 19:46 UTC. Preview will be ready when the GitHub Pages deployment is complete.