PyPTO-Gym 算子分解决策指南：基于 decomposition-primitives 的分类、证据与验证边界-开发者社区

人工智能
大模型
算子库
AI 技能/插件

【免费下载链接】pypto-gym

PyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库

导读

在 PyPTO-Pro（PyPTO-Gym 的算子开发主路径）中，将一个算子拆分成多个阶段（stage）是常见的工程动作：某个阶段可能需要不同的合法 tile 形状、精度边界、计算引擎或文档化的分发路径。但拆分并非总是正确——错误的拆分可能悄悄改变数学结果、破坏 dtype 契约，甚至把本应留在设备内核里的计算搬到宿主侧。本文以 decomposition-primitives.md 为核心，系统讲解 PyPTO-Gym 知识库（KB）中"拆分前必须先分类"的决策方法：四类拆分语义（exact / lossy / algorithmic / forbidden）如何判定、各自要求何种验证动作，以及什么情况下拆分根本不成立。读完本文，你将掌握在 PyPTO-Pro 算子拆分前做结构化分类的完整流程，并知道如何用 golden、容差、数学推导和源码证据来支撑每一次拆分决策。

为什么拆分前必须先分类

PyPTO-Pro 的算子实现遵循"单内核交付边界"（见 wrapper-boundary.md）：宿主侧包装器只能做参数校验、读取元数据、用torch.empty分配输出并启动一个@pl.jit内核。任何数据形状或 dtype 处理都必须发生在内核内部。在这种约束下，"拆分"指的是把一个逻辑算子内部划分为多个阶段，而不是把工作挪到宿主侧——后者直接违反交付边界，属于 forbidden 类别。

知识库的 README.md 给出了知识条目的保留门槛：技术主张必须引用官方文档/源码路径，或保留可审查的验证产物。decomposition-primitives 正是这一原则在"拆分决策"上的落点：在实现任何提议的拆分之前，先对拆分进行分类，而不是直接动手。这是因为不同类别的拆分对 golden、容差、验证方式的要求完全不同，混淆它们会导致验证失真或把错误的语义悄悄引入实现。

四类拆分语义与所需动作

decomposition-primitives 定义了四类拆分，每一类都有明确的"含义"与"必需动作"：

类别	含义	必需动作
exact（保真）	重组保留了数学结果与 dtype 契约	保留原有 golden；验证阶段边界
lossy（有损）	强制转换、量化或近似改变了数值行为	在 golden 中建模相同的边界，并定义有来源的容差
algorithmic（算法级）	用不同的稳定算法实现同一契约	保留数学推导，并与独立的 golden 比较
forbidden（禁止）	宿主计算、静默契约收窄或不支持的语义变更	重新设计；不要实现

这张表的判读要点在于"动作"列的差异：exact 拆分不需要新的 golden（数学结果不变），但要验证阶段边界——即确认重组确实逐位保持了原结果；lossy 拆分必须让 golden 也走同样的有损边界（否则 golden 与实现不在同一契约上），并且容差必须有来源（derive from the project standard for the actual output dtype and algorithm，见 precision.md 检查清单第 5 条），绝不能从无关样例复制；algorithmic 拆分则要求一份数学推导加一个独立 golden，用独立实现互相印证。

forbidden 类别是硬性红线。其中"宿主计算"直接对应 wrapper-boundary.md 的规则：宿主侧任何设备算子调用（.to()、.contiguous()、.reshape()等）都可能在评估环境的 CANN 清单上不存在（实测出现过aclnnInplaceCopy failed, error code is 561103），即使本地能跑，也会计入端到端设备耗时。而"静默契约收窄"则呼应 precision.md 的核心规则——dtype、累加类型、舍入、饱和、缩放、容差都是算子契约的一部分，为性能改变其中之一而不更新 golden 与验收标准，就是契约收窄。此类拆分必须重新设计，而非"先实现再补文档"。

合法拆分的触发条件：四个明确理由

分类之后还要回答一个前置问题：这次拆分到底有没有必要？decomposition-primitives 给出了唯一的合法触发条件：

仅当某个阶段需要不同的合法 tile 形状、精度边界、计算引擎或文档化的分发路径时，才进行拆分。

不同的合法 tile 形状：例如一个阶段需要 N256 的 Right tile，另一个阶段受内存或同步约束只能容纳更小的形状（关于 tile 形状与内存合法性，见 tiling.md 与 memory-layout.md）。
精度边界：例如 FP32 累加与 BF16 中间存储之间的边界，或量化前后必须分开的阶段（量化语义见 precision.md 检查清单第 4 条：scale、舍入、clamp 范围、反量化位置必须在 kernel 与 golden 中同时显式化）。
计算引擎：Cube（矩阵乘）与 Vector（逐元素/归约）引擎的切换，例如整数 Cube 收缩直接喂给浮点 Vector epilogue（见 cv-quant-matmul-direct-epilogue.md）。
文档化的分发路径：文档明确声明的分派分支。

反例同样重要：一个仅仅增加了一次 GM（Global Memory）往返的拆分，没有任何可复用的正当理由。这条判据与知识库的保留门槛一致（README.md 第 2 条：用途必须超越单次实验/分支/环境/日期可复用）。从源码结构看，PyPTO-Pro 的跨阶段通信需要显式的 GM workspace 加同步协议（见 staged-cube-matmul-gates.md 中关于 workspace 字节数、读写流量、barrier 的记录要求），因此"为了拆而拆"引入的 GM 往返既消耗带宽又引入同步复杂度，属于无正当理由的拆分。

流式 softmax 拆分的特殊约束：online-softmax-tail 的定位

