PyPTO-Pro 性能知识卡片写作规范基于事实包生成带注释示例的完整实践指南【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym导读PyPTO-Gym 仓库中的pypto-pro-op-perf-tuneSkill 维护着一套采用 Open Knowledge FormatOKFv0.2 组织的性能优化知识卡片库用于在 NPUAscend 950PR / 950DT算子调优时快速检索适用的优化方法。本文以知识卡片库中的教学材料 带注释的知识卡片示例 为骨架完整讲解事实不足时如何填写性能卡片从事实包的输入规范、Agent 生成卡片的完整结构到证据等级、未知项保留与人工评审机制。读完本文你将掌握一套可复制的事实包 → 待评审卡片 → review 合入工作流并理解如何在证据不足时不补猜、不虚构地写出专业、可评审的性能优化卡片。一、知识卡片体系概述示例卡片在其中的位置性能优化知识卡片库位于 knowledge-cards/其入口是唯一登记清单 index.md。卡片按稳定类别放入子目录目前内置 15 张 VF/VEC 卡片vec-01至vec-15全部以statusstable登记到 Active 表。示例目录中的 annotated-card.md 是教学材料不是可登记或执行的性能卡片其中事实为虚构材料sample-01只用于演示真实贡献需从 index.md 分配 ID并使用自己的技术材料。围绕示例卡片该目录还提供四个配套文件构成完整的卡片生命周期文件角色CARD_TEMPLATE.md新卡结构与默认字段模板PROFILE.mdOKF 字段、来源与状态规则约定CONTRIBUTING.md事实包准备与 Agent 生成流程入口index.md卡片清单唯一入口与 ID 分配规则二、输入给 Agent 的事实包允许未知禁止补猜示例卡片首先演示了输入侧的规范贡献者/用户把尽量多的原始材料交给 Agent不知道的内容明确写未知或待验证。示例中的事实包如下profiler 显示一个 VF 的内层循环反复读取同一份只读数据具体报告尚未归档候选方向是把不变量读取移到循环外并在循环内复用目标 SoC、公开 API、Tile 容量、tail 正确性和性能数据都未知没有可附的参考资料。这个事实包足以表达一个候选机制循环不变量外提但不足以证明它可实现、正确或有收益。按照 CONTRIBUTING.md 的定义事实包至少应覆盖六个维度问题与诊断当前代码/生成物/profiler 中可直接核对的现象及优化理由优化方法before、after、各步骤关系以及减少或重排了什么工作适用边界何时适用、何时不适用以及容量、dtype、shape、layout、tail、同步等约束目标能力方法依赖的设备、公开 API 与已知限制验证方法与已有材料正确性覆盖、性能指标、测试条件和机制证据参考资料可选文档链接、代码路径或实验材料。可复制的空白事实包模板没有的项目写未知问题与诊断 候选优化方法 before after 适用条件 不适用条件与失败案例 适用设备、公开 API 与已知限制 正确性、性能和机制验证材料 参考资料可选 仍然未知的内容关键纪律是只有口头经验、旧版本数字或未定位的代码片段也可以投稿但 Agent 应保留其不确定性供评审核对。示例中事实包目标 SoC、公开 API、Tile 容量、tail 正确性和性能数据都未知Agent 就不应在卡片中补写设备、API 或数字而应在卡片中如实保留待确认项。三、Agent 生成的待评审卡片字段、结构与代码证据等级3.1 frontmatter 字段详解示例卡片展示了 Active 状态卡片的完整 frontmatter--- type: PyPTO Performance Optimization Card title: 在 VF 内将循环不变量读取移出内层循环教学示例 description: 当同一只读数据被 VF 内层循环重复读取时在容量允许的前提下读取一次并复用。 status: stable tags: [pypto-pro, vec, example] item_id: sample-01 bound_hint: memory applicability: VF 内层循环重复读取同一只读不变量且外提后的 live set 可被目标容量容纳当前读取热点及容量材料待补充 target_api_gate: 目标 SoC 和公开 API 支持均待核验 ---各字段用途依据 PROFILE.md 约定如下字段用途type/title/description/tags类型、标题、摘要和分类卡片类型固定为PyPTO Performance Optimization Cardstatus卡片唯一状态字段stableActive、draftDraft、deprecatedRetiredsources可选参考资料提供resource需逐项引用时配id和同名脚注item_id稳定编号如vec-01对应文件名前缀与索引bound_hint预期主要影响的计算、访存、标量或调度瓶颈compute\|memory\|scalar\|scheduling\|mixedapplicability方法的使用场景和技术条件target_api_gate方法依赖的设备、公开 API 能力及已知限制注意示例中bound_hint: memory与target_api_gate: 目标 SoC 和公开 API 支持均待核验都如实反映了证据缺口——这正是示例要教学的核心行为。状态规则方面Agent 默认以statusstable提交并登记到 Active 表Draft 不进入调优候选Retired 保留 ID、历史与退役原因且编号不复用。ID 规则为类别-两位递增序号文件名item_id-短名.md编号从已登记条目中该类别的最大编号递增。3.2 卡片正文的标准六段式示例卡片的正文遵循 CARD_TEMPLATE.md 定义的结构六个核心小节各有明确职能何时用诊断特征列出可从当前源码、生成物或 profiler 直接核对的特征。示例中给出内层循环重复读取同一份只读不变量且这些读取构成热点的诊断特征并注明当前事实包尚未提供可定位报告读取热点、设备容量和公开 API 仍待核验。经验阈值与 ratio 只能作为线索不能作为结论。何时不适用列出方法不成立的技术条件和容易误判的相邻情形。示例明确数据会被循环体修改、每次迭代读取范围不同、外提会超出 Tile/寄存器容量、重复读取不是热点时均不适用改写需保持 shape、layout、tail 和同步语义等价。原理解释改动减少或重排的工作、搬运、依赖、冲突或固定开销。示例说明候选动作把循环内的重复读取改为一次读取和多次复用目标是减少重复搬运及其固定开销但不会自动减少消费者计算也不保证端到端性能提升。怎么改before / after用最小 before/after 说明主要改动详见 3.3 代码证据等级。性能与验证指标写明预期变化的指标、正确性覆盖及已有证据未实测时不填写收益结论。技术限制与风险说明精度、dtype/layout、容量、tail、同步等限制以及额外开销或实现风险。示例中列出复用要求值在循环内不变保持数据流、同步/并发所有权和 wrapper 合同等价额外占用可能引入 spill等风险。3.3 代码证据等级三种 fence 标注CARD_TEMPLATE.md 规定卡片内的代码 fence 必须标注为以下三种之一示例卡片对应的是第三种结构示意只展示数据流明确缺少哪些上下文且不可直接编译或交付嵌入片段使用已核验的公开pl.*/vf.*API并说明嵌入的 kernel/VF 上下文、dtype、shape、tail 等必要前提能力门控伪码API 尚未确认或存在已知缺口禁止直接复制实现写清缺口和补证方法不因卡片 Active 而视为可用。示例卡片中的改动展示即为能力门控伪码before: for each iteration: read invariant - consume after: read invariant once - for each iteration: consume cached value并在正文中明确声明以下是能力门控伪码只表达数据流公开 PyPTO-Pro API、设备支持和容量尚未核验禁止直接复制实现。与此同时不得臆造 PyPTO-Pro API也不得把生成 C 或 AscendC 写法伪装成 Python API——这是整个卡片库的底线。3.4 真实卡片对照从教学示例到已登记卡片示例卡片的主题VF 内循环不变量外提与复用在真实卡片库中有直接对应物。以 vec-06 不变量广播一次 多行 VL merge 为例它把跨行不变量在 VF setup 中只 load 一次落成了三层能力分层单 B32 标量广播pl.LoadDist.BRC_B32有官方 ST/API 依据、一个 32B block 广播候选pl.LoadDist.BLK启用前补 8 哨兵 value ST、多行 VL mergepacked Tile 组内蝶式 shuffle需完整 value ST/trace。该卡明确告诫单标量广播、8 值 block 广播和多行 merge 是三层不同能力不能互相冒充并规定 A 路径为嵌入片段、B/C 路径为能力门控伪码——这与示例卡的教学要点完全一致能力未核验就不写成已证实结论。另一张 vec-09 外层循环下沉进 VF 同样体现了setup 外提机制把 kernel 中逐行调用 VF 的循环折进一个pl.vector_function让 mask、广播常量与地址 setup 只初始化一次其代码标注为VF 嵌入片段并写清行间独立性和逐行 valid 必须由具体 kernel 提供的前提。两张真实卡都是按卡片模板自查、保留未知项、代码等级准确的正面范例。四、示例要点证据不足时怎么写才算合格示例卡片结尾总结了四条评审要点这也是 Agent 生成卡片后的自查清单保留事实包中的主要机制与限制卡片完整保留了怀疑重复读取这一候选机制及其限制没有把它改写成已证实结论未知项保持未知设备、API、容量和性能仍明确标注为未知没有生成貌似可信的值——不为填满字段而补猜代码等级准确按默认 Active 状态提交但代码仍明确标为能力门控伪码采用前需核验所需能力给出下一步补证方法卡片说明如何补证核对设备容量与 API 支持、覆盖边界 shape/tail 的正确性用例、注明 baseline/candidate 测试条件的性能材料供专业人员在合入前 review。从源码组织看还可以补充两点结构性要求一是卡片与索引变更须一并提交 PRitem_id、文件名和 Active 索引行必须一致提交前重新读取 index.md 以避免并行贡献占用同一编号二是 Active 仅表示调优候选实际应用时的适用性判断、实验和结果记录按 性能调优 Skill 执行——SKILL.md 中知识卡片来源knowledge_card的闭合要求是按 Active 表列出候选、不扫描目录可能适用且能力已确认的项逐个实验其余项说明不适用或能力不支持的依据未知能力先补证。五、完整贡献流程从事实包到合入综合 CONTRIBUTING.md 与示例卡片一次完整的卡片贡献分为四步准备事实包按前文模板填写未知项明确写未知已有用例、数据或 trace 一并提供。让 Agent 生成卡片把事实包附在提示词后交给仓库内 Agent提示词要求 Agent 完整阅读 CONTRIBUTING / PROFILE / CARD_TEMPLATE / index 四个文件不臆造 API、版本、数值、来源或适用范围缺失内容明确标为待验证。Agent 输出待评审的 Active 卡片事实包不足时按本示例的方式保留语义并显式暴露缺口。提交前检查按模板整理内容人工核对机制、适用条件、改法和验证方法是否清楚代码等级是否准确未知项是否如实保留确认类别目录、文件名、item_id和 Active 索引行一致。提交与人工评审将卡片和索引变更一并提交 PR专业人员合入前 review 机制、适用边界、来源、能力缺口和验证方法贡献者按评审意见修改。六、结论带注释示例 annotated-card.md 虽然只是一张教学卡但它浓缩了整个知识卡片体系最重要的写作哲学事实与推断分开写能力未核验就标注为能力门控伪码未知项如实保留并给出补证方法。在 PyPTO-Pro 面向 Ascend 950 的算子性能调优中这套纪律保证了卡片库既能为调优提供高质量候选Active 表又不会让未经证实的内容污染决策。真实卡片如vec-01至vec-15与示例一脉相承任何一张卡都明确写清适用条件、不适用情形、API 门控与验证指标。若你需要贡献新卡从 CARD_TEMPLATE.md 复制结构、按 PROFILE.md 填写字段、参照本示例处理证据缺口即可产出可评审、可追溯、可执行的性能知识卡片。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考