[Bug]: AssertionError at kv_cache_utils.py:1042 — dense draft model + hybrid-attention main (DeltaNet+SWA) fails in unify_kv_cache_spec_page

[Bug]: AssertionError at kv_cache_utils.py:1042 — dense draft model + hybrid-attention main (DeltaNet+SWA) fails in unify_kv_cache_spec_page_size

快速结论：此报错发生在为混合注意力（DeltaNet + Sliding Window Attention）主模型搭配密集 draft 模型（如 LocoOperator-4B）进行推测解码时。优先排查主模型与 draft 模型之间的 KV 缓存页大小（page_size_bytes）是否不一致，问题出在 vLLM 的 `unify_kv_cache_spec_page_size` 函数中。

问题场景

用户在使用 vLLM 的推测解码功能（speculative decoding）时，主模型为混合注意力架构（Qwen3-Coder-Next-80B-A3B，包含 DeltaNet 和 SWA），draft 模型为密集注意力架构（LocoOperator-4B）。引擎初始化（engine init）阶段触发断言错误，确定性地在三次启动中复现。硬件为单张 RTX PRO 6000 Blackwell GPU，TP=1，kv-cache-dtype 设置为 fp8_e4m3，vLLM 镜像版本为 v0.20.2-cu129-ubuntu2404。

报错原文

File "/usr/local/lib/python3.12/site-packages/vllm/v1/worker/gpu_model_runner.py", line 5951, in profile_cudagraph_memory
    self._init_minimal_kv_cache_for_profiling()
File "/usr/local/lib/python3.12/site-packages/vllm/v1/worker/gpu_model_runner.py", line 5870, in _init_minimal_kv_cache_for_profiling
    kv_cache_groups = get_kv_cache_groups(self.vllm_config, kv_cache_spec)
File "/usr/local/lib/python3.12/site-packages/vllm/v1/core/kv_cache_utils.py", line 1654, in get_kv_cache_groups
    kv_cache_spec = unify_kv_cache_spec_page_size(kv_cache_spec)
File "/usr/local/lib/python3.12/site-packages/vllm/v1/core/kv_cache_utils.py", line 1042, in unify_kv_cache_spec_page_size
    assert new_spec.page_size_bytes == max_page_size
AssertionError

原因分析

可能原因：在 `unify_kv_cache_spec_page_size` 函数（`vllm/v1/core/kv_cache_utils.py` 第 1042 行）中，vLLM 试图统一所有注意力机制的 KV 缓存页大小，但密集 draft 模型与混合注意力主模型（DeltaNet + SWA）的 `page_size_bytes` 不匹配。代码中的缩放逻辑对 `MambaSpec` 无效——`MambaSpec` 的 `page_size_bytes` 来源于状态形状（state shapes），不会随 `block_size` 变化，而当前断言正是针对 MambaSpec 场景的特定检查。该断言缺少错误信息（`assert new_spec.page_size_bytes == max_page_size` 没有 `f”…”` 子句），导致无法直接获取预期与实际值。历史上，这类配对在早期提交（a29a754d1b）中正常工作，说明此验证可能是后来添加或收紧的。

环境排查

• 确认 vLLM 版本：信息显示为镜像 `vllm/vllm-openai:v0.20.2-cu129-ubuntu2404`，建议检查当前版本。
• 确认主模型架构：Qwen3-Coder-Next-80B-A3B（DeltaNet + SWA 混合注意力）。
• 确认 draft 模型架构：LocoOperator-4B（密集注意力）。
• 确认 KV 缓存类型：`–kv-cache-dtype fp8_e4m3`。
• 确认 GPU 架构：SM_120（Blackwell）。
• 确认推测解码参数：`–speculative-config ‘{“model”: “/draft”, “num_speculative_tokens”: 3}’`。

解决步骤

1. 回退版本验证（可优先尝试）：使用已知正常工作的旧提交版本（如 `a29a754d1b`）测试配对是否恢复功能。如果问题消失，则确认为后续更改引入的回归。
2. 修改 `unify_kv_cache_spec_page_size` 函数：在 `vllm/v1/core/kv_cache_utils.py` 中，修改第 1042 行的断言逻辑。一个建议方案是：使用所有 `page_size_bytes` 的最小公倍数（LCM）代替直接断言相等，确保所有注意力类型能共享统一分配。示例逻辑如下：

   # 将断言替换为 LCM 统一分配
   from functools import reduce
   from math import gcd
   def lcm(a: int, b: int) -> int:
       return a * b // gcd(a, b)
   page_size_bytes_list = [spec.page_size_bytes for spec in kv_cache_specs]
   unified_size = reduce(lcm, page_size_bytes_list)
   # 更新所有 spec 使用统一大小（需要根据 spec 类型做相应处理）

3. 更新 `MambaSpec` 处理逻辑：注意 `MambaSpec` 的 `page_size_bytes` 不受 `block_size` 缩放影响。如果涉及 MambaSpec，应使用其已提供的 `page_size_padded` 字段，确保迭代状态缩放后仍保持一致。
4. 添加详细错误日志：在断言处添加错误信息（例如 `f”draft spec page_size_bytes={new_spec.page_size_bytes} != main max_page_size={max_page_size}”`）以辅助调试。

验证方法

修改后重新启动 vLLM 引擎，加载相同的混合注意力主模型与密集 draft 模型组合，确保引擎初始化不再抛出 `AssertionError`，并确认推测解码能正常进行（如验证解码速度提升）。

参考来源

vllm-project/vllm #43626

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。