执行摘要

• 一句话：修正 DSV4 支持的 KV cache 数据类型
• 推荐动作：此 PR 可直接合并，无需特别关注。它是一个小的 bugfix，修正了先前引入的不正确声明，避免用户遇到运行时错误。

功能与动机

PR #44699 引入了 FlashMLA V4 后端，但 DeepseekV4FlashMLABackend 错误地声明了 bfloat16 KV cache 支持（FlashMLA kernel 不支持），且 DeepseekV4FlashInferMLASparseBackend 错误地声明了 fp8_ds_mla 支持（FlashInfer 使用普通 per-tensor fp8 而非 FlashMLA 的 packed 格式）。

实现拆解

本 PR 通过调整 supported_kv_cache_dtypes 和 supported_dtypes 类的类变量，修正了两个后端声明的 KV cache 数据类型支持。

1. 修正 DeepseekV4FlashMLABackend.supported_kv_cache_dtypes（vllm/models/deepseek_v4/sparse_mla.py）：从支持列表中移除 "bfloat16"，因为 FlashMLA kernel 不支持 bfloat16 KV cache。保留 "auto", "fp8_ds_mla", 和 "fp8"。

2. 修正 DeepseekV4FlashInferMLASparseBackend（vllm/models/deepseek_v4/nvidia/flashinfer_sparse.py）：新增 supported_dtypes 和 supported_kv_cache_dtypes 类变量，明确声明仅支持 [torch.bfloat16] 输入 dtype，以及 ["auto", "bfloat16", "fp8"] KV cache dtype。之前继承父类的声明，导致错误地声明支持 fp8_ds_mla（FlashInfer 使用普通 per-tensor fp8 而非 FlashMLA 的 packed 格式）。同时简化了类文档字符串，移除了过时的 V3.2 对比描述。

3. 更新文档（docs/design/attention_backends.md）：更新表格中 FLASHINFER_MLA_SPARSE_DSV4 和 FLASHMLA_SPARSE_DSV4 的 dtype 和 KV dtype 列，与代码中的声明保持一致。

关键文件：

• vllm/models/deepseek_v4/nvidia/flashinfer_sparse.py（模块 模型；类别 source；类型 data-contract；符号 DeepseekV4FlashInferMLASparseBackend）: 新增 supported_dtypes 和 supported_kv_cache_dtypes 类变量，修正 FlashInfer 后端错误声明支持 fp8_ds_mla 的问题。
• vllm/models/deepseek_v4/sparse_mla.py（模块 模型；类别 source；类型 data-contract；符号 DeepseekV4FlashMLABackend）: 从 DeepseekV4FlashMLABackend.supported_kv_cache_dtypes 列表中移除 "bfloat16"，因为 FlashMLA kernel 不支持 bfloat16 KV cache。
• docs/design/attention_backends.md（模块 文档；类别 docs；类型 documentation）: 更新文档表格以反映修正后的数据类型支持。

关键符号：未识别

关键源码片段

vllm/models/deepseek_v4/nvidia/flashinfer_sparse.py

新增 supported_dtypes 和 supported_kv_cache_dtypes 类变量，修正 FlashInfer 后端错误声明支持 fp8_ds_mla 的问题。

class DeepseekV4FlashInferMLASparseBackend(DeepseekV4FlashMLABackend):
    """Shares the FlashMLA V4 metadata/cache pipeline; swaps the attention impl."""
​
    # 显式声明该后端支持的数据类型和 KV cache 数据类型
    # FlashInfer 只支持 bf16 输入，以及 auto/bfloat16/fp8 KV cache 格式
    supported_dtypes: ClassVar[list[torch.dtype]] = [torch.bfloat16]
    supported_kv_cache_dtypes: ClassVar[list[CacheDType]] = ["auto", "bfloat16", "fp8"]
​
    @staticmethod
    def get_name() -> str:
        return "FLASHINFER_MLA_SPARSE_DSV4"

vllm/models/deepseek_v4/sparse_mla.py

从 DeepseekV4FlashMLABackend.supported_kv_cache_dtypes 列表中移除 "bfloat16"，因为 FlashMLA kernel 不支持 bfloat16 KV cache。

class DeepseekV4FlashMLABackend(AttentionBackend):
    # ...
    supported_dtypes: ClassVar[list[torch.dtype]] = [torch.bfloat16]
    supported_kv_cache_dtypes: ClassVar[list[CacheDType]] = [
        "auto",
        # "bfloat16", # removed: FlashMLA kernel does NOT support bfloat16 KV cache
        "fp8_ds_mla",
        "fp8", # alias for fp8_ds_mla
    ]
    # ...

评论区精华

本 PR 没有实质性的讨论。zyongye 审核并批准了 PR。

• 暂无高价值评论线程

风险与影响

• 风险：此 PR 风险极低：
  • 变更仅为修正声明常量，不涉及任何运行时逻辑。
  • 移除了后端不支持的数据类型，用户将无法再选择错误的 KV cache 类型，执行路径更安全。
  • 没有测试文件变更，但此类声明修正通常不需要测试，因为属于类型定义。
  • 影响：影响范围小，仅影响 DeepSeek V4 模型的稀疏 MLA 后端的 KV cache 数据类型声明。用户将无法再为 FLASHMLA_SPARSE_DSV4 选择 bfloat16 KV cache（之前选择它会导致运行时错误），为 FLASHINFER_MLA_SPARSE_DSV4 选择 fp8_ds_mla KV cache（同样会导致运行时错误）。文档修正有助于用户正确配置。
  • 风险标记：暂无

关联脉络

• PR #44699 [DSV4] Decouple DS V4 Sparse MLA Metadata from DS V3.2: 本 PR 正是修复 #44699 引入的问题——FlashMLABackend 错误声明了 bfloat16 支持，FlashInfer 后端错误声明了 fp8_ds_mla 支持。