External Cannbot Ops Pypto Op Develop

PyPTO 算子实现

基于需求规格、设计方案和参考实现，完成代码实现、验证和 README 交付。

所需输入

需求规格信息

从 SPEC.md 中提取：

设计方案信息

从 DESIGN.md 中提取：

参考实现信息

从 {op}_golden.py 中提取：

如果以上信息不足，向用户逐步提问补充。

参考文件

开发阶段

阶段一：环境准备

1. 检查 CANN 是否安装

echo ${PATH} | grep cann-8.5.0

2. 检查 pto-isa 源码是否获取

echo ${PTO_TILE_LIB_CODE_PATH}

• 如果路径不存在，执行 scripts/environment_prepare.sh 进行环境初始化
• 如果仍不成功，参考 docs/install/prepare_environment.md 获取 pto-isa 源码并设置环境变量

3. 验证关键文档及示例目录

ls docs/api/
ls examples/

4. 设置 device_id

# 查找空闲 chip id
`bash scripts/list_idle_chip_ids.sh`

# 根据输出结果设置环境变量（例如输出为 "0 1 3 ..." 时，先选 chip 0）
export TILE_FWK_DEVICE_ID=$(bash scripts/list_idle_chip_ids.sh | awk '{print $1}')
export PTO_TILE_LIB_CODE_PATH=./pto_isa/pto-isa/

• 如果脚本无输出，说明当前所有 chip 都被进程占用，不能随意设置 TILE_FWK_DEVICE_ID

⚠️ 未设置 TILE_FWK_DEVICE_ID 会导致运行时报错："If no NPU environment is available"

如果以上检查未通过，参考 docs/install 中的资料完成环境准备。

阶段二：代码生成

输出目录：custom/{op}/

生成顺序：

1. 根据输入信息，先梳理 API 映射、tiling 策略、loop 结构，确认可行后再进入实现
2. 进入实现前，读取 references/execution-constraints.md，把框架级约束、基础类型约束、控制流约束和高频 operation 约束落实到本次实现
3. 基于 references/impl-template.py 生成 {op}_impl.py
4. 基于 references/test-template.py 生成 test_{op}.py（前置：{op}_impl.py 已生成）
5. 生成 README.md

⚠️ 实现代码与测试代码必须分离，禁止混写 golden / impl / test 到同一文件。

生成 {op}_impl.py

PyPTO kernel 函数实现，基于固定模板 references/impl-template.py 生成。

实现前必须逐项核对 references/execution-constraints.md，尤其是：输出写回、动态轴标注、Element 使用、TileShape、valid_shape、loop/cond、同图内读写回环。

生成 test_{op}.py

torch golden 函数精度对比测试，基于固定模板 references/test-template.py 生成。

结构：

精度对比强制规范：

生成 README.md

必须包含：

• 中文说明
• 算子概述与公式
• 目录结构
• 运行方式
• 验证入口
• 已知限制

Design 到代码文件的映射

阶段三：测试验证

优先使用 NPU 模式进行验证。

验证步骤：

1. 编译安装（如未安装 pypto）：

python3 build_ci.py -f python3 --disable_auto_execute

已安装则无需反复编译。

2. 执行算子验证： 检测到存在 NPU 卡时，直接使用 run_mode=npu 执行：

python3 custom/{op}/test_{op}.py

3. 验证失败处理： ⚠️ 先确认是否有错误码：有则必须走错误码流程，无则跳过 检查方法：在 stderr 或日志中搜索 Errcode: F / ErrCode: F
   • 有错误码（如 ErrCode: FC0000!） → 必须走错误码排查流程：见 references/error-code-troubleshooting.md
   • 无错误码 → 跳过，直接分析报错信息或日志定位问题

推荐验证顺序：

1. 小规模功能验证：先确认代码能运行、基础输出形状正确
2. 典型规模验证：使用目标场景下的常规输入做主路径验证
3. 边界与极值验证：检查零值、大值、特殊 shape、动态 shape 等情况
4. 大规模或性能相关验证：在功能和精度稳定后再推进

测试类型：

• 单元测试：基本功能验证
• 精度测试：精度符合要求
• 性能测试：已完成性能测量，并基于实测数据判断是否符合要求

⚠️ 有 NPU 卡的情况下，不要使用 run_mode=sim。

实现注意点

