optimization-catalog

优化目录路由器

将此技能用作调度器。共享的根知识库仍是适用于多种实现语言的算法模式的权威存放位置。语言专属叠加层则记录与特定 DSL 或编程模型相关的实现细节。

加载顺序

1. 如果模式属于算法层面，请阅读 docs/knowledge/optimizations/ 和 docs/knowledge/anti-patterns/ 下的共享根知识。
2. 加载所选实现语言对应的语言专属优化目录技能。
3. 仅当实现细节取决于该语言对应的接口时，才阅读 docs/knowledge/languages/<language>/... 下的语言叠加层。

语言专属目录技能

语言键	加载此技能	语言专属知识根目录
cutile-dsl	/optimization-catalog-cutile-dsl	docs/knowledge/languages/cutile-dsl/
cute-dsl	/optimization-catalog-cute-dsl	docs/knowledge/languages/cute-dsl/

分类规则

• 共享根目录中的目录用于记录可跨 DSL 复用的算法模式、工作负载形状规则和反模式。
• 语言叠加层用于记录依赖特定 API、编译器行为、代码生成接口或调度模型的实现细节。
• 如有疑问，将可复用机制保留在共享根目录中，仅针对实现接口添加语言专属叠加层。

当前迁移状态

• docs/knowledge/optimizations/ 和 docs/knowledge/anti-patterns/ 中的共享根目录仍是保持兼容的基线。
• 新的语言专属叠加层正在添加到 docs/knowledge/languages/ 下。
• 在迁移期间，指向旧根目录路径的现有引用仍可使用。

知识库原则

此目录旨在积累可复用的 cuTile 内核设计知识，而非收集设备传闻。

因此，每个条目都必须写成：

• 可跨内核复用的模式或反模式，
• 并清楚说明其适用的上下文，
• 明确列出受影响的性能指标，
• 在适用时，将证据分为本地验证和通用结论。

如果设备和架构信息有助于明确规则，欢迎纳入，例如：

• Blackwell 或 Hopper 等架构系列，
• Tensor Cores、TMA、线程块集群、调度器行为或共享内存限制等架构特性，
• 设备级规格，例如峰值 FP16/BF16 TFLOP/s、峰值内存带宽、拐点、SM 数量、每个 SM 的寄存器数量或 SMEM 容量。

但这些信息必须转化为可复用的指导。除非某项观察仅用于支持更广泛的模式，否则条目应避免简化为“设备 Y 上的内核 X 适合配置 Z”。

此目录的工作方式

1. 下方的索引将触发条件映射到优化方案和详情文件
2. 编排器读取索引，根据分析结果选择优化方案
3. 内核设计者读取详情文件，实现特定优化
4. 新增优化：在 docs/knowledge/optimizations/ 中创建详情文件，并在索引中添加一行
5. 失败的优化：在 docs/knowledge/anti-patterns/ 中创建反模式，并在下方添加一行

优化索引

ID	优化项	触发条件	预估影响	注意事项	详细文件
O1	Split-KV 按比例分配 block	双路径内核中的潜变量与解压缩工作量严重失衡；平均分配 block 会导致某一路径资源不足	很高	需要归约内核和中间张量	docs/knowledge/optimizations/split-kv.md
O2	按 Head 分组以复用共享操作数	同一操作数会在多个 Head 间复用（例如潜变量 Z），且 Bh=1 会导致每个 Head 的 MMA 规模过窄或 TC 利用率接近零	很高	会增加寄存器压力；不适用于解压缩后的 K/V 等仅供单个 Head 使用的操作数	docs/knowledge/optimizations/head-grouping.md
O3	独立路径调度	采用 Split-KV 后，潜变量路径和解压缩路径仍需要不同的流式粒度或加载调度	低至中	如果寄存器压力和占用率没有改善，收益有限	docs/knowledge/optimizations/independent-tiles.md
O4	Swizzle 调度	分块内核会在相邻 CTA 间复用一个操作数，且 block 顺序对 L2 局部性的影响可测量	低	计算受限的内核可能只有微小收益；一维重映射会增加索引开销	docs/knowledge/optimizations/swizzle.md
O5	延迟提示	内核结构已合理，但仍需调优加载与计算的重叠；且各路径的 DRAM 压力差异足够大，编译器指导可能有助于调度	低	难以单独评估；提示只是建议，并非保证	docs/knowledge/optimizations/latency-hints.md
O6	CGA 线程 block 集群	Hopper 及更新架构的内核存在实际的 CTA 间数据共享机会，或需要正确理解 num_ctas 语义和集群启动行为	中	与硬件相关；如果没有实际共享收益，很容易误用	docs/knowledge/optimizations/cga.md
O7	在线 softmax 的快速数学	在线 softmax 循环大量使用 exp2/除法；更大的 tile 会导致计算吞吐量骤降；且可接受使用降低精度的推理数学运算	高	不能替代合理的分块；如果溢出或带宽成为主要瓶颈，收益会减少	docs/knowledge/optimizations/fast-math-online-softmax.md
O8	因果 K 循环拆分	因果注意力包含大量完全未屏蔽的 K tile，只有对角线/尾部 tile 需要屏蔽逻辑，且可以跳过后续 tile	中至高	如果目标瓶颈不再显著受屏蔽影响，效果可能持平或变差	docs/knowledge/optimizations/causal-k-loop-split.md
O9	因果 ProgramId 重映射	三角形工作分布会导致 CTA 间出现波尾不均衡，且可以简单反转启动顺序	低至中	如果工作分布已经均匀或网格很小，收益有限	docs/knowledge/optimizations/causal-program-id-remap.md
O10	自适应 tile 和占用率自动调优	最佳 tile/占用率取决于序列长度或设备能力；固定的手动配置会导致短形状利用不足，或长形状过度占用资源	高	如果搜索空间未经筛选，规模可能急剧膨胀；无法挽救结构有缺陷的内核	docs/knowledge/optimizations/adaptive-tile-autotuning.md
O11	流水线驱动的低占用率调度	每个 CTA 不可避免的状态量很大，导致每个 SM 只能运行一个 CTA 或占用率很低；内核必须依靠重叠和调度取胜，而非增加驻留 warp 数量	高	需要架构/DSL 支持细粒度调度；不能用单体 CTA 来模拟	docs/knowledge/optimizations/pipeline-driven-low-occupancy.md

