Skip to content

[TRTLLM-12339][feat] add dual KV cache resource management - #15400

Closed
cascade812 wants to merge 1 commit into
NVIDIA:mainfrom
cascade812:codex/split-dual-kv-cache
Closed

[TRTLLM-12339][feat] add dual KV cache resource management#15400
cascade812 wants to merge 1 commit into
NVIDIA:mainfrom
cascade812:codex/split-dual-kv-cache

Conversation

@cascade812

@cascade812 cascade812 commented Jun 16, 2026

Copy link
Copy Markdown
Collaborator

Description

Split out the dual KV-cache resource-management slice from #13919.

This PR adds the PyTorch executor resource plumbing needed to maintain a separate cross-attention KV cache pool for encoder-decoder models:

  • add ResourceManagerType.CROSS_KV_CACHE_MANAGER
  • split encoder-decoder self/cross KV budgets without mutating the base config
  • create/register/teardown the cross KV cache manager
  • size the cross pool using decoder-layer count and encoder-side KV geometry
  • handle cross-pool prepare/update behavior separately from the self-attention pool
  • update target/draft budget splitting to return explicit cloned configs
  • add focused unit coverage for dual-pool resource wiring and budget splits

This intentionally leaves model enablement, encoder execution, BART/T5 integration, and beam-width cross-KV block-offset expansion for follow-up split PRs.

Test Coverage

  • PYTHONPYCACHEPREFIX=/private/tmp/trtllm_pycache python3 -m py_compile tensorrt_llm/_torch/pyexecutor/_util.py tensorrt_llm/_torch/pyexecutor/resource_manager.py tests/unittest/_torch/executor/test_kv_cache_budget_split.py tests/unittest/_torch/executor/test_dual_pool_kv_cache.py
  • git diff --cached --check

Not run locally: pytest tests/unittest/_torch/executor/test_kv_cache_budget_split.py tests/unittest/_torch/executor/test_dual_pool_kv_cache.py because this local system Python does not have pytest installed.

PR Checklist

  • PR description clearly explains what and why.
  • PR follows TRT-LLM coding guidelines to the best of my knowledge.
  • Test cases are provided for new code paths.
  • No new dependencies are added.

Summary by CodeRabbit

  • New Features

    • Added support for encoder-decoder models with dual KV cache pools (self and cross attention).
    • Improved KV cache budget splitting for speculative decoding scenarios.
  • Refactor

    • Enhanced KV cache sizing, budgeting, and manager construction for flexible resource allocation.
  • Tests

    • Expanded test coverage for dual-pool KV cache configuration and budget splitting.

@cascade812
cascade812 requested review from a team as code owners June 16, 2026 06:16
@cascade812
cascade812 requested a review from joyang-nv June 16, 2026 06:16
@cascade812
cascade812 marked this pull request as draft June 16, 2026 06:16
@cascade812

Copy link
Copy Markdown
Collaborator Author

/bot run

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54497 [ run ] triggered by Bot. Commit: 130e0fd Link to invocation

@coderabbitai

coderabbitai Bot commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

This PR adds a dedicated cross KV cache pool for encoder-decoder models. It introduces CROSS_KV_CACHE_MANAGER as a new resource type, extends KvCacheCreator to propagate per-manager kv_cache_config overrides through cost computation and manager class selection, redesigns _split_kv_cache_budget_for_draft to return an immutable (target, draft) tuple, adds cross-pool budget splitting helpers, extends _create_kv_cache_manager with geometry overrides, reworks build_managers to register and teardown the cross pool, and wires cross-pool ordering and no_schedule_until_state gating into all scheduler paths.

Changes

Dual-pool (self + cross) KV cache for encoder-decoder models

