RuntimeError: kv must have shape (num_blocks, page_block_size, h_kv, bytes_per_token)

快速结论：该报错在启用 DSpark 推测解码（--spec-method dspark）时触发，常见于 NVIDIA H200 (SM90) 环境。优先检查 DeepseekV4Attention.get_kv_cache_spec 中是否传入了正确的 kv_quant_mode，以及 DSpark 草稿模型权重的路径映射是否正确。

问题场景

用户在使用 vLLM 0.23.1rc1.dev788+gfa4321de3 部署 deepseek-ai/DeepSeek-V4-Flash-DSpark 模型时，启用了 DSpark 推测解码（--spec-method dspark --spec-tokens 5），在 KV-cache 预热阶段引擎初始化失败。不启用推测解码时服务正常。

报错原文

RuntimeError: kv must have shape (num_blocks, page_block_size, h_kv, bytes_per_token)
File ".../vllm/models/deepseek_v4/nvidia/flashmla.py", line 219, in _forward_decode
    out, _ = flash_mla_with_kvcache(
...

原因分析

该问题由两个独立 bug 共同导致：

草稿模型权重路径不匹配：_remap_dspark_name 函数将检查点名称 mtp.{i}.* 映射到 model.layers.{num_hidden_layers + i}.*，但实际参数在 PyTorch 中注册的名称为 model.layers.{i}.*（ModuleList 索引从 0 开始），导致草稿层权重未正确加载，可能随机初始化。
KV-cache 形状不匹配：DeepseekV4Attention.get_kv_cache_spec 返回的 MLAAttentionSpec 未设置 kv_quant_mode，导致 cache_dtype_str 被传递为 "auto"，进而 get_kv_cache_shape 返回错误的形状（512 bytes per token）。对于 --kv-cache-dtype fp8 的 fp8_ds_mla 布局，正确值应为 584 bytes per token。

环境排查

vLLM 版本：0.23.1rc1.dev788+gfa4321de3
PyTorch 版本：2.11.0+cu129
GPU：NVIDIA H200 (SM90), 8张 GPU
模型：deepseek-ai/DeepSeek-V4-Flash-DSpark
启动参数：--tensor-parallel-size 8 --kv-cache-dtype fp8 --block-size 256 --spec-method dspark --spec-tokens 5 --trust-remote-code
其他尝试失败的参数：--kv-cache-dtype bfloat16（报错 AssertionError: DeepseekV4 fp8_ds_mla layout only supports fp8 kv-cache, got bfloat16）；--attention-backend FLASHINFER_MLA_SPARSE_DSV4（报错 Unsupported architecture on SM90）

解决步骤

修复权重路径映射：修改 vllm/models/deepseek_v4/nvidia/dspark.py 中的 _remap_dspark_name 函数，将 mtp.{i}.* 映射到 model.layers.{i}.*（而非 model.layers.{num_hidden_layers + i}.*）。
修复 KV-cache 形状：修改 vllm/models/deepseek_v4/attention.py 中的 DeepseekV4Attention.get_kv_cache_spec 函数，在返回的 MLAAttentionSpec 中添加 kv_quant_mode=get_kv_quant_mode(self.kv_cache_dtype)。同时设置 alignment=576（适用于 fp8_ds_mla 布局）。
重建或更新 vLLM：应用上述修改后，重新编译或安装 vLLM（建议升级到包含修复的最新 main 分支版本）。
可优先尝试：如果无法自行修改代码，可确认是否使用 vllm-main 分支的最新代码，其中已包含 _remap_dspark_name 修复，但 kv_quant_mode 修复可能尚未合并（截至 Issue 关闭时的上游状态）。

验证方法

使用 Issue 中的启动命令（vllm serve ... --spec-method dspark --spec-tokens 5）启动模型服务，确认引擎初始化完成且无 RuntimeError 报错。可通过 /v1/completions 接口发送请求验证正常推理。也可运行 vllm bench serve 进行压力测试，确认吞吐量和接受率在合理范围（如接受率 25-36%）。