执行摘要
此 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。
- 代码示例：
python
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，以简化用户体验并提高可靠性，尤其是在混合模型等复杂架构中。
参与讨论