Layer / File(s) Summary
CROSS_KV_CACHE_MANAGER enum and prepare/update_resources refactor
tensorrt_llm/_torch/pyexecutor/resource_manager.py
Adds CROSS_KV_CACHE_MANAGER to ResourceManagerType; refactors prepare_resources to route cross KV through _prepare_cross_resources (encoder alloc, beam_width=1) and self-attention context through _collect_context_sequences; adds extra_rewind pass in update_resources to release reserved draft-token slack.
KvCacheCreator cost model and kv_cache_config override propagation
tensorrt_llm/_torch/pyexecutor/_util.py
Extends _get_model_kv_cache_manager_cls, _per_manager_cache_cost, _get_kv_size_per_token, _get_target_and_draft_cache_costs, and draft KV creation paths to accept and propagate an optional kv_cache_config override, including cross-encoder cost aggregation and V2 fallback evaluation against the effective config.
_split_kv_cache_budget_for_draft redesign and cross-pool budget helpers
tensorrt_llm/_torch/pyexecutor/_util.py
Redesigns _split_kv_cache_budget_for_draft to return an immutable (target_cfg, draft_cfg) tuple; adds ValueError on infeasible GPU budget; introduces cross-pool helpers for encoder KV geometry, per-token cross cost, and budget splitting across self/cross pools using cross_kv_cache_fraction for GPU, host, and free-memory-fraction budgets.
_create_kv_cache_manager extension and build_managers orchestration
tensorrt_llm/_torch/pyexecutor/_util.py
Extends _create_kv_cache_manager to accept num_kv_heads, head_dim, and kv_cache_type overrides (defaulting to CacheType.SELF); reworks build_managers to split self/cross budgets first, conditionally split draft budgets, pass per-manager config overrides, register CROSS_KV_CACHE_MANAGER, and extend teardown.
create_py_executor_instance cross-pool scheduler wiring
tensorrt_llm/_torch/pyexecutor/_util.py
Moves CROSS_KV_CACHE_MANAGER to the end of resource invocation order; gates encoder-decoder scheduling at ENCODER_INIT; forwards cross_kv_cache_manager and no_schedule_until_state into V2 interleaved, Python unified, and bind-capacity scheduler constructors.
Dual-pool unit tests and updated budget-split tests
tests/unittest/_torch/executor/test_dual_pool_kv_cache.py, tests/unittest/_torch/executor/test_kv_cache_budget_split.py
Adds test_dual_pool_kv_cache.py with seven test classes covering cross-budget splitting, encoder geometry usage, cross-pool registration for encoder-decoder models, and scheduler wiring for all paths; updates test_kv_cache_budget_split.py to use (target_config, draft_config) tuple destructuring and immutability assertions.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related PRs

  • NVIDIA/TensorRT-LLM#14373: Modifies the same KvCacheCreator draft KV budget-splitting logic in _util.py and shares the test_kv_cache_budget_split.py test file, which this PR updates for the new tuple return convention.

Suggested reviewers

  • lancelly
  • ziyixiong-nv
  • Tabrizian
  • niukuo
  • yizhang-nv
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 39.06% 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 identifies the main feature added: dual KV cache resource management, with proper ticket ID and type prefix.
Description check ✅ Passed The description covers the what, why, test coverage, and checklist items. It clearly explains dual KV cache resource management infrastructure, test validation performed, and deferred work.
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 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.

🧹 Nitpick comments (1)
tests/unittest/_torch/executor/test_dual_pool_kv_cache.py (1)

493-512: ⚡ Quick win

Assert cross-pool registration in resources for both non-estimation and estimation paths.

These tests currently prove the constructor call but not the actual resource-map wiring contract. Add an assertion that resources[ResourceManagerType.CROSS_KV_CACHE_MANAGER] is the created cross manager to catch silent registration regressions.

Suggested test tightening
-        creator._create_cross_kv_cache_manager = Mock(return_value=Mock())
+        cross_mgr = Mock()
+        creator._create_cross_kv_cache_manager = Mock(return_value=cross_mgr)

         resources = {}
         creator.build_managers(resources, estimating_kv_cache=False)

         creator._create_cross_kv_cache_manager.assert_called_once()
+        assert resources[ResourceManagerType.CROSS_KV_CACHE_MANAGER] is cross_mgr
-        creator._create_cross_kv_cache_manager = Mock(return_value=Mock())
+        cross_mgr = Mock()
+        creator._create_cross_kv_cache_manager = Mock(return_value=cross_mgr)

         resources = {}
         creator.build_managers(resources, estimating_kv_cache=True)

         creator._create_cross_kv_cache_manager.assert_called_once()
+        assert resources[ResourceManagerType.CROSS_KV_CACHE_MANAGER] is cross_mgr

