执行摘要

• 一句话：为 FlashMLA KV 内核添加 q-head padding，支持纯 TP 配置下的 FP8 注意力计算。
• 推荐动作：建议精读 nsa_backend.py 中的填充实现，关注 _forward_flashmla_kv 方法的设计决策；同时注意默认配置变更对部署的影响。

功能与动机

FlashMLA 内核要求 q 头数为 64 或 128，但在纯 TP 配置中，头数被 TP 分割（如 GLM-5 的 64 头 / TP8 = 8 头），导致内核失败。PR body 指出：'Adds q-head padding for flashmla_kv to support pure-TP configurations.'，Issue 评论中 Fridge003 提到：'We should do some padding when flashmla is set as the decode backend ... It's at least better than broken'。

实现拆解

主要改动在三个文件：1) nsa_backend.py：在 __init__ 中添加 flashmla_kv_num_q_heads 计算逻辑，根据模型头数决定填充目标（64 或 128）；在 init_forward_metadata 中确定是否使用 flashmla_kv；在 _forward_flashmla_kv 中实现填充和切片操作。2) server_args.py：更新 Hopper FP8 默认预填充后端为 flashmla_kv，移除 flashmla_auto 的启发式选择。3) deepseek_v32.md：文档更新以反映新默认配置和硬件特定行为。

关键文件：

• docs/basic_usage/deepseek_v32.md（模块 documentation）: 更新 DeepSeek V3.2 使用文档，反映默认注意力后端变更和硬件特定行为。
• python/sglang/srt/layers/attention/nsa_backend.py（模块 attention）: 核心实现文件，添加 q-head padding 逻辑以支持 FlashMLA KV 内核在纯 TP 配置下的运行。
• python/sglang/srt/server_args.py（模块 server configuration）: 修改服务器参数默认设置，将 Hopper FP8 预填充后端从 flashmla_auto 更改为 flashmla_kv。

关键符号：init, init_forward_metadata, _forward_flashmla_kv, _compute_flashmla_metadata

评论区精华

Issue 评论中，Fridge003 和 mmangkad 讨论了 padding 的必要性：Fridge003 建议参考 PR #13646 进行 padding，认为比 broken 好；mmangkad 最初担心 prefill 的内存开销，但最终采纳填充方案并实现切片。结论是添加 padding 以支持纯 TP 案例，同时保持输出正确性。

• Padding 设计和必要性 (design): 添加 padding 逻辑到 nsa_backend.py 中，确保 FlashMLA KV 内核在头数不足时正常工作。

风险与影响

• 风险：风险包括：1) 内存开销：填充 q 头到 64/128 可能增加临时内存使用，尤其在 prefill 阶段；2) 性能影响：额外的填充和切片操作可能引入轻微开销；3) 正确性：切片操作需确保输出与原始头数匹配，可能存在边界情况错误；4) 兼容性：默认配置变更可能影响现有部署，需用户注意。
• 影响：影响范围：1) 用户：纯 TP 配置下的 FP8 模型（如 GLM-5, DeepSeek V3.2）现在可正常运行，提升模型支持范围；2) 系统：注意力计算逻辑扩展，增加代码复杂性，但修复了关键限制；3) 团队：需维护新 padding 逻辑，并确保测试覆盖。
• 风险标记：内存开销增加, 默认配置变更, 潜在性能开销

关联脉络

• PR #21166 [Not-Merge][AMD] GLM-5 performance optimization: 修改相同文件 nsa_backend.py，涉及注意力内核的后端优化，可能与本 PR 的 padding 逻辑有技术关联。