docs: rebuild the unified HF deployment support matrix from the deploy test suite (NVBug 6550792)

[Edwardf0t1]

What does this PR do?

Type of change: documentation

Fixes NVBug 6550792 / OMNIML-5693.

The Unified HF Checkpoint Deployment Model Support Matrix listed 9 model families and no VLMs, while tests/examples/hf_ptq/test_deploy.py already deploy-tests 81 checkpoints (218 model×backend combinations) across TRT-LLM, vLLM, and SGLang — including Qwen2.5-VL, Qwen3-VL-235B-A22B, Phi-4-multimodal, and Nemotron-3-Nano-Omni. QA (the filer) could not use the doc to scope testing, and users could not tell what is actually supported.

Filing also surfaced that the matrix lived in three places that had drifted apart:

Claim	examples/hf_ptq/README.md	docs/…/3_unified_hf.rst	.agents/…/support-matrix.md
Qwen3-VL on TRT-LLM	absent	listed	absent
Qwen3.5 MoE FP4 on SGLang	listed	absent	absent

Changes

1. Rebuilt the matrix in docs/source/deployment/3_unified_hf.rst directly from test_deploy.py, split into four tables — language models, vision-language/multimodal, speculative decoding drafters, diffusion — with a three-state legend:

   • Y — covered by the release deployment test suite (loads the exported checkpoint in the framework and runs generation)
   • ~ — documented as working previously but not in the current suite; expected to work, unvalidated
   • - — not currently covered

   The ~ state is what lets the table grow honestly: entries carried over from the old matrix (Qwen 2.5, QwQ-32B, Mixtral) are not silently promoted to "validated", and export-succeeds is never conflated with serves-correctly.

2. Removed the two duplicate copies, replacing them with links, so there is one table to keep current.

3. Fixed stale prose in the deployment tabs that still claimed FP8-only support on vLLM v0.6.5 and a source build of SGLang main from Jan 2025 — both contradicted the version table 50 lines above them.

Also added the Blackwell/sm_103 CUDA-13 note and a "models not listed here" section explaining that the frameworks load unified HF checkpoints generically, so an unlisted model often deploys with no modelopt change.

Usage

N/A — documentation only.

Testing

• docutils parse of the modified .rst: no warnings or errors from the new content; all 5 tables parse.
• Cross-checked every Y cell against tests/examples/hf_ptq/test_deploy.py by AST-parsing the ModelDeployerList(...) calls rather than reading the file by eye.
• pre-commit run --files … passes (markdownlint-cli2 and the three rst hooks included).

Before your PR is "Ready for review"

• Is this change backward compatible?: ✅
• 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?: N/A
• Did you update Changelog?: N/A — documentation only
• Did you get Claude approval on this PR?: ❌ — not yet run

Additional Information

Known follow-up: this PR removes the three-way drift structurally, but nothing yet enforces that the doc matrix tracks test_deploy.py. A generator plus a CI check would close that for good; filing separately rather than growing a doc fix.

For the filer (@kenny Kang): the Y cells are exactly the scope the release deploy suite covers, and test_deploy.py carries the checkpoint, TP size, and minimum SM version per entry. If QA can validate any ~ cells, those flip to Y.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Replaced scattered framework-specific model lists with a unified, maintained deployment support matrix.
  • Added validated coverage for language, multimodal, speculative-decoding, and diffusion models across supported frameworks and quantization formats.
  • Documented minimum framework versions, NVFP4 hardware and build requirements, and guidance for unlisted models.
  • Expanded TensorRT-LLM, vLLM, and SGLang guidance for FP8 and NVFP4 configurations.
  • Updated examples and references, including the NVFP4 inference requirement to TensorRT-LLM 1.2 or later.

[coderabbitai]

📝 Walkthrough

Walkthrough

The deployment documentation now contains the canonical unified support matrix, updated framework requirements, and guidance for unlisted models. Supporting references link to the documentation and deployment validation test.

Changes

Unified deployment support

Layer / File(s)	Summary
Canonical deployment support matrix docs/source/deployment/3_unified_hf.rst	Adds framework versions, validation status, language, multimodal, speculative-decoding, and diffusion support tables. Documents NVFP4 requirements, tested checkpoints, and unlisted-model guidance.
Framework deployment requirements docs/source/deployment/3_unified_hf.rst, examples/diffusers/README.md, examples/hf_ptq/README.md	Updates TensorRT-LLM, vLLM, and SGLang requirements for FP8 and NVFP4 support. Updates example documentation to require TensorRT-LLM v1.2 for NVFP4 inference.
Supporting reference alignment .agents/skills/deployment/references/support-matrix.md, examples/hf_ptq/README.md	Replaces embedded matrices with links to the canonical documentation and validation test. Documents validated coverage and VLM quantization behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: realasma, kevalmorabia97

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main documentation change: rebuilding the unified HF deployment support matrix from the deployment test suite.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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	The commit changes only three Markdown/RST files; no Python or dependency files changed, and added lines contain none of the listed security anti-patterns.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/unified-hf-deployment-support-matrix