As per coding guidelines, tests under tests/** should include actionable coverage checks and clearly verify wiring behavior.

Also applies to: 513-537

🤖 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 `@tests/unittest/_torch/executor/test_dual_pool_kv_cache.py` around lines 493 -
512, The test method test_build_managers_registers_cross_pool_for_enc_dec
currently verifies that _create_cross_kv_cache_manager is called, but does not
verify that the created manager is actually registered in the resources
dictionary with the correct key. After calling creator.build_managers(resources,
estimating_kv_cache=False), add an assertion that confirms
resources[ResourceManagerType.CROSS_KV_CACHE_MANAGER] is set to the mock manager
object that was returned by _create_cross_kv_cache_manager (capture the mock's
return value and compare it to the resources entry). This same verification
pattern needs to be applied to the sibling test at lines 513-537 as well.

Source: Coding guidelines

🤖 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.

Nitpick comments:
In `@tests/unittest/_torch/executor/test_dual_pool_kv_cache.py`:
- Around line 493-512: The test method
test_build_managers_registers_cross_pool_for_enc_dec currently verifies that
_create_cross_kv_cache_manager is called, but does not verify that the created
manager is actually registered in the resources dictionary with the correct key.
After calling creator.build_managers(resources, estimating_kv_cache=False), add
an assertion that confirms resources[ResourceManagerType.CROSS_KV_CACHE_MANAGER]
is set to the mock manager object that was returned by
_create_cross_kv_cache_manager (capture the mock's return value and compare it
to the resources entry). This same verification pattern needs to be applied to
the sibling test at lines 513-537 as well.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: c1f0ee35-e93a-4caf-8fef-2ea2105b0275

📥 Commits

Reviewing files that changed from the base of the PR and between 0ec3250 and 130e0fd.

📒 Files selected for processing (4)
  • tensorrt_llm/_torch/pyexecutor/_util.py
  • tensorrt_llm/_torch/pyexecutor/resource_manager.py
  • tests/unittest/_torch/executor/test_dual_pool_kv_cache.py
  • tests/unittest/_torch/executor/test_kv_cache_budget_split.py

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54497 [ run ] completed with state SUCCESS. Commit: 130e0fd
/LLM/main/L0_MergeRequest_PR pipeline #43559 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

Link to invocation

@cascade812

Copy link
Copy Markdown
Collaborator Author

/bot run

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54563 [ run ] triggered by Bot. Commit: 130e0fd Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54563 [ run ] completed with state SUCCESS. Commit: 130e0fd
/LLM/main/L0_MergeRequest_PR pipeline #43606 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

@cascade812

Copy link
Copy Markdown
Collaborator Author

/bot run

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54585 [ run ] triggered by Bot. Commit: 130e0fd Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54585 [ run ] completed with state SUCCESS. Commit: 130e0fd
/LLM/main/L0_MergeRequest_PR pipeline #43628 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

Link to invocation

@cascade812

Copy link
Copy Markdown
Collaborator Author

/bot run

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54598 [ run ] triggered by Bot. Commit: 130e0fd Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54598 [ run ] completed with state SUCCESS. Commit: 130e0fd
/LLM/main/L0_MergeRequest_PR pipeline #43637 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

Link to invocation

@cascade812

Copy link
Copy Markdown
Collaborator Author

/bot run

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54605 [ run ] triggered by Bot. Commit: 130e0fd Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54605 [ run ] completed with state SUCCESS. Commit: 130e0fd
/LLM/main/L0_MergeRequest_PR pipeline #43644 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

Link to invocation

@cascade812

Copy link
Copy Markdown
Collaborator Author

/bot run

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54612 [ run ] triggered by Bot. Commit: 130e0fd Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54612 [ run ] completed with state SUCCESS. Commit: 130e0fd
/LLM/main/L0_MergeRequest_PR pipeline #43651 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

Link to invocation

@cascade812

Copy link
Copy Markdown
Collaborator Author

/bot run

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54616 [ run ] triggered by Bot. Commit: 130e0fd Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54616 [ run ] completed with state SUCCESS. Commit: 130e0fd
/LLM/main/L0_MergeRequest_PR pipeline #43653 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

@cascade812

Copy link
Copy Markdown
Collaborator Author

/bot run

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54621 [ run ] triggered by Bot. Commit: 130e0fd Link to invocation

@cascade812
cascade812 force-pushed the codex/split-dual-kv-cache branch from 130e0fd to f875cb6 Compare June 16, 2026 16:42
@cascade812

Copy link
Copy Markdown
Collaborator Author

/bot run

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54632 [ run ] triggered by Bot. Commit: f875cb6 Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54621 [ run ] completed with state ABORTED. Commit: 130e0fd

Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54632 [ run ] completed with state FAILURE. Commit: f875cb6
/LLM/main/L0_MergeRequest_PR pipeline #43663 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

Link to invocation

Signed-off-by: Guiju Zhang <guijuz@nvidia.com>
@cascade812
cascade812 force-pushed the codex/split-dual-kv-cache branch from f875cb6 to c6a5239 Compare June 16, 2026 18:45
@cascade812

Copy link
Copy Markdown
Collaborator Author

/bot run

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54661 [ run ] triggered by Bot. Commit: c6a5239 Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #54661 [ run ] completed with state FAILURE. Commit: c6a5239
/LLM/main/L0_MergeRequest_PR pipeline #43693 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

Link to invocation

@cascade812

Copy link
Copy Markdown
Collaborator Author

Close this PR as #13919 has been merged into main.

@cascade812 cascade812 closed this Jun 16, 2026
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.

2 participants