CANN/cannbot-skills算子开发错误处理指南

> Ascend C 算子开发工作流程 - 各阶段错误类型、回退策略、问题定位流程---## 概述本文档统一说明算子开发四阶段流程中各阶段的错误处理策略，包括：- 各阶段常见错误类型- 回退策略（回退到哪个阶段重新验证）- 重试阈值（最多重试几次）- 问题定位流程（先检查什么，后检查什么）---## 错误处理原则### 核心原则1. **问题回退不跳过** -

石喜宏Melinda

910人浏览 · 2026-05-09 16:03:43

石喜宏Melinda · 2026-05-09 16:03:43 发布

错误处理统一说明

【免费下载链接】cannbot-skills CANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体，本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills

Ascend C 算子开发工作流程 - 各阶段错误类型、回退策略、问题定位流程

概述

本文档统一说明算子开发四阶段流程中各阶段的错误处理策略，包括：

各阶段常见错误类型
回退策略（回退到哪个阶段重新验证）
重试阈值（最多重试几次）
问题定位流程（先检查什么，后检查什么）

错误处理原则

核心原则

问题回退不跳过 - 验证失败时，必须修复问题后从当前阶段重新验证，不能跳过
保留阶段版本 - 保留每个阶段的代码版本，便于回退和对比
先定位后修复 - 不要盲目修改代码，先定位问题根因
分层排查 - 按照 Host → Kernel → 环境的顺序排查
记录问题 - 复杂问题创建 ./issues/issue_{YYYYMMDD}_{关键词}_序号.md（如 issue_20260403_opbuild-dt-float16_01.md，模板见 issue-template.md），LOG.md 只放链接

重试阈值

验证类型	重试次数	说明
UT 编译失败	3次	编译问题一般是语法或环境问题
ST 精度测试失败	3轮	每轮修复后重新验证
性能测试失败	5轮	优化迭代需要多次尝试
代码检视问题	1轮	修复问题后必须重新执行精度和性能测试

第一阶段：设计

1.1 开发准备

常见错误类型

错误类型	典型表现	严重程度
开发日志创建失败	无法在 docs 目录创建文件	低
目录权限问题	无写入权限	中

回退策略

回退到： 检查目录权限和磁盘空间

步骤：

检查 docs 目录是否存在
检查是否有写入权限
检查磁盘空间是否充足

1.2 需求分析

常见错误类型

错误类型	典型表现	严重程度
需求不完整	缺少关键信息（数据类型、精度要求等）	高
需求冲突	功能描述与约束条件矛盾	高
目标环境不明确	未指定 SOC 版本、操作系统	中
性能指标缺失	无明确性能基线或对标目标	中

回退策略

回退到： 用户重新提供需求信息

步骤：

列出缺失的关键信息
请用户补充完整需求
重新执行需求分析

问题定位流程

需求分析失败
    │
    ├─ 是否缺少关键信息？
    │   └─ 是 → 列出缺失项 → 请用户补充
    │
    ├─ 是否存在需求冲突？
    │   └─ 是 → 列出冲突项 → 请用户确认
    │
    └─ 目标环境是否明确？
        └─ 否 → 请用户明确 SOC 版本、操作系统等

1.3 方案设计

常见错误类型

错误类型	典型表现	严重程度
模板选择不当	选择的模板不支持需求功能	高
技术方案不可行	设计方案在 NPU 上无法实现	高
性能方案不合理	无法达到性能基线要求	中
风险评估不足	未识别关键技术难点	中

回退策略

回退到： 重新进行方案设计

步骤：

评审技术方案可行性
重新选择合适的模板
调整性能优化方案
更新风险评估

问题定位流程

方案设计失败
    │
    ├─ 模板选择是否合适？
    │   └─ 否 → 查阅 kernel-templates.md → 重新选择
    │
    ├─ 技术方案是否可行？
    │   └─ 否 → 参考 AscendC API 文档 → 调整方案
    │
    └─ 性能方案是否合理？
        └─ 否 → 分析算子特性 → 调整优化策略

1.4 测试设计

常见错误类型

错误类型	典型表现	严重程度
测试点不完整	覆盖率不足，遗漏关键场景	高
精度标准不当	阈值设置过高或过低	中
用例数量不合理	L0/L1/L2 用例数超出范围	中
数据类型组合缺失	未覆盖有效数据类型组合	中
Phase规划不清晰	每个Phase的测试内容不明确	高

