# PR #28595 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[FA3] Add unit test for only_qv (NoPE) KV decode path
- 合并时间：2026-06-18 14:41
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/28595

---

# 执行摘要

- 一句话：为 FA3 only_qv (NoPE) 解码路径添加单元测试
- 推荐动作：结构清晰，适合需要了解 FA3 only_qv 测试方法的开发者阅读。合并后可增强注意力内核的可靠性。建议在后续 FA3 架构扩展时更新跳过条件。

# 功能与动机

FA3 为 SM90 (Hopper) 引入了 only_qv (NoPE) 解码路径，用于稀疏 MLA 场景。该路径跳过 QK^T 矩阵乘法，直接计算 softmax(qv * V)，需要单元测试保证其在 paged V cache 下的正确性和数值稳定性。PR body 明确说明 'Add Unit Test Add unit test for NoPE kv.'

# 实现拆解

1. 创建新测试文件 test/registered/jit/test_flash_attention_3_only_qv.py，并引入必要的依赖（pytest、torch、einops、flash_attn_with_kvcache 等）。
2. 定义参考函数 _only_qv_reference，通过 PyTorch 张量操作模拟等效计算：从 v_cache 和 page_table 重构 V，使用 einsum 和 softmax 得到注意力输出。
3. 使用 pytest 的 @parametrize 装饰批量大小 (1,2)、序列长度 (129,257)、查询头数 (8,16) 组合，生成参数化测试函数 test_flash_attn_kvcache_only_qv。
4. 在测试函数中初始化随机张量，分别调用参考函数和 flash_attn_with_kvcache（设置 only_qv=True, ver=3），对比输出并断言最大误差 <= 8e-3、平均误差 <= 3e-4。
5. 添加 unittest 包装类 TestFlashAttentionV3OnlyQV，支持直接通过 python -m unittest 运行；通过 register_cuda_ci 注册到 CI 套件（base-b-kernel-unit-1-gpu-large），并设置跳过条件仅允许 SM90 架构执行。

关键文件：
- `test/registered/jit/test_flash_attention_3_only_qv.py`（模块 单元测试；类别 test；类型 test-coverage；符号 _only_qv_reference, test_flash_attn_kvcache_only_qv, TestFlashAttentionV3OnlyQV, test_only_qv_smoke）: 新增的单元测试文件，核心变更，覆盖 FA3 only_qv 解码路径。

关键符号：_only_qv_reference, test_flash_attn_kvcache_only_qv, TestFlashAttentionV3OnlyQV.test_only_qv_smoke


# 评论区精华

1. **测试注册方式**：Fridge003 建议不需要注册为 nightly test，DovenImp 回应 'done'。最终文件仅使用 register_cuda_ci 注册到常规 CI 套件，未涉及 nightly。
2. **跳过条件**：Fridge003 指出测试应跳过 compute capability >= 10 的设备，DovenImp 回应 'done'。最终 skip_condition 为 `torch.cuda.get_device_capability()[0] != 9`，即仅允许 SM90，已覆盖 sm100+ 跳过。

- 测试注册方式：是否需要注册为 nightly test？ (testing): 移除了 nightly 注册，仅保留常规 CI 套件注册（register_cuda_ci 套件为 base-b-kernel-unit-1-gpu-large）。
- 跳过条件：应跳过 compute capability >= 10 的设备 (correctness): 跳过条件已包含 sm100+，同时也跳过了 pre-Hopper 架构，符合预期。

# 风险与影响

- 风险：低风险。纯测试文件新增，不涉及生产代码。主要风险在于跳过条件可能未完全覆盖未来 FA3 支持的新架构（如 Blackwell+），但当前条件正确排除了非 SM90 设备。误差阈值（max 8e-3, mean 3e-4）基于参考实现与内核的数值差异设定，相对宽松但合理。
- 影响：直接影响：为 CI 增加约 30 秒的测试用例，提供 FA3 only_qv 功能的回归保护。对生产系统、用户无运行时影响。团队可依赖此测试验证后续对 only_qv 路径的修改。
- 风险标记：低风险 , 仅覆盖 sm90 架构

# 关联脉络

- 暂无明显关联 PR