Skip to content

[KV Connector] Support MooncakeStore with hybrid DCP prefix caching - #53324

Open
wzhao18 wants to merge 1 commit into
vllm-project:mainfrom
wzhao18:wzhao/k3-dcp-mk-2
Open

[KV Connector] Support MooncakeStore with hybrid DCP prefix caching#53324
wzhao18 wants to merge 1 commit into
vllm-project:mainfrom
wzhao18:wzhao/k3-dcp-mk-2

Conversation

@wzhao18

@wzhao18 wzhao18 commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

Purpose

This PR enables MooncakeStoreConnector for mamba hybrid models (e.g., kimi k3) using decode context parallelism (DCP) and fixes a bug where incorrect load keys are constructed under fine-grained prefix hits, causing KV load failures.

Failure Example

Consider Kimi-K3 with DCP 8 + DSpark and --prefix-match-unit 128:

  • Attention block span under DCP: 1,536 × 8 = 12,288 tokens
  • Mamba block span: 1,536 tokens
  • Prefix-match unit: 128 tokens

Reproduction steps:

  1. Send a 15,000-token prompt.
  2. Clear GPU local cache.
  3. Send the same prompt again.

Cache blocks stored and keys:

KV group Stored state Store-key hash
Full attention First physical block through 12,288 H_12288
Full attention Second physical block valid through 14,848 H_14848
Mamba Checkpoint at 13,824 H_13824
Mamba Partial state at 14,848 H_14848

Lookup

  1. Attention matches its second physical block under H_14848.
  2. EAGLE rewinds one 128-token unit, reducing the candidate hit length to 14,720.
  3. Mamba has no checkpoint at 14,720, so it falls back to H_13824.
  4. All groups converge to a safe hit_length = 13,824.

The existing load path derives the key for a group's partially reused physical block from hit_length. As a result, it requested H_13824 for the attention block, even though that physical block was stored under H_14848. Mooncake therefore returned -704 because the derived key did not exist.

This PR fixes this load failure by recording the precise token boundaries for partial cache store so that subsequent load requests can use the correct load key.

Test Plan

  • Mooncake store unit tests
  • E2E Kimi k3 accuracy with dspark and mooncake

Test Result

  • Validated Kimi k3 DCP + dspark produces coherent results with mooncake external cache hits by clearing GPU local cache.
  • Validate the same workload which causes -704 load failure now passes with the fix.

Essential Elements of an Effective PR Description Checklist
  • The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
  • The test plan, such as providing test command.
  • The test results, such as pasting the results comparison before and after, or e2e results
  • (Optional) The necessary documentation update, such as updating supported_models.md and examples for a new model.

Scale attention cache blocks for DCP while keeping recurrent state replicated. Preserve the actual stored hash boundary through hybrid prefix-hit reconciliation so loads do not derive missing Mooncake keys. Align coordinator behavior for multiple attention groups and add regression coverage for DCP, Mamba, EAGLE, and partial-prefix loads.

Assisted-by: OpenAI Codex
Signed-off-by: wzhao18 <wzhao18.sz@gmail.com>

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

@ivanium

ivanium commented Aug 21, 2026

Copy link
Copy Markdown
Collaborator

cc @GirasoleY for a look too

@ivanium ivanium left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Thanks for the feature and the fix! Left one nit and another PCP question for @GirasoleY to confirm.

# to final hit_length.
for group in self.attention_groups:
if not isinstance(group.spec, FullAttentionSpec):
continue

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I think we have sorted the groups to always put FullAttn groups at the beginning. Can you verify if this is still the case? If so, we can break here

Suggested change
continue
break

Comment on lines +648 to +652
def resolve_dcp_kv_block_size(spec: KVCacheSpec, dcp_world_size: int) -> int:
"""Return the token span of a cache block under DCP."""
if isinstance(spec, AttentionSpec):
return spec.block_size * dcp_world_size
return spec.block_size

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

This is good; but I heard from @GirasoleY that now we have revised the PCP kv cache layout design, and technically we should exclude PCP world size from all this kind of block size calculation. In other words, we should make resolve_dcp_kv_block_size the right way for resolve_dcp_kv_block_size. @GirasoleY is my understanding correct?

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I feel this is non-blocking though. If confirmed, I am okay if we just leave a TODO note here for a future fix PR

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.

Right PCP should be excluded from block calculation now. The current implementation is sound here.

GirasoleY

This comment was marked as duplicate.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants