PyPTO-Pro 算子知识库路由指南基于 ROUTER.md 与 topology-map 的确定性知识检索与 Stage 1–4 协同机制【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym本篇指南完整讲解 PyPTO-Gym 仓库中pypto-pro-op-kb知识库的路由Routing机制它以 ROUTER.md 为入口通过机器可读的 topology-map.json 把算子的计算拓扑与 dtype/shape 属性确定性映射到约束constraints与可复用模式patterns并由 Planner、Architect、Coder、Verifier 四个角色按契约产出KB_SELECTION.json与KB_USAGE.json。读完本文你将掌握按计算形状而非算子名路由的核心方法论、7 步路由规则的执行细节、9 类拓扑与 7 类属性修饰符的映射关系以及如何用check_kb_integrity.py守护知识库的链路完整性与验证记录可信度。1. 知识库与路由器先匹配技能再打开冻结参考pypto-pro-op-kb是 PyPTO-Pro 算子的可复用知识库存放设计约束、数据流模式与经过验证的研究内核。它的定位是已安装 PyPTO-Pro API 文档与官方示例的补充而非替代——签名与平台相关行为以官方文档为准。ROUTER.md 给出的使用纪律只有两条先使用匹配的技能如pypto-pro-op-design、pypto-pro-op-develop再打开冻结进该类KB_SELECTION.json的参考不要漫无目的地浏览整个知识库。这种先路由、后打开的设计是为了保证每个算子类class只加载当前决策真正需要的参考页避免把其他平台、其他算子的数值上限误当成通用事实。2. 任务 → 技能 → 参考ROUTER 的主路由表ROUTER.md 的核心是一张任务路由表它回答了遇到什么任务该用哪个技能、打开哪份参考。表中所有参考路径均以知识库根目录cannbot-skills/ops/pypto-pro-op-kb/为基准任务技能聚焦参考选择保留的研究实现pypto-pro-material-exploreexamples/kernel-index.md选择可复用数据流pypto-pro-op-designpatterns/pattern-index.md检查 dtype 与 cast 行为pypto-pro-op-design/pypto-pro-op-developconstraints/precision.md检查 tile 形状与内存放置pypto-pro-op-design/pypto-pro-op-developconstraints/tiling.md再 constraints/memory-layout.md检查向量编写选择pypto-pro-op-developconstraints/vec.md检查同步pypto-pro-op-design/pypto-pro-op-developconstraints/sync-stitch.md检查动态尾部pypto-pro-op-design/pypto-pro-op-developconstraints/tail-validshape.md选择 A5 约束仅在目标检测后使用其数值上限design/develop/perf 技能constraints/arch-a5.md判断哪些逻辑可运行在 host 侧pypto-pro-op-design/pypto-pro-op-developconstraints/wrapper-boundary.md度量并调优一个已正确的内核pypto-pro-op-perf-tuneevidence-protocol.md定位数值误差pypto-pro-op-developplaybooks/numerical-error-localisation.md按行量化且 scale 同时是输出pypto-pro-op-designpatterns/vec-per-token-dynamic-quant.md整数 Cube 收缩直接喂给浮点 epiloguepypto-pro-op-design/pypto-pro-op-developpatterns/cv-quant-matmul-direct-epilogue.md改造多阶段 Cube matmul需要目标版本的精度/性能门槛pypto-pro-op-develop/pypto-pro-op-perf-tunereferences/staged-cube-matmul-gates.md选择或变化每次 launch 的block_dim/ core 数pypto-pro-op-develop/pypto-pro-op-perf-tunereferences/pypto-pro-launch-block-dim.md命中框架限制或调试无法解释的现象任意references/pypto-pro-framework-findings.mdAPI 看似不支持或调用正确却返回过期/错误数据任意references/pypto-pro-dsl-limitations-a5.md——按严重度排序静默失败优先调查持续无法收敛或即将信任一个测量任意references/investigation-discipline.md整次运行一次性全失败0/N或改动毫无效果或数字异常完美复现任意references/investigation-discipline.md §2、§13再配合pypto-pro-environment-check多个 Agent 并行编辑同一共享记录或合并分支任意references/investigation-discipline.md §10映射中英文硬件、流水线、tiling、布局术语任意references/terminology.md注意其中的 A5 纪律当运行时/构建选择 A5 或工作流默认 A5 生效时才加载 constraints/arch-a5.md在其精确设备与来源确认之前不得使用其中的数值上限。3. 按拓扑路由以计算形状为唯一路由依据ROUTER.md 明确声明topology-map.json 是唯一被维护的路由来源路由依据是计算的形状绝不是算子名。Planner、Architect、Coder 和 Verifier 都不得维护自己的拓扑枚举或路由表副本。这条规则的理由在 README.md 中说得很清楚算子名对新算子没有任何可复用信息而计算形状tile 宽度、pitch 字节数、pass 次数、是否跨 lane、是否别名等才是读者可以对照自己内核判断的结构属性。3.1 路由的 7 步规则一个算子可能匹配零个或多个拓扑。路由要求记录每一个实际匹配不允许覆盖、不允许唯一胜出漏记即无效。当声明的拓扑都不匹配时记录topologies: []——这不代表未知或跳过而是已评估公式、无拓扑命中此时拓扑贡献为空但 property、target 与 mandatory 路由照常执行。完整流程收集约束取每个匹配拓扑路由的约束并集收集属性约束取每个匹配的 property 约束加入目标门控约束按显式目标或工作流默认选取的 target-gated 约束加入强制约束取每条mandatory_constraints中applies_to角色参与的条目去重为required_constraints不得截断形成模式候选池由每个匹配拓扑与每个适用的属性修饰符路由的模式取并集仅当候选的前置条件成立且为该类贡献独特、具体的设计决策时保留没有数量上限无模式命中设置no_matching_pattern: true但这不解除任何约束。这套分离设计是刻意的模式patterns是可选的复用设计约束constraints是义务。模式的相关性靠明确的设计影响判定而不是靠数量截断。3.2 九类拓扑与它们的路由结果从 topology-map.json 的topologies段可以看到当前声明的全部拓扑拓扑路由的模式路由的约束语义注释elementwise—constraints/vec.md、constraints/tiling.md每输入元素一个输出元素无跨 lane 数据搬运决策点是编写风格vf 还是 tile op与 tile 宽度运行时可变输入元数通过is_list属性路由row-reductionpatterns/vec-row-reduce-broadcast.mdconstraints/vec.md每行归约为标量再广播回行内覆盖 norm、softmax 式、mean/variance 形状scanpatterns/vec-scan-prefix-dependent.mdconstraints/sync-stitch.md、constraints/tiling.md前缀依赖输出元素 i 依赖 0..i模式覆盖 inner1 / inner1 分支、rows-on-lanes 加 padding gather pitch、outer1 时并行度降低gather-scatter-indexingpatterns/vec-ub-strip-gather.md、patterns/vec-scatter-owner-model.mdconstraints/memory-layout.md、constraints/precision.md数据移动由索引张量驱动索引 dtype 宽度与越界/重复索引语义主导正确性cube-matmulpatterns/cube-only.md、patterns/batched-2d-contraction.mdconstraints/memory-layout.md在 cube 单元上对共享维做收缩quantized-matmulpatterns/quant-matmul-scaled-mm.md、patterns/cv-quant-matmul-direct-epilogue.md、patterns/cube-only.md、patterns/batched-2d-contraction.mdconstraints/precision.md、constraints/memory-layout.md整数收缩epilogue 是显式 scale/round/clamp 整数输出还是直接浮点 epilogue二者公式 oracle 不同按算子实际 epilogue 选模式multi-phase-fusionpatterns/online-softmax-tail.md、patterns/buffer-reuse-lifetime.mdconstraints/sync-stitch.md一个内核内多个依赖阶段阶段间携带状态long-axispatterns/buffer-reuse-lifetime.mdconstraints/tiling.md、constraints/memory-layout.md某轴超出单个 tile 容量强制多 tile 遍历并携带状态paired-lane-rotationpatterns/vec-paired-lane-rotation.mdconstraints/vec-alignment-and-rotation.md、constraints/vec.md最内层轴两 lane 成对由小表查出的系数做旋转变换旋转位置编码只是实例而非定义row-wise-dynamic-quantpatterns/vec-per-token-dynamic-quant.mdconstraints/precision.md、constraints/vec.md每行由该行导出的 scale 量化且 scale 本身是输出与 row-reduction 的区别是归约结果离开了内核而非只广播回去值得注意quantized-matmul的注释它继承 cube-matmul 的 tile 几何与 L0/L1 预算因为量化修改的是收缩而非定义一个无关的计算拓扑——这正是按形状分类的体现。3.3 属性修饰符、目标门控与强制约束除拓扑外路由还叠加三个正交的决策层属性修饰符property_modifiers——算子实际持有的 dtype/shape 属性触发额外约束或模式属性路由的模式路由的约束tail_blocks—constraints/tail-validshape.mdunaligned_shapes—constraints/tail-validshape.md、constraints/memory-layout.mdmixed_precision—constraints/precision.md、constraints/vec-mask-width.mdindex_dtypes—constraints/precision.mdlong_axis—constraints/tiling.mddynamic_dims—constraints/tail-validshape.mdis_listpatterns/vec-tensorlist-fixed-arity.md—目标门控target_gated——仅在目标确认后加载防止非 A5 的规划者把 A5 常量当通用事实constraints/arch-a5.md运行时/构建选择 A5或未指定目标且工作流默认 A5 时加载patterns/cv-quant-matmul-direct-epilogue.md仅 A5。页面冻结了 A5 内存容量、事件映射与宽度门槛。强制约束mandatory_constraints——当前只有一条但对所有类无条件生效constraints/wrapper-boundary.md其applies_to角色为 architect、coder、verifier理由是公开可调用对象不得在单个 PyPTO-Pro 内核 launch 周围分发 host 侧张量内核。它会被自动并入required_constraints。3.4 契约词汇表single source of truthtopology-map.json 的contract块定义了与消费方共享的词汇表契约版本为3selection_filename:KB_SELECTION.jsonusage_filename:KB_USAGE.jsonimplementation_statuses:implemented、deviated、not_applicable没有verified——验证裁决权归 verifierproperty_keys:dtypes、ranks、unaligned_shapes、tail_blocks、long_axis、mixed_precision、index_dtypes、dynamic_dims、is_list消费方是仓库的 Stage 1–4 流程pypto-pro-op-plan写KB_SELECTION.jsonpypto-pro-op-develop写KB_USAGE.json的实现声明pypto-pro-op-verifier独立验证两者后编排器才完成对应阶段。4. 阶段所有权四个角色各司其职ROUTER.md 明确了知识库选择在 Stage 1–4 工作流中的所有权划分Planner规划者读取这张路由图写出冻结的按类选择KB_SELECTION.jsonArchitect架构师读取冻结的可选模式与必需约束把每一条转化为具体的设计不变量design invariant不重新路由 KBCoder编码者实现这些不变量记录实现位置与声明claimsVerifier验证者独立地把选择与这张路由图对照检查并把使用声明与真实设计与代码对照。只有其 PASS 才允许阶段完成。从 CONTRACT.md 看除 Stage 2 外每个阶段都要求 verifier PASS 才能完成Stage 2 仅在用户显式要求时如此。契约不依赖任何外部评估器。5. 选择与使用产物KB_SELECTION.json 与 KB_USAGE.json5.1 参考分类与数量规则路由图按职责区分参考三者数量规则完全不同类含义数量规则optional_patterns为本类选出的可复用实现/数据流模式无固定上限只收录具有独特、具体设计效果的模式required_constraints由拓扑、属性、目标或全局策略触发的正确性/边界规则所有适用约束绝不截断mandatory_constraints作用于每个匹配任务、带显式applies_to角色的约束自动并入required_constraints绝不截断模式选择由相关性而非数量上限控制每个入选模式必须为本类描述一个独特的设计决策仅仅相似的算子、未满足的前置条件、重复指导或泛泛背景阅读都不可入选。约束独立于模式选择永不被抑制。5.2 KB_SELECTION.json 字段规则Planner 依据计算拓扑与 dtype/shape 属性而非算子名推导此文件字段要求schema_version等于contract.contract_versionop算子名class_id类目录扁平布局时为.永不为空topologies数组可为空只能是topology-map.json.topologies的当前键消费方必须读图而非复制枚举[]仅表示已评估且公式未命中任何声明拓扑绝不强制 best-fit绝不用空数组表示未知或跳过每个实际匹配都要记录可共存无覆盖无唯一胜出properties键取自contract.property_keys的事实optional_patterns全部且仅限实质适用的模式参考每条含 KB 相对路径、类专属理由、独特预期设计效果与内容哈希required_constraints每条适用约束无数量上限每条含 KB 相对路径、理由与内容哈希no_matching_pattern恰在无模式适配时为true必需约束仍可存在Stage 1 必须等pypto-pro-op-verifier依据当前路由图确认该选择后才能通过。5.3 KB_USAGE.json 字段规则Coder 记录每个被选参考对实现造成了什么改变但它不认证自己的工作字段要求schema_version等于contract.contract_versionop、class_id与KB_SELECTION.json一致invariants对每个可选模式与必需约束至少一条reference恰好一条存在于选择产物中的路径invariant为本类推导出的具体规则implementation.file、implementation.symbol状态为implemented或deviated时必须为真实实现位置implementation.status只能是implemented、deviated、not_applicable之一justificationdeviated与not_applicable必须提供verified刻意不是 Coder 可写的状态。Verifier 会打开每条被引用的文件与符号把不变量与代码对照向编排器返回 PASS 或 FAIL。被选参考未产生任何改变时会被拒绝除非 verifier 接受有理由的not_applicable声明。6. 完整性守护check_kb_integrity.py 的 19 项检查路由图要长期可信必须有机器检查兜底。check_kb_integrity.py 是一个刻意零依赖无 torch、无 pytest的检查器在 CI 与笔记本上都能直接运行python3 cannbot-skills/ops/pypto-pro-op-kb/check_kb_integrity.py它以非零码退出并打印每条违规覆盖 19 项检查CHECKS元组核心规则如下链接可解析links resolve断裂的链接是静默什么都不做的引用必须报出文件可达files are reachable每个保留文件都必须能从 ROUTER.md、README.md 或两个维护索引patterns/pattern-index.md、examples/kernel-index.md直接或传递地到达——不可达文件就是原始实验输出在知识库中堆积的方式拓扑图有效topology map is valid路由到的每个路径必须存在且模式/约束必须待在各自声明的命名空间patterns/与constraints/内同时反向校验每个模式/约束页都必须可被路由命中check_every_page_is_routable仅被索引链接但无法被选中的页面会被报出契约块已声明contract block is declaredschema_version必须等于contract_version属性修饰符必须来自property_keysCONTRACT.md必须声明对应版本文件名持久filenames are durable禁止wip、tmp、draft、final、old、score、日期/run/v 版本等瞬态标签按分隔符切分整段匹配避免golden误伤old、reduce_sum误伤sum路径可移植paths are portable禁止机器特定绝对路径/home、/data、/tmp等使知识库可在任意 checkout 工作样本不得删除共享目录samples do not delete shared directories保留样本若执行shutil.rmtree或rm -rf即违规——它教坏了 Agent 规则明令禁止的行为验证记录的作用域validation records are scoped样本若断言验证结果头部必须带SAMPLE PROVENANCE标记防止生成副本继承不应得的验证记录validated 行必须有记录validated rows have a recordkernel-index中任何标记validated的行必须引用真实存在的样本文件且该文件前 40 行内存在验证记录验证记录必须匹配代码validation records match the code通过VALIDATED-CODE-SHA256字段把验证记录钉在实测代码上——代码一旦被改写而记录未更新即失败。哈希按去掉整行注释与空行后的代码行计算刻意不做 token 化因为token.type在不同 Python 版本间会漂移PEP 701 也会改变 f-string 的 token 结构重验证后用--stamp-validation-hashes重新盖章validated 模式必须引用证据validated patterns cite evidencepattern-index.md中声明 validated 的行其实现引用必须在磁盘或已 fetch 的命名分支上可解析引用仅在未 fetch 的分支上时报告SKIP不确定而非通过跨包链接可解析cross-package links resolve扫描所有ops/pypto-*技能中形如../pypto-...的跨包链接——技能以符号链接安装进cannbot-skills/ops/..会物理解析回兄弟目录因此 sibling 形式在 checkout 与安装两种布局下都能解析CONTRACT.md 实测 41/41 全部通过报告副本一致report copies agreeKB 的 A5 限制页与 docs/pypto-pro-dsl-limitations.md 的 Part I 条目标题必须一致参考引用可解析reference citations resolve任何 KB 页面引用custom/...或tools/...都必须能解析花括号引用{A.py,B.py}要求每个成员都在all而非any章节引用可解析section citations resolve§N引用必须指向目标页确实定义的章节多 Part 条目必须限定multi-part entries are qualified在多 Part 报告中裸entry N必须指明 Part如entry II-14且限定引用必须落在该 Part 实际定义的条目范围内。运行输出用ok、FAIL与SKIP三态区分SKIP表示该项检查没有可检查的对象不确认任何事实。仓库自带负向测试 tests/test_check_kb_integrity.py每一个用例都是曾经全绿通过的真实缺陷运行方式python -m unittest discover -s cannbot-skills/ops/pypto-pro-op-kb/tests7. 内容治理保留门槛与可复用规则的写法知识库的质量不止靠路由还靠内容治理。README.md 定义了保留门槛Retention Gate——只有同时满足以下全部条件KB 条目才允许保留有活跃的路由器或选择器链接到它其用途可超越单次实验、分支、环境、日期、基准分数或会话而复用技术声明引用了官方文档/源码路径或保留的、可审查的验证产物代码仅在验证状态为validated时入选失败、进行中与诊断探针不得进入生产选择器。文件名用场景与技术名实测数值放进验证证据绝不进文件名。7.1 以形状为分类主体trigger → rule → evidenceREADME.md 把可复用规则的写作方法概括为trigger → rule → evidence三段式Trigger触发条件读者无需知道任何其他算子、仅凭自己内核的结构属性即可判定的特征——tile 宽度lanes、pitchbytes、pass 次数、循环是否跨 lane、tile 是否别名Rule规则做什么措辞要能跨越 SKU 与算子的变化而存活Evidence证据测量结果带足够的出处供读者判断是否可信。最典型的失败模式是把算子当成规则的主体——例如写算子 X 的 pitch 是 80 元素而不是pitch 是 32 B 的偶倍数会冲突在访问实际发生的 tile 上检查它。前者让读者必须先重构类比规则就无法迁移。三种算子提及是合法的不应被清除拓扑的定义语义如 gather-scatter 页上的torch.gather、API 名如vf.scatter、验证出处如custom/op/作为 validated 骨架背后的保留产物。写作自查方法删掉句子中所有算子名如果规则仍能告诉读者何时适用、该做什么就是写对了。7.2 validated 与 study两种状态区别重大examples/kernel-index.md 用两态区分内核样本validated——保留文件记录了通过的正确性结果跑过什么、在什么目标上、达到什么精度记录取自 Ascend 950 系列 A5 目标在其他架构或 SDK 版本上把该行视为候选并重跑正确性study——文件带内嵌测试但没有保留通过记录。读它只为了解实现形状它不是实现正确的证据也不会给模仿它的任何东西授予验证。check_kb_integrity.py强制validated 行必须携带验证记录check_validated_rows_have_records因为此前曾有 12 个文件在无任何记录的情况下被笼统声称 validated。8. 实战一次完整的路由与产物落地把以上机制串起来一次标准流程是这样的规划Stage 1Planner 拿到一个新算子任务先按计算的形状判断其拓扑例如逐元素输出 运行时可变输入个数应匹配elementwiseis_list属性读取 topology-map.json 执行 7 步路由产出KB_SELECTION.json验证选择Verifier 对照路由图独立复核选择PASS 前 Stage 1 不得完成设计Stage 2/3Architect 把optional_patterns与required_constraints转成设计不变量Coder 实现并把每条不变量落到KB_USAGE.json的implemented/deviated/not_applicable声明验证实现Stage 4Verifier 打开每个被引用的文件与符号把不变量与真实代码对照PASS 才允许阶段完成守护任何时刻运行check_kb_integrity.py保证路由表、链接、命名、路径与验证记录始终自洽。9. 常见误区与边界topologies: []不等于未评估它只在公式被求值且未命中任何声明拓扑后使用且不跳过 property、target 与 mandatory 路由A5 数值不是通用事实在精确设备与来源确认前不得使用 constraints/arch-a5.md 中的数值上限约束不可截断、不可被无模式豁免no_matching_pattern: true只说明没有可复用模式所有适用约束依旧生效知识库不覆盖官方文档签名与平台行为以已安装 API 文档与官方示例为准constraints/README.md 特别声明若 KB 陈述与已安装 API 文档、官方样例或正确性运行冲突以目标环境的证据为准并更新派生设计不要维护自己的路由副本拓扑枚举与路由表只有 topology-map.json 一份消费方必须读图否则契约词汇一旦漂移没有任何机制能发现。从源码结构看这套路由器 机器可读路由图 契约产物 完整性检查的闭环正是为了让不同 AgentPlanner/Architect/Coder/Verifier在共享同一个知识库时既能并行工作、又能对选择了什么、依据是什么、是否真被实现保持完全一致的可审计记录。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考