decomposition-primitives 还针对一个常见场景给出了专门提醒：流式 softmax。文档明确要求把 online-softmax-tail.md 仅当作概念性数学参考使用，因为它没有保留完整内核验证参考。

这是一个重要的证据边界案例。查看 pattern-index.md 可以看到知识库对模式的两种验证状态：

validated skeleton：页面引用了保留的可运行实现，且通过结果覆盖其声称的范围；
conceptual only：只能使用其中的方程与决策规则，任何研究代码都当作未经验证的输入，不能当作已验证的起点。

online-softmax-tail 在 pattern-index 中明确标注为conceptual only（"a softmax reduction streams across multiple score chunks"）。其页面自身也声明：知识库没有保留验证完整流式 QK/softmax/PV 管线的可运行 PyPTO-Pro 参考，不要把该页当作实现骨架复制；必须对照目标 SDK 的官方 flash-attention 示例确认 API 签名与同步方式。已保留的 softmax_impl.py 样例只验证了"整行能装进一个 tile"的基础情况，golden 见 softmax_golden.py。

对拆分决策的启示是：若你的拆分方案要依据 online-softmax-tail 的递推公式（running maximum、denominator、unnormalized output 的更新），该递推只能作为数学基础，拆分后的阶段边界、同步点、尾块掩码位置都必须重新用官方参考或独立 golden 验证，而不能宣称"参考了该模式即已验证"。这也正是 exact 类拆分要求"验证阶段边界"的含义——概念页不是验证证据。

判定方法在工作流中的落地：KB_SELECTION 与 KB_USAGE

分类决策最终要落到知识库的可审计工件上。CONTRACT.md 定义了连接知识库与 PyPTO-Pro 阶段工作流的契约（contract_version为 3）：

Planner 在 Stage 1 通过前写入KB_SELECTION.json（依据计算拓扑与 dtype/shape 属性，而非算子名）；
Coder 在 Stage 4 期间向KB_USAGE.json写入实现声明；
pypto-pro-op-verifier独立验证工件与被引用代码。

其中 KB_USAGE.json 记录的是selected reference -> derived invariant -> implementation location -> implementation claim。当你的拆分涉及某个被选中的 reference（例如 precision.md 中的精度边界规则，或某个 pattern）时，必须在KB_USAGE.json中登记由此拆分推导出的不变量及其实现位置。Coder 只能声明implemented、deviated或not_applicable，不能声明verified——验证结论归 verifier 所有。这意味着：

若拆分被分类为 exact，你需要在KB_USAGE.json中声明阶段边界不变量的实现位置；
若拆分为 lossy，需要声明容差来源与 golden 建模的对应边界；
若无法实现，应声明deviated并给出理由（justification），而不是静默改变契约——这正对应 forbidden 类"重新设计"的要求。

与精度契约的联动：为什么"保持同一 golden"不总是够的

exact 类要求"保留原有 golden"，这隐含一个前提：原 golden 本身正确且覆盖了拆分后的每个阶段边界。precision.md 给出了需要同步检查的契约面：输入、中间量、累加器、输出 dtype 都要记录；数值敏感的归约与超越函数要保持契约要求的累加精度（默认 FP32，除非窄路径被显式文档化并验证）；量化场景下 scale、舍入模式、clamp 范围、反量化位置在 kernel 与 golden 中都要显式。一个阶段边界往往就是一个精度边界——例如"宽化链"（widen → compute → reduce）要求把vf.astype放在可能溢出的运算之前而不是归约之前，否则窄类型早已产生inf（见 precision.md 的代码示例）。因此在做 exact 分类时，"保留同一 golden"意味着同时确认该 golden 在各阶段边界处的累加/舍入行为与拆分后的实现一致；不一致则说明拆分其实引入了未声明的有损行为，应重新分类为 lossy 并建模边界。

另外值得注意：KB 的跨包链接使用 sibling 形式（../pypto-pro-op-kb/…与反向../../pypto-pro-op-kb/…），因为技能以符号链接安装到cannbot-skills/ops/，物理文件系统会解析回同一目录（CONTRACT.md 实测 41/41 链接在 checkout 与安装两种布局下都能解析）。这意味着你在拆分设计中引用的约束与模式页面，无论从哪个技能出发都能稳定解析到知识库根目录下的同一份文件，check_kb_integrity.py也会实际遍历这些跨包链接进行完整性检查（负例见 tests/test_check_kb_integrity.py）。

结论：拆分决策清单

综合 decomposition-primitives 与其关联约束、模式页面，一次合规的 PyPTO-Pro 拆分决策应依次回答：

必要性：拆分是否因为阶段需要不同的合法 tile 形状、精度边界、计算引擎或文档化分发路径？若只是增加 GM 往返，则不成立。
分类：拆分的语义属于 exact、lossy、algorithmic 还是 forbidden？
- exact → 保留同一 golden，验证阶段边界；
- lossy → golden 建模同一有损边界，容差有来源；
- algorithmic → 保留数学推导，与独立 golden 比较；
- forbidden（宿主计算 / 静默契约收窄 / 不支持的语义变更）→ 重新设计，不实现。
证据：若引用模式页（如 online-softmax-tail），确认其验证状态是validated skeleton还是conceptual only；conceptual only 页面只提供数学，不提供验证。
精度联动：每个阶段边界是否与精度契约一致——dtype/累加类型/舍入/缩放/容差是否被显式记录并映射到 golden？
工件落地：在KB_USAGE.json中登记由拆分推导的不变量与实现位置，由 verifier 独立核验后再放行。