PyPTO-Pro 已验证内核样例Validated Study Kernels复用指南从 kernel-index 选择器到可交付算子的边界【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gymPyPTO-Pro 知识库Knowledge Base中的examples/目录沉淀了一批经过板端验证的可复用内核实现本文以 examples/README.md 为骨架结合 kernel-index.md 选择器、wrapper-boundary.md 边界约束与check_kb_integrity.py完整性检查说明如何正确地从样例中复制内核、如何判断验证状态、以及为什么不能把样例的驱动代码搬进交付物。读完本文你将掌握 PyPTO-Pro 算子开发中样例 → 内核 → 可交付 wrapper的完整取舍规则以及验证证据的解读与重跑前提。一、examples 目录在知识库中的定位PyPTO-Pro 知识库位于 cannbot-skills/ops/pypto-pro-op-kb/是对已安装 PyPTO-Pro API 文档与官方示例的补充而非替代。其入口是 ROUTER.md按任务 → 技能 → 聚焦参考路由选择一条保留的 study 实现 →pypto-pro-material-explore→examples/kernel-index.md决定主机侧host可以做什么 → 设计/开发技能 →constraints/wrapper-boundary.md选择可复用的数据流 →pypto-pro-op-design→patterns/pattern-index.md。examples/目录本身承载两类文件examples/README.md选择器使用契约本文主题定义样例的进入/退出标准与复制边界examples/kernel-index.md已验证实现的唯一生产选择器是样例目录的机器可读索引examples/validation-records.md模式级验证记录的留存表examples/samples/实际的内核样例实现impl 与 golden 成对出现。从源码结构看完整性检查脚本 check_kb_integrity.py 将ROUTER.md、README.md设为根入口、将patterns/pattern-index.md与examples/kernel-index.md设为目录索引根任何未被它们直接或传递可达的保留文件都会报错——这保证了examples/中每一个样例都必须通过选择器被发现否则就是一个永远不会被任何阶段选中的死文件。二、kernel-index唯一的生产选择器kernel-index.md 是唯一的生产选择器the only production selector所有路径相对cannbot-skills/ops/pypto-pro-op-kb/。选择器中刻意排除了性能数据——针对实际平台、形状与软件版本重新 profile。索引中的每一行都包含四个要素一个通用拓扑或技术topology / technique而非某个算子名一条规范的实现路径canonical implementation pathvalidated状态由文件内嵌的验证记录支撑可审查的证据实现自身或配套 golden 中可复核的验证记录。当前选择器收录的 21 行样例按 dtype、实现路径、状态与证据列示如下topology / techniquedtypeimplementationstateretained evidencesingle-tile matmulfp32samples/matmul_float_mmad/matmul_float_mmad_impl.pyvalidatedfile validation record goldentransposed-left matmulfp32samples/matmul_kmkn_fp32_out/matmul_tn_impl.pyvalidatedembedded correctness testsquantized matmulfp32→int8samples/matmul_quant_int8/matmul_quant_int8_impl.pystudyembedded correctness testmatmul operand reusebf16samples/bf16_matmul_operand_reuse/bf16_matmul_operand_reuse_impl.pystudyembedded correctness testcube→vector handofffp32samples/fused_matmul_add/fused_matmul_add_impl.pyvalidatedembedded correctness testmatmul biasfp32samples/matmul_bias/matmul_bias_impl.pystudyembedded correctness testmatmul bias activationfp32samples/matmul_bias_relu/matmul_bias_relu_impl.pystudyembedded correctness testmatmul activationfp32samples/matmul_relu/matmul_relu_impl.pystudyembedded correctness testmatmul row normalizationfp32samples/matmul_rowwise_norm/matmul_rowwise_norm_impl.pyvalidatedembedded correctness testmatmul row L2 normalizationfp32samples/matmul_rowwise_l2_norm/matmul_rowwise_l2_norm_impl.pystudyembedded correctness testmatmul row softmaxfp32samples/matmul_softmax/matmul_softmax_impl.pyvalidatedembedded correctness testcube→vector with atomic outputfp32samples/cube_vec_atomic_add_two_outputs/cube_vec_atomic_add_two_outputs_impl.pyvalidatedembedded correctness testvector→cube handofffp32samples/vec_cube_abs_sqrt_matmul/vec_cube_abs_sqrt_matmul_impl.pyvalidatedembedded correctness testrow softmax tile opsfp32samples/softmax/softmax_impl.pyvalidatedfile validation record goldenrow normalization tile opsfp32samples/norm_softmax_rms_l2/norm_softmax_rms_l2_impl.pyvalidatedembedded correctness testslayer normalization tile opsfp32samples/vector_kernels/layernorm_impl.pyvalidatedembedded correctness testactivation normalization tile opsfp32samples/vector_kernels/act_layernorm_elementwise_impl.pystudyembedded correctness testsrow sum tile opsfp32samples/vector_kernels/reduce_sum_impl.pyvalidatedembedded correctness testinterleaved rotary embeddingfp32samples/vector_kernels/rope_interleave_impl.pyvalidatedembedded correctness testcumulative sum by contractionfp32samples/vector_kernels/cumsum_matmul_impl.pyvalidatedembedded correctness testvector-function elementwisefp32samples/vf_vs_tileop/vf_elementwise_impl.pystudyembedded correctness testvector-function L2 norm activationfp32samples/vf_vs_tileop/vf_l2norm_silu_impl.pystudyembedded correctness testvector-function layer norm rotary embeddingfp32samples/vf_vs_tileop/vf_layernorm_rope_impl.pystudyembedded correctness testvector-function normalization and reductionsfp32samples/vf_vs_tileop/vf_rms_silu_gelu_reduce_impl.pystudyembedded correctness testvector-function row softmaxfp32samples/vf_vs_tileop/vf_softmax_impl.pystudyembedded correctness test选择器的排除规则同样明确失败的failed、进行中的work-in-progress、诊断性的diagnostic以及仅用于 benchmark 的探针一律不得进入选择器。这类文件不是可复用知识进入选择器只会让下游 Agent 在不确定的状态上建模。最容易被忽略的一点是采用前提在生产中采纳某个样例前必须在实际目标上重新运行其保留的验证。历史验证只能证明该代码在记录时的目标与 SDK 上正确不能建立与不同 PyPTO/CANN 版本或平台之间的兼容性——这是知识库反复强调的硬性前提。三、validated 与 study两种状态差别很大选择器中的每一行只有两种状态且语义严格区分见 kernel-index.mdvalidated保留文件记录了通过的正确性结果——跑了什么、在什么目标上、达到什么精度。这些记录取自 Ascend 950 系列 A5 目标。在其它架构或不匹配的 SDK 版本上把该行视为候选重新运行正确性验证study文件内嵌了测试但没有保留已通过的记录。它只用于阅读实现形态shape of the implementation不是实现正确的证据也不会为任何以它为模板的代码授予验证状态。validated状态并非自我宣称即可。完整性检查脚本 check_kb_integrity.py 中的check_validated_rows_have_records强制索引行只有在其引用文件的头部记录了验证结果时才允许声称validated。这一条规则是针对一次真实事故引入的——此前有一批共 12 个文件在没有任何验证记录的情况下被笼统标为 validated脚本注释原文the previous blanket claim covered twelve files that had no record at all。check_validation_records_match_code进一步把记录与代码钉在一起每个 validated 样例头部必须携带VALIDATED-CODE-SHA256: 64位哈希该哈希是对代码行剔除整行注释与空行计算的 SHA-256。任何后续代码改动都会使哈希失配检查失败直到样例被重新验证并重新打戳--stamp-validation-hashes。正是这条机制阻止了ABI 重写在未变的状态头下悄悄发布脚本注释记录的真实历史一个 ABI 重写曾在数周前测得的验证记录下发布。验证记录的措辞还必须限定在样例自身范围任何出现STATUS: VALIDATED、max_abs_diff 、PASS.等声称的.py文件头部必须带SAMPLE PROVENANCE标记check_sample_provenance_claims。原因在于生成的代码若复制了头注释就会继承一份它并未挣得的验证记录。四、从样例复制什么复制内核不复制驱动这是 examples/README.md 的核心契约一句话概括Copy the kernel. Do not copy the driver.一个样例的价值在于pl.jit内核体及其周围的数据流dataflow。部分样例还定义了*_wrapper或__main__块其职责是让文件能独立运行standalone分配输出、把操作数 reshape 成内核期望的布局、调用torch.npu.synchronize()以便冒烟测试测到东西。这些是harness测试驱动调用不是交付形态。而交付 wrapper 的规则要窄得多——用torch.empty分配输出仅此而已布局工作放在内核内部。该规则完整定义在 constraints/wrapper-boundary.mdCasting、slicing、transposing、padding、concatenating 以及任何其它数据 shape/dtype 处理必须发生在pl.jit内核内部。wrapper 只允许校验参数、读取shape/ndim/dim()/size()/stride()/dtype/device/layout/numel()/storage_offset()元数据、推导 Python 整数、用torch.empty分配当前契约声明的输出、以及启动一个内核。样例的 wrapper 不是这条规则的示例也绝不能当作允许性证据——把它的写法搬进custom/op/test_{op}.py会产生样例从未授权过的边界违规a boundary violation that the sample never claimed to license。4.1 违反边界的代价不只是慢为什么这不是风格偏好因为 wrapper 在设备侧的开销是每个算子的杠杆。在规则提炼所依据的测量中带有大量数据整形data shaping的 wrapper消耗了设备总时间的 10%62%。更关键的是兼容性风险——host 侧算子可能在评测 runner 上直接失败。评测容器的 CANN 不是开发机的 CANN实测评测 CANN 9.1.0 vs 开发 9.2.0其算子清单也不是超集一个在本地运行良好的 wrapper.to(torch.float32)在真实交付的所有 fp16/bf16 用例上抛出了aclnnInplaceCopy failed, error code is 561103EZ1013: aclnnInplaceCopy_1_CastAiCore cannot be found只有 fp32 用例通过。不派发任何设备算子的 wrapper 则没有这种依赖。两个持久成立的推论内核时间与可调用时间可能反向移动。某个算子的内核提升了约三分之一但端到端反而变慢——因为它的 wrapper 增长快于内核收缩。正确的性能单元是wrapper kernel一起。host 整形并不罕见。在那次运行生成的内核中占比最高的调用是.to()、.contiguous()和.reshape()远超其它一切。因此每个生成的 wrapper 都要做完整的静态审计——profile 输出无法证明边界被遵守。4.2 反例全景规则原文给出一个真实的生成 wrapper已改名每个被标注的行都会变成实测的设备内核def op_wrapper(input_tensor, dim-1, ...): x_fp32 input_tensor.to(torch.float32) # cast - measured x_transposed x_fp32.movedim(dim, -1).contiguous() # transposecopy - measured x_2d x_transposed.reshape(M, D_full) y_2d torch.empty(M, D_out, ...) op_kernel(x_2d, y_2d, ...) # the actual work y_transposed y_2d.reshape(*non_dim_shape, D_out) y y_transposed.movedim(-1, dim).contiguous() # transposecopy - measured return y.to(out_dtype) # cast - measured4 个实测设备算子包围着 1 次内核启动。内核被写成想要一个规范的 FP32 连续 2-D 输入host 便去制造它——这份便利按全价收费。4.3 应当怎么做把 host 操作搬进内核规则给出了完整的迁移对照表Host 侧这样做搬进内核后这样做输入上.to(torch.float32)以原生 dtype 加载到 UB再片上转换——tile 级pl.cast或寄存器级vf.astype没有vf.cast输出上.to(out_dtype)每 tile 在store前pl.cast/vf.astype.movedim/.permute/.transpose在 tile 循环里用 stride/offset 索引该轴.contiguous()stridedDataCopy或把 stride 折进循环边界reshape 成 2-D传真实 shape在内核中计算 flat offset切分操作数slicing传基址指针加 offset 参数操作数torch.cat传两个操作数在循环内选择padding 到 tile 倍数尾部用pl.set_validshapetorch.zeros/zeros_like初始化写满每个输出元素或在内核内初始化arange/ 索引构造在内核中用算术计算索引torch.npu.synchronize()删掉——同步属于调用方这只是在 wrapper 内加了一次不必要的流等待对 TensorList 循环逐元素启动内核展开为一组有限的固定槽位每个 TensorList 参数一个Ptr/槽地址不进 tiling 数据、校验真实槽位、未用槽以n_i0填充只启动一次这种扁平化只适用于连续、秩不敏感的语义其它布局需要单独有界的 ABI表中最后一行是foreach类算子的昂贵项这类算子存在的全部理由就是消除逐张量启动开销逐元素启动等于把基线已经消除的东西原样加回来且差距随列表长度拉大。需要注意的边界细节前两行的片上转换 API 是平台门控的使用前需确认目标平台支持见 constraints/precision.md 关于转换链应保持的 dtype。把 cast 搬进内核是规则但不支持的 API 不是迁移的豁免——应当上报能力阻塞而不是把.to()留在 host纯 view 的 reshape 可能零成本但这不授权它在交付 wrapper 中出现。成本与合规是两回事没有任何 profile 结果可以豁免此边界位重解释也必须留在内核pl.Ptr形参不做 dtype 检查同一张量可以按一种 dtype 传入、按另一种 dtype 读取——有符号数据经UINT32tile 携带、int64 对按两个 32 位字查看都在内核内完成wrapper 不需要.view()。host 侧.view()即使只是 view 也违反交付边界。4.4 边界管什么、怎么查该边界管辖每一个生成的实现 wrapper既包括分阶段stagedwrapper也包括交付的{op}_wrapper位于custom/op/test_{op}.py。它对examples/samples/下 study 样例的驱动函数不生效——那些函数存在的目的是让样例可独立运行是 harness 而非交付形态。落地机制KB_USAGE.json必须记录该不变式验证器verifier会拒绝任何 wrapper 执行了允许清单之外动作的类。DESIGN.md、KB_USAGE.json、deviated理由、成本说明或 profile 结果都不能覆盖这条规则——如果某个变换看起来无法在内核中表达那么该设计不可交付报告设计/能力阻塞并附证据。反作弊规则在另一个方向同样成立wrapper 也不能执行算子的算术且恰好只有一个pl.jit内核、只启动一次。五、样例族全景与代表性内核剖析samples/下按目录组织样例目录列表每个样例的 impl 头部都带SAMPLE PROVENANCE与状态记录。以下按技术族剖析代表性内核展示样例真正可复制的东西是什么形态。5.1 单 tile 矩阵乘matmul_float_mmadvalidatedmatmul_float_mmad_impl.py 是 fp32 单 tile 矩阵乘状态为 validated2026-07-17Ascend a5/950 板端验证FP32 与 golden 逐位一致max_abs_diff 0.000e00。它的数据流为GM - L1(Mat) - L0A(Left, NZ) / L0B(Right, ZN) - matmul - L0C(Acc, fractal1024) - GM实现要点pl.make_tile_group分别声明 L1 的 A/Bpl.MemorySpace.Mat、pl.NZ布局、L0Apl.MemorySpace.Left、L0Bpl.MemorySpace.Right、pl.ZN与 L0C 累加器pl.MemorySpace.Acc、fractal1024在pl.section_cube()中依次pl.load→pl.move→pl.matmul→pl.store。头注释明确pl没有 RunMode.SIM因此只可能在 Tier-3 NPU 上验证bisheng 编译 运行。配套的 matmul_float_mmad_golden.py 是纯 torch 的参考实现def matmul_float_mmad_golden(x, y): z x y.T with FP32 accumulation. return x.float() y.float().t()其中.float()是承重设计pypto 孪生实现pypto twin在 L0C 中以 FP32 累加golden 也必须以 FP32 累加否则两者不可比。这体现了样例族的一个通用惯例golden 的精度语义必须与内核的累加语义对齐。5.2 Cube→Vector 融合手递fused_matmul_addvalidatedfused_matmul_add_impl.py 演示带手工流水同步的融合 matmul-add 手递状态 validated2026-07-1864×64 用例 FP32 逐位一致。其注释点明它是通往 bias / rowwise-norm / attention 的网关模式cube 段加载、搬运、pl.matmul然后用AccToVecMode.DualModeSplitM把 L0C 的 M 维拆分到 2 个向量子块64 → 2×32并发出FIX流水信号vector 段等待、加残差 tile、pl.store全程用pl.system.sync_src/sync_dstMTE2↔MTE1、MTE1↔M、M↔FIX 等与pl.system.set_cross_core/wait_cross_core协调流水内嵌的test_mm_add_gate_a在Ascend950设备上以q k x1为参考做torch.testing.assert_closertol/atol1e-3。该样例的注释还给出了推广配方bias 版用pl.add加广播 bias tilerow_expand 风格norm 版在同一手递后用row_max/row_sum/...处理 UB tile。5.3 动态形状行 softmaxsoftmaxvalidatedsoftmax_impl.py 是 attention 的 online-softmax 模式见 patterns/online-softmax-tail.md的向量引擎核心状态 validated2026-07-17rows64 cols64max_abs_diff2.98e-08multicoreblock_dim4行数和列数都完全动态形参声明为pl.Tensor[[pl.DYNAMIC, pl.DYNAMIC], pl.DT_FP32]MAX_N 512是编译期 UB tile 宽度上限行 tile 跨向量核分发num_tiles按TILE_ROWS 16分块循环for tile_id in pl.range(core_id, num_tiles, num_cores)把不同行 tile 分到不同核尾部用pl.set_validshape处理每个 tile 的实际有效行数valid_rows pl.min(TILE_ROWS, rows - row_off)在 load 与每个中间结果上设置 valid shape——这正是 constraints/tail-validshape.md 约束的样例体现数据流row_maxmmax over N→row_expand_subx−m→exp→row_sums→row_expand_div/s。注意其 wrapper 仍是 harness 形态torch.empty_like分配 torch.npu.synchronize()仅用于独立运行不可复制进交付物。5.4 LayerNorm一个关键修复的活教材validatedlayernorm_impl.py 状态 validated2026-07-22Gate A maxdiff2.86e-6 vsF.layer_norm判定为 COMPUTE-bound。它是一份珍贵的修复记录样例头注释记录了真实调试结论KEY FIX: gamma/beta/negbeta 必须是make_tile_group不能是裸make_tile——裸的计算 tilenegbetamul(beta,-1)不受auto_mutex同步保护导致col_expand_sub读到陈旧数据maxdiff≈5。实现还展示了两次归约先 mean再对中心化数据求 var、rsqrt/div在 row-major 别名上进行、-beta用col_expand_sub实现不存在col_expand_add以及大 tile 用make_tile_group被auto_mutex追踪、归约用单一别名make_tile的分配纪律。文件同时内嵌了torch_npu.profiler的实测流程aiv_vec_ratio等指标与 GM 带宽折算演示验证 测量一体。5.5 其它族matmul 系列 study 样例matmul_bias、matmul_relu、matmul_bias_relu、matmul_rowwise_l2_norm、matmul_quant_int8、bf16_matmul_operand_reuse内嵌正确性测试但无保留记录只用于阅读融合形态vector-functionvf系列 study 样例vf_vs_tileop/下 5 个用 vf 寄存器级 API 实现 elementwise、L2 normsilu、layernormrope、归一化与归约、softmax与 tile-op 写法形成对照向量 tile 系列reduce_sum、rope_interleave、cumsum_matmul、act_layernorm_elementwise、norm_softmax_rms_l2、cube_vec_atomic_add_two_outputs、vec_cube_abs_sqrt_matmul、matmul_rowwise_norm、matmul_softmax等覆盖行归约、旋转位置编码、规约转矩阵乘等高频拓扑。六、验证证据的留存validation-records 与模式级作用域除样例级记录外examples/validation-records.md 保留模式级pattern-level验证证据供 pattern 页面引用不依赖外部仓库、分支或评测 harness。这些记录是历史兼容性证据不是替代在当前 SDK/目标上重跑正确性。表内每行都含Pattern、Recorded target、Validated scope、Recorded result、Explicit exclusions。例如UB strip gatherAscend950PR_9579、CANN 9.2.012/12 组合逐位一致但完整 hoisting 前提、第二族C Irun路径与 general-modulo 路径不由本记录确立TensorList fixed arity历史 host-view harness 覆盖 1–64 长度、三种 dtype可交付的独立Ptr内核视图 ABI 不在本记录验证范围内需端到端目标运行Paired-lane rotation保留的交错 fp32 样例在其多核行 tile 循环内 validatedsplit-half 配对、运行时 divisor/rank、查表体制均未被该样例验证。关键原则当 pattern 页面声称的范围超过上述记录时以更窄的记录为准the narrower scope wins。七、完整性检查与负向控制让ok可信check_kb_integrity.py 是一个刻意零依赖无 torch、无 pytest可在 CI 与笔记本上运行的完整性检查器从仓库任意位置运行python3 cannbot-skills/ops/pypto-pro-op-kb/check_kb_integrity.py非零退出并打印全部违规。它执行的检查项与目的检查目的Reachability可达性每个保留文件必须能从 ROUTER.md 或维护中的索引直接/传递到达无引用的文件永远不会被任何阶段选中是原始实验输出沉淀进知识库的途径Link resolution链接解析失效链接是静默无效的引用Filename hygiene文件名卫生文件名不得携带 run id、日期、分数、状态词wip、tmp、final、score、v1、20260等且按整段匹配避免golden误伤oldPortable paths可移植路径禁止机器相关绝对路径/home、/data、/tmp等保证任意 checkout 可用Topology maptopology-map.json路由的每个路径必须存在pattern/constraint 必须待在各自命名空间反向检查每个页面都可被路由check_every_page_is_routableSample provenance headers保留样例不得声明生成副本会继承的验证结果缺失SAMPLE PROVENANCE标记即报错validated 行必须有记录索引声称validated的行必须引用记录了验证结果的样例文件记录与代码匹配VALIDATED-CODE-SHA256哈希与代码指纹一致代码改动未重验即失败配套的 tests/test_check_kb_integrity.py 是负向控制negative controls其中的每个用例都是一个曾经全绿通过的真实缺陷——向真实 KB 页面注入一个缺陷、运行应当捕获它的单个检查、然后恢复页面。其设计哲学写在文件头只有当某样东西能让它变红时ok一行才值得信任这些缺陷每个都是在检查被写好并手动验证之后、由评审发现的。运行方式python -m unittest discover -s cannbot-skills/ops/pypto-pro-op-kb/tests八、落地清单如何正确采纳一个样例综合本文全部规则采纳流程可以收敛为七步从选择器出发只在 kernel-index.md 中选行按计算形状topology匹配不要按算子名匹配不把失败/进行中/诊断/benchmark-only 探针带进选择器读状态与证据区分validated与studyvalidated还要读文件头部的SAMPLE PROVENANCE、STATUS、VALIDATED-CODE-SHA256以及保留的 golden/内嵌测试确认验证范围目标、dtype、精度只复制内核提取pl.jit内核体与数据流tile 布局、内存空间、流水同步、尾部 validshape不复制*_wrapper的 host 整形与同步在当前目标上重跑验证历史验证不建立跨版本/跨平台兼容性采纳前必须重验必要时重新打戳--stamp-validation-hashes按 wrapper-boundary 组装交付wrapper 只允许读元数据、torch.empty分配当前契约声明的输出、启动一个内核cast/transpose/reshape/cat/padding/sync 全部搬进内核无法搬入时上报设计/能力阻塞而非在 host 豁免用黄金对照对齐精度语义参照样例的 golden 惯例保证参考实现的累加 dtype 与内核一致如 L0C FP32 累加 ↔ golden.float()接受完整性检查的约束新样例的文件名不带瞬态标签、路径可移植、验证记录限定自身作用域让check_kb_integrity.py与负向控制测试继续把关。把上面任何一步跳过都会回到这个知识库用真实事故换来的教训上复制了驱动、移植了 host 整形、或者信任了一条没有记录的validated——三者都曾经以全绿的姿态发布过。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考