[TRTLLM-9660][feat] Convert cuteDSL GEMM to opt-in feature

[longlee0622]

Summary by CodeRabbit

• New Features

  • Added NVFP4 GEMM backend configuration to model settings for more granular control over available optimization backends.

• Refactor

  • Updated NVFP4 backend specification to use a list of allowed backends instead of a single backend parameter, enabling flexible backend selection and fallback strategies.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Description

Test Coverage

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)

• 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

/bot [-h] ['run', 'kill', 'skip', 'reuse-pipeline'] ...

Provide a user friendly way for developers to interact with a Jenkins server.

Run /bot [-h|--help] to print this help message.

See details below for each supported subcommand.

run [--reuse-test (optional)pipeline-id --disable-fail-fast --skip-test --stage-list "A10-PyTorch-1, xxx" --gpu-type "A30, H100_PCIe" --test-backend "pytorch, cpp" --add-multi-gpu-test --only-multi-gpu-test --disable-multi-gpu-test --post-merge --extra-stage "H100_PCIe-TensorRT-Post-Merge-1, xxx" --detailed-log --debug(experimental)]

Launch build/test pipelines. All previously running jobs will be killed.

--reuse-test (optional)pipeline-id (OPTIONAL) : Allow the new pipeline to reuse build artifacts and skip successful test stages from a specified pipeline or the last pipeline if no pipeline-id is indicated. If the Git commit ID has changed, this option will be always ignored. The DEFAULT behavior of the bot is to reuse build artifacts and successful test results from the last pipeline.

--disable-reuse-test (OPTIONAL) : Explicitly prevent the pipeline from reusing build artifacts and skipping successful test stages from a previous pipeline. Ensure that all builds and tests are run regardless of previous successes.

--disable-fail-fast (OPTIONAL) : Disable fail fast on build/tests/infra failures.

--skip-test (OPTIONAL) : Skip all test stages, but still run build stages, package stages and sanity check stages. Note: Does NOT update GitHub check status.

--stage-list "A10-PyTorch-1, xxx" (OPTIONAL) : Only run the specified test stages. Examples: "A10-PyTorch-1, xxx". Note: Does NOT update GitHub check status.

--gpu-type "A30, H100_PCIe" (OPTIONAL) : Only run the test stages on the specified GPU types. Examples: "A30, H100_PCIe". Note: Does NOT update GitHub check status.

--test-backend "pytorch, cpp" (OPTIONAL) : Skip test stages which don't match the specified backends. Only support [pytorch, cpp, tensorrt, triton]. Examples: "pytorch, cpp" (does not run test stages with tensorrt or triton backend). Note: Does NOT update GitHub pipeline status.

--only-multi-gpu-test (OPTIONAL) : Only run the multi-GPU tests. Note: Does NOT update GitHub check status.

--disable-multi-gpu-test (OPTIONAL) : Disable the multi-GPU tests. Note: Does NOT update GitHub check status.

--add-multi-gpu-test (OPTIONAL) : Force run the multi-GPU tests in addition to running L0 pre-merge pipeline.

--post-merge (OPTIONAL) : Run the L0 post-merge pipeline instead of the ordinary L0 pre-merge pipeline.

--extra-stage "H100_PCIe-TensorRT-Post-Merge-1, xxx" (OPTIONAL) : Run the ordinary L0 pre-merge pipeline and specified test stages. Examples: --extra-stage "H100_PCIe-TensorRT-Post-Merge-1, xxx".

--detailed-log (OPTIONAL) : Enable flushing out all logs to the Jenkins console. This will significantly increase the log volume and may slow down the job.

--debug (OPTIONAL) : Experimental feature. Enable access to the CI container for debugging purpose. Note: Specify exactly one stage in the stage-list parameter to access the appropriate container environment. Note: Does NOT update GitHub check status.

For guidance on mapping tests to stage names, see docs/source/reference/ci-overview.md
and the scripts/test_to_stage_mapping.py helper.

kill

kill

Kill all running builds associated with pull request.

skip

skip --comment COMMENT

Skip testing for latest commit on pull request. --comment "Reason for skipping build/test" is required. IMPORTANT NOTE: This is dangerous since lack of user care and validation can cause top of tree to break.

reuse-pipeline

reuse-pipeline

Reuse a previous pipeline to validate current commit. This action will also kill all currently running builds associated with the pull request. IMPORTANT NOTE: This is dangerous since lack of user care and validation can cause top of tree to break.

[coderabbitai]

📝 Walkthrough

Walkthrough

