Repository navigation
[TRTLLM-16722][feat] Dflash Unified KVCache - #20486
allisonlim-nv wants to merge 37 commits into
Conversation
Signed-off-by: Allison Lim <allim@nvidia.com>
Signed-off-by: Allison Lim <allim@nvidia.com>
Signed-off-by: Allison Lim <allim@nvidia.com>
Signed-off-by: Allison Lim <allim@nvidia.com>
Signed-off-by: Allison Lim <allim@nvidia.com>
Signed-off-by: Allison Lim <allim@nvidia.com>
Signed-off-by: Allison Lim <allim@nvidia.com>
Signed-off-by: Allison Lim <allim@nvidia.com>
Signed-off-by: Allison Lim <allim@nvidia.com>
Signed-off-by: Allison Lim <allim@nvidia.com>
Signed-off-by: Allison Lim <allim@nvidia.com>
Signed-off-by: Allison Lim <allim@nvidia.com>
Separate NVFP4 data and block scales from other equal-size buffers while keeping shared lifecycle slot allocation. Preserve matching role order and require matching scale roles. Add one regression test for mixed NVFP4 and BF16 storage, checking scale addresses at slot 1 and the final slot. Signed-off-by: Allison Lim <allim@nvidia.com>
Read the data-only view of three-dimensional pointer tables for non-FP4 layers while preserving NVFP4 scale handling and legacy two-dimensional tables. Add one native-binding regression covering mixed BF16/NVFP4 pointer tables and legacy BF16 tables. Signed-off-by: Allison Lim <allim@nvidia.com>
Signed-off-by: Allison Lim <allim@nvidia.com>
Preserve explicit and legacy layer configuration while applying upstream pool rebalancing settings to both paths. Signed-off-by: Allison Lim <allim@nvidia.com>
Preserve unified DFlash storage specs across model geometry refactoring, combine per-layer cache layouts with mixed-precision pool handling, and retain both acceptance references. Add CPU regression coverage for unification selection and storage-spec forwarding. Signed-off-by: Allison Lim <allim@nvidia.com>
NVIDIA#20178 foundation) Squashed net change of PR NVIDIA#20486 at head 714916d relative to the main it last merged (0829689), ported onto feat/musespark-open-agentx; unrelated main commits are not included. NVIDIA#20486 carries the unified KV cache manager foundation of PR NVIDIA#20178 through eea6dcb (NVIDIA#20178's later 61248ec, 77d4eae and 636715a are not part of the NVIDIA#20709 stack and are not ported). Commits: 3bc36a5 [None][feat] add unified KV cache layout foundation dad9f1f [None][refactor] simplify unified KV cache layer specs 6ea5ad8 [None][test] remove unified KV cache foundation tests 090cbc0 [None][docs] remove unified KV cache design document 511975f [None][feat] support per-layer storage layouts in KVCacheManagerV2 bfc8bc7 fix: normalize explicit KV cache spec windows 18c71c1 fix: use explicit KV cache dtype for cold-page codec ae64dca test: cover explicit KV cache dtype for cold-page codec 701abea fix: honor physical slot strides in KV cache views 623816c test: cover mixed KV cache odd-slot addressing 7cde28e fix: restore KV cache subclass and test compatibility 4a3bb25 [None][test] fix mixed KV cache slot address arithmetic 9d0107b [None][fix] align NVFP4 data and scale page layouts e273a98 [None][fix] accept mixed KV cache pointer table layouts f6b1d08 [None][fix] preserve sink and reuse policy in KV cache costing b6db612 [TRTLLM-20434][feat] Dflash Unified KVCache 39d814d [None][fix] share the DFlash draft KV cache in disagg only with speculative_config in both sections 22cf25c [None][fix] gate the disagg shared draft KV cache on matching tensor_parallel_size feed06a [None][test] cover the disagg shared draft KV gate for generation-only speculative_config and mismatched TP 0319dc3 test: use default timeout for unified DFlash KV test 1f39128 fix: restore DFlash private arena fallback for separate KV caches 97fb214 fix: seed unified DFlash context lengths from bounded token counts caf4c45 test: cover DFlash mixed-precision block tables 875eff2 fix: require matching attention DP for shared draft KV 212fdab test: enable shared draft KV in DFlash integration test 1302d43 fix: keep mixed-window DFlash caches separate Port conflict resolutions (base = main 0829689, ours = agentx b7979ca + !10912): - kv_cache_manager_v2.py: our joint_kv_cache_reuse kwarg and the PR's layer_specs kwarg land at the same spot in _get_per_request_layer_tokens, get_cache_bytes_per_request and get_cache_quota_per_request (5 hunks): keep both. The generic layer_configs loop moves under the PR's `else:`; main's kv_pool_rebalance_config (NVIDIA#19077) is not on agentx and is dropped. - _util.py: agentx's _per_manager_cache_cost has no tokens_per_block parameter (main-only); keep the PR's unified layer_specs injection. - dflash.py: keep agentx's windowed VANILLA arena (_ctx_base) branch; ctx_len_gen (PR) equals self._ctx_len[slots]. - rank_info.py: drop main's bounded_replay_on_generation (not on agentx); keep num_draft_layers. - tests: drop main-only imports (PyTorchModelEngine, KvCacheRetentionConfig). !10912 stays intact: validate_block_attention_windows() is not re-added. Signed-off-by: Allison Lim <allim@nvidia.com> Signed-off-by: Zheyu Fu <zheyuf@nvidia.com>
Squashed increment of draft PR NVIDIA#20709 at head 1703851 over NVIDIA#20486 at 714916d (both on main 0829689; the NVIDIA#20709 tree contains all of NVIDIA#20486), ported onto feat/musespark-open-agentx. Commits: 7a85a73 [None][feat] unify the standalone DSpark target and draft KV cache d492b52 [None][feat] reshard unified target/draft KV by per-view attention heads Port conflict resolutions (base = NVIDIA#20486 on main 0829689, ours = the NVIDIA#20486 port): - kv_extractor.py: agentx lacks main's view_partition hook (NVIDIA#19727); add only kv_heads_for_layer and the Callable import its annotation needs (Muse target and draft buffers differ in size, so they never share a physical pool/view). - kv_cache_manager_v2.py add_dummy_requests: keep agentx's stop_committing() for the dummy and size it with the PR's _kv_alloc_extra_tokens. - test_kvcm2_integration.py: keep agentx's DecoderRunner import and add the PR's tests only (main's generation-block reuse tests, NVIDIA#19710, are not on agentx). Signed-off-by: Allison Lim <allim@nvidia.com> Signed-off-by: Zheyu Fu <zheyuf@nvidia.com>
…indings The ported NVIDIA#20178/NVIDIA#20486/NVIDIA#20709 Python assumes main's KV cache manager bindings. Two pieces are not on agentx: - Per-layer AttentionReusePolicy (main NVIDIA#19727 C++). The stack only ever uses REQUIRED, which is what agentx does for every layer, so the reuse_policy field, its AttentionLayerConfig argument and its place in the scratch and pool-group keys are dropped. The one test that needs PRIVATE is skipped. - BufferConfig.coalescing_group (the stack's own C++, which the agentx image does not carry). Group 0 is what the prebuilt bindings do implicitly, so the argument is passed only for nonzero (NVFP4) groups, which fail loudly unless the bindings are rebuilt from this branch's cpp/. Signed-off-by: Zheyu Fu <zheyuf@nvidia.com>
Keep upstream cache-layer validation and preserve DFlash mixed-dtype coverage. Update unified-cache dtype access for the model engine refactor and distinguish model geometry from storage layer specs in tests. Signed-off-by: Allison Lim <allim@nvidia.com>
|
/bot run --disable-fail-fast |
|
PR_Github #80565 [ run ] triggered by Bot. Commit: |
|
PR_Github #80565 [ run ] completed with state
|
Signed-off-by: Allison Lim <allim@nvidia.com>
|
/bot run --disable-fail-fast |
|
PR_Github #80661 [ run ] triggered by Bot. Commit: |
Yes, here are the stats for the improvements: perf numbers |
|
PR_Github #80661 [ run ] completed with state
|
|
/bot run --reuse-test 66416 |
|
PR_Github #80722 [ run ] triggered by Bot. Commit: |
|
PR_Github #80722 [ run ] completed with state
|
|
Should be reviewed by kv cache manager owners before merging |
SimengLiu-nv
left a comment
There was a problem hiding this comment.
Approve to unblock. Left comments to address.
Preserve unified DFlash cache layer offsets in the fused block-table decoder and cover nonzero offsets in the existing kernel regression test. Retain the ModelEngine rename alongside cache storage layer specifications. Signed-off-by: Allison Lim <allim@nvidia.com>
Require compatible target and draft attention backends, static drafting, and supported page sizes on every disaggregated peer before enabling shared draft KV. Keep separate caches when the effective page size is unsupported by DFlash, and cover the launcher and local fallback decisions. Signed-off-by: Allison Lim <allim@nvidia.com>
|
/bot run --disable-fail-fast |
|
PR_Github #80992 [ run ] triggered by Bot. Commit: |
Dev Engineer Review
KVCacheManagerV2. Other runs retain separate draft-cache handling.PR_Github #78565completed withFAILUREfor commitb6db612.PR_Github #78633completed withSUCCESSfor commitb757065, but its triggered L0 Merge Request pipeline reportedFAILURE. Failure details are unavailable. Current review severity counts are unavailable.QA Engineer Review
TestQwen3_8BDFlash::test_gsm8k_1p1d_unified_draft_kvintegration test checks acceptance length and a shared-manager log marker. The test is listed intests/integration/test_lists/test-db/l0_dgx_b200.yml.Per-File QA Perspective
cpp/tensorrt_llm/batch_manager/kv_cache_manager_v2/config.h: Verify that the defaultcoalescingGrouppreserves existing behavior.cpp/tensorrt_llm/batch_manager/kv_cache_manager_v2/storage/config.cpp: Verify that buffers coalesce only when both group and expanded size match.cpp/tensorrt_llm/nanobind/batch_manager/kvCacheManagerV2.cpp: Verify that the optionalcoalescing_groupargument and writable property match the Python stub.cpp/tensorrt_llm/thop/attentionOp.cpp: Verify pointer-table handling for 2D and 3D non-FP4 inputs, including mixed-format tables. The FP4 path is unchanged.tensorrt_llm/_torch/attention/backends/flashinfer.py: Verify that layers with different KV factors receive separate page-index spaces.tensorrt_llm/_torch/attention/backends/sparse/minimax_m3/cache_manager.py: Verify compatibility with the base method’s optionalkv_factorargument.tensorrt_llm/_torch/disaggregation/native/peer.py: Verify that matching draft-layer counts allow peer registration and mismatches raiseValueError.tensorrt_llm/_torch/disaggregation/native/rank_info.py: Verify draft-layer counts with and without layer specs, plus compatibility with older serialized payloads.tensorrt_llm/_torch/pyexecutor/_util.py: Verify unified-cache selection gates, fallback behavior, and consistent layer specs in manager construction and cost estimation. Verify draft quantization handling for DFlash and DSpark.tensorrt_llm/_torch/pyexecutor/kv_cache/kv_cache_manager_v2.py: Verify per-layer ownership, dtype, buffer roles, KV factors, page indexing, cache views, and cost calculations. Verify legacy behavior when layer specs are absent.tensorrt_llm/_torch/pyexecutor/scheduler/scheduler_v2.py: Verify disaggregated generation initialization when only the target manager receives prompt KV.tensorrt_llm/_torch/speculative/dflash.py: Verify unified-pool binding, metadata validation, block offsets, and context-length handling. Unsupported unified layouts should fail rather than use a private arena.tensorrt_llm/_torch/speculative/interface.py: Verify that a shared target and draft manager bypass separate-cache handling.tensorrt_llm/_torch/speculative/utils.py: Verify that a draft view identical to the target manager is not returned as a separate manager.tensorrt_llm/runtime/kv_cache_manager_v2/__init__.pyi: Verify that thecoalescing_groupstub matches the bound constructor and property.tests/integration/defs/accuracy/references/acceptance_length.yaml: Adds the unified DFlash GSM8K acceptance-length reference. Verify the reference and minimum against the intended B200 run.tests/integration/defs/accuracy/test_disaggregated_serving.py: Adds a Qwen3-8B DFlash test with an acceptance-length check and shared-manager log assertion. Its CI list entry is intests/integration/test_lists/test-db/l0_dgx_b200.yml.tests/integration/test_lists/test-db/l0_dgx_b200.yml: Adds the unified DFlash test to the two-GPU B200 pre-merge MPI/PyTorch list with a 60-second timeout.tests/unittest/_torch/attention/sparse/glm_kpool/test_glm_kpool.py: Initializeslayer_specsin a cache-cost test. Verify the legacy configuration path.tests/unittest/_torch/attention/sparse/msa/test_minimax_m3_shared_draft_layers.py: Initializeslayer_specsin NVFP4 role tests for MiniMax M3 and generic managers. Verify both paths.tests/unittest/_torch/executor/kv_cache/test_dflash_unified_kv_gate.py: Covers aggregated and disaggregated unification gates, head-layout comparisons, and per-layer head-count rejection.tests/unittest/_torch/executor/kv_cache/test_kv_cache_estimation.py: Covers cache-cost calculations for sink tokens and reuse policies, quota conversion, per-request layer-token values, and draft-layer rounding.tests/unittest/_torch/executor/kv_cache/test_kvcm2_integration.py: Covers mixed-role pools, NVFP4 scale-page indexing, metadata pointer views, and cold-codec dtype selection and rejection.tests/unittest/_torch/executor/kv_cache/test_mamba_cache_manager.py: Initializeslayer_specsin three hybrid-manager setups. Verify quota and pool-ratio checks.tests/unittest/disaggregated/test_minimax_m3_kv_transfer.py: Covers cache-index arguments and results, and initializes manager fields in the block-count-limit test.tests/unittest/disaggregated/test_peer.py: Covers peer registration with matching and mismatched unified draft-layer counts.tests/unittest/disaggregated/test_rank_info.py: Covers draft-layer counts, serialization, and defaulting older payloads to zero.tensorrt_llm/commands/serve.py: SetsTRTLLM_DISAGG_SHARED_DRAFT_KVbased on speculative configuration and matching tensor-parallel sizes. Verify that other configurations disable shared draft KV.Description
Follow-up to #20178. Integrate DFlash with the unified key-value cache manager so target and draft layers share one manager while retaining their respective cache data types.
Test Coverage
The following 24 comparisons cover tensor parallel configurations, CUDA graphs, overlap scheduling, attention data parallelism, and mixed cache precision.
All result columns report AL. Measurements come from the generation server’s
/metrics, except the attention data parallelism comparisons, which use per-request statistics from a concurrent client. Both configuration columns show tensor parallel sizes; the disaggregated configuration lists prefill → decode.The mixed cache precision runs use the following configuration. Here, bfloat16 denotes the 16-bit brain floating-point format.
Only the target cache uses 8-bit floating point; target weights and activations remain bfloat16. Runtime logs confirm the intended target and draft cache types on every rank, with the drafter using the shared bfloat16 pool and no fallback to its private cache. Transfer unit coverage verifies that draft pages use two-byte elements even when the servers advertise the target cache’s one-byte element size.
Results:
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.