反模式索引

ID	反模式	失效模式	来源	详细说明文件
A1	异构路径采用相等的分块拆分	对不等量的潜在计算与解压计算进行 50/50 分块分配，会造成串行瓶颈，而非实现重叠	MLA-var6+ V0	docs/knowledge/anti-patterns/equal-block-split.md
A2	TILE_M=1 合并/解压	单行合并 GEMM 会禁用 Tensor Cores，并在较小的 s 下留下持续的尾部开销	MLA-var6+ V0/V2/V3	docs/knowledge/anti-patterns/tile-m-one-combine.md
A3	持久化并发度不足	常驻 block 预算低于 SM 数量，会导致 GPU 空闲，使重叠处理失效	MLA-var6+ V4	docs/knowledge/anti-patterns/underfilled-persistent.md
A4	达到寄存器上限的持久化阶段	持久化内核达到寄存器上限（每线程 255 个寄存器），导致占用率骤降，并受延迟限制	MLA-var6+ V4	docs/knowledge/anti-patterns/spill-heavy-persistent.md
A5	盲目移植大型分块	从其他设备复制分块形状，却未重新验证寄存器、SMEM、本地内存流量和网格大小，会越过资源临界点	FlashAttention 学习链	docs/knowledge/anti-patterns/blind-large-tile-port.md
A6	统一因果掩码	在每个 K 分块上都执行完整的因果掩码逻辑会浪费计算，因为大多数分块要么完全有效，要么完全跳过	FlashAttention 学习链	docs/knowledge/anti-patterns/uniform-causal-masking.md
A7	小于 16 的 MMA 维度	将任一有效 MMA 维度（M、N 或 K）缩小到 16 以下，通常会破坏 Tensor Core 覆盖率并使延迟激增，而非解决占用率问题	FlashMLA V1 手动探测 + Tensor Core 形状约束	docs/knowledge/anti-patterns/sub-16-mma-dimension.md
A8	盲目翻转数据流	将资源敏感型 Tensor Core 内核改写为代数等价的操作数方向，会显著改变代码生成，导致重新出现溢出或恶化 SMEM 行为	FlashMLA V1 → V2	docs/knowledge/anti-patterns/blind-dataflow-flip.md

交叉参考：指标 → 优化

性能分析指标状态	可能的优化
耗时相同的内核执行了明显不同的工作量	O1（Split-KV 按比例分配块）
Bh=1，或多个头在共享操作数上分别执行瘦身 MMA	O2（头分组）
Split-KV 后，双路径内核的性能停滞在接近脊点的位置	O3（独立路径调度）
L2 命中率 < 90%，且相邻 CTA 重新加载了相同的操作数分块	O4（Swizzle 调度）
内核结构相同，但路径级内存压力不同，表明编译器调度变更可能会有帮助	O5（延迟提示）
Hopper 及更新架构上的跨 CTA 数据共享，或对 num_ctas 实际控制内容的疑惑	O6（CGA 线程块集群）
Tensor Core/MMA 结构合理，但在线 softmax 的特殊函数主导了热点循环	O7（在线 softmax 快速数学运算）
因许多 K 分块完全有效、未来分块完全跳过，因果内核仍在掩码/控制流上耗费大量时间	O8（因果 K 循环拆分）
因果/三角形工作负载显示 CTA 之间存在尾部负载不均，或各波次完成时间不一致	O9（因果 ProgramId 重映射）
短形状无法充分利用 GPU，而长形状更适合不同的分块或占用率提示	O10（自适应分块与占用率自动调优）
寄存器/SMEM 限制导致每个 SM 只能运行一个 CTA，可运行 warp 数很低，且内核受计算限制但仍未充分利用 Tensor Core	O11（由流水线驱动的低占用率调度）
合并阶段的 TILE_M=1 且 TC Util = 0%	A2（TILE_M=1 合并/解压缩）
持久驻留块数 < SM 数，或波次数/SM < 1	A3（持久化并发不足）
持久化阶段达到每线程 255 个寄存器，且占用率只有个位数	A4（寄存器上限导致的持久化阶段限制）
移植大型分块后，在目标设备上导致寄存器/SMEM 瓶颈、本地内存流量或网格规模骤减	A5（盲目移植大型分块）
尽管存在明显的完全有效区和完全跳过区，因果掩码逻辑仍被均匀地应用于所有 K 分块	A6（统一因果掩码）
候选分块使任何有效 MMA 维度小于 16，或更改为“更小分块”后 Tensor Core FLOPs 远低于算法 FLOPs	A7（MMA 维度小于 16）
提议的优化只是代数上的操作数/数据流转换，尤其是在接近寄存器或 SMEM 瓶颈时	A8（盲目转换数据流）

知识库更新协议

如需查看完整更新协议、详细文件模板和分步说明，请加载 /orchestration-workflow 技能。