docs(perf-attn): KV-0冗余 prefix sharing attention mask 方案设计与分析

[Jackie2049]

概述

新增 docs/developer-docs/impr-perf-attn.md（892 行）—— PrefixSharing 性能优化的下一阶段方向文档：从当前「物理 KV 展开（流派 C）」迁移到「扁平打包 + attention mask（流派 D）」实现 KV-0冗余。文档涵盖完整的研究分析、方案设计、测试验证路径和分阶段开发计划。本 PR 含 3 个 commit（初稿 + 文件改名 + build_kv 梯度描述修正），纯文档新增，不涉及任何代码改动。

设计简介

• 核心问题：当前 build_kv 把 provider prefix 在 KV 张量中物理复制 N 份（N = reuser 数），KV 尺寸从 P+S 膨胀到 P+N*S，带宽随 rollout group size 线性增长。
• 目标方案：用 block-causal / block-sparse attention mask 控制可见性，替代 data duplication——prefix KV 只存一份，Q/K/V 均为去重扁平布局，单次 forward pass，数学严格等价。
• 四条 kernel 适配路线：GPU 走 PyTorch FlexAttention（推荐，rectangle spec 而非 full mask）、MagiAttention FFA（替代）、TE attention_mask（Megatron 原型）、NPU npu_fusion_attention。
• 三阶段开发计划：Phase 1 原型验证（Mask 构造工具 + TorchRef mask-based attention + CPU 正确性）→ Phase 2 GPU/NPU 路径（TE bias / NPU fusion_attention mask + 性能对比）→ Phase 3 集成优化（verl FSDP/Megatron engine 集成 + mask 内存优化 + 多级树支持）。

关键变更

• 新增 docs/developer-docs/impr-perf-attn.md（+892 行），包含四大章节：
  • §1 研究分析：问题定义（现有 build_kv 物理展开瓶颈 + 零冗余目标）、两个流派对比（物理展开 vs 扁平打包+mask）、与 miniFLUX/BTT mask 方案关联、FA varlen vs FA causal mask 性能差异、现有代码分析（build_kv 全链路 + 三个 Backend mask 机制 + plan/store/layout 角色变更）、业界调研（RFC #6401 Meituan/SandAI 最相关方案 + FA varlen causal mask 技术限制 + kernel 选择全景表）
  • §2 方案设计：总体架构（核心思路 + 转换流程对比 + 模块变更清单）、Mask 构造算法（扁平 GRPO 场景 + 多级树 chain 场景 + 与 DTA/RFC #6401 AttnSlice 对比）、Mask 格式与 kernel 适配（GPU FlexAttention / MagiAttention FFA / TE / NPU 四条路线 + 适配总结）
  • §3 测试验证：正确性验证（mask 构造数值验证 + 与 build_kv 数学等价性 + 梯度等价性）、性能基准（单 batch 对比 + NPU 场景 + baseline 对比）
  • §4 开发计划：三阶段里程碑
• commit 37d57367：修正 build_kv 梯度描述——实际代码用 .copy_() 而非 clone+detach，梯度通过 copy_ 回流，原文档表述有误。

测试结果

• 本 PR 为纯文档新增（+892/-0，无代码变更），无可执行测试。
• 文档内嵌的 §3 测试验证章节是设计层面的验证路径规划，尚未在本 PR 中落地为实际脚本或数值结果——Phase 1 原型验证完成后才会回填实测数据。

遗留问题

• 分支落后 base 87 commits：open-source_perf-attn 相对 open-source_refactor behind_by=87，合并会产生 merge commit 或需先 rebase。由于本 PR 只新增一个 docs/ 文件，与 refactor 侧 87 个 commit 产生路径冲突的概率极低。
• 文档内尚无实测数据：§3 测试验证和性能基准章节目前是方法设计，Phase 1（mask 构造工具 + TorchRef 原型）完成后需回填实际数值。
• kernel 路线选择未定：四条路线（FlexAttention / MagiAttention / TE / NPU）的 §2.3.5 适配总结是设计建议，最终落地哪条取决于 PoC 阶段（open-source_attention 分支上正在进行的 FlexAttention PoC）的实测结果。