PyPTO 不透明错误码排查实战从Errcode: FFFFF/UNKNOWN到F21004的完整调试工作流pypto-gym【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym本文是 CANN / pypto-gym 仓库中pypto-general-debug技能包针对不透明错误码Errcode: FFFFF!、UNKNOWN、0x3FFFF、INVALID_VAL (0x21004)等的官方排查行动手册原文档见 error-codes.md。它面向在仓库 src/pypto_gym/ops/pypto_tensor 下开发复杂 PyPTO 算子的开发者与 Agent完整覆盖错误码的捕获与路由、设备日志slog提取、ast-grep 高效检索、内核级爆炸半径收敛以及F21004 / REGISTER_COPY向量 tile 形状问题的标准修复。读完本文你将掌握一套先收集证据、再分类、后收敛的可重复调试协议并学会用set_vec_tile_shapes快速修复最典型的向量算子报错。适用范围与铁律什么才算真正可以停止本 playbook 适用于三类常见失败形态它们在复杂 PyPTO 内核开发中几乎必然出现不透明错误码如FFFFF、UNKNOWN、0x3FFFF只有代码、没有叙事Python 侧静默成功运行看似正常但输出错误或全零且Python 层完全不报任何错误NPU 侧早期崩溃只留下一行简短信息如Inner Error, please contact Huawei Engineer。核心政策原文档 PolicyErrcode: FFFFF!、UNKNOWN、0x3FFFF或其他看起来吓人的错误码都不是结束会话、报告失败或放弃的理由——除非 rules.md 中定义的Stop Conditions停止条件真正生效。Token 与轮次预算不构成本工作流的约束请持续迭代、收集证据、按结构化策略逐条尝试直到问题解决或证明存在真正的阻塞点。原文档还明确列出了被禁止的放弃行为只打印错误码就停手、不查阅文档就宣称任务不可能、跳过日志、拒绝尝试新的角度。仓库规则 rules.md 第 13 条Do not stop on cryptic errors alone与之完全一致FFFFF、UNKNOWN、0x3FFFF或其他不透明的Errcode: F…!行不是放弃任务的理由必须继续收集日志、运行extract_pypto_calls.py并执行逐算子协议。第一步动作总是执行捕获、路由、记录无论错误形态如何调试都必须从以下三个固定动作开始① 捕获完整消息——包括 stderr、Python traceback以及任何pypto-log*.log/ 设备日志行。在日志中检索Errcode、ErrCode、F 数字、aicore等关键字。② 路由错误码——根据错误码前缀定位组件文档。本仓库内可直接参考 error-code-troubleshooting.md 的错误码前缀决定组件归属规则例如F7XXXX属于 machine 组件、FC0XXX属于 vector 组件、F6xxxx属于 codegen 组件。对于许多F2xxxx风格的代码打开 FUNCTION 组件文档如果错误码是F21004或涉及REGISTER_COPY、无效向量 tile请直接跳到本文F21004 深度解析一节。③ 追加记录到custom/operator_name/MEMORY.md的 Development debug log——记录什么失败了、运行命令、假设、下一步。不允许出现空的stopped结尾。这一要求与 rules.md 的 Memory file 规则每个回合都要更新custom/operator_name/MEMORY.md相互呼应其模板见 MEMORY.template.md。错误码从哪来两条获取途径仓库内的 error-code-troubleshooting.md 给出了错误码的两条获取途径二者适用场景不同途径适用场景特点stderr运行异常前端参数校验错误直接抛 RuntimeError包含Errcode: Fxxxxx!日志文件编译/运行阶段深层错误pypto-log*.log中[ERROR] ... ErrCode: Fxxxxx!关键区别在于前端参数校验错误如 FC0000 dtype 不匹配不会写入日志文件直接从异常信息获取即可而编译/运行阶段错误会写入日志文件需要开启日志排查。因此先确认报错是否包含错误码格式Errcode: Fxxxxx!或ErrCode: Fxxxxx!有错误码则走错误码排查流程无错误码则直接分析报错信息或日志定位问题。不透明失败三连UNKNOWN / FFFFF / 静默失败本节处理三种关联的失败模式无叙事的不透明错误码、Python 侧看似成功但输出错误且无任何 Python 层报错、NPU 早期死亡只留一行简讯。三种情况下 Python stderr 都不够用——真正的错误在设备 slog 里。你必须把它拉进 stdout、捕获到文件、然后高效检索。2a. 强制设备日志进 stdout 并捕获设置两个 ASCEND 环境变量并把 stdout 重定向到日志文件后重跑export ASCEND_GLOBAL_LOG_LEVEL0 # 0 DEBUG, 1 INFO, 2 WARN, 3 ERROR, 4 NULL export ASCEND_SLOG_PRINT_TO_STDOUT1 # route slog to stdout instead of on-disk slog files python failing_file.py result.log 21注意事项原文档明确要求不可省略用追加而不是重复运行会累积证据方便之后 diff 对比21必须保留某些 ASCEND 层即使设置了PRINT_TO_STDOUT1也仍向 stderr 输出ASCEND_GLOBAL_LOG_LEVEL0非常啰嗦对任意非平凡内核单算子、L1 shape、完整 NT 循环result.log通常轻松超过10 MB在 NPU 服务器上通过Run file on npu:N运行环境变量作用于该进程。2b. 用 ast-grep 高效检索result.log直接grep -n ERROR result.log只能得到 ERROR 行的列表会丢失每条错误周围的结构化上下文前面的[TRACE]面包屑、CCE 文件路径、栈帧而手工滚动 10 MB 的 slog 是死路。推荐检索命令按顺序执行每步进一步缩小噪声所有 ERROR 级行 5 行尾随上下文尾随行通常携带 ERROR 行引用的设备栈帧ast-grep run --pattern ERROR --context-after 5 result.log只有未安装 ast-grep 时才退回grep -nA 5 ERROR result.log。过滤携带错误码的 ERROR 行F2xxxx、E1xxxx、0xXXXXX、Errcode、ErrCodeast-grep run --pattern ERROR $CODE --regex F[0-9]{5}|E[0-9]{5}|0x[0-9A-Fa-f]|Errcode|ErrCode result.log提取匹配的 CCE 文件路径错误引用生成的设备代码时ast-grep run --pattern $PATH.cce --regex /.*\.cce result.log只收窄到最后一个 ERROR 块如果运行提前死亡Python traceback 之前的最后一条错误通常是真正原因tac result.log | ast-grep run --pattern ERROR --context-before 5 --context-after 20 --max-count 1如果算子使用了pypto.loop且怀疑是与迭代相关的失败还要搜索框架发出的循环索引面包屑loop iter、chunk、NT step。这些内容在同一条日志里但往往位于 ERROR 行下方所以步骤 1 中的--context-after 20会一并捕获它们。2c. 对定位到的错误块分类一旦隔离出相关 ERROR 块通常 20–50 行而不是 10 MB按前缀分类F2xxxx走 FUNCTION 组件排查文档若是F21004见本文F21004 深度解析F4/F5pass / 编译错误——见布局 CI 与 pass 回归运行干净结束但输出错误即使LOG_LEVEL0也没有 ERROR 行这是真正的静默精度/正确性失败转精度排查仓库内可加载pypto-precision-debug/pypto-precision-compare子技能见 SKILL.md 的子技能路由策略。2d. 计算图 / 程序 dump若怀疑计算图本身有问题按排查文档中的computation-graph / program-dump指引操作上游文档可能称其为 view computation graph不要把 unknown 当作终点要把它当作需要更多信号更多日志、更小复现、更早的 checkpoint。2e. 将发现追加到记忆文件每次产生有效信号的 ASCEND 日志检索ERROR 码、CCE 文件、循环索引面包屑都记录到custom/op/MEMORY.md→ Development debug log包含三要素使用的确切 ast-grep 命令匹配块不是 10 MB 全量日志只放收窄后的结果由此得出的分类结论。这保留了搜索轨迹便于后续二分定位也便于验证环节交接。内核级排查缩小爆炸半径定位到错误后回到内核层面逐模块收敛原文档 §3确认当前生效的分阶段文件如op_module12.py等——见 rules.md 规则 14 的分阶段文件链operator_name_module1.py→…_module12.py→…_module123.py后缀数字表示累积的模块范围。对该文件或最终内核运行extract_pypto_calls.py运行python3 cannbot-skills/ops/pypto-op-review/scripts/extract_pypto_calls.py kernel.py并遵循 pypto-general-debug SKILL.md 中的逐算子op-by-op检查协议一次只激活一个模块必要时用 golden 供给的张量 stub 下游用detailed_tensor_compare来自 detailed_tensor_compare.py仓库 rules.md 规则 9 规定其为唯一主报告工具重跑模块边界检查并把结果记录进Per-module verification log修复后重跑当前分阶段文件和/或test_operator_name.py确认每一个内核输出规则 10必须比较所有叶子输出禁止只验第一个张量。3a. 布局 CI 与 pass 回归快速要点布局 / 循环布局与结构规则由 pypto-op-lint 钩子自动强制执行文件写入时及阶段闸口处没有单独的布局脚本可跑。lintFAIL意味着要修复 memory /test_op.py/ 分阶段文件命名OL44 等或者删除内核代码中的 Python 循环——把这种迭代改用pypto.loop表达在_your_op_kernel_impl/ JIT 内核中。宿主包装器中用for ... in range(...)驱动内核是OL45JIT 图内出现while或非 range 的 Pythonfor是OL57——两者都违反 rules.md 的 Prohibition B / 规则 18迭代必须用pypto.loop绝不用 Pythonfor/while。图编辑后立即出现 pass / 编译失败如果日志显示PASS范围代码F4/F5对 PyPTO 图做二分例如最近已知正常的分阶段文件 vs 当前文件并在大改前通过pypto-docs-search技能或直接查阅 API 文档重新核对算子 API 约束pypto-op.md。在失败文件上重跑extract_pypto_calls.py看是否新的算子顺序触发了 pass 问题。extract_pypto_calls.py脚本本身见 extract_pypto_calls.py基于 Python AST 静态解析它会先收集import pypto/from pypto import ...的别名再遍历所有ast.Call节点输出按行列排序的行号 调用形态列表支持--json供机器消费。这正是逐算子核对清单的单一事实来源——SKILL.md 的 Step 0 要求必须先在失败内核文件上运行它。F21004 深度解析REGISTER_COPY与向量 tile 形状F21004INVALID_VAL即TileShape::Current().GetVecTile()无效是本仓库调试中最常见、也最有代表性的向量类报错值得单独一节讲透。框架侧原因F21004在Operation的构造函数中被抛出触发条件是TileShape::Current().GetVecTile()无效例如framework/src/interface/operation/operation.cpp约 191–195 行。为什么错误信息里出现REGISTER_COPYREGISTER_COPY是一个AIV 算子。即使该算子是编译器插入的例如内存冲突 pass 插入的拷贝它同样需要一个有效的向量 tile。不存在单独的 REGISTER_COPY tiling 注册——与普通 vec 算子相同的 tile 规则同样适用。何时VecTile才有效存储的 tile 列表必须非空且每个值必须 0见tile_shape.cpp。在 PyPTO Python 侧如何修复在该作用域内任何向量/张量工作之前包括最终会引出REGISTER_COPY的代码先设置向量tile 尺寸import pypto pypto.set_vec_tile_shapes(1, 1, 128, 128) # 按文档要求传入正整数在jit/ 内核函数体的开头调用它如果所用 API 使用嵌套作用域则每次作用域切换后再调用一次。不要只依赖set_cube_tile_shapes——cube tile不能替代像REGISTER_COPY这样的 AIV 算子的向量 tile。若同时使用 cube 与 vector 算子两者都要设置pypto.set_cube_tile_shapes([128, 128], [128, 128], [128, 128]) pypto.set_vec_tile_shapes(1, 1, 128, 128)仓库源码佐证真实算子中的 tile 设置模式仓库中的真实实现印证了上述模式其中 fused_swiglu_impl.py 是一个cube vec 混用、作用域内反复设置 tile的典型样本第 50 行pypto.loop之前先pypto.set_vec_tile_shapes(128, 128)第 58 行在 matmulcube 算子之前设置pypto.set_cube_tile_shapes([128, 128], [128, 256], [128, 128])第 61 行在 sigmoid / 逐元素乘vector 算子之前再次调用pypto.set_vec_tile_shapes(128, 128)。这个先 vec → 切 cube → 切回 vec的顺序正是 error-codes.md §4 要求的任何会增加算子的操作reshape、view、pass 插入拷贝必须在该执行路径上的set_vec_tile_shapes之后运行的工程化体现。纯向量算子的仓库样本可见 apply_rms_prop_impl.py其内核开头第 38 行即pypto.set_vec_tile_shapes(32, 512)随后才做grad * grad、sqrt等逐元素运算——单参数形式两个值即向量 tile 的 2 维表达而 §4 给出的四参数形式(1, 1, 128, 128)对应更高维度配置具体以所用 PyPTO 版本的 set_vec_tile_shapes API 文档为准。仍然失败时的检查清单无效参数或零值确保所有参数都是正整数rules.md 规则 16 也强制要求传入正整数 tile 参数顺序错误任何增加算子的操作reshape、view、插入拷贝的 pass必须在该执行路径上的set_vec_tile_shapes之后运行符号/动态形状确保 tile 参数能解析为具体的正整数配合SymbolicScalar使用。结论REGISTER_COPY上的F21004几乎总是创建该算子时当前作用域没有有效的vec_tile_shapes。修复方式就是在这些算子运行前用全正尺寸的pypto.set_vec_tile_shapes(...)完成设置。错误码快速参考仓库内索引本仓库可直接使用的错误码索引见 error-code-troubleshooting.md对应 error-codes.md §6 的快速参考该技能包的完整调试路由索引见 DEBUG_GUIDEBOOK.md §1–§7 →error-codes.md。常见错误码速查表错误码组件含义排查入口FC0000VECTORERR_PARAM_INVALIDerror-code-troubleshooting.mdvector 排查文档FC0001VECTORERR_PARAM_DTYPE_UNSUPPORTED同上FC1000VECTORERR_CONFIG_TILE同上FC1001VECTORERR_CONFIG_ALIGNMENT同上F62014CODEGENSYMBOL_NOT_FOUNDcodegen 排查文档F63001CODEGENCOMPILE_CODE_FAILEDcodegen 排查文档涉及并行编译时需串行编译F21004FUNCTIONINVALID_VALVecTile 无效本文F21004 深度解析一节F40005—UB 分配超限scan/大轴归约scan-and-reduction.md要点回顾错误码前缀决定组件归属F7XXXX查 machine 组件、FC0XXX查 vector 组件、F6xxxx查 codegen 组件前端校验错误无需看日志直接从异常信息获取错误码与描述编译问题需串行编译见 codegen 排查文档F21004/ vec tile /REGISTER_COPY见本文上文专门一节精度类问题可加载pypto-precision-debug/pypto-precision-compare技能见 SKILL.md 的路由决策树detailed_tensor_compare返回all_close: false且无崩溃、无 aicore 错误 → 加载pypto-precision-debug仍失败或发散 checkpoint 未定位 → 加载pypto-precision-compare。停止条件什么时候才允许停下只有在与 rules.md 中的Stop Conditions对齐时才允许暂停包括参考代码缺失、归一化 golden 无法等价、框架从根本上阻塞所需的集成形态、缺少用户必须提供的日志、或经过穷尽的结构化尝试后证明只能盲目猜测。一条孤立的隐晦错误行永远不够。最终提醒宁可留下十条带日志引用的失败尝试记录也不要一次过早退出。未知错误码意味着升级证据与方法而不是停止。完整的调试路径情况 → 叶子文档映射始终从 DEBUG_GUIDEBOOK.md 出发不透明错误码 →error-codes.mdF21004 / REGISTER_COPY→error-codes.md§4再视修复方向进入 tile-shapes.mdNPU 启动失败Errcode: FFFFFF! launch aicpu→ npu-launch-failures.md。按照捕获 → 路由 → 记录 → 分类 → 收敛的节奏迭代复杂 PyPTO 内核开发中的绝大多数不透明错误都能被定位并修复。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PyPTO 不透明错误码排查实战：从 `Errcode: FFFFF` / `UNKNOWN` 到 `F21004` 的完整调试工作流（pypto-gym）
PyPTO 不透明错误码排查实战从Errcode: FFFFF/UNKNOWN到F21004的完整调试工作流pypto-gym【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym本文是 CANN / pypto-gym 仓库中pypto-general-debug技能包针对不透明错误码Errcode: FFFFF!、UNKNOWN、0x3FFFF、INVALID_VAL (0x21004)等的官方排查行动手册原文档见 error-codes.md。它面向在仓库 src/pypto_gym/ops/pypto_tensor 下开发复杂 PyPTO 算子的开发者与 Agent完整覆盖错误码的捕获与路由、设备日志slog提取、ast-grep 高效检索、内核级爆炸半径收敛以及F21004 / REGISTER_COPY向量 tile 形状问题的标准修复。读完本文你将掌握一套先收集证据、再分类、后收敛的可重复调试协议并学会用set_vec_tile_shapes快速修复最典型的向量算子报错。适用范围与铁律什么才算真正可以停止本 playbook 适用于三类常见失败形态它们在复杂 PyPTO 内核开发中几乎必然出现不透明错误码如FFFFF、UNKNOWN、0x3FFFF只有代码、没有叙事Python 侧静默成功运行看似正常但输出错误或全零且Python 层完全不报任何错误NPU 侧早期崩溃只留下一行简短信息如Inner Error, please contact Huawei Engineer。核心政策原文档 PolicyErrcode: FFFFF!、UNKNOWN、0x3FFFF或其他看起来吓人的错误码都不是结束会话、报告失败或放弃的理由——除非 rules.md 中定义的Stop Conditions停止条件真正生效。Token 与轮次预算不构成本工作流的约束请持续迭代、收集证据、按结构化策略逐条尝试直到问题解决或证明存在真正的阻塞点。原文档还明确列出了被禁止的放弃行为只打印错误码就停手、不查阅文档就宣称任务不可能、跳过日志、拒绝尝试新的角度。仓库规则 rules.md 第 13 条Do not stop on cryptic errors alone与之完全一致FFFFF、UNKNOWN、0x3FFFF或其他不透明的Errcode: F…!行不是放弃任务的理由必须继续收集日志、运行extract_pypto_calls.py并执行逐算子协议。第一步动作总是执行捕获、路由、记录无论错误形态如何调试都必须从以下三个固定动作开始① 捕获完整消息——包括 stderr、Python traceback以及任何pypto-log*.log/ 设备日志行。在日志中检索Errcode、ErrCode、F 数字、aicore等关键字。② 路由错误码——根据错误码前缀定位组件文档。本仓库内可直接参考 error-code-troubleshooting.md 的错误码前缀决定组件归属规则例如F7XXXX属于 machine 组件、FC0XXX属于 vector 组件、F6xxxx属于 codegen 组件。对于许多F2xxxx风格的代码打开 FUNCTION 组件文档如果错误码是F21004或涉及REGISTER_COPY、无效向量 tile请直接跳到本文F21004 深度解析一节。③ 追加记录到custom/operator_name/MEMORY.md的 Development debug log——记录什么失败了、运行命令、假设、下一步。不允许出现空的stopped结尾。这一要求与 rules.md 的 Memory file 规则每个回合都要更新custom/operator_name/MEMORY.md相互呼应其模板见 MEMORY.template.md。错误码从哪来两条获取途径仓库内的 error-code-troubleshooting.md 给出了错误码的两条获取途径二者适用场景不同途径适用场景特点stderr运行异常前端参数校验错误直接抛 RuntimeError包含Errcode: Fxxxxx!日志文件编译/运行阶段深层错误pypto-log*.log中[ERROR] ... ErrCode: Fxxxxx!关键区别在于前端参数校验错误如 FC0000 dtype 不匹配不会写入日志文件直接从异常信息获取即可而编译/运行阶段错误会写入日志文件需要开启日志排查。因此先确认报错是否包含错误码格式Errcode: Fxxxxx!或ErrCode: Fxxxxx!有错误码则走错误码排查流程无错误码则直接分析报错信息或日志定位问题。不透明失败三连UNKNOWN / FFFFF / 静默失败本节处理三种关联的失败模式无叙事的不透明错误码、Python 侧看似成功但输出错误且无任何 Python 层报错、NPU 早期死亡只留一行简讯。三种情况下 Python stderr 都不够用——真正的错误在设备 slog 里。你必须把它拉进 stdout、捕获到文件、然后高效检索。2a. 强制设备日志进 stdout 并捕获设置两个 ASCEND 环境变量并把 stdout 重定向到日志文件后重跑export ASCEND_GLOBAL_LOG_LEVEL0 # 0 DEBUG, 1 INFO, 2 WARN, 3 ERROR, 4 NULL export ASCEND_SLOG_PRINT_TO_STDOUT1 # route slog to stdout instead of on-disk slog files python failing_file.py result.log 21注意事项原文档明确要求不可省略用追加而不是重复运行会累积证据方便之后 diff 对比21必须保留某些 ASCEND 层即使设置了PRINT_TO_STDOUT1也仍向 stderr 输出ASCEND_GLOBAL_LOG_LEVEL0非常啰嗦对任意非平凡内核单算子、L1 shape、完整 NT 循环result.log通常轻松超过10 MB在 NPU 服务器上通过Run file on npu:N运行环境变量作用于该进程。2b. 用 ast-grep 高效检索result.log直接grep -n ERROR result.log只能得到 ERROR 行的列表会丢失每条错误周围的结构化上下文前面的[TRACE]面包屑、CCE 文件路径、栈帧而手工滚动 10 MB 的 slog 是死路。推荐检索命令按顺序执行每步进一步缩小噪声所有 ERROR 级行 5 行尾随上下文尾随行通常携带 ERROR 行引用的设备栈帧ast-grep run --pattern ERROR --context-after 5 result.log只有未安装 ast-grep 时才退回grep -nA 5 ERROR result.log。过滤携带错误码的 ERROR 行F2xxxx、E1xxxx、0xXXXXX、Errcode、ErrCodeast-grep run --pattern ERROR $CODE --regex F[0-9]{5}|E[0-9]{5}|0x[0-9A-Fa-f]|Errcode|ErrCode result.log提取匹配的 CCE 文件路径错误引用生成的设备代码时ast-grep run --pattern $PATH.cce --regex /.*\.cce result.log只收窄到最后一个 ERROR 块如果运行提前死亡Python traceback 之前的最后一条错误通常是真正原因tac result.log | ast-grep run --pattern ERROR --context-before 5 --context-after 20 --max-count 1如果算子使用了pypto.loop且怀疑是与迭代相关的失败还要搜索框架发出的循环索引面包屑loop iter、chunk、NT step。这些内容在同一条日志里但往往位于 ERROR 行下方所以步骤 1 中的--context-after 20会一并捕获它们。2c. 对定位到的错误块分类一旦隔离出相关 ERROR 块通常 20–50 行而不是 10 MB按前缀分类F2xxxx走 FUNCTION 组件排查文档若是F21004见本文F21004 深度解析F4/F5pass / 编译错误——见布局 CI 与 pass 回归运行干净结束但输出错误即使LOG_LEVEL0也没有 ERROR 行这是真正的静默精度/正确性失败转精度排查仓库内可加载pypto-precision-debug/pypto-precision-compare子技能见 SKILL.md 的子技能路由策略。2d. 计算图 / 程序 dump若怀疑计算图本身有问题按排查文档中的computation-graph / program-dump指引操作上游文档可能称其为 view computation graph不要把 unknown 当作终点要把它当作需要更多信号更多日志、更小复现、更早的 checkpoint。2e. 将发现追加到记忆文件每次产生有效信号的 ASCEND 日志检索ERROR 码、CCE 文件、循环索引面包屑都记录到custom/op/MEMORY.md→ Development debug log包含三要素使用的确切 ast-grep 命令匹配块不是 10 MB 全量日志只放收窄后的结果由此得出的分类结论。这保留了搜索轨迹便于后续二分定位也便于验证环节交接。内核级排查缩小爆炸半径定位到错误后回到内核层面逐模块收敛原文档 §3确认当前生效的分阶段文件如op_module12.py等——见 rules.md 规则 14 的分阶段文件链operator_name_module1.py→…_module12.py→…_module123.py后缀数字表示累积的模块范围。对该文件或最终内核运行extract_pypto_calls.py运行python3 cannbot-skills/ops/pypto-op-review/scripts/extract_pypto_calls.py kernel.py并遵循 pypto-general-debug SKILL.md 中的逐算子op-by-op检查协议一次只激活一个模块必要时用 golden 供给的张量 stub 下游用detailed_tensor_compare来自 detailed_tensor_compare.py仓库 rules.md 规则 9 规定其为唯一主报告工具重跑模块边界检查并把结果记录进Per-module verification log修复后重跑当前分阶段文件和/或test_operator_name.py确认每一个内核输出规则 10必须比较所有叶子输出禁止只验第一个张量。3a. 布局 CI 与 pass 回归快速要点布局 / 循环布局与结构规则由 pypto-op-lint 钩子自动强制执行文件写入时及阶段闸口处没有单独的布局脚本可跑。lintFAIL意味着要修复 memory /test_op.py/ 分阶段文件命名OL44 等或者删除内核代码中的 Python 循环——把这种迭代改用pypto.loop表达在_your_op_kernel_impl/ JIT 内核中。宿主包装器中用for ... in range(...)驱动内核是OL45JIT 图内出现while或非 range 的 Pythonfor是OL57——两者都违反 rules.md 的 Prohibition B / 规则 18迭代必须用pypto.loop绝不用 Pythonfor/while。图编辑后立即出现 pass / 编译失败如果日志显示PASS范围代码F4/F5对 PyPTO 图做二分例如最近已知正常的分阶段文件 vs 当前文件并在大改前通过pypto-docs-search技能或直接查阅 API 文档重新核对算子 API 约束pypto-op.md。在失败文件上重跑extract_pypto_calls.py看是否新的算子顺序触发了 pass 问题。extract_pypto_calls.py脚本本身见 extract_pypto_calls.py基于 Python AST 静态解析它会先收集import pypto/from pypto import ...的别名再遍历所有ast.Call节点输出按行列排序的行号 调用形态列表支持--json供机器消费。这正是逐算子核对清单的单一事实来源——SKILL.md 的 Step 0 要求必须先在失败内核文件上运行它。F21004 深度解析REGISTER_COPY与向量 tile 形状F21004INVALID_VAL即TileShape::Current().GetVecTile()无效是本仓库调试中最常见、也最有代表性的向量类报错值得单独一节讲透。框架侧原因F21004在Operation的构造函数中被抛出触发条件是TileShape::Current().GetVecTile()无效例如framework/src/interface/operation/operation.cpp约 191–195 行。为什么错误信息里出现REGISTER_COPYREGISTER_COPY是一个AIV 算子。即使该算子是编译器插入的例如内存冲突 pass 插入的拷贝它同样需要一个有效的向量 tile。不存在单独的 REGISTER_COPY tiling 注册——与普通 vec 算子相同的 tile 规则同样适用。何时VecTile才有效存储的 tile 列表必须非空且每个值必须 0见tile_shape.cpp。在 PyPTO Python 侧如何修复在该作用域内任何向量/张量工作之前包括最终会引出REGISTER_COPY的代码先设置向量tile 尺寸import pypto pypto.set_vec_tile_shapes(1, 1, 128, 128) # 按文档要求传入正整数在jit/ 内核函数体的开头调用它如果所用 API 使用嵌套作用域则每次作用域切换后再调用一次。不要只依赖set_cube_tile_shapes——cube tile不能替代像REGISTER_COPY这样的 AIV 算子的向量 tile。若同时使用 cube 与 vector 算子两者都要设置pypto.set_cube_tile_shapes([128, 128], [128, 128], [128, 128]) pypto.set_vec_tile_shapes(1, 1, 128, 128)仓库源码佐证真实算子中的 tile 设置模式仓库中的真实实现印证了上述模式其中 fused_swiglu_impl.py 是一个cube vec 混用、作用域内反复设置 tile的典型样本第 50 行pypto.loop之前先pypto.set_vec_tile_shapes(128, 128)第 58 行在 matmulcube 算子之前设置pypto.set_cube_tile_shapes([128, 128], [128, 256], [128, 128])第 61 行在 sigmoid / 逐元素乘vector 算子之前再次调用pypto.set_vec_tile_shapes(128, 128)。这个先 vec → 切 cube → 切回 vec的顺序正是 error-codes.md §4 要求的任何会增加算子的操作reshape、view、pass 插入拷贝必须在该执行路径上的set_vec_tile_shapes之后运行的工程化体现。纯向量算子的仓库样本可见 apply_rms_prop_impl.py其内核开头第 38 行即pypto.set_vec_tile_shapes(32, 512)随后才做grad * grad、sqrt等逐元素运算——单参数形式两个值即向量 tile 的 2 维表达而 §4 给出的四参数形式(1, 1, 128, 128)对应更高维度配置具体以所用 PyPTO 版本的 set_vec_tile_shapes API 文档为准。仍然失败时的检查清单无效参数或零值确保所有参数都是正整数rules.md 规则 16 也强制要求传入正整数 tile 参数顺序错误任何增加算子的操作reshape、view、插入拷贝的 pass必须在该执行路径上的set_vec_tile_shapes之后运行符号/动态形状确保 tile 参数能解析为具体的正整数配合SymbolicScalar使用。结论REGISTER_COPY上的F21004几乎总是创建该算子时当前作用域没有有效的vec_tile_shapes。修复方式就是在这些算子运行前用全正尺寸的pypto.set_vec_tile_shapes(...)完成设置。错误码快速参考仓库内索引本仓库可直接使用的错误码索引见 error-code-troubleshooting.md对应 error-codes.md §6 的快速参考该技能包的完整调试路由索引见 DEBUG_GUIDEBOOK.md §1–§7 →error-codes.md。常见错误码速查表错误码组件含义排查入口FC0000VECTORERR_PARAM_INVALIDerror-code-troubleshooting.mdvector 排查文档FC0001VECTORERR_PARAM_DTYPE_UNSUPPORTED同上FC1000VECTORERR_CONFIG_TILE同上FC1001VECTORERR_CONFIG_ALIGNMENT同上F62014CODEGENSYMBOL_NOT_FOUNDcodegen 排查文档F63001CODEGENCOMPILE_CODE_FAILEDcodegen 排查文档涉及并行编译时需串行编译F21004FUNCTIONINVALID_VALVecTile 无效本文F21004 深度解析一节F40005—UB 分配超限scan/大轴归约scan-and-reduction.md要点回顾错误码前缀决定组件归属F7XXXX查 machine 组件、FC0XXX查 vector 组件、F6xxxx查 codegen 组件前端校验错误无需看日志直接从异常信息获取错误码与描述编译问题需串行编译见 codegen 排查文档F21004/ vec tile /REGISTER_COPY见本文上文专门一节精度类问题可加载pypto-precision-debug/pypto-precision-compare技能见 SKILL.md 的路由决策树detailed_tensor_compare返回all_close: false且无崩溃、无 aicore 错误 → 加载pypto-precision-debug仍失败或发散 checkpoint 未定位 → 加载pypto-precision-compare。停止条件什么时候才允许停下只有在与 rules.md 中的Stop Conditions对齐时才允许暂停包括参考代码缺失、归一化 golden 无法等价、框架从根本上阻塞所需的集成形态、缺少用户必须提供的日志、或经过穷尽的结构化尝试后证明只能盲目猜测。一条孤立的隐晦错误行永远不够。最终提醒宁可留下十条带日志引用的失败尝试记录也不要一次过早退出。未知错误码意味着升级证据与方法而不是停止。完整的调试路径情况 → 叶子文档映射始终从 DEBUG_GUIDEBOOK.md 出发不透明错误码 →error-codes.mdF21004 / REGISTER_COPY→error-codes.md§4再视修复方向进入 tile-shapes.mdNPU 启动失败Errcode: FFFFFF! launch aicpu→ npu-launch-failures.md。按照捕获 → 路由 → 记录 → 分类 → 收敛的节奏迭代复杂 PyPTO 内核开发中的绝大多数不透明错误都能被定位并修复。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考