[Performance] DSV4 prefix cache hit rate optimize (vllm-project#11107)

### What this PR does / why we need it?
refer to this issue:
vllm-project#10970 and
vllm-project/vllm#43447 ,
vllm-project/vllm#44082 , Address the issue of
0% DSV4 prefix cache hit rate, which is caused by turning on MTP

### How was this patch tested?

test result:
<img width="1644" height="416" alt="image"
src="https://github.com/user-attachments/assets/2a7c1d2c-fd4c-439f-8777-91b25c219d36"
/>

model script:
export OMP_PROC_BIND=false
export OMP_NUM_THREADS=10
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export
LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libjemalloc.so.2:$LD_PRELOAD
export HCCL_BUFFSIZE=1024
export VLLM_ASCEND_ENABLE_FLASHCOMM1=1
export TASK_QUEUE_ENABLE=1
export HCCL_OP_EXPANSION_MODE="AIV"
export VLLM_PREFIX_CACHE_RETENTION_INTERVAL=16384

vllm serve
/nas/disk6/DeepSeek-V4-Flash-HW-W8A8/DeepSeek-V4-Flash-HW-W8A8_20260512_02
\
    --max_model_len 1048576 \
    --max-num-batched-tokens 10240 \
    --served-model-name dsv4 \
    --gpu-memory-utilization 0.9 \
    --api-server-count 1 \
    --max-num-seqs 32 \
    --data-parallel-size 2 \
    --tensor-parallel-size 8 \
    --enable-expert-parallel \
    --tokenizer-mode deepseek_v4 \
    --tool-call-parser deepseek_v4 \
    --enable-auto-tool-choice \
    --reasoning-parser deepseek_v4 \
    --safetensors-load-strategy 'prefetch' \
    --enable-prefix-caching \
--model-loader-extra-config='{"enable_multithread_load": "true",
"num_threads": 128}' \
    --quantization ascend \
    --port 8898 \
    --block-size 128 \
--speculative-config '{"num_speculative_tokens": 1,"method":
"mtp","enforce_eager": true}' \
    --async-scheduling \
    --compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY"}'\
    --additional-config '
    {"ascend_compilation_config":{
        "enable_npugraph_ex":true,
        "enable_static_kernel":false
        },
    "enable_cpu_binding": true,
    "enable_dsa_cp": true,
    "multistream_overlap_shared_expert":true}'

test script:
vllm bench serve --backend openai-chat --model dsv4 --served-model-name
dsv4 --tokenizer
/nas/disk6/DeepSeek-V4-Flash-HW-W8A8/DeepSeek-V4-Flash-HW-W8A8_20260512_02
--percentile-metrics ttft,tpot,itl,e2el --dataset-name random --port
8898 --max-concurrency 10 --num-prompts 40 --endpoint
/v1/chat/completions --seed 42 --ignore-eos --random-input-len 48000
--random-output-len 300 --random-range-ratio 0 --random-prefix-len 20000

- vLLM version: v0.23.0
- vLLM main:
vllm-project/vllm@967c5c3

Signed-off-by: HF-001 <1670186653@qq.com>

Author: HF-001

tests/ut/patch/platform/test_prefix_cache_cp_patches.py

@@ -304,6 +304,84 @@ def _fake_ascend_coordinator(*args, **kwargs):
     assert coordinator is sentinel
 
 