---

_{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-2087/
Built to branch gh-pages at 2026-08-07 05:58 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[coderabbitai]

Warning

CodeRabbit couldn't request changes on this pull request because it doesn't have sufficient GitHub permissions.

Please grant CodeRabbit Pull requests: Read and write permission and re-run the review.

👉 Steps to fix this

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/source/deployment/3_unified_hf.rst`:
- Around line 139-149: Document the conditional EAGLE test prerequisite
consistently: in docs/source/deployment/3_unified_hf.rst lines 139-149, add that
EAGLE coverage requires MODELOPT_LOCAL_EAGLE_MODEL and an existing local drafter
directory; in .agents/skills/deployment/references/support-matrix.md lines 5-12,
qualify EAGLE coverage with the same prerequisite; and in
examples/hf_ptq/README.md lines 597-600, qualify the statement that every entry
loads and runs. Preserve the meaning that Y indicates coverage when the
prerequisite is available.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 19ce3c6f-7119-4d00-8414-269841f99320

📥 Commits

Reviewing files that changed from the base of the PR and between 19e0121 and 3a47fc1.

📒 Files selected for processing (3)

• .agents/skills/deployment/references/support-matrix.md
• docs/source/deployment/3_unified_hf.rst
• examples/hf_ptq/README.md

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 66.98%. Comparing base (19e0121) to head (5742dba).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2087      +/-   ##
==========================================
- Coverage   67.15%   66.98%   -0.18%     
==========================================
  Files         521      521              
  Lines       59857    59857              
==========================================
- Hits        40199    40097     -102     
- Misses      19658    19760     +102     

Flag	Coverage Δ
examples	43.04% <ø> (-0.21%)	⬇️

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.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

docs/source/deployment/3_unified_hf.rst (2)

183-187: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Replace the stale Y reference.

The tables and legend now use ✅, but Line 183 still says “every Y above”. Change this to “every checkmark above” or “every ✅ above”.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/source/deployment/3_unified_hf.rst` around lines 183 - 187, Update the
deployment documentation sentence referring to “every ``Y`` above” so it instead
refers to the current checkmark notation, using “every checkmark above” or
“every ``✅`` above”; leave the surrounding checkpoint and link references
unchanged.

---

170-173: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Scope the Blackwell requirement to the serving paths.

• In docs/source/deployment/3_unified_hf.rst, state that the Blackwell and CUDA 13 requirements apply to unified HF serving.
• In examples/diffusers/README.md, state that the Blackwell and TensorRT-LLM v1.2 requirements apply to the TensorRT-LLM table. The Wan 2.2 VAE NVFP4 path supports SM80+ GPUs.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/source/deployment/3_unified_hf.rst` around lines 170 - 173, Scope the
hardware and software requirements to the relevant serving paths: in
docs/source/deployment/3_unified_hf.rst lines 170-173, state that the Blackwell
GPU and CUDA 13 requirements apply to unified HF serving; in
examples/diffusers/README.md line 81, state that Blackwell and TensorRT-LLM v1.2
are required for the TensorRT-LLM table while documenting that the Wan 2.2 VAE
NVFP4 path supports SM80+ GPUs.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@docs/source/deployment/3_unified_hf.rst`:
- Around line 183-187: Update the deployment documentation sentence referring to
“every ``Y`` above” so it instead refers to the current checkmark notation,
using “every checkmark above” or “every ``✅`` above”; leave the surrounding
checkpoint and link references unchanged.
- Around line 170-173: Scope the hardware and software requirements to the
relevant serving paths: in docs/source/deployment/3_unified_hf.rst lines
170-173, state that the Blackwell GPU and CUDA 13 requirements apply to unified
HF serving; in examples/diffusers/README.md line 81, state that Blackwell and
TensorRT-LLM v1.2 are required for the TensorRT-LLM table while documenting that
the Wan 2.2 VAE NVFP4 path supports SM80+ GPUs.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8bd6d1e9-8eaa-4f03-b2fc-f1d672583f56

📥 Commits

Reviewing files that changed from the base of the PR and between 3a47fc1 and 5742dba.

📒 Files selected for processing (3)

• docs/source/deployment/3_unified_hf.rst
• examples/diffusers/README.md
• examples/hf_ptq/README.md

🚧 Files skipped from review as they are similar to previous changes (1)

• examples/hf_ptq/README.md