[TRTLLM-12288][feat] Support Nemotron-H nvfp4 ckpt on Hopper

[JadoTu]

Summary by CodeRabbit

• New Features

  • Added W4A16 NVFP4 quantization support with automatic fallback handling for Hopper architecture.

• Tests

  • Added accuracy validation test for W4A16 NVFP4 quantization on 4-GPU Hopper systems.

Description

Enables NVFP4 Nemotron-H checkpoints to run on Hopper GPUs, which lack a native NVFP4 tensor-core GEMM. We add a W4A16 path that loads the NVFP4 weights and dequantizes them on-the-fly per forward step via Triton kernel. CUDA-graph capturable; Blackwell paths are untouched.

1. This method will fallback different moe backends to one, which is a new path for nvfp4 on hopper.
2. The dequantization of nvfp4 is done by triton, which needs further improvement.
3. Functional tests have passed with Nemotron ultra/super on h100/h200, enabling MTP.
4. The perf now is not tuned. Here is a example of ultra model running the full dataset of gsm8k on 8xh100: 13 mins.
5. A new ci test is added.

PR Checklist

Please review the following before submitting your PR:

• PR description clearly explains what and why. If using CodeRabbit's summary, please make sure it makes sense.

• PR Follows TRT-LLM CODING GUIDELINES to the best of your knowledge.

• Test cases are provided for new code paths (see test instructions)

• If PR introduces API changes, an appropriate PR label is added - either api-compatible or api-breaking. For api-breaking, include BREAKING in the PR title.

• Any new dependencies have been scanned for license and vulnerabilities

• CODEOWNERS updated if ownership changes

• Documentation updated as needed

• Update tava architecture diagram if there is a significant design change in PR.

• The reviewers assigned automatically/manually are appropriate for the PR.

• Please check this after reviewing the above items as appropriate for this PR.

GitHub Bot Help

To see a list of available CI bot commands, please comment /bot help.

[JadoTu]

/bot run

[tensorrt-cicd]

PR_Github #51160 [ run ] triggered by Bot. Commit: 047bc21 Link to invocation

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR implements a W4A16 quantization fallback for NVFP4 on Hopper GPUs, enabling dequantization-based execution when FP4 hardware is unavailable. The changes span Triton kernels, quantization method classes, MoE and linear execution paths, model-level integration, and validation tests.

Changes

Hopper W4A16 NVFP4 Fallback

Layer / File(s)	Summary
Triton NVFP4 dequantization kernels tensorrt_llm/_torch/modules/fused_moe/triton_dequant_nvfp4.py	Adds Triton-based dequantization for MoE (active-expert-only 3D path with active mask) and linear (2D path with per-tensor scale), with E2M1 FP4 codebook lookup, per-block FP8 scale conversion, and CUDA-graph-safe active expert masking via scatter_.
MoE W4A16 execution path tensorrt_llm/_torch/modules/fused_moe/quantization.py, tensorrt_llm/_torch/modules/fused_moe/fused_moe_cutlass.py	Introduces W4A16NVFP4CutlassFusedMoEMethod for weight unswizzling and active-expert dequantization, plus CutlassFusedMoE dispatch that bypasses FP4 quantization and delegates to _run_moe_w4a16_nvfp4, which dequantizes active experts and calls torch.ops.trtllm.fused_moe with empty scales.
Linear W4A16 execution method tensorrt_llm/_torch/modules/linear.py	Adds W4A16NVFP4LinearMethod for weight-scale preparation, FP8 input inversion, and on-the-fly NVFP4 weight dequantization via Triton, executing GEMM through cublas_mm or F.linear with output reshaping.
Nemotron-H model Hopper fallback wiring tensorrt_llm/_torch/models/modeling_nemotron_h.py	Implements FP4-hardware detection in NemotronHLayer, disables NVFP4 on Mamba mixer for SM<100, and adds context manager patching of quantization methods at NemotronHForCausalLM initialization and post-initialization to apply W4A16 fallback during model construction.
Hopper W4A16 accuracy test tests/integration/defs/accuracy/test_llm_api_pytorch.py, tests/integration/test_lists/test-db/l0_dgx_h100.yml	Adds test_nvfp4_4gpus_hopper_w4a16 test for Nemotron-3-Super-120B-A12B-NVFP4 on H100 with W4A16 fallback semantics, registered in the pre-merge H100 4-GPU test suite.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Suggested reviewers

• danielafrimi
• StanleySun639
• nv-guomingz
• lfr-0531
• yuxianq

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 45.16% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main feature: adding NVFP4 Nemotron-H checkpoint support on Hopper GPUs.
Description check	✅ Passed	The description explains the motivation (NVFP4 on Hopper lacks native GEMM), the solution approach (W4A16 dequantization path), key design notes, testing status, and performance context. However, it lacks specific details about Test Coverage as required by the template.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 4

🤖 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 `@tensorrt_llm/_torch/models/modeling_nemotron_h.py`:
- Around line 793-797: The code unconditionally sets
TRTLLM_ENABLE_ATTENTION_NVFP4_OUTPUT="0" process-wide; instead, capture the
previous os.environ.get("TRTLLM_ENABLE_ATTENTION_NVFP4_OUTPUT"), then set the
env var only within the same context manager used for the class-level patches
(the existing patch context used in this module) and ensure you restore the
original value in a finally block so other model inits don't inherit the change;
reference the env var name TRTLLM_ENABLE_ATTENTION_NVFP4_OUTPUT, the logger call
using get_sm_version(), and wrap the assignment/usage in try/finally (or use the
existing patch context manager) to guarantee restoration.