回退策略

回退到： 重新进行测试设计

步骤：

对照验收标准检查测试点完整性
调整精度标准阈值
优化用例抽样策略
补充数据类型组合
明确每个Phase的测试内容划分

问题定位流程

测试设计失败
    │
    ├─ 测试点是否完整？
    │   └─ 否 → 对照验收标准 → 补充测试点
    │
    ├─ 精度标准是否合理？
    │   └─ 否 → 参考数据类型特性 → 调整阈值
    │
    ├─ 用例数量是否合理？
    │   └─ 否 → 优化抽样策略 → 重新生成用例
    │
    └─ Phase规划是否清晰？
        └─ 否 → 明确每个Phase的测试内容 → 重新规划

第二阶段：开发

2.1 初始化算子目录 + Phase规划

常见错误类型

错误类型	典型表现	严重程度
目录创建失败	权限问题或路径不存在	中
文件复制失败	源文件不存在或目标路径问题	中
Phase规划不清晰	无法明确每个Phase的开发内容	高

回退策略

回退到： 检查权限和路径，重新规划Phase

步骤：

检查 ops 目录是否存在且有写入权限
检查 docs 中的临时文件是否存在
删除已创建的不完整目录后重试
根据详细设计和测试设计重新规划Phase

Phase 1-3：算子实现与ST用例开发（双轨道并行）

算子实现问题回退机制

当验证失败时：

UT 失败 → 问题一般在 Host 代码（Tiling 计算、参数传递等），回退修复 Host 逻辑
ST 精度失败但 UT 通过 → 大概率是 Kernel 计算逻辑问题，小概率是 Host 给 Kernel 的参数不对
- 先检查 Host 传给 Kernel 的参数是否正确
- 若参数正确，则定位 Kernel 计算逻辑问题
性能不达标 → 分析瓶颈，调整优化策略

原则：保留每个阶段的代码版本，问题修复后从该阶段重新验证

Git 回退参考（tag 定义见 data-flow.md）：

回退范围	命令
仅算子代码	`git checkout operators/{operator_name}/iterN-passed -- operators/{operator_name}/op_kernel/ operators/{operator_name}/op_host/`
全量回退	`git checkout operators/{operator_name}/iterN-passed -- operators/{operator_name}/`
查看可用锚点	`git tag -l "operators/{operator_name}/*"`
对比两个迭代	`git diff operators/{operator_name}/iter1-passed operators/{operator_name}/iter2-passed -- operators/{operator_name}/`

回退后需 git commit -m "revert({operator_name}): 回退到 {tag}"

Phase 1：基础功能开发

常见错误类型

错误类型	典型表现	严重程度
UT 编译失败	语法错误、头文件缺失、链接错误	高
UT 执行失败	用例 assert 失败、段错误	高
ST 基础用例失败	Kernel 计算错误、结果不匹配	高
Host 传参错误	传给 Kernel 的参数不对	中

回退策略

验证类型	失败原因	回退策略
UT 编译失败	语法错误、环境问题	修复语法 → 重新编译（最多3次）
UT 执行失败	Host 逻辑错误	修复 Host 代码 → 重新执行
ST 基础用例失败	Kernel 计算错误	检查 Host 传参 → 定位 Kernel 逻辑 → 修复

问题定位流程

Phase 1 验证失败
    │
    ├─ UT 编译失败？
    │   └─ 检查语法错误 → 检查头文件 → 检查环境配置
    │
    ├─ UT 执行失败？
    │   ├─ 检查 Tiling 计算逻辑
    │   ├─ 检查参数传递
    │   └─ 检查异常拦截逻辑
    │
    └─ ST 基础用例失败？
        ├─ 先检查 Host 传给 Kernel 的参数是否正确
        │   └─ 参数正确 → 定位 Kernel 计算逻辑问题
        └─ 参数错误 → 修复 Host 代码

Phase 2：功能完善开发

常见错误类型

错误类型	典型表现	严重程度
UT 覆盖率不达标	新增分支未覆盖	高
ST 精度失败	误差超过阈值	高
多 TilingKey 切换错误	TilingKey 分支逻辑错误	中
多 dtype 支持问题	数据类型转换错误	中

回退策略