Replaces single-string backend parameters with an explicit allowed-backends list/string across NVFP4 GEMM surfaces. Public APIs, runner internals, model config, argument parsing, and tests now accept and validate comma-separated or list-style allowed_backends (new token cuda_core added); selection/validation logic updated to operate on the allowed set instead of a single backend token.

Changes

Cohort / File(s)	Change Summary
Patterns tensorrt_llm/_torch/compilation/patterns/ar_residual_norm.py	Pattern function signatures updated: backend: str → allowed_backends: str. Validation logic replaced to parse and validate comma-separated allowed_backends tokens (includes cuda_core).
Custom ops / Runner tensorrt_llm/_torch/custom_ops/torch_custom_ops.py	NVFP4GemmUnifiedRunner ctor changed to accept allowed_backends: List[str] and internal state now stores allowed_backends. Cache key (unique_id) updated to include allowed_backends tuple. Helpers _is_backend_allowed / _is_only_backend added. get_valid_tactics() and forward path refactored to compute tactics from allowed_backends; CuteDSL gating moved behind allowed_backends checks. Public nvfp4_gemm API signature changed: allowed_backends: str = "cutlass,cublaslt,cuda_core". Parsing/validation of allowed_backends implemented and errors raised for invalid/empty lists. Fake registrations/implementations updated accordingly.
Linear module tensorrt_llm/_torch/modules/linear.py	Linear constructor and public API changed: nvfp4_backend: str → nvfp4_allowed_backends: Optional[List[str]]. Uses get_model_extra_attrs to derive per-model defaults; NVFP4LinearMethod.apply now builds a comma-separated allowed_backends string from module.nvfp4_allowed_backends when invoking GEMM ops.
Model config tensorrt_llm/_torch/model_config.py	Added nvfp4_gemm_allowed_backends: List[str] to ModelConfig with default_factory ['cutlass','cublaslt','cuda_core'] and explanatory comments.
Executor / Loader tensorrt_llm/_torch/pyexecutor/model_loader.py	Config loading extended to accept nvfp4_gemm_allowed_backends from llm args and store it under config.extra_attrs['nvfp4_gemm_allowed_backends'].
LLM args / API tensorrt_llm/llmapi/llm_args.py	Added Nvfp4GemmConfig StrictBaseModel with allowed_backends: List[str] and validator (allowed tokens {cutlass,cublaslt,cutedsl,cuda_core}, non-empty). Added nvfp4_gemm_config: Nvfp4GemmConfig to TorchLlmArgs and wired deserialization in update helpers.
Tests tests/unittest/_torch/thop/parallel/test_fp4_linear.py	Updated tests to replace nvfp4_backend usage with nvfp4_allowed_backends; nvfp4_gemm calls updated to use allowed_backends (comma-separated or single token) and assertions/messages aligned to new terminology.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Areas needing extra attention:
  • NVFP4GemmUnifiedRunner.unique_id() — ensure allowed_backends tuple ordering and representation prevent cache collisions.
  • get_valid_tactics() and tactic-resolution — verify correctness when multiple allowed_backends provided, and correct error paths when a single explicitly-forced backend is unavailable.
  • Public nvfp4_gemm parsing/validation — ensure consistent handling of comma-separated string vs list, and clear error messages for invalid/empty inputs.
  • Linear/module propagation — confirm model-derived defaults via config.extra_attrs integrate in all codepaths.
  • Tests — confirm test updates reflect real-world allowed_backends permutations and maintain coverage for CuteDSL gating and cuda_core inclusion.

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.
Description check	⚠️ Warning	The pull request description is incomplete. It contains only the template boilerplate with empty/unfilled required sections (Description, Test Coverage) and does not provide specific implementation details beyond the title.	Fill in the Description section with details about why cuteDSL GEMM is being converted to opt-in and explain the solution. Add Test Coverage section listing relevant tests. Complete the PR checklist sections appropriately.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: converting cuteDSL GEMM to an opt-in feature, which is supported by the raw summary showing changes to backend handling and the introduction of 'auto_no_cutedsl' option.

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4485e51 and 0ddefcf.

📒 Files selected for processing (7)

• tensorrt_llm/_torch/compilation/patterns/ar_residual_norm.py (4 hunks)
• tensorrt_llm/_torch/custom_ops/torch_custom_ops.py (9 hunks)
• tensorrt_llm/_torch/model_config.py (1 hunks)
• tensorrt_llm/_torch/modules/linear.py (4 hunks)
• tensorrt_llm/_torch/pyexecutor/model_loader.py (1 hunks)
• tensorrt_llm/llmapi/llm_args.py (3 hunks)
• tests/unittest/_torch/thop/parallel/test_fp4_linear.py (9 hunks)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4485e51 and 5ba48ff.

