Skip to content

[TRTLLM-12352][feat] add post-transform capability profiles - #16238

Merged
chienchunhung merged 2 commits into
NVIDIA:mainfrom
chienchunhung:codex/mx-capability-registry-harness
Jul 15, 2026
Merged

[TRTLLM-12352][feat] add post-transform capability profiles#16238
chienchunhung merged 2 commits into
NVIDIA:mainfrom
chienchunhung:codex/mx-capability-registry-harness

Conversation

@chienchunhung

@chienchunhung chienchunhung commented Jul 10, 2026

Copy link
Copy Markdown
Collaborator

Description

Replace the MX staged-receiver isinstance allowlist with an immutable, backend-neutral post-transform capability registry.

The registry matches an exact qualified profile across:

  • root model class
  • Hugging Face architecture and model_type
  • speculative decoding mode
  • transfer protocol and component scope
  • explicitly supported lifecycle features

The same decision now gates MX reception before P2P, validates the staged path after preload, and gates post-transform source publication. Unqualified models fall back to disk and are not republished.

For qualified post-transform sources, the receiver now establishes structural aliases after source metadata is validated and before exact-name P2P matching begins. This mirrors the producer's post-load module graph without running tensor transforms; runtime finalization repeats the idempotent alias step and refreshes derived state.

This PR retains exactly one profile: target-only LlamaForCausalLM using transform protocol v1. It does not enable another model family or add the separate transform-layout ABI follow-up.

A reusable unit qualification harness now:

  • simulates exact-name transfer of fully transformed parameters
  • rejects name, shape, dtype, layout, stride, or storage-offset differences
  • compares exact parameter and registered-buffer values after staged finalization
  • verifies transform_weights() is never invoked on the receiver
  • compares transform guards and family-specific alias/derived-state probes

Design context: https://github.com/chienchunhung/TensorRT-LLM/blob/docs-and-plans/docs/design/mx-gms-integration/21-mx-readiness-gaps-and-model-family-plan.md