验证类型	失败原因	回退策略
UT 覆盖率不达标	分支未覆盖	补充 UT 用例 → 重新验证
ST 精度失败	Kernel 计算问题	定位问题 → 修复 → 重新验证（最多3轮）

问题定位流程

Phase 2 验证失败
    │
    ├─ UT 覆盖率不达标？
    │   ├─ 检查新增 TilingKey 分支
    │   ├─ 检查多 dtype 分支
    │   └─ 检查边界条件处理
    │
    └─ ST 精度失败？
        │
        ├─ 误差 > 1%？
        │   └─ 功能问题 → 检查算法逻辑
        │
        ├─ 误差 0.1%-1%？
        │   └─ 触发 ascendc-precision-debug
        │
        ├─ 误差 < 0.1%？
        │   └─ 检查是否为特定场景问题
        │
        └─ 误差 < 精度标准？
            └─ 通过

Phase 3：规格完整开发

常见错误类型

错误类型	典型表现	严重程度
全dtype支持问题	数据类型转换错误	高
边界处理问题	边界值处理错误	高
广播逻辑错误	广播场景失败	高
UT/ST 回归	新增功能导致旧功能失败	中

回退策略

验证类型	失败原因	回退策略
全dtype支持问题	数据类型处理不当	修复 dtype 处理逻辑 → 重新验证
边界处理问题	边界值处理错误	修复边界逻辑 → 重新验证
广播逻辑错误	广播规则实现错误	修复广播逻辑 → 重新验证
UT/ST 回归	新增功能引入错误	检查新增代码 → 修复 → 重新验证

问题定位流程

Phase 3 验证失败
    │
    ├─ 全dtype支持问题？
    │   ├─ 检查数据类型转换逻辑
    │   ├─ 检查模板参数化是否正确
    │   └─ 修复 → 重新验证
    │
    ├─ 边界处理问题？
    │   ├─ 检查尾块处理
    │   ├─ 检查对齐处理
    │   └─ 修复 → 重新验证
    │
    ├─ 广播逻辑错误？
    │   └─ 检查广播规则实现 → 修复 → 重新验证
    │
    └─ UT/ST 回归？
        └─ 检查新增代码 → 修复 → 重新验证

第三阶段：验证

3.1 性能测试

常见错误类型

错误类型	典型表现	严重程度	触发技能
性能不达标	未达到性能基线	高	perf-tuning
精度回归	性能优化后精度下降	高	ascendc-precision-debug

回退策略

错误类型	回退策略	技能支持
性能不达标	分析瓶颈 → 调整优化策略 → 重新验证（最多5轮）	perf-tuning
精度回归	检查优化代码 → 可能回退第二阶段迭代三	ascendc-precision-debug

cannsim 与 perf-tuning 调用关系

性能测试阶段
    │
    └─ 直接调用 perf-tuning 技能
        │
        ├─ perf-tuning 内部调用 cannsim（ascend950 仿真）
        │   └─ 生成性能 trace
        │
        └─ 分析性能瓶颈
            ├─ 理论算力利用率
            ├─ 内存带宽利用率
            └─ 指令级分析

重要：性能测试阶段直接调用 perf-tuning，cannsim 作为底层工具由 perf-tuning 内部调用。仅在需要单独仿真（非性能分析）时直接调用 cannsim。

问题定位流程

性能问题定位
    │
    ├─ 内存带宽利用率低？
    │   └─ 优化内存访问模式 → 双缓冲、数据预取
    │
    ├─ 理论算力利用率低？
    │   └─ 优化计算并行度 → 流水线、指令优化
    │
    ├─ Tiling 策略不当？
    │   └─ 调整 tiling 策略 → 优化数据分块
    │
    └─ 同步次数过多？
        └─ 减少不必要的同步 → 异步执行

第四阶段：上库

4.1 文档与示例

常见错误类型

错误类型	典型表现	严重程度
README 生成失败	缺少必要信息、格式不规范	低
示例代码编译失败	语法错误、依赖缺失	中

回退策略

错误类型	回退策略
README 生成失败	补充信息 → 重新生成
示例代码编译失败	修复代码 → 重新编译验证

4.2 代码检视

常见错误类型

错误类型	典型表现	严重程度	触发技能
代码规范问题	命名不规范、注释缺失、格式问题	中	ascendc-code-review
与设计文档不一致	代码实现与 DESIGN 不符	高	-
与测试设计不一致	测试用例未覆盖所有场景	高	-