+class _FakeEagleManager:
+    def __init__(self) -> None:
+        self.use_eagle = False
+
+
+def test_verify_and_split_propagates_eagle_to_managers() -> None:
+    """Regression for DeepSeek-V4 prefix-cache hit rate 0% with MTP/EAGLE.
+
+    The eagle bit must reach each single-type manager: the SWA write path
+    (``cache_blocks`` -> ``reachable_block_mask``) keys the retained checkpoint
+    tail on ``manager.use_eagle``, while the read path
+    (``find_longest_cache_hit``) applies ``drop_eagle_block`` to the same
+    groups. If the manager keeps the default ``use_eagle=False`` the retained
+    tail is one block short of the eagle peek boundary, the SWA group never
+    hits, and the min-over-groups hybrid hit collapses to 0%.
+    """
+    kv_cache_config = _make_deepseek_v4_kv_cache_config()
+
+    coordinator = AscendHybridKVCacheCoordinator.__new__(AscendHybridKVCacheCoordinator)
+    coordinator.kv_cache_config = kv_cache_config
+    coordinator.dcp_world_size = 1
+    coordinator.pcp_world_size = 1
+    coordinator.enable_caching = True
+    # The c128 group (index 1) carries the EAGLE/MTP layers.
+    coordinator.eagle_group_ids = {1}
+
+    coordinator.single_type_managers = (_FakeEagleManager(), _FakeEagleManager())
+
+    coordinator.verify_and_split_kv_cache_groups()
+
+    assert coordinator.single_type_managers[1].use_eagle is True
+    assert coordinator.single_type_managers[0].use_eagle is False
+
+
+def test_verify_and_split_propagates_eagle_to_merged_spec_siblings() -> None:
+    """Upstream ``_annotate_eagle_groups_deepseek_v4`` flags only the single
+    group holding the MTP layer, but the read path merges same-spec groups and
+    applies ``drop_eagle_block`` to the whole merged group. So every sibling
+    sharing that spec must also get ``use_eagle=True`` on the write path, else
+    ``get_cached_block`` (which needs the block cached for *all* group ids)
+    misses and the hit collapses to 0%.
+    """
+    base_config = _make_deepseek_v4_kv_cache_config()
+    # Reuse the c128 spec object so the two c128 groups compare equal and merge
+    # into one attention group in verify_and_split.
+    c128_group_spec = base_config.kv_cache_groups[1].kv_cache_spec
+    kv_cache_config = KVCacheConfig(
+        num_blocks=base_config.num_blocks,
+        kv_cache_tensors=base_config.kv_cache_tensors,
+        kv_cache_groups=[
+            base_config.kv_cache_groups[0],  # c4   -> gid 0 (distinct spec)
+            base_config.kv_cache_groups[1],  # c128 -> gid 1
+            KVCacheGroupSpec(layer_names=["c128_attn_mtp"], kv_cache_spec=c128_group_spec),  # gid 2
+        ],
+    )
+
+    coordinator = AscendHybridKVCacheCoordinator.__new__(AscendHybridKVCacheCoordinator)
+    coordinator.kv_cache_config = kv_cache_config
+    coordinator.dcp_world_size = 1
+    coordinator.pcp_world_size = 1
+    coordinator.enable_caching = True
+    # Only the MTP sibling (gid 2) is flagged, exactly as upstream does.
+    coordinator.eagle_group_ids = {2}
+
+    coordinator.single_type_managers = (
+        _FakeEagleManager(),
+        _FakeEagleManager(),
+        _FakeEagleManager(),
+    )
+
+    coordinator.verify_and_split_kv_cache_groups()
+
+    # Both gid 1 and gid 2 share the c128 spec and merge, so both must be eagle.
+    assert coordinator.single_type_managers[1].use_eagle is True
+    assert coordinator.single_type_managers[2].use_eagle is True
+    assert coordinator.single_type_managers[0].use_eagle is False
+
+
 def test_deepseek_v4_detection_handles_non_mapping_nested_specs() -> None:
     kv_cache_spec = SimpleNamespace(
         kv_cache_specs=[

vllm_ascend/patch/platform/patch_kv_cache_coordinator.py

@@ -197,6 +197,28 @@ def verify_and_split_kv_cache_groups(self) -> None:
             if any(gid in self.eagle_group_ids for gid in group_ids)
         }
 
+        # Propagate the eagle bit to every manager in an eagle-containing
+        # attention group, mirroring upstream
+        # HybridKVCacheCoordinator.verify_and_split_kv_cache_groups. Managers
+        # default to ``use_eagle=False`` ("initialized lazily by the
+        # coordinator", see SingleTypeKVCacheManager.__init__).
+        #
+        # Required for prefix-cache correctness on DeepSeek-V4 + MTP/EAGLE: the
+        # SWA write path (``cache_blocks`` -> ``reachable_block_mask``) keys the
+        # retained checkpoint tail on ``manager.use_eagle``, while the read path
+        # (``find_longest_cache_hit``) applies ``drop_eagle_block`` to every gid
+        # merged into the eagle attention group (and ``get_cached_block``
+        # requires the block cached for *all* of them). If any such manager
+        # keeps the default False, its retained tail ends one block short of the
+        # eagle "peek" boundary the read looks at, the SWA group never hits, and
+        # the min-over-groups hybrid hit collapses to 0%. Note the upstream
+        # ``_annotate_eagle_groups_deepseek_v4`` flags only the single group
+        # holding the MTP layer, so iterating ``eagle_group_ids`` alone would
+        # miss its same-spec siblings.
+        for idx in self.eagle_attn_group_indices:
+            for gid in self.attention_groups[idx][1]:
+                self.single_type_managers[gid].use_eagle = True
+
         # The LCM of the block sizes of all attention types.
         # The cache hit length must be a multiple of the LCM of the block sizes
         # to make sure the cache hit length is a multiple of the block size of