AKO4PTO 任务要求规范用 TASK_REQUIREMENTS.md 为 PTO 算子优化设定边界、指标与行为约束【免费下载链接】pto-isaParallel Tile Operation (PTO) is a virtual instruction set architecture designed by Ascend CANN, focusing on tile-level operations. This repository offers high-performance, cross-platform tile operations across Ascend platforms.项目地址: https://gitcode.com/cann/pto-isa导读在 CANN pto-isa 仓库的 AKO4PTOAgentic Kernel Optimization for PTO工作流中TASK_REQUIREMENTS.md是每个算子优化项目立项时自动生成的第一份约束文件它以结构化的方式固化默认测试 shape、优先优化规模、文件可编辑边界、行为保持约束和重点性能指标并附带面向调优 Agent 的行为纪律提示。本文基于 project_template 下的 TASK_REQUIREMENTS.md 模板结合 task.md 主流程与 runs 迭代模板完整讲解该文件的每一项配置如何书写、如何被后续迭代协议消费以及如何借助它保证优化正确、可衡量、可重复、瓶颈驱动。一、TASK_REQUIREMENTS.md 在 AKO4PTO 工作区中的定位AKO4PTO 是一个多算子、多项目隔离的 PTO 算子调优工作区见 README.md核心设计目标是不污染原始pto-kernels目录每个算子使用独立项目目录在各自项目的隔离副本中修改代码通过远程 Ascend 环境做 benchmark 验证对每一轮调优保留完整记录。每个算子项目由project_template/复制而来其标准结构为project_template/ ├── TASK_REQUIREMENTS.md # 当前任务的附加要求本文主题 ├── ITERATIONS.md # 每轮迭代的简约摘要表 ├── context/ # 可选的共享参考资料 ├── runs/ # 每轮产物iter-XXX/files.txt, patch.diff, notes.md │ ├── _template/ │ └── README.md └── workspace/ # 被隔离修改的 PTO 代码副本 └── README.md按照 task.md 主流程 的第 4 步Agent 在确认算子、case 和远程环境后会自动创建项目工作区并根据用户提供的 case 信息自动生成TASK_REQUIREMENTS.md含算子名、case 配置、可调参数等随后向用户确认是否需要修改context/参考资料和本文件。也就是说这份文件是用户意图 → Agent 可执行约束之间的契约载体它写在优化开始之前贯穿整个迭代过程。二、附加要求区五类核心约束的写法与含义模板的Task Requirements一节明确列出了可以写的内容共五大类。下面逐一结合仓库实际讲解每类的用途、写法要点与下游影响。1. 指定默认测试 shape- 指定默认测试 shape例如 BNSD1,16,8192,512这是给 benchmark 设定一个默认且可复现的输入规模。在 task.md 的确认优化 Case步骤中shape、dtype、是否 causal mask 等构成一次优化的 case 配置写成BNSD1,16,8192,512这样的紧凑形式可以让后续所有构建与 benchmark 命令如generate_cases.py --cases ...、gen_data.py --cases ...、./fa_performance --cases ...统一引用同一组规模避免每轮各跑各的导致前后不可比。从源码结构看PTO-tile-lib 场景如fa_performance正是通过--cases case_config字符串把 shape 配置传入编译期 case 生成与数据生成脚本的因此把默认 shape 固化在TASK_REQUIREMENTS.md中等价于固化了Benchmark 纪律里强调的相同 workload 原则——前后对比必须使用相同 case否则数据无意义。2. 指定必须优先优化的输入规模- 指定必须优先优化的输入规模当算子在多个 shape 下表现差异显著时例如长序列小 batch 的 attention、大 batch 小 head 的 FFN这一项用于告诉 Agent先打哪块靶。它和默认 shape 的区别在于默认 shape 解决可复现优先规模解决优先级排序。在迭代协议中连续多轮实验如果只优化了次要 shape会被视为偏离任务目标有了这一条Agent 每次选假设、排实验顺序时都应以该规模为准。3. 指定不允许修改的文件或模块- 指定不允许修改的文件或模块这是对 task.md 可编辑范围 规则 的细化。默认规则是只允许修改算子 kernel 源码和紧密相关的参数配置不得修改 benchmark 脚本、运行 harness、测试逻辑、正确性阈值、workload shapes而本项允许用户把这条边界收得更紧例如- 不要改动与 flash_attention_score 无关的算子 - 不允许修改 workspace/kernel/include/ 下的公共头文件之所以要显式声明是因为 Agent 在自动寻优时可能为了绕过正确性检查或降低编译难度而触碰 harness 相关文件明确列出禁区可在意图层面直接阻断这类通过让 benchmark 变简单来提分的行为。4. 指定必须保留的行为约束- 指定必须保留的行为约束用于声明无论怎么优化都不能破坏的东西例如数值语义、causal mask 行为、输出 layout、API 签名等。它与上一项的区别在于文件边界约束管能不能动行为约束管动完之后必须保持什么。在 notes.md 模板 中Pre-Edit阶段要求填写Main risk其典型来源正是这里声明的行为约束——任何可能破坏该约束的改动都应被判定为高风险变更。5. 指定本次任务特别关注的性能指标- 指定本次任务特别关注的性能指标例如优先优化 TFLOPS 而非 latency关注 GMEM 搬运量下降或必须超越 torch_npu baseline 才计为 kept。这一项直接喂给迭代协议的结果判定环节kept的准确定义是结果正确且优于当前已知最好结果而最好的具体度量由任务要求决定同时它也会写进 ITERATIONS.md 摘要表 的Baseline / PTO两列作为每一轮的量化对比口径。三、编写示例的完整解析模板给出了一个可直接套用的文本块- 把默认的 size 改成 BNSD1,16,8192,512 - 优先关注 torch_npu baseline 对比 - 不要改动与 flash_attention_score 无关的算子逐条解析行对应约束类别实际作用把默认的 size 改成 BNSD1,16,8192,512默认测试 shape锁定 benchmark 与数据生成的统一规模保证前后可比优先关注 torch_npu baseline 对比重点性能指标把优化成败的参照系绑定到torch.nn.functional.scaled_dot_product_attention的 baseline 上与 task.md 第 7 步 的 torch_npu baseline 环节呼应不要改动与 flash_attention_score 无关的算子不允许修改的文件/模块缩小可编辑范围防止 Agent 动无关算子引入回归或混淆实验归因结合 task.md 可以看到这三条正好覆盖了 PTO-DSL 典型算子flash_attention_score的优化闭环先锁定 shape再锁定参照torch_npu最后锁定改动范围。这也说明TASK_REQUIREMENTS.md的最佳编写粒度是一算子一份、一 case 一组约束与一个项目只服务于一个算子的工作区原则保持一致见 workspace/README.md。四、Hints 区面向 Agent 的行为纪律模板的Hints一节给出了两条默认调优纪律它们属于流程级约束作用于每一轮迭代而非单个参数小步、隔离的 kernel 改动正确性失败是本轮迭代的硬性停止条件。这与 task.md 一轮一假设 与 正确性先于性能 两条优化规则完全对齐每轮只测试一个假设且必须按修改 → 构建 → 正确性测试 → 通过后才跑性能的顺序执行。正确性不通过时性能结果无效本轮直接终止并记录不允许放宽容差、不允许修改验证逻辑。若连续 3 轮无实质性改善必须重读remote.md、检查ITERATIONS.md的历史轮次、上网搜索额外优化思路并重新评估调优方向后再继续。这条对应 task.md 三轮失败规则停止盲目局部微调先复查瓶颈分类是否在攻击症状而非根因再寻找结构性变化。被重读的remote.md即 远程环境 Bring-Up 文档它承载 SSH 连通、工作区上传、Python 选择、依赖安装与 benchmark 验证等环境前置信息而ITERATIONS.md则是每轮一行简约摘要的流水账Iter / Hypothesis / Changes / Baseline / PTO / Correct / Result是快速复盘的最短路径。这两条 Hint 的模板注释还提示了可以追加的内容算子特定的约束或禁用设置、远程主机注意事项、建议尝试或避免的策略、Agent 行为控制、依赖策略例如不要安装任何包。用户或后续维护者可以在!-- ... --注释位置按需扩展。五、与迭代记录体系的配合从要求到证据TASK_REQUIREMENTS.md不是一份孤立文档它与项目模板中的迭代记录体系形成闭环ITERATIONS.md 提供逐轮摘要表是要求是否达成的追踪视图runs/_template/notes.md 提供单轮详档结构Pre-EditKernel / Current bottleneck / Evidence / Hypothesis / Why it should help on Ascend / Expected improved metric / Main risk→Changes修改类型、文件、旧值→新值、完整参数快照、基于哪一轮→Post-RunCorrectness / Performance / Stability / Result→Analysis→Nextruns/README.md 规定每轮必须保存files.txt、patch.diff、notes.md三件套调参类迭代的patch.diff按参数变更说明格式记录如PARAMold_value → PARAMnew_value。在实际执行中TASK_REQUIREMENTS.md中的约束会成为上述记录字段的输入例如重点关注 GMEM 搬运会出现在每一轮Current bottleneck的候选分类里task.md 的强制瓶颈分类表 共列出 GMEM traffic bound、UB/tile buffer pressure、small-transfer inefficiency、compute under-utilization、AIC/AIV imbalance、pipeline bubble、barrier/wait/sync overhead、register pressure、bad tile shape、dependency chain、CV FIFO pressure 等 11 类而必须保留的行为约束会成为Main risk与高风险变更判定如更大 tile 可能导致 UB 爆炸、删除 barrier 前缺少依赖证明等的依据。六、编写与使用的最佳实践清单综合模板本身与 task.md 主流程一份合格的TASK_REQUIREMENTS.md应满足具体到可执行shape、规模、指标都要给出可输入命令的具体值如BNSD1,16,8192,512避免尽量快一点这类无法验证的描述边界明确同时写清默认/优先做什么与禁止/保留不做什么防止 Agent 越界或目标漂移与参照系绑定写明要对比的 baseline如 torch_npu、PTO initial确保结果判定口径统一一项目一份每个算子项目独立维护随 case 变化而更新并在新一轮会话开始前重新确认task.md 第 8 步 要求每次新会话先读context/与TASK_REQUIREMENTS.md保留失败信息Hint 区鼓励追加避免的策略与Agent 行为控制让后一轮 Agent 直接继承前几轮的教训避免重复踩坑不替代码说话本文件只约束目标、边界与纪律不承载 benchmark 脚本逻辑可编辑性检查以 task.md 可编辑范围 为准。七、小结在 AKO4PTO 工作流中TASK_REQUIREMENTS.md扮演着任务契约的角色它把用户在 shape、规模优先级、文件边界、行为约束与性能指标上的意图翻译成 Agent 在每一轮迭代中必须遵守的硬约束并与ITERATIONS.md、runs/iter-XXX/三件套、remote.md环境文档、notes.md单轮详档共同构成要求 → 实验 → 证据 → 复盘的完整闭环。掌握它的五类约束写法与 Hint 纪律是让 PTO 算子优化从随机 trial-and-error走向瓶颈驱动、可衡量、可重复的第一步。【免费下载链接】pto-isaParallel Tile Operation (PTO) is a virtual instruction set architecture designed by Ascend CANN, focusing on tile-level operations. This repository offers high-performance, cross-platform tile operations across Ascend platforms.项目地址: https://gitcode.com/cann/pto-isa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AKO4PTO 任务要求规范：用 TASK_REQUIREMENTS.md 为 PTO 算子优化设定边界、指标与行为约束
AKO4PTO 任务要求规范用 TASK_REQUIREMENTS.md 为 PTO 算子优化设定边界、指标与行为约束【免费下载链接】pto-isaParallel Tile Operation (PTO) is a virtual instruction set architecture designed by Ascend CANN, focusing on tile-level operations. This repository offers high-performance, cross-platform tile operations across Ascend platforms.项目地址: https://gitcode.com/cann/pto-isa导读在 CANN pto-isa 仓库的 AKO4PTOAgentic Kernel Optimization for PTO工作流中TASK_REQUIREMENTS.md是每个算子优化项目立项时自动生成的第一份约束文件它以结构化的方式固化默认测试 shape、优先优化规模、文件可编辑边界、行为保持约束和重点性能指标并附带面向调优 Agent 的行为纪律提示。本文基于 project_template 下的 TASK_REQUIREMENTS.md 模板结合 task.md 主流程与 runs 迭代模板完整讲解该文件的每一项配置如何书写、如何被后续迭代协议消费以及如何借助它保证优化正确、可衡量、可重复、瓶颈驱动。一、TASK_REQUIREMENTS.md 在 AKO4PTO 工作区中的定位AKO4PTO 是一个多算子、多项目隔离的 PTO 算子调优工作区见 README.md核心设计目标是不污染原始pto-kernels目录每个算子使用独立项目目录在各自项目的隔离副本中修改代码通过远程 Ascend 环境做 benchmark 验证对每一轮调优保留完整记录。每个算子项目由project_template/复制而来其标准结构为project_template/ ├── TASK_REQUIREMENTS.md # 当前任务的附加要求本文主题 ├── ITERATIONS.md # 每轮迭代的简约摘要表 ├── context/ # 可选的共享参考资料 ├── runs/ # 每轮产物iter-XXX/files.txt, patch.diff, notes.md │ ├── _template/ │ └── README.md └── workspace/ # 被隔离修改的 PTO 代码副本 └── README.md按照 task.md 主流程 的第 4 步Agent 在确认算子、case 和远程环境后会自动创建项目工作区并根据用户提供的 case 信息自动生成TASK_REQUIREMENTS.md含算子名、case 配置、可调参数等随后向用户确认是否需要修改context/参考资料和本文件。也就是说这份文件是用户意图 → Agent 可执行约束之间的契约载体它写在优化开始之前贯穿整个迭代过程。二、附加要求区五类核心约束的写法与含义模板的Task Requirements一节明确列出了可以写的内容共五大类。下面逐一结合仓库实际讲解每类的用途、写法要点与下游影响。1. 指定默认测试 shape- 指定默认测试 shape例如 BNSD1,16,8192,512这是给 benchmark 设定一个默认且可复现的输入规模。在 task.md 的确认优化 Case步骤中shape、dtype、是否 causal mask 等构成一次优化的 case 配置写成BNSD1,16,8192,512这样的紧凑形式可以让后续所有构建与 benchmark 命令如generate_cases.py --cases ...、gen_data.py --cases ...、./fa_performance --cases ...统一引用同一组规模避免每轮各跑各的导致前后不可比。从源码结构看PTO-tile-lib 场景如fa_performance正是通过--cases case_config字符串把 shape 配置传入编译期 case 生成与数据生成脚本的因此把默认 shape 固化在TASK_REQUIREMENTS.md中等价于固化了Benchmark 纪律里强调的相同 workload 原则——前后对比必须使用相同 case否则数据无意义。2. 指定必须优先优化的输入规模- 指定必须优先优化的输入规模当算子在多个 shape 下表现差异显著时例如长序列小 batch 的 attention、大 batch 小 head 的 FFN这一项用于告诉 Agent先打哪块靶。它和默认 shape 的区别在于默认 shape 解决可复现优先规模解决优先级排序。在迭代协议中连续多轮实验如果只优化了次要 shape会被视为偏离任务目标有了这一条Agent 每次选假设、排实验顺序时都应以该规模为准。3. 指定不允许修改的文件或模块- 指定不允许修改的文件或模块这是对 task.md 可编辑范围 规则 的细化。默认规则是只允许修改算子 kernel 源码和紧密相关的参数配置不得修改 benchmark 脚本、运行 harness、测试逻辑、正确性阈值、workload shapes而本项允许用户把这条边界收得更紧例如- 不要改动与 flash_attention_score 无关的算子 - 不允许修改 workspace/kernel/include/ 下的公共头文件之所以要显式声明是因为 Agent 在自动寻优时可能为了绕过正确性检查或降低编译难度而触碰 harness 相关文件明确列出禁区可在意图层面直接阻断这类通过让 benchmark 变简单来提分的行为。4. 指定必须保留的行为约束- 指定必须保留的行为约束用于声明无论怎么优化都不能破坏的东西例如数值语义、causal mask 行为、输出 layout、API 签名等。它与上一项的区别在于文件边界约束管能不能动行为约束管动完之后必须保持什么。在 notes.md 模板 中Pre-Edit阶段要求填写Main risk其典型来源正是这里声明的行为约束——任何可能破坏该约束的改动都应被判定为高风险变更。5. 指定本次任务特别关注的性能指标- 指定本次任务特别关注的性能指标例如优先优化 TFLOPS 而非 latency关注 GMEM 搬运量下降或必须超越 torch_npu baseline 才计为 kept。这一项直接喂给迭代协议的结果判定环节kept的准确定义是结果正确且优于当前已知最好结果而最好的具体度量由任务要求决定同时它也会写进 ITERATIONS.md 摘要表 的Baseline / PTO两列作为每一轮的量化对比口径。三、编写示例的完整解析模板给出了一个可直接套用的文本块- 把默认的 size 改成 BNSD1,16,8192,512 - 优先关注 torch_npu baseline 对比 - 不要改动与 flash_attention_score 无关的算子逐条解析行对应约束类别实际作用把默认的 size 改成 BNSD1,16,8192,512默认测试 shape锁定 benchmark 与数据生成的统一规模保证前后可比优先关注 torch_npu baseline 对比重点性能指标把优化成败的参照系绑定到torch.nn.functional.scaled_dot_product_attention的 baseline 上与 task.md 第 7 步 的 torch_npu baseline 环节呼应不要改动与 flash_attention_score 无关的算子不允许修改的文件/模块缩小可编辑范围防止 Agent 动无关算子引入回归或混淆实验归因结合 task.md 可以看到这三条正好覆盖了 PTO-DSL 典型算子flash_attention_score的优化闭环先锁定 shape再锁定参照torch_npu最后锁定改动范围。这也说明TASK_REQUIREMENTS.md的最佳编写粒度是一算子一份、一 case 一组约束与一个项目只服务于一个算子的工作区原则保持一致见 workspace/README.md。四、Hints 区面向 Agent 的行为纪律模板的Hints一节给出了两条默认调优纪律它们属于流程级约束作用于每一轮迭代而非单个参数小步、隔离的 kernel 改动正确性失败是本轮迭代的硬性停止条件。这与 task.md 一轮一假设 与 正确性先于性能 两条优化规则完全对齐每轮只测试一个假设且必须按修改 → 构建 → 正确性测试 → 通过后才跑性能的顺序执行。正确性不通过时性能结果无效本轮直接终止并记录不允许放宽容差、不允许修改验证逻辑。若连续 3 轮无实质性改善必须重读remote.md、检查ITERATIONS.md的历史轮次、上网搜索额外优化思路并重新评估调优方向后再继续。这条对应 task.md 三轮失败规则停止盲目局部微调先复查瓶颈分类是否在攻击症状而非根因再寻找结构性变化。被重读的remote.md即 远程环境 Bring-Up 文档它承载 SSH 连通、工作区上传、Python 选择、依赖安装与 benchmark 验证等环境前置信息而ITERATIONS.md则是每轮一行简约摘要的流水账Iter / Hypothesis / Changes / Baseline / PTO / Correct / Result是快速复盘的最短路径。这两条 Hint 的模板注释还提示了可以追加的内容算子特定的约束或禁用设置、远程主机注意事项、建议尝试或避免的策略、Agent 行为控制、依赖策略例如不要安装任何包。用户或后续维护者可以在!-- ... --注释位置按需扩展。五、与迭代记录体系的配合从要求到证据TASK_REQUIREMENTS.md不是一份孤立文档它与项目模板中的迭代记录体系形成闭环ITERATIONS.md 提供逐轮摘要表是要求是否达成的追踪视图runs/_template/notes.md 提供单轮详档结构Pre-EditKernel / Current bottleneck / Evidence / Hypothesis / Why it should help on Ascend / Expected improved metric / Main risk→Changes修改类型、文件、旧值→新值、完整参数快照、基于哪一轮→Post-RunCorrectness / Performance / Stability / Result→Analysis→Nextruns/README.md 规定每轮必须保存files.txt、patch.diff、notes.md三件套调参类迭代的patch.diff按参数变更说明格式记录如PARAMold_value → PARAMnew_value。在实际执行中TASK_REQUIREMENTS.md中的约束会成为上述记录字段的输入例如重点关注 GMEM 搬运会出现在每一轮Current bottleneck的候选分类里task.md 的强制瓶颈分类表 共列出 GMEM traffic bound、UB/tile buffer pressure、small-transfer inefficiency、compute under-utilization、AIC/AIV imbalance、pipeline bubble、barrier/wait/sync overhead、register pressure、bad tile shape、dependency chain、CV FIFO pressure 等 11 类而必须保留的行为约束会成为Main risk与高风险变更判定如更大 tile 可能导致 UB 爆炸、删除 barrier 前缺少依赖证明等的依据。六、编写与使用的最佳实践清单综合模板本身与 task.md 主流程一份合格的TASK_REQUIREMENTS.md应满足具体到可执行shape、规模、指标都要给出可输入命令的具体值如BNSD1,16,8192,512避免尽量快一点这类无法验证的描述边界明确同时写清默认/优先做什么与禁止/保留不做什么防止 Agent 越界或目标漂移与参照系绑定写明要对比的 baseline如 torch_npu、PTO initial确保结果判定口径统一一项目一份每个算子项目独立维护随 case 变化而更新并在新一轮会话开始前重新确认task.md 第 8 步 要求每次新会话先读context/与TASK_REQUIREMENTS.md保留失败信息Hint 区鼓励追加避免的策略与Agent 行为控制让后一轮 Agent 直接继承前几轮的教训避免重复踩坑不替代码说话本文件只约束目标、边界与纪律不承载 benchmark 脚本逻辑可编辑性检查以 task.md 可编辑范围 为准。七、小结在 AKO4PTO 工作流中TASK_REQUIREMENTS.md扮演着任务契约的角色它把用户在 shape、规模优先级、文件边界、行为约束与性能指标上的意图翻译成 Agent 在每一轮迭代中必须遵守的硬约束并与ITERATIONS.md、runs/iter-XXX/三件套、remote.md环境文档、notes.md单轮详档共同构成要求 → 实验 → 证据 → 复盘的完整闭环。掌握它的五类约束写法与 Hint 纪律是让 PTO 算子优化从随机 trial-and-error走向瓶颈驱动、可衡量、可重复的第一步。【免费下载链接】pto-isaParallel Tile Operation (PTO) is a virtual instruction set architecture designed by Ascend CANN, focusing on tile-level operations. This repository offers high-performance, cross-platform tile operations across Ascend platforms.项目地址: https://gitcode.com/cann/pto-isa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考