Skip to content

[Bugfix][KV Offloading] Preserve MTP/Mamba state across external hits - #249

Merged
yangzhuxinyzx merged 3 commits into
1CatAI:mainfrom
Leonccaa:agent/mtp-exact-boundary-offload-1cat
Aug 22, 2026
Merged

yangzhuxinyzx merged 3 commits into
1CatAI:mainfrom
Leonccaa:agent/mtp-exact-boundary-offload-1cat

Conversation

@Leonccaa

@Leonccaa Leonccaa commented Aug 19, 2026

Copy link
Copy Markdown
Contributor

Purpose

Fix incorrect native CPU KV offload restores for hybrid Mamba/GDN models when
MTP speculative decoding is enabled.

This PR depends on 1Cat PR #247. PR #247 removes the original external-KV
assertion and backports the Mamba boundary-alignment fixes from upstream vLLM,
but it does not cover MTP-owned accepted-token state or mutable Mamba align
source blocks. This branch is stacked on the fixed head of #247
(c514f39e15ca74a1f51bb5270f0f4734d1da8bc7) and will be rebased after #247
lands.

Root cause

On a real external CPU-tier hit, MTP4 output consistently lost exactly four
tokens. The fixed loss matching the MTP width exposed two related ownership
bugs:

  1. Asynchronous accepted-token D2H copies targeted mutable InputBatch rows.
    Rows can be removed, condensed, resumed, or reused before the event is
    consumed, so accepted-token state could be applied to the wrong request.
  2. A Mamba align table is not append-only. MTP scratch blocks move to new
    logical positions when a boundary is committed, while the native connector's
    block mirror only appends. A positional store could therefore save a stale
    Mamba state under a valid prefix key.

Changes

  • Store accepted-token D2H results in runner-owned buffers and remap them by
    request identity after synchronization. New, resumed, or same-ID replacement
    requests reset their speculative state.
  • Clip attention block tables at the computed-token frontier without clipping
    allocator-defined non-attention state groups.
  • Emit exact core-selected Mamba align boundary block IDs to the connector.
  • Exclude mutable Mamba groups from the normal positional store path and build
    their store jobs only from exact boundary handoffs.
  • Keep the existing pending-job fence on each source block until the async
    store completes, including deduplication when MTP aliases one physical block.

Scope and duplicate-work check

This is not duplicate work:

  • 1Cat [Bugfix][KV Offloading] Backport mamba/GDN CPU offloading fixes (upstream vllm#42554 + vllm#44599) #247 is the required base fix; it does not address MTP state ownership
    or the exact external-hit corruption described here.
  • Upstream vLLM
    #51358 implements exact
    Mamba boundary persistence for Mooncake with its own pin/watermark protocol;
    this PR adapts the correctness invariant to the native OffloadingConnector
    and its per-job fence lifecycle.
  • Upstream vLLM
    #52771 fixes MTP/EAGLE
    lookups being reduced to zero. In this reproduction the external hit was
    already real; the restored recurrent state was wrong.
  • Upstream vLLM
    #52832 concerns
    Mooncake finish-time partial tails and does not cover this native exact-
    boundary path.

No open 1Cat PR or issue was found for this mechanism.

Test Plan

.venv/bin/python -m pytest -q \
  tests/v1/core/test_prefix_caching.py \
  tests/v1/kv_connector/unit/offloading_connector/test_scheduler.py \
  tests/v1/core/test_scheduler.py

.venv/bin/python -m pytest -q tests/v1/worker/test_gpu_model_runner.py \
  -k 'sync_mamba_accepted_token_state_tracks_request_ownership or mamba_align_postprocess_uses_runner_owned_d2h_buffers or mamba_align_cpu_postprocess_mirrors_runner_owned_snapshot or mamba_all_mode_uses_runner_owned_d2h_buffers'

pre-commit run --from-ref upstream/pr-247 --to-ref HEAD
git diff --check upstream/pr-247..HEAD

Test Result

AI assistance

AI assistance was used for implementation, test orchestration, root-cause
analysis, and drafting this PR. The human submitter has reviewed every changed line and is submitting this
PR for maintainer review.

lwh9346 and others added 3 commits August 19, 2026 09:08
…ream vllm#42554 + vllm#44599)

Hybrid GDN models (Qwen3.8, Qwen3-Next family) with the native CPU
offloading connector crashed or corrupted outputs on any repeated prefix:

1. Scheduler asserted num_external_computed_tokens==0 in
   _mamba_block_aligned_split ("External KV connector is not verified
   yet"), killing the engine whenever the offloading connector reported
   a hit (backport of vllm-project/vllm#42554, merge 68f5e565: drop the
   assert; skip the mamba-aligned split when load_kv_async).

2. OffloadingConnector treated MambaSpec groups like sliding-window
   attention and returned hit windows not aligned to the mamba block
   size, which is incorrect for align cache mode (mamba keeps a single
   state per block). Hit windows are now rounded down to the offloaded
   block size via resolve_mamba_align_size() (backport of
   vllm-project/vllm#44599, merge b927004c).

Validation on Qwen3.8-27B-FP8 (8xV100, TP4, --kv-offloading-size 64
native): cold prefill 10.7s -> CPU-offload hit 2.2s with byte-identical
greedy outputs; engine stays healthy on subsequent requests.
(1Cat tests/test_gdn_offload.py)

Drop this commit when rebasing onto an upstream base that contains both
PRs.
@github-actions

Copy link
Copy Markdown

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

PRs do not trigger a full CI run by default. Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can either: Add ready label to the PR or enable auto-merge.

If you have any questions, please reach out to us on Slack at https://slack.vllm.ai.

Agent Guidelines

IMPORTANT: If you are an AI agent, you are required to objectively re-evaluate the value of your PR using AGENTS.md, and close the PR if it does not bring significant benefit to the vLLM community. Failure to do so may result in an immediate ban.

🚀

@yangzhuxinyzx yangzhuxinyzx 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.

源码审计通过:accepted-token D2H 状态按请求身份安全重映射;attention lookahead 裁剪与非 attention 状态隔离;Mamba align 使用同一步 scheduler 的精确 boundary block handoff,并在异步 store 生命周期沿用 source-block fence。当前 main 合并态及 diff/语法/Ruff/格式检查通过。

@yangzhuxinyzx
yangzhuxinyzx merged commit f5ca10d into 1CatAI:main Aug 22, 2026
2 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.

3 participants