1. PyPTO tensor 创建后是未初始化随机值：使用前先初始化，或者保证先写后读；不要把 pypto.tensor(...) 当成已初始化张量使用。
2. 禁止无中生有 op：实现时只能使用 PyPTO 已支持的 API，遇到缺失能力应回退到 API 探索或设计阶段重新确认。
3. 优先使用 @pypto.frontend.jit 写法：选择最新的非 wrapper 包装写法，参考 docs/api/pypto-frontend-jit.md，与现有示例和文档保持一致。
4. golden / impl / test 必须职责分离：不要把 golden 逻辑、实现逻辑和测试逻辑混写到同一个文件中。
5. 动态数据范围使用 valid_shape：当最后一块数据量可能小于固定块大小时，pypto.view / pypto.reshape 中必须指定 valid_shape。
6. 动态循环边界使用 unroll_list：当循环次数为动态值时，需要使用 unroll_list；多层循环嵌套时，最内层使用 unroll_list。
7. matmul / cube 场景：必须确认 set_cube_tile_shapes(...) 已正确配置。
8. 输出写回必须显式完成：使用 output[:] = ...、output.move(...) 或 pypto.assemble(..., output)；不要写 output = ...。
9. 动态轴必须显式标注：所有动态 shape 输入和输出都要在 Tensor 注解中标成 pypto.DYNAMIC / pypto.DYN。
10. Element 用于固定标量 dtype：当标量参与计算且 dtype 不能依赖隐式映射时，显式使用 pypto.Element(dtype, value)。
11. 避免同图内回环读写：同一 Tensor 不要在同一图里既 view 读取又 assemble 回写。
12. 如果设计中已有 tiling / loop 约束，编码时优先遵循 DESIGN.md，不要临时拍脑袋改写。

常见问题与解决方案

常见的 7 类错误

1. BFloat16 转 NumPy 失败：必须先 .float() 再 .numpy()
2. 环境变量未设置：先运行 bash scripts/list_idle_chip_ids.sh 确认可用 chip id，再设置 export TILE_FWK_DEVICE_ID=<空闲 chip id>
3. 动态轴定义位置错误：必须在 jit 函数外部定义
4. Tile Shape 未设置：matmul 前必须调用 set_cube_tile_shapes；vec 操作前需要 set_vec_tile_shapes
5. 精度标准不合理：bfloat16 使用 atol=0.0001, rtol=0.0078125
6. 使用 PyTorch 作为 Golden：使用 NumPy 实现 golden 函数时，bfloat16 数据类型转换不够准确；golden 必须独立在 {op}_golden.py，使用纯 torch 实现
7. SymbolicScalar 用作 list 索引报错：TypeError: list indices must be integers or slices, not SymbolicScalar。原因：pypto.loop 返回的是编译时符号值，不是 Python runtime 对象。解决方法：使用 tensor slice 或 pypto.view/pypto.assemble 构建数据流。

三种状态标记约定

生成的 test_{op}.py 必须使用以下模式输出精度判定标记：

import sys
import numpy as np

def run_test():
    # ... setup inputs, call golden and impl ...
    try:
        np.testing.assert_allclose(impl_output, golden_output, rtol=rtol, atol=atol)
        print("[PRECISION_PASS]")
    except AssertionError as e:
        print(f"[PRECISION_FAIL] {e}", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        # 功能问题（无标记），exit code ≠ 0
        print(f"Runtime error: {e}", file=sys.stderr)
        sys.exit(2)

if __name__ == "__main__":
    run_test()

标记含义：

• [PRECISION_PASS]: 精度验证通过
• [PRECISION_FAIL]: 精度验证失败（数值不匹配）
• 无标记 + exit ≠ 0: 功能问题（代码崩溃、逻辑错误等）

assert_allclose 抛出的 AssertionError 包含 Not equal to tolerance 关键字，调用方据此区分"运行失败"和"精度失败"。

Checklist

1. 3 个文件（test_{op}.py + {op}_impl.py + README.md）全部存在
2. test_{op}.py 可执行（无语法错误）
3. 测试包含 [PRECISION_PASS] / [PRECISION_FAIL] 标记逻辑，无其他功能问题
4. 验证失败时已确认是否有错误码：有则走错误码流程，无则跳过
5. {op}_impl.py 已按 references/execution-constraints.md 自检：输出写回、动态轴、TileShape、valid_shape、Element、loop/cond、assemble 回环均已检查