In `@tensorrt_llm/_torch/modules/fused_moe/quantization.py`:
- Around line 2905-2919: process_weights_after_loading currently unswizzles only
resident expert scales (module.w3_w1_weight_scale, module.w2_weight_scale) after
calling super(), but super().process_weights_after_loading() finalizes and
deletes shared EPLB buffers (local_shared_*_scale_tensors) so migrated experts
remain swizzled and later dequant_active_experts_to_hp() misbehaves; fix by
handling shared EPLB scale buffers before super() is called (e.g., detect and
call the existing _unswizzle_inplace on module.local_shared_*_scale_tensors /
any module.local_shared_{w1,w2,w3}_weight_scale if present) or alternatively
mark eplb_support_status = UNSUPPORTED for this class so EPLB paths are disabled
for this override. Ensure references to process_weights_after_loading,
_unswizzle_inplace, module.local_shared_*_scale_tensors,
module.w3_w1_weight_scale, module.w2_weight_scale, eplb_support_status and
dequant_active_experts_to_hp are used to locate and update the code.

In `@tensorrt_llm/_torch/modules/fused_moe/triton_dequant_nvfp4.py`:
- Around line 155-194: The wrapper that launches _dequant_nvfp4_active_kernel
must validate tensor contiguity/strides and companion shapes before launching:
assert that the innermost (K-packed) dimension is unit-stride for packed_weight
(packed_weight.stride(2)==1) and for scale_linear's last dimension
(scale_linear.stride(1)==1), ensure active_mask has unit stride/contiguous
layout for its indexing (e.g., active_mask.is_contiguous() or
active_mask.stride(0)==1), and validate weight_scale_2 is scalar (numel()==1)
when the 2D path expects a single element; add equivalent checks in the other
wrapper (the 290-333 block that launches the non-active kernel) so kernels
cannot silently read from wrong addresses. Ensure assertions include descriptive
messages naming the offending tensor and expected constraint.

In `@tensorrt_llm/_torch/modules/linear.py`:
- Around line 1891-1896: Replace the current assert with a real guard that
ensures static scales were actually loaded and dynamic quantization is not
forced: when handling FP8 input (input.dtype == torch.float8_e4m3fn) check
module.force_dynamic_quantization and module.inv_input_scale explicitly—if
force_dynamic_quantization is false but module.inv_input_scale is None, raise a
clear RuntimeError (fail fast); only perform the division by
module.inv_input_scale when module.inv_input_scale is present and
module.force_dynamic_quantization is false. Reference
NVFP4LinearMethod.create_weights(), module.inv_input_scale and
module.force_dynamic_quantization to locate and update the logic around the FP8
input handling.

🪄 Autofix (Beta)

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: b2225cc5-e534-4968-a8fd-7877c046fab5

📥 Commits

Reviewing files that changed from the base of the PR and between 15bb791 and 047bc21.

📒 Files selected for processing (7)

• tensorrt_llm/_torch/models/modeling_nemotron_h.py
• tensorrt_llm/_torch/modules/fused_moe/fused_moe_cutlass.py
• tensorrt_llm/_torch/modules/fused_moe/quantization.py
• tensorrt_llm/_torch/modules/fused_moe/triton_dequant_nvfp4.py
• tensorrt_llm/_torch/modules/linear.py
• tests/integration/defs/accuracy/test_llm_api_pytorch.py
• tests/integration/test_lists/test-db/l0_dgx_h100.yml

[tensorrt-cicd]

PR_Github #51160 [ run ] completed with state SUCCESS. Commit: 047bc21
/LLM/main/L0_MergeRequest_PR pipeline #40594 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

[JadoTu]

/bot run

[tensorrt-cicd]

PR_Github #51202 [ run ] triggered by Bot. Commit: b23cffd Link to invocation

[tensorrt-cicd]

PR_Github #51202 [ run ] completed with state FAILURE. Commit: b23cffd
/LLM/main/L0_MergeRequest_PR pipeline #40630 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

[JadoTu]

/bot run

[tensorrt-cicd]

PR_Github #51219 [ run ] triggered by Bot. Commit: b23cffd Link to invocation

[tensorrt-cicd]

PR_Github #51219 [ run ] completed with state SUCCESS. Commit: b23cffd
/LLM/main/L0_MergeRequest_PR pipeline #40642 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

[JadoTu]

/bot run

[tensorrt-cicd]

PR_Github #51242 [ run ] triggered by Bot. Commit: b23cffd Link to invocation

[tensorrt-cicd]

PR_Github #51242 [ run ] completed with state SUCCESS. Commit: b23cffd
/LLM/main/L0_MergeRequest_PR pipeline #40665 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

• Please check the failed tests and fix your PR
• If you cannot view the failures, ask the CI triggerer to share details
• Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

[JadoTu]

/bot run

[tensorrt-cicd]

PR_Github #51254 [ run ] triggered by Bot. Commit: b23cffd Link to invocation

[JadoTu]

/bot run

[tensorrt-cicd]

PR_Github #51259 [ run ] triggered by Bot. Commit: b23cffd Link to invocation

[tensorrt-cicd]

PR_Github #51254 [ run ] completed with state ABORTED. Commit: b23cffd

Link to invocation

[tensorrt-cicd]

PR_Github #51259 [ run ] completed with state SUCCESS. Commit: b23cffd
/LLM/main/L0_MergeRequest_PR pipeline #40680 completed with status: 'SUCCESS'
Pipeline passed with automatic retried tests. Check the rerun report for details.

CI Report

Link to invocation

[JadoTu]

Thanks for you review @Wanli-Jiang . I will collect all the changes and apply them in next follow-up PR. The new model will be released soon so that I don't want to push new commits and rerun the CI. In this way we can first have this functional flow on the new model. I will paste the new PR once I get all changes.

[HuiGao-NV]

LGTM

[JadoTu]

The follow-up PR is: #14862