📒 Files selected for processing (3)

• tensorrt_llm/_torch/compilation/patterns/ar_residual_norm.py (1 hunks)
• tensorrt_llm/_torch/custom_ops/torch_custom_ops.py (6 hunks)
• tensorrt_llm/_torch/modules/linear.py (2 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

**/*.py

📄 CodeRabbit inference engine (CODING_GUIDELINES.md)

**/*.py: The code developed for TensorRT-LLM should conform to Python 3.8+
Indent Python code with 4 spaces; do not use tabs
Always maintain the namespace when importing in Python, even if only one class or function from a module is used (e.g., use from package.subpackage import foo and then foo.SomeClass() instead of from package.subpackage.foo import SomeClass)
Python filenames should use snake_case (e.g., some_file.py)
Python class names should use PascalCase (e.g., class SomeClass)
Python function and method names should use snake_case (e.g., def my_awesome_function():)
Python local variable names should use snake_case, with prefix k for variable names that start with a number (e.g., k_99th_percentile = ...)
Python global variables should use upper snake_case with prefix G (e.g., G_MY_GLOBAL = ...)
Python constants should use upper snake_case (e.g., MY_CONSTANT = ...)
Avoid shadowing variables declared in an outer scope in Python
Initialize all externally visible members of a Python class in the constructor
For Python interfaces that may be used outside a file, prefer docstrings over comments
Python comments should be reserved for code within a function, or interfaces that are local to a file
Use Google style docstrings for Python classes and functions, which can be parsed by Sphinx
Python attributes and variables can be documented inline with type and description (e.g., self.x = 5 followed by """<type>: Description of 'x'""" )
Avoid using reflection in Python when functionality can be easily achieved without reflection
When using try-except blocks in Python, limit the except clause to the smallest set of specific errors possible instead of catching all exceptions
When using try-except blocks in Python to handle multiple possible variable types (duck-typing), keep the body of the try as small as possible and use the else block to implement the logic

Files:

• tensorrt_llm/_torch/compilation/patterns/ar_residual_norm.py
• tensorrt_llm/_torch/modules/linear.py
• tensorrt_llm/_torch/custom_ops/torch_custom_ops.py

**/*.{cpp,h,cu,py}

📄 CodeRabbit inference engine (CODING_GUIDELINES.md)

All TensorRT-LLM Open Source Software code files should contain an NVIDIA copyright header that includes the current year at the top

Files:

• tensorrt_llm/_torch/compilation/patterns/ar_residual_norm.py
• tensorrt_llm/_torch/modules/linear.py
• tensorrt_llm/_torch/custom_ops/torch_custom_ops.py

🧠 Learnings (5)

📚 Learning: 2025-11-14T11:22:03.729Z

Learnt from: nzmora-nvidia
Repo: NVIDIA/TensorRT-LLM PR: 9163
File: tensorrt_llm/_torch/auto_deploy/custom_ops/quant.py:107-113
Timestamp: 2025-11-14T11:22:03.729Z
Learning: In TensorRT-LLM AutoDeploy custom ops, when adding hardware capability checks to select between kernel implementations (e.g., cuBLAS vs. CUDA kernel), use descriptive variable names that identify the specific GPU architectures or families being targeted (e.g., `is_blackwell_geforce_or_ada`) rather than generic names like `enable_cuda_core`. This makes it clear that the code is selecting an implementation path based on hardware capabilities, not enabling/disabling hardware features.

Applied to files:

• tensorrt_llm/_torch/compilation/patterns/ar_residual_norm.py
• tensorrt_llm/_torch/custom_ops/torch_custom_ops.py

📚 Learning: 2025-10-20T16:54:09.824Z

Learnt from: nvchenghaoz
Repo: NVIDIA/TensorRT-LLM PR: 8469
File: tensorrt_llm/_torch/auto_deploy/custom_ops/rms_norm.py:6-6
Timestamp: 2025-10-20T16:54:09.824Z
Learning: In tensorrt_llm/_torch/auto_deploy/custom_ops/rms_norm.py, the import `from ...modules.mamba.layernorm_gated import _layer_norm_fwd` is correct and should not be changed to modules.fla.layernorm_gated. The _layer_norm_fwd function exists in both modules/mamba/layernorm_gated.py and modules/fla/layernorm_gated.py, but the mamba version is the intended implementation for this use case.

Applied to files:

• tensorrt_llm/_torch/compilation/patterns/ar_residual_norm.py

📚 Learning: 2025-10-20T17:09:21.560Z

Learnt from: nvchenghaoz
Repo: NVIDIA/TensorRT-LLM PR: 8469
File: tensorrt_llm/_torch/auto_deploy/transform/library/rms_norm.py:180-182
Timestamp: 2025-10-20T17:09:21.560Z
Learning: In tensorrt_llm/_torch/auto_deploy/transform/library/rms_norm.py, the _gated_rmsnorm_replacement function does not need to cast the output of torch.ops.auto_deploy.torch_rmsnorm_gated back to the input dtype, even though the custom op returns fp32. The dtype handling is managed elsewhere or the fp32 output is acceptable for downstream consumers.

Applied to files:

• tensorrt_llm/_torch/compilation/patterns/ar_residual_norm.py

📚 Learning: 2025-08-21T21:48:35.135Z

Learnt from: djns99
Repo: NVIDIA/TensorRT-LLM PR: 7104
File: cpp/tensorrt_llm/cutlass_extensions/include/cutlass_extensions/epilogue/fusion/sm90_visitor_scatter.hpp:399-417
Timestamp: 2025-08-21T21:48:35.135Z
Learning: CUTLASS extensions in TensorRT-LLM (located under cpp/tensorrt_llm/cutlass_extensions/) are designed to integrate with and extend functionality in the external CUTLASS repository. When analyzing these extensions, their consumers and functionality wiring may exist in the CUTLASS codebase rather than within TensorRT-LLM itself.

Applied to files:

• tensorrt_llm/_torch/custom_ops/torch_custom_ops.py

📚 Learning: 2025-08-22T01:54:35.850Z

Learnt from: djns99
Repo: NVIDIA/TensorRT-LLM PR: 7104
File: cpp/tensorrt_llm/kernels/cutlass_kernels/include/moe_kernels.h:999-1000
Timestamp: 2025-08-22T01:54:35.850Z
Learning: The `internal_cutlass_kernels` directory in TensorRT-LLM is a mirror of an internal NVIDIA repository and maintains its own implementation and API that may diverge from the public `cutlass_kernels` version. API inconsistencies between these two directories are intentional and by design, not bugs to be fixed.

Applied to files:

• tensorrt_llm/_torch/custom_ops/torch_custom_ops.py

🧬 Code graph analysis (1)

tensorrt_llm/_torch/custom_ops/torch_custom_ops.py (3)

tensorrt_llm/_torch/custom_ops/cute_dsl_custom_ops.py (5)

• unique_id (253-254)
• unique_id (668-677)
• unique_id (955-964)
• unique_id (1283-1291)
• unique_id (1586-1594)

tensorrt_llm/_torch/autotuner.py (1)

• unique_id (215-224)

tensorrt_llm/_torch/custom_ops/trtllm_gen_custom_ops.py (6)

• unique_id (196-197)
• unique_id (550-551)
• unique_id (824-832)
• unique_id (1112-1120)
• unique_id (1380-1388)
• unique_id (1635-1641)

🪛 Ruff (0.14.7)

tensorrt_llm/_torch/custom_ops/torch_custom_ops.py

932-933: Avoid specifying long messages outside the exception class

(TRY003)

---

983-983: Unused function argument: backend

(ARG001)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Pre-commit Check

🔇 Additional comments (8)

tensorrt_llm/_torch/compilation/patterns/ar_residual_norm.py (1)

616-619: LGTM: Valid backends updated for pattern matching.

The addition of 'auto_no_cutedsl' to the valid backends set is consistent with the broader PR changes introducing this new backend option. This ensures the NVFP4 GEMM prologue pattern matcher correctly validates the new backend value.

tensorrt_llm/_torch/custom_ops/torch_custom_ops.py (6)

698-712: LGTM: Runner correctly parameterized for CuteDSL exclusion.

The exclude_cutedsl parameter is properly added to the constructor and stored on the instance. The unique_id method correctly includes both backend and exclude_cutedsl in the cache key, ensuring different backend configurations don't share cached tactics.

---

758-760: LGTM: CuteDSL exclusion logic is correct.

The condition if backend in ["auto", "cutedsl"] and not self.exclude_cutedsl: correctly implements the exclusion logic. Since exclude_cutedsl is only set to True when backend == "auto_no_cutedsl" (which gets normalized to "auto"), explicit "cutedsl" requests will still work as expected.

---

889-889: Default backend changed to "auto_no_cutedsl" - this is the main API change.

This change shifts the default from including CuteDSL in auto-selection to excluding it, prioritizing faster build times over potential extreme performance gains. Users who want CuteDSL can explicitly opt-in with backend="auto" or backend="cutedsl".

---

928-943: LGTM: Backend normalization logic is clean and correct.

The approach of normalizing "auto_no_cutedsl" to "auto" internally while setting exclude_cutedsl=True is a clean implementation that avoids duplicating logic in get_valid_tactics. The runner receives the effective backend and exclusion flag to make appropriate decisions.

---

974-987: Fake registration correctly mirrors the updated signature.

The backend parameter is intentionally unused in the fake implementation (flagged by static analysis as ARG001) because the fake only needs to compute the output tensor shape, not actually dispatch to a backend. The signature must match the real function for torch.compile compatibility.

---

912-918: Good documentation of the new backend options.

The docstring clearly explains the difference between 'auto_no_cutedsl' (default, faster build) and 'auto' (includes cutedsl, extreme performance). This helps users understand the tradeoff.

tensorrt_llm/_torch/modules/linear.py (1)

2057-2068: LGTM: Linear module constructor updated consistently.

The default nvfp4_backend parameter is changed to "auto_no_cutedsl" to match the underlying nvfp4_gemm function. The docstring clearly documents all supported values and the tradeoff between build time and performance.

[longlee0622]

/bot run

[tensorrt-cicd]

PR_Github #26836 [ run ] triggered by Bot. Commit: 5ba48ff

[tensorrt-cicd]

PR_Github #26836 [ run ] completed with state FAILURE. Commit: 5ba48ff
/LLM/main/L0_MergeRequest_PR pipeline #20441 completed with status: 'FAILURE'

[longlee0622]

/bot run

[tensorrt-cicd]

PR_Github #26838 [ run ] triggered by Bot. Commit: 5ba48ff

[tensorrt-cicd]

PR_Github #26838 [ run ] completed with state SUCCESS. Commit: 5ba48ff
/LLM/main/L0_MergeRequest_PR pipeline #20444 completed with status: 'FAILURE'

[longlee0622]

/bot run

[longlee0622]

@coderabbitai summary

[coderabbitai]

✅ Actions performed

Summary regeneration triggered.

[longlee0622]

/bot run

[tensorrt-cicd]

PR_Github #26921 [ run ] triggered by Bot. Commit: c8f5f75

[tensorrt-cicd]

PR_Github #26921 [ run ] completed with state FAILURE. Commit: c8f5f75
/LLM/main/L0_MergeRequest_PR pipeline #20513 completed with status: 'FAILURE'

[longlee0622]

/bot run

[tensorrt-cicd]

PR_Github #26946 [ run ] triggered by Bot. Commit: c8f5f75

[tensorrt-cicd]

PR_Github #26946 [ run ] completed with state SUCCESS. Commit: c8f5f75
/LLM/main/L0_MergeRequest_PR pipeline #20533 completed with status: 'FAILURE'

[longlee0622]

/bot run

[tensorrt-cicd]

PR_Github #26972 [ run ] triggered by Bot. Commit: c8f5f75

[longlee0622]

/bot run

[tensorrt-cicd]

PR_Github #27030 [ run ] triggered by Bot. Commit: 6267aca

[tensorrt-cicd]

PR_Github #27030 [ run ] completed with state SUCCESS. Commit: 6267aca
/LLM/main/L0_MergeRequest_PR pipeline #20612 completed with status: 'FAILURE'

[longlee0622]

/bot run --disable-fail-fast

[tensorrt-cicd]

PR_Github #27048 [ run ] triggered by Bot. Commit: 6267aca

[tensorrt-cicd]

PR_Github #27048 [ run ] completed with state SUCCESS. Commit: 6267aca
/LLM/main/L0_MergeRequest_PR pipeline #20627 completed with status: 'FAILURE'

[longlee0622]

/bot run

[tensorrt-cicd]

PR_Github #27078 [ run ] triggered by Bot. Commit: 2155c3c

[tensorrt-cicd]

PR_Github #27078 [ run ] completed with state SUCCESS. Commit: 2155c3c
/LLM/main/L0_MergeRequest_PR pipeline #20653 completed with status: 'FAILURE'

[longlee0622]

/bot run

[tensorrt-cicd]

PR_Github #27101 [ run ] triggered by Bot. Commit: 2155c3c

[tensorrt-cicd]

PR_Github #27101 [ run ] completed with state SUCCESS. Commit: 2155c3c
/LLM/main/L0_MergeRequest_PR pipeline #20674 completed with status: 'FAILURE'

[longlee0622]

/bot run --disable-fail-fast

[tensorrt-cicd]

PR_Github #27173 [ run ] triggered by Bot. Commit: 2155c3c

[tensorrt-cicd]

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