Test Plan

  • Changed-file pre-commit suite
  • Python syntax compilation for all changed Python files
  • Standalone registry smoke tests for exact profile selection, subclass rejection, and speculative-mode selection
  • Iterative trtllm-review self-review; all findings addressed and final pass found no new issues
  • Initial full CI isolated an exact-name alias-ordering failure in the new tiny-Llama lifecycle test; fixed in 598967b4c9
  • Linux CI focused lifecycle coverage passed on B200 package sanity, A10, A100X, DGX H100, and B300
  • Full CI rerun on 598967b4c9 succeeded (PR_Github #58686, merge pipeline #47272): x86 50,406 passed / 15,839 skipped / 0 failed; SBSA 54 passed / 3 skipped / 0 failed

Local pytest collection is unavailable in the macOS control environment because it does not have torch, transformers, or the built TRT-LLM runtime. The completed Linux full-CI gate is the authoritative executable verification.

Summary by CodeRabbit

  • New Features

    • Added profile-based qualification for staged post-transform weight loading.
    • Improved support for speculative decoding and draft-model weight scenarios.
    • Added receiver preparation during eligible staged loading to ensure correct weight sharing.
    • Exposed post-transform qualification types for broader integration.
  • Bug Fixes

    • Improved fallback behavior for unsupported or unqualified configurations.
    • Prevented post-load publishing when staged loading is not eligible.

Signed-off-by: Chien-Chun Hung <2679986+chienchunhung@users.noreply.github.com>

Copy link
Copy Markdown
Collaborator Author

/bot run

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #58672 [ run ] triggered by Bot. Commit: 9a7e8ef Link to invocation

Signed-off-by: Chien-Chun Hung <2679986+chienchunhung@users.noreply.github.com>

Copy link
Copy Markdown
Collaborator Author

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #58686 [ run ] triggered by Bot. Commit: 598967b Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #58672 [ run ] completed with state ABORTED. Commit: 9a7e8ef
/LLM/main/L0_MergeRequest_PR pipeline #47258 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

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #58686 [ run ] completed with state SUCCESS. Commit: 598967b
/LLM/main/L0_MergeRequest_PR pipeline #47272 completed with status: 'SUCCESS'

CI Report

Link to invocation

@chienchunhung
chienchunhung marked this pull request as ready for review July 10, 2026 23:24
@chienchunhung
chienchunhung requested review from a team as code owners July 10, 2026 23:24
@coderabbitai

coderabbitai Bot commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

Changes

MX post-transform loading now uses a validated profile registry instead of a static allowlist. ModelLoader passes qualification context through staged loading and publishing, while MXCheckpointLoader prepares receivers before P2P writes. Tests cover profile matching, fallback behavior, callback ordering, and lifecycle equivalence.

MX post-transform loading

Layer / File(s) Summary
Post-transform profile contracts
tensorrt_llm/_torch/weight_sharing/post_transform_profiles.py, tensorrt_llm/_torch/weight_sharing/__init__.py
Defines profile dimensions, qualification reasons, feature support, registry validation, exact matching, and public exports.
ModelLoader qualification flow
tensorrt_llm/_torch/pyexecutor/model_loader.py
Replaces the MX allowlist with profile qualification and threads speculative-mode and draft-loading state through staged loading and publishing.
MX receiver preparation hook
tensorrt_llm/_torch/models/checkpoints/mx/checkpoint_loader.py
Adds prepare_post_transform_receiver, invoking it after qualification and before direct P2P writes.
Qualification and lifecycle validation
tests/unittest/_torch/weight_sharing/test_post_transform_profiles.py, tests/unittest/utils/post_transform_qualification.py
Tests exact matching, feature handling, registry validation, and producer/receiver lifecycle equivalence.
MX loading integration tests
tests/unittest/_torch/executor/test_model_loader_*.py, tests/unittest/_torch/models/checkpoints/mx/test_mx_checkpoint_loader.py
Covers qualified staging, callback ordering, fallback behavior, and post-load publishing decisions.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ModelLoader
  participant PostTransformProfileRegistry
  participant MXCheckpointLoader
  participant ReceiverModel
  participant MXP2PTransfer
  ModelLoader->>PostTransformProfileRegistry: qualify model and enabled features
  PostTransformProfileRegistry-->>ModelLoader: return qualification decision
  ModelLoader->>MXCheckpointLoader: load weights with staging options
  MXCheckpointLoader->>ReceiverModel: prepare receiver aliases and state
  MXCheckpointLoader->>MXP2PTransfer: write staged weights
Loading

Possibly related PRs

Suggested reviewers: yuxianq, pcastonguay, xxi-nv, QiJune, brb-nv, litaotju

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 4.65% 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 It follows the required ticket/type format and accurately summarizes the main change.
Description check ✅ Passed It clearly explains the feature and includes testing details, though the PR Checklist section is missing.
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.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 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 `@tests/unittest/_torch/executor/test_model_loader_gms.py`:
- Around line 152-155: Annotate the `_load_weights` static test double with
explicit parameter and return types, including the variadic arguments and
callback-related keyword arguments, while preserving its current behavior of
invoking `prepare_post_transform_receiver` and returning an empty dictionary.

In `@tests/unittest/_torch/executor/test_model_loader_mx.py`:
- Around line 295-305: The new and modified test helpers and test functions lack
required type annotations. Add parameter and return annotations to the callback
methods and every affected function, including
_UnsafePostTransformMxLoader._load_weights and the helpers at the referenced
locations, using appropriate types for their arguments and return values.

In `@tests/unittest/_torch/models/checkpoints/mx/test_mx_checkpoint_loader.py`:
- Line 305: Add -> None return annotations to all newly added test methods,
including test_post_transform_full_success_prepares_receiver_before_p2p and the
other tests identified in the review, following the existing test annotation
style.
🪄 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: a1bdd143-8089-4b74-999f-b53ba97fa48d

📥 Commits

Reviewing files that changed from the base of the PR and between b9838f5 and 598967b.

📒 Files selected for processing (9)
  • tensorrt_llm/_torch/models/checkpoints/mx/checkpoint_loader.py
  • tensorrt_llm/_torch/pyexecutor/model_loader.py
  • tensorrt_llm/_torch/weight_sharing/__init__.py
  • tensorrt_llm/_torch/weight_sharing/post_transform_profiles.py
  • tests/unittest/_torch/executor/test_model_loader_gms.py
  • tests/unittest/_torch/executor/test_model_loader_mx.py
  • tests/unittest/_torch/models/checkpoints/mx/test_mx_checkpoint_loader.py
  • tests/unittest/_torch/weight_sharing/test_post_transform_profiles.py
  • tests/unittest/utils/post_transform_qualification.py

Comment thread tests/unittest/_torch/executor/test_model_loader_gms.py
Comment thread tests/unittest/_torch/executor/test_model_loader_mx.py
@litaotju
litaotju requested a review from kaiyux July 14, 2026 05:53
Comment thread tensorrt_llm/_torch/pyexecutor/model_loader.py
@mikeiovine
mikeiovine requested a review from cascade812 July 14, 2026 19:40
@chienchunhung
chienchunhung requested a review from kaiyux July 14, 2026 19:59
Comment thread tensorrt_llm/_torch/weight_sharing/post_transform_profiles.py
@chienchunhung

Copy link
Copy Markdown
Collaborator Author

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59305 [ run ] triggered by Bot. Commit: 598967b Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59305 [ run ] completed with state SUCCESS. Commit: 598967b
/LLM/main/L0_MergeRequest_PR pipeline #47789 completed with status: 'SUCCESS'

CI Report

Link to invocation

@kaiyux kaiyux left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving on behalf of model devs.

@kaiyux
kaiyux requested a review from a team July 15, 2026 01:21
@kaiyux
kaiyux requested review from BowenFu and brnguyen2 July 15, 2026 01:21
@chienchunhung
chienchunhung enabled auto-merge (squash) July 15, 2026 05:34
@brnguyen2

Copy link
Copy Markdown
Collaborator

Nitpick: the description explains the mechanism being replaced but not why it needed replacing. A reader coming cold doesn't know that isinstance silently passes for unqualified subclasses, or that missing receiver alias setup caused exact-name P2P mismatches. Neither commit message has a body either. A few sentences on each failure mode would make this reviewable without the design doc.

@brnguyen2

Copy link
Copy Markdown
Collaborator

Nitpick: the linked JIRA ticket doesn't seem to match this change. Worth linking a more accurate one.

Comment thread tests/unittest/_torch/executor/test_model_loader_mx.py
Comment thread tensorrt_llm/_torch/pyexecutor/model_loader.py
@chienchunhung
chienchunhung merged commit a1302a5 into NVIDIA:main Jul 15, 2026
20 of 22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants