tilegym-improve-cutile-kernel-perf

cuTile 内核性能迭代优化

在 TileGym 仓库中，系统地分析性能、诊断瓶颈，并迭代调优 cuTile 内核的性能。

说明

按顺序完成三个阶段：Setup 环境并建立基线，运行带有跟踪日志的 Experimentation 循环，然后持续迭代 The experiment loop，直到达到性能目标或收益趋于平稳。

Setup

与用户一起准备优化环境：

1. 创建一个新的 git 分支：建议分支名称，例如从当前分支创建 cutile-perf-<kernel_name>-<date>。执行 git checkout -b <branch name>

2. 定位目标内核：

   • cuTile 内核位于 src/tilegym/suites/<suite>/cutile/ 或 src/tilegym/ops/cutile/ 下
   • 阅读内核文件并识别：由 @ct.kernel 装饰的函数、启动封装（ct.launch() 或 ct_experimental.autotune_launch()）、@register_impl 注册，以及当前的自动调优配置（如有）

3. 对内核进行分类：

   • 算术强度 < 10 → 受内存限制
   • 算术强度为 10-50 → 均衡
   • 算术强度 > 50 → 受计算限制

   注意：分类仅用于选择实验循环中的优化优先级。核心指标始终是 latency (ms)。

4. 检查 GPU 环境：

   • 确保有可用的 GPU 节点（Blackwell 或 Ampere GPU）
   • 后续所有基准测试命令都应在 GPU 节点上运行

5. 阅读相关参考资料：

   • references/optimization-playbook.md：各项优化（A 到 J）的分步方案，附有优化前后的代码示例
   • references/perf-knobs-catalog.md：所有可调参数的完整目录（TMA、持久化调度、占用率、分块尺寸、延迟提示等）
   • references/cutile-api-reference.md：cuTile API 参考和 18 条关键规则
   • references/performance-model.md：Roofline/性能模型、瓶颈诊断、自动调优
   • references/ir-dump-guide.md：IR 转储、分析和错误诊断
   • references/cutile-patterns-reference.md：常见 cuTile 模式和转换速查表

6. 创建 @sandbox/perf_results.md 以跟踪进度。首次运行会写入基线

7. 确认后开始：获得确认后，启动实验

Experimentation

每轮实验只对目标内核应用一项优化，验证正确性、重新进行基准测试并记录结果。每轮实验必须在 10 分钟内完成。

目标

• 改进核心指标：降低 latency (ms)
• 满足核心约束：正确性不得退化——每项优化都必须保持数值正确性。与基线相比，latency (ms) 的退化幅度不得超过 2%。

可更改内容

• src/tilegym/suites/<suite>/cutile/ 或 src/tilegym/ops/cutile/ 下的目标内核文件：内核主体、分块尺寸、占用率、num_ctas、TMA 用法、延迟提示、flush_to_zero、自动调优配置、持久化调度及其他 cuTile 专属参数
• 内核的启动封装：网格计算、自动调优配置空间
• @sandbox/：可以添加新文件或修改你创建的文件，但不要将其提交到 git

不可更改内容

• 内核功能语义（输入、输出及容差范围内的数值行为）
• 测试基础设施和基准测试工具
• 上述列表以外的任何内容

实验输出说明

正确性测试：

python -m pytest tests/suites/.../test_<kernel_name>.py -k "test_ and cutile and not test_perf" -v

性能基准测试：

每轮迭代：

1. 运行 pytest 基准测试：python -m pytest ... --print-record → 提取延迟（ms）
2. 在 perf_results.md 中记录延迟

基准测试命令行：

python -m pytest tests/suites/.../test_<kernel_name>.py -k "test_perf and cutile" --print-record -v

延迟样本：

Cutile: {'forward': {'mean': 3.7903138461538455, 'std': 0.0016941310873207053, 'rel_std': 0.044696327430505396, 'median': 3.789880999999999, 'min': 3.7883389999999992, 'max': 3.7941230000000004, 'nrep': 13, 'peak_mem_mb': 913}} ms

跟踪实验进度

使用 @sandbox/perf_results.md 记录每次迭代的结果。文件中只能包含一个有 5 列的 Markdown 表格：

• iteration：迭代编号，从 0（基线）开始
• optimization：应用的优化（例如，“baseline”“TMA replace gather”“persistent scheduling”）
• latency_ms：内核延迟（毫秒），保留 6 位小数
• correctness：PASS 或 FAIL
• status：此迭代的状态，可以是 keep、revert 或 crash

示例内容：

| iteration | optimization       | latency_ms | correctness | status |
|----------:|:-------------------|-----------:|:------------|-------:|
| 0         | baseline           |   0.820000 | PASS        | keep   |
| 1         | TMA replace gather |   0.390000 | PASS        | keep   |

如果文件为空，则创建表头。每次迭代追加一行。

基线

第一次迭代（迭代 0）不会更改任何代码，只运行正确性测试和性能基准测试。结果将作为基线列在第一行。

实验循环

核心方法是每次迭代从 playbook 中应用一项优化，验证正确性、进行基准测试，并决定保留还是回退。每次只尝试一项优化，并保持实验记录清晰。

循环：

1. 检查 git status：确认当前所在的 git 分支/提交

2. 从 references/optimization-playbook.md 中选择并应用一项优化：

3. 验证正确性——如果失败，立即回退。常见原因：flush_to_zero/rounding_mode=APPROX 改变了结果、tile size 越界、allow_tma=False 语义不符、持久化循环边界错误

4. 重新进行基准测试，并与当前基线比较

5. Git 提交

6. 将结果记录到 @sandbox/perf_results.md

7. 决策规则：

   结果	操作
   提升（latency (ms)）>= 5%	接受为新基线，继续
   提升 2-5%	接受，降低下一次迭代的优先级
   提升 < 2%	接受，但停止，除非用户希望继续
   任意配置出现回退	立即回退，尝试下一项优化
   连续 2 次迭代均无提升	停止
   根本原因是 scheduling 或 unknown	上报用户

8. 如果保留，则更新基线数据并继续循环

9. 如果回退，则将 git reset 到开始时的状态，并按优先级顺序尝试下一项优化 直到：所有尝试均已完成，或迭代次数超过 25 次，或用户中断

自主执行：在设置阶段向用户询问需要澄清的问题。进入实验循环后，不要暂停并询问用户反馈：运用最佳判断做出决策，及时查阅 optimization playbook 和性能调节参数目录；如果遇到困难，则深入思考。