回退策略

错误类型	回退策略
代码规范问题	修复代码规范问题 → 无需重新测试
与设计文档不一致	修复代码 → 必须重新执行第三阶段精度测试和性能测试
与测试设计不一致	补充测试用例 → 必须重新执行第三阶段测试

检视结果处理流程

代码检视
    │
    ├─ 无问题
    │   └─ 进入第四阶段 4.3（开发总结）
    │
    └─ 有问题
        │
        ├─ 仅代码规范问题？
        │   └─ 修复代码规范问题 → 直接进入第四阶段 4.3
        │
        └─ 有逻辑问题或与设计文档不一致？
            └─ 修复代码 → 必须重新执行第三阶段精度测试和性能测试
                │
                ├─ 精度测试失败 → 修复 → 重新验证
                └─ 性能测试失败 → 修复 → 重新验证

问题定位流程

代码检视问题定位
    │
    ├─ 代码规范问题？
    │   └─ 对照编码规范 → 修复命名、注释、格式
    │
    ├─ 与 DESIGN 不一致？
    │   └─ 对比设计文档 → 修正代码实现
    │
    └─ 与 TEST 不一致？
        └─ 对照测试设计 → 补充测试用例

4.3 开发总结

常见错误类型

错误类型	典型表现	严重程度
开发日志不完整	缺少关键阶段记录	低
README 不规范	缺少必要说明	低

回退策略

回退到： 补充完善文档

通用问题定位流程

修改代码后的验证流程

修改代码
    │
    ├─ 修改 Host 代码（tiling、infershape 等）
    │   └─ 先验证 UT → UT 通过 → 执行 ST 端到端验证
    │
    └─ 修改 Kernel 代码
        └─ 直接执行 ST 端到端验证

分层排查流程

问题出现
    │
    ├─ 1. 检查环境
    │   └─ CANN 环境是否正确？
    │   └─ 编译环境是否正确？
    │
    ├─ 2. 检查 Host 代码
    │   ├─ Tiling 计算是否正确？
    │   ├─ 参数传递是否正确？
    │   └─ 异常拦截是否完整？
    │
    ├─ 3. 检查 Kernel 代码
    │   ├─ 计算逻辑是否正确？
    │   ├─ 内存访问是否越界？
    │   └─ 数据类型转换是否正确？
    │
    └─ 4. 检查数据
        ├─ 测试数据是否合理？
        ├─ 边界值是否正确？
        └─ 数据类型是否支持？

错误处理速查表

阶段	子阶段	验证类型	失败表现	回退策略	重试次数
第一阶段	1.2 需求分析	需求不完整	缺少关键信息	请用户补充	-
第一阶段	1.3 方案设计	方案不可行	技术方案无法实现	重新设计方案	-
第一阶段	1.4 测试设计	测试点不完整	覆盖率不足	补充测试点	-
第二阶段	2.1 初始化	初始化失败	文件复制失败	检查权限路径 → 重试	-
第二阶段	迭代一	UT 编译失败	语法错误、环境问题	修复语法 → 重新编译	3次
第二阶段	迭代一	UT 执行失败	Host 逻辑错误	修复 Host 代码 → 重新执行	-
第二阶段	迭代一	ST 基础用例失败	Kernel 计算错误	检查 Host 传参 → 修复 Kernel	-
第二阶段	迭代二	ST 精度失败	误差 > 0.1%	精度调试（最多3轮）	3轮
第二阶段	迭代二	UT 分支覆盖不达标	分支未覆盖	补充用例 → 重新验证	-
第二阶段	迭代三	全dtype支持问题	数据类型处理错误	修复 dtype 处理 → 重新验证	-
第二阶段	迭代三	边界处理问题	边界值处理错误	修复边界逻辑 → 重新验证	-
第二阶段	迭代三	UT/ST 回归	新增功能导致失败	检查新增代码 → 修复	-
第三阶段	3.1 性能达标验收	性能不达标	未达基线	分析瓶颈 → 调整策略	5轮
第三阶段	3.1 性能达标验收	精度回归	优化后精度下降	检查优化代码 → 可能回退	-
第四阶段	4.2 代码检视	代码规范问题	命名、注释、格式	修复规范问题	-
第四阶段	4.2 代码检视	与设计不一致	代码与设计不符	修复 → 重新执行第三阶段测试	-