执行摘要

此 PR 修复了混合模型在使用 --calculate-kv-scales 时导致 FP8 KV 缓存比例损坏的严重 bug，通过自动禁用该选项并记录警告，防止输出腐败，影响使用混合模型和 FP8 的用户，提升了系统鲁棒性。

功能与动机

修复 issue #37554。当在混合模型（如 Qwen3.5）中使用 --calculate-kv-scales 时，循环层（GDN、Mamba、SSM）在校准虚拟前向传播中状态未初始化，产生垃圾激活，损坏 FP8 KV 比例，导致输出幻觉、话题循环和胡言乱语。由于 --calculate-kv-scales 已弃用（将在 v0.19 移除），PR 选择禁用它以保护用户体验，避免静默错误。

实现拆解

修改 vllm/model_executor/models/config.py 中的 HybridAttentionMambaModelConfig.verify_and_update_config() 方法：

• 关键逻辑：在方法开头添加代码块，检查 cache_config.calculate_kv_scales。
• 代码示例：
  

  if cache_config.calculate_kv_scales:
      logger.warning(
          "Disabling calculate_kv_scales for hybrid model '%s'. "
          "Hybrid models with recurrent layers (GDN, Mamba, SSM) "
          "produce unreliable KV cache scales during the "
          "calibration pass because recurrent state is "
          "uninitialized. Using default scale of 1.0 instead.",
          vllm_config.model_config.model,
      )
      cache_config.calculate_kv_scales = False
  

• 模块影响：所有注册的混合模型都会自动应用此逻辑，确保比例计算被禁用。

评论区精华

• 警告消息设计：gemini-code-assist[bot] 指出："The warning message specifically mentions 'FP8 KV cache scales' ... could be confusing for users who are not using fp8 cache." Young-Leo 响应并更新代码，移除 'FP8' 特异性，使警告更通用。
• 修复弃用选项的合理性：vadiklyutiy 询问："From other side it is a bit unclear why we should fix it if it be deprecated very soon..." mgoin 解释："there is no alternative at the moment ... I wanted to remove confusion for the users and simplify." Young-Leo 补充："this lightweight change can save current users from some frustrating debugging experiences."
• 添加 issue 引用：vadiklyutiy 要求："Could you add ref to the issue here pls"，Young-Leo 在代码注释中添加 issue 链接，增强可追溯性。

风险与影响

• 技术风险：风险较低，变更仅涉及配置验证，不修改核心推理路径。但警告消息需保持清晰，避免用户混淆；依赖于弃用逻辑，未来移除时需同步清理。
• 影响分析：对使用混合模型和 FP8 KV 缓存的用户，修复了严重输出损坏问题，影响程度高。对系统，提升了鲁棒性，防止静默错误传播。不影响其他模型或功能，范围有限。

关联脉络

• 与 PR #37201 相关，后者引入了 --calculate-kv-scales 的弃用，本 PR 是弃用路径上的一个补丁，帮助当前用户过渡。
• 在更大的功能演进中，反映了 vLLM 在量化校准策略上的转变：从动态计算比例（通过 --calculate-kv-scales）转向依赖预校准比例或默认值 1.0，以简化用户体验并提高可靠性，尤其是在混合模型等复杂架构中。