[None][feat] Add KV cache manager V2 support for DSA - #16060
Open
yizhang-nv wants to merge 11 commits into
Open
Conversation
yizhang-nv
force-pushed
the
codex/dsa-kv-cache-v2-main
branch
from
July 8, 2026 09:03
8ff6b1c to
69404fe
Compare
Member
Author
|
/bot run --disable-fail-fast |
Collaborator
|
PR_Github #58215 [ run ] triggered by Bot. Commit: |
Collaborator
|
PR_Github #58215 [ run ] completed with state
|
yizhang-nv
force-pushed
the
codex/dsa-kv-cache-v2-main
branch
from
July 20, 2026 05:29
69404fe to
767b3be
Compare
Member
Author
|
/bot run --disable-fail-fast |
Collaborator
|
PR_Github #60273 [ run ] triggered by Bot. Commit: |
Collaborator
|
PR_Github #60273 [ run ] completed with state
|
yizhang-nv
marked this pull request as ready for review
July 21, 2026 08:38
yizhang-nv
requested review from
BowenFu,
EmmaQiaoCh,
JunyiXu-nv,
QiJune,
kris1025,
tburt-nv,
yingguo-trt,
yufeiwu-nv,
yunruis and
zhaoyangwang-nvidia
July 21, 2026 08:38
yizhang-nv
force-pushed
the
codex/dsa-kv-cache-v2-main
branch
from
July 21, 2026 08:56
767b3be to
eeadb01
Compare
Member
Author
|
/bot run --disable-fail-fast |
Collaborator
|
PR_Github #60657 [ run ] triggered by Bot. Commit: |
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughThe PR adds DSA support for V1 and V2 KV cache managers. It updates indexer cache sizing and mappings, draft replay metadata handling, stable pool mapping, manager selection, model defaults, tests, and documentation. ChangesDSA cache manager contracts and V2 implementation
Indexer offsets and full-KV mappings
KV cache manager selection and compatibility
Stable pool representatives and mapping validation
Indexer mappings and draft replay restoration
Kernel documentation and supporting metadata
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant LLMConfig
participant get_sparse_attn_kv_cache_manager
participant DSACacheManagerV2
participant DSAtrtllmAttentionMetadata
participant prepare_attn_metadata_for_draft_replay
LLMConfig->>get_sparse_attn_kv_cache_manager: select KV cache manager V2
get_sparse_attn_kv_cache_manager->>DSACacheManagerV2: construct DSA V2 manager
DSACacheManagerV2->>DSAtrtllmAttentionMetadata: provide page parameters and cache buffers
prepare_attn_metadata_for_draft_replay->>DSAtrtllmAttentionMetadata: bind draft buffers and recompute mappings
DSAtrtllmAttentionMetadata-->>prepare_attn_metadata_for_draft_replay: restore target metadata after replay
Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Collaborator
|
PR_Github #60657 [ run ] completed with state
|
VALLIS-NERIA
approved these changes
Aug 7, 2026
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
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/features/kvcache.md`:
- Around line 54-70: The KV Cache Manager Version section incorrectly describes
universal V2 selection and error behavior. Update the documentation to state
that use_kv_cache_manager_v2 only selects V1 versus V2 for DSA, while other
sparse algorithms ignore it; document NotImplementedError for connectors, beam
width greater than one, and DSA with STAR, and the base KVCacheManagerV2
AssertionError for STAR in other V2 managers.
🪄 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: 8735da93-714c-4e5f-8a00-36fc84d53cd6
📒 Files selected for processing (6)
docs/source/features/kvcache.mdtensorrt_llm/_torch/models/modeling_deepseekv3.pytensorrt_llm/_torch/pyexecutor/kv_cache_manager_v2.pytests/unittest/_torch/attention/sparse/dsa/test_dsa_indexer.pytests/unittest/_torch/executor/test_kv_cache_v2_extra_buffers.pytests/unittest/_torch/speculative/test_eagle3.py
💤 Files with no reviewable changes (2)
- tests/unittest/_torch/speculative/test_eagle3.py
- tests/unittest/_torch/attention/sparse/dsa/test_dsa_indexer.py
🚧 Files skipped from review as they are similar to previous changes (3)
- tensorrt_llm/_torch/pyexecutor/kv_cache_manager_v2.py
- tests/unittest/_torch/executor/test_kv_cache_v2_extra_buffers.py
- tensorrt_llm/_torch/models/modeling_deepseekv3.py
Comment on lines
+54
to
+70
| ### KV Cache Manager Version | ||
|
|
||
| `KvCacheConfig.use_kv_cache_manager_v2` selects the V2 manager; `"auto"` uses | ||
| the model-specific default. When a sparse-attention model selects V2, | ||
| TensorRT LLM raises `NotImplementedError` for V2-incompatible features instead | ||
| of silently falling back to the V1 manager. | ||
|
|
||
| `DeepseekV3ForCausalLM`, `DeepseekV32ForCausalLM`, | ||
| `GlmMoeDsaForCausalLM`, and `MistralLarge3ForCausalLM` select V2 by default | ||
| when this option is `"auto"`. Set the option to `false` to select V1 | ||
| explicitly. | ||
|
|
||
| For DSA, KV cache manager V2 does not support STAR context parallelism. Use | ||
| another context-parallel mode, or set | ||
| `kv_cache_config.use_kv_cache_manager_v2: false` to use the DSA V1 cache | ||
| manager with STAR. | ||
|
|
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 8 \
'use_kv_cache_manager_v2|NotImplementedError|STAR|context_parallel' \
tensorrt_llm/_torch/attention_backend/sparse/utils.py \
tensorrt_llm/_torch/pyexecutor/_util.py \
tensorrt_llm/_torch/models/modeling_deepseekv3.py
rg -n -C 5 \
'get_model_defaults|use_kv_cache_manager_v2' \
tensorrt_llm/_torch/modelsRepository: NVIDIA/TensorRT-LLM
Length of output: 50375
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- documented section ---'
sed -n '1,95p' docs/source/features/kvcache.md
printf '%s\n' '--- V2 validation path ---'
sed -n '600,675p' tensorrt_llm/_torch/pyexecutor/_util.py
printf '%s\n' '--- sparse manager selection ---'
sed -n '1,55p' tensorrt_llm/_torch/attention_backend/sparse/utils.py
printf '%s\n' '--- listed model registrations and defaults ---'
rg -n -C 4 \
'DeepseekV3ForCausalLM|DeepseekV32ForCausalLM|GlmMoeDsaForCausalLM|MistralLarge3ForCausalLM|use_kv_cache_manager_v2' \
tensorrt_llm/_torch/models \
-g '*.py' | head -n 240
printf '%s\n' '--- relevant call sites and config semantics ---'
rg -n -C 5 \
'_kv_cache_manager_v2|use_kv_cache_manager_v2.*False|use_kv_cache_manager_v2.*True|_create_kv_cache_manager' \
tensorrt_llm/_torch/pyexecutor/_util.py \
tensorrt_llm/_torch \
-g '*.py' | head -n 300Repository: NVIDIA/TensorRT-LLM
Length of output: 50377
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
import ast
from pathlib import Path
files = [
Path("tensorrt_llm/_torch/models/modeling_deepseekv3.py"),
Path("tensorrt_llm/_torch/models/modeling_mistral_large3.py"),
Path("tensorrt_llm/_torch/pyexecutor/_util.py"),
Path("tensorrt_llm/_torch/attention_backend/sparse/utils.py"),
]
trees = {p: ast.parse(p.read_text()) for p in files}
print("--- registered model names and inherited defaults ---")
for path, tree in trees.items():
for node in ast.walk(tree):
if isinstance(node, ast.ClassDef):
registrations = []
for dec in node.decorator_list:
if (isinstance(dec, ast.Call) and isinstance(dec.func, ast.Name)
and dec.func.id == "register_auto_model"
and dec.args and isinstance(dec.args[0], ast.Constant)):
registrations.append(dec.args[0].value)
if registrations or node.name == "MistralLarge3ForCausalLM":
methods = {n.name for n in node.body if isinstance(n, ast.FunctionDef)}
print(path, node.name, "bases=", [
ast.unparse(base) for base in node.bases
], "registered=", registrations,
"defines_get_model_defaults=",
"get_model_defaults" in methods)
print("--- sparse manager branches ---")
sparse_tree = trees[Path("tensorrt_llm/_torch/attention_backend/sparse/utils.py")]
for node in ast.walk(sparse_tree):
if isinstance(node, ast.FunctionDef) and node.name == "get_sparse_attn_kv_cache_manager":
for child in ast.walk(node):
if isinstance(child, ast.Return):
print(ast.unparse(child.value))
print("--- V2 validation exception branches ---")
util_tree = trees[Path("tensorrt_llm/_torch/pyexecutor/_util.py")]
for node in ast.walk(util_tree):
if isinstance(node, ast.FunctionDef) and node.name == "_validate_or_fallback_kv_cache_manager_v2":
for child in ast.walk(node):
if isinstance(child, ast.Raise):
print(ast.unparse(child))
PY
printf '%s\n' '--- option declaration and auto-resolution references ---'
rg -n -C 6 \
'use_kv_cache_manager_v2\s*:|use_kv_cache_manager_v2.*auto|model defaults|model_defaults|get_model_defaults' \
tensorrt_llm/llmapi tensorrt_llm/_torch \
-g '*.py' | head -n 260Repository: NVIDIA/TensorRT-LLM
Length of output: 22923
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- DSA cache-manager STAR handling ---'
rg -n -C 8 \
'class DSACacheManager|class DSACacheManagerV2|CpType\.STAR|cp_type|context_parallel' \
tensorrt_llm/_torch/attention_backend/sparse \
tensorrt_llm/_torch/pyexecutor \
-g '*.py' | head -n 360
printf '%s\n' '--- DSA and STAR tests/configuration ---'
rg -n -C 5 \
'dsa|DSA|STAR|use_kv_cache_manager_v2' \
tests \
docs \
examples \
-g '*.py' -g '*.yaml' -g '*.yml' -g '*.md' | head -n 360Repository: NVIDIA/TensorRT-LLM
Length of output: 50375
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- MiniMax V2 construction and STAR path ---'
rg -n -C 18 \
'class MiniMaxM3KVCacheManagerV2|class DeepseekV4CacheManager|super\(\).__init__|CpType\.STAR|Star attention is not supported' \
tensorrt_llm/_torch/attention_backend/sparse/minimax_m3.py \
tensorrt_llm/_torch/attention_backend/sparse/deepseek_v4.py \
tensorrt_llm/_torch/pyexecutor/kv_cache_manager_v2.py \
-g '*.py'
printf '%s\n' '--- sparse algorithms and V2 manager classes ---'
python3 - <<'PY'
import ast
from pathlib import Path
path = Path("tensorrt_llm/_torch/attention_backend/sparse/utils.py")
tree = ast.parse(path.read_text())
for node in ast.walk(tree):
if isinstance(node, ast.FunctionDef) and node.name == "get_sparse_attn_kv_cache_manager":
for branch in node.body:
if isinstance(branch, ast.If):
print(ast.unparse(branch.test), "=>", ast.unparse(branch.body[-1]))
elif isinstance(branch, ast.Return):
print("return", ast.unparse(branch.value))
PY
printf '%s\n' '--- exact sparse V2 incompatibility gate ---'
sed -n '611,665p' tensorrt_llm/_torch/pyexecutor/_util.pyRepository: NVIDIA/TensorRT-LLM
Length of output: 4150
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- locate sparse manager implementations ---'
fd -t f -i 'minimax.*m3|deepseek.*v4|dsa' tensorrt_llm/_torch/attention_backend
fd -t f 'minimax_m3.py' 'deepseek_v4.py' tensorrt_llm/_torch
printf '%s\n' '--- locate V2 subclasses and constructors ---'
rg -l 'class MiniMaxM3KVCacheManagerV2|class DeepseekV4CacheManager' \
tensorrt_llm/_torch/attention_backend/sparse
rg -n -C 15 \
'class MiniMaxM3KVCacheManagerV2|class DeepseekV4CacheManager|super\(\).__init__' \
tensorrt_llm/_torch/attention_backend/sparse \
-g '*.py' | head -n 260Repository: NVIDIA/TensorRT-LLM
Length of output: 28827
Align the section with sparse-manager routing.
NotImplementedErrorcovers KV connectors, beam width greater than one, and DSA with STAR. Other V2 managers can reach a baseKVCacheManagerV2AssertionErrorfor STAR.use_kv_cache_manager_v2selects between V1 and V2 only for DSA. Other sparse algorithms ignore this option.- Update the documentation or expand validation to provide one consistent error contract.
🤖 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/features/kvcache.md` around lines 54 - 70, The KV Cache Manager
Version section incorrectly describes universal V2 selection and error behavior.
Update the documentation to state that use_kv_cache_manager_v2 only selects V1
versus V2 for DSA, while other sparse algorithms ignore it; document
NotImplementedError for connectors, beam width greater than one, and DSA with
STAR, and the base KVCacheManagerV2 AssertionError for STAR in other V2
managers.
Member
Author
|
/bot run --disable-fail-fast |
Collaborator
|
PR_Github #64549 [ run ] triggered by Bot. Commit: |
Collaborator
|
PR_Github #64538 [ run ] completed with state |
Collaborator
|
PR_Github #64549 [ run ] completed with state
|
Signed-off-by: Yi Zhang <187001205+yizhang-nv@users.noreply.github.com>
Signed-off-by: yizhang-nv <187001205+yizhang-nv@users.noreply.github.com> Signed-off-by: Yi Zhang <187001205+yizhang-nv@users.noreply.github.com>
Signed-off-by: Yi Zhang <187001205+yizhang-nv@users.noreply.github.com>
Signed-off-by: Eric Tsai <ertsai@nvidia.com>
Signed-off-by: Yi Zhang <187001205+yizhang-nv@users.noreply.github.com>
Signed-off-by: Yi Zhang <187001205+yizhang-nv@users.noreply.github.com>
Signed-off-by: Yi Zhang <187001205+yizhang-nv@users.noreply.github.com>
Signed-off-by: Yi Zhang <187001205+yizhang-nv@users.noreply.github.com>
Signed-off-by: Yi Zhang <187001205+yizhang-nv@users.noreply.github.com>
yizhang-nv
force-pushed
the
codex/dsa-kv-cache-v2-main
branch
from
August 8, 2026 13:03
4282bb1 to
43f11d5
Compare
2 tasks
Member
Author
|
/bot run --disable-fail-fast |
Collaborator
|
PR_Github #64829 [ run ] triggered by Bot. Commit: |
Signed-off-by: Yi Zhang <187001205+yizhang-nv@users.noreply.github.com>
Member
Author
|
/bot run --disable-fail-fast |
Collaborator
|
PR_Github #64835 [ run ] triggered by Bot. Commit: |
Collaborator
|
PR_Github #64829 [ run ] completed with state |
Signed-off-by: Yi Zhang <187001205+yizhang-nv@users.noreply.github.com>
Member
Author
|
/bot run --disable-fail-fast |
Collaborator
|
PR_Github #64843 [ run ] triggered by Bot. Commit: |
Collaborator
|
PR_Github #64835 [ run ] completed with state |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
7 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Dev Engineer Review
Role.INDEX_KEYbuffer.QA Engineer Review
Test code changes are present.
Added or updated coverage includes:
TestGLM52.test_nvfp4.indexer_k_cache_scatter_op.No corresponding
tests/integration/test_lists/changes were reported for these tests. Test-list coverage cannot be confirmed from the available changes.Verdict: needs follow-up.
Description
Port the DSA KV cache manager V2 work from liji-nv@492422b onto the latest
main.This change:
DSACacheManagerV2selection throughuse_kv_cache_manager_v2while preserving the V1 path.Role.INDEX_KEYbuffer managed by V2.Role.ALL, runtime quota calculation, and static KV cache warm-up estimation.Test Coverage
git diff --checkpassed.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-compatibleorapi-breaking. Forapi-breaking, includeBREAKINGin 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.