CANN ops-transformer 算子调试调优全指南：从 AI Core Kernel 调试到上板性能分析

CANN ops-transformer 算子调试调优全指南从 AI Core Kernel 调试到上板性能分析【免费下载链接】ops-transformer本项目是CANN提供的transformer类大模型算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-transformer导读本文面向在 CANN ops-transformer 仓库中开发与维护 AI Core 算子的开发者系统讲解算子运行出现执行失败、精度异常、性能瓶颈时的完整排查与调优方法论。文章以仓库内置的add_example示例算子为主线覆盖 Host 侧 plog 日志获取、aclnn 异常信息定位、Kernel 内 printf / DumpTensor / msDebug 调试、msSanitizer 内存与竞争检测以及 msprof 上板性能采集与 NPU Simulator 流水图仿真两大调优手段帮助读者在真实 NPU 与无硬件仿真两种场景下快速定位问题并优化指令排布。调试定位AI Core 算子算子运行过程中如果出现算子执行失败、精度异常等问题可以打印各阶段信息如 Kernel 中间结果进行问题分析和定位。调试链路自顶向下分为三层Host 侧日志、aclnn 接口层异常信息、Kernel 内核级调试。1. Host 侧日志获取方式plog 获取程序执行结束后Host 日志默认保存在$HOME/ascend/log目录下日志文件存储路径如下$HOME/ascend/log/debug/plog/plog-pid_*.log开启环境变量ASCEND_SLOG_PRINT_TO_STDOUT可以将 log 日志直接打屏显示1为开启打屏0为关闭打屏配置示例如下export ASCEND_SLOG_PRINT_TO_STDOUT1日志的级别、格式、落盘路径等更完整的行为由 CANN 软件包的日志参考与环境变量参考文档定义原文档给出了 CANN 社区文档对应章节读者可结合所安装 CANN 版本的《日志参考》与《环境变量参考》查阅。aclnn 异常错误信息获取当 aclnn 接口调用过程中出现异常如参数错误、Tensor 为空等时可通过aclGetRecentErrMsg接口参见《Runtime 运行时 API》获取最近一次调用的异常信息使用方法如下printf(%s, aclGetRecentErrMsg());打印错误信息样例如下[PID:646612] 2026-01-24-11:53:44.671.727 AclNN_Parameter_Error(EZ1001): Expected a proper Tensor but got null for argument addmmTensor.self.从样例可以看到错误信息包含错误码EZ1001、错误类型AclNN_Parameter_Error以及具体的非法参数描述可直接据此定位到 aclnn 调用代码中出问题的入参。关于错误码的完整说明可参见 aclnn 返回码说明。2. Kernel 调试printfAscendC::PRINTF接口支持在 Kernel 内打印 Scalar 类型数据如整数、字符、布尔型等详细介绍参见《Ascend C API》中算子调测 API printf章节。典型用法是在算子初始化阶段打印 tiling 计算结果用于核对切分逻辑是否正确blockLength_ tilingData-totalLength / AscendC::GetBlockNum(); tileNum_ tilingData-tileNum; tileLength_ blockLength_ / tileNum_ / BUFFER_NUM; // 打印当前核计算Block长度 AscendC::PRINTF(Tiling blockLength is %llu\n, blockLength_);以上代码段与仓库中 add_example.h 的Init实现完全对应blockLength_由tilingData-totalLength除以核数得到tileLength_再按tileNum_与BUFFER_NUM双缓冲值为 2二次切分printf打印的正是每个 Block 的实际计算长度用于验证 Host 侧 tiling 数据是否正确传递到了 Kernel。DumpTensorDumpTensor接口支持 Dump 指定 Tensor 的内容同时支持打印自定义附加信息比如当前行号等详细介绍参见《Ascend C API》中算子调测 API DumpTensor章节。典型用法是在CopyOut阶段检查待搬出 UB 的结果数据AscendC::LocalTensorT zLocal outputQueueZ.DeQueT(); // 打印zLocal Tensor信息 DumpTensor(zLocal, 0, 128); AscendC::DataCopy(outputGMZ[progress * tileLength_], zLocal, tileLength_);其中zLocal取自outputQueueZ出队的结果 LocalTensorDump 从偏移 0 开始的 128 个元素可直观比对计算输出是否符合预期。msDebug 单步调试对于复杂场景的问题定位比如算子卡死、GM/UB 访问越界等场景可以采取 msDebug 单步调试的方式具体操作步骤如下编译 O0 -g 的 Kernel使用 msDebug 调试前需要编译不带优化且带调试信息的 Kernel通过--op_debug_config ccec_O0,ccec_g选项实现bash build.sh --pkg --opsadd_example --socascend910b --op_debug_config ccec_O0,ccec_g若上述编译失败或运行算子本身就存在精度问题可能是由于该算子 tilingKey 较多大算子需要对目标 tilingKey 对应的分支代码单独调试。此时需要增加--tiling_key选项指定目标 tilingKey。首先可用 msdebug 直接运行一次算子观察 Kernel 启动信息来确定目标 tilingKey[Launch of Kernel RunAicpuKfcResInit on Device 0] [Launch of Kernel RunAicpuKfcResInit on Device 1] [Launch of Kernel AddExample_c9e4347749ac13425bf7e31c6a5e306a_7 on Device 1] [Launch of Kernel AddExample_c9e4347749ac13425bf7e31c6a5e306a_7 on Device 0]其中_c9e4347749ac13425bf7e31c6a5e306a即为 tilingKey。确定目标 tilingKey 后编译命令如下bash build.sh --pkg --opsadd_example --socascend910b --op_debug_config ccec_O0,ccec_g --tiling_keyc9e4347749ac13425bf7e31c6a5e306atilingKey 机制的源码依据从 add_example.cpp 可以看到Kernel 入口通过enum class AddExampleTilingKey区分不同调度分支并用if constexpr (schMode ...)在编译期选择对应的实例化模板而 tilingKey 的取值由 Host 侧 add_example_tiling.cpp 根据输入数据类型决定DT_FLOAT走ELEMENTWISE_TPL_SCH_MODE_0DT_INT32走ELEMENTWISE_TPL_SCH_MODE_1。对应单元测试 test_add_example_tiling.cpp 也验证了 shape 为1*2*8*16时 FLOAT/INT32 分别得到 tilingKey 0 与 1、tilingData 为256 8。因此算子 tilingKey 越多Kernel 二进制包含的分支越复杂单步调试时按 tilingKey 定向编译分支代码就尤为重要。启动 msDebug 调试安装算子包后进入算子可执行文件所在目录使用 msdebug 启动调试msdebug ./test_aclnn_add_example更多 msDebug 使用方法请参见 msDebug 算子调试工具的官方用户指南。3. Kernel 检测msSanitizer 是 Ascend C 算子内存检测和竞争检测工具可用于检测 Kernel 运行过程中的 GM/UB 越界访问、内存泄漏、并发竞争等问题。下面以add_example算子为例介绍使用步骤编译使能检测的 Kernel通过--op_debug_config sanitizer选项编译带检测的 Kernel将下述命令中的add_example替换为实际待检测的算子名bash build.sh --pkg --opsadd_example --socascend910b --op_debug_config sanitizer对于 Ascend 950当前需临时修改 CANN 包中的 opc 编译脚本在_gen_compile_cmd_c310函数中添加--cce-enable-sanitizer、-g、-fno-jump-tables选项vim ${ASCEND_HOME_PATH}/cann/python/site-packages/asc_op_compile_base/asc_op_compiler/ascendc_compile_v220.py安装编译包编译完成后进入build_out目录安装生成的算子包文件名随 SoC 版本不同而变化以 950 为例cd build_out bash cann-ops-transformer-custom_linux-aarch64.run cd ..编译并运行测试用例通过--run_example一键编译并运行示例用例cust表示使用自定义算子包模式详细参数可查阅 build.sh 的--run_example帮助信息bash build.sh --run_example add_example eager cust --socascend910b执行 msSanitizer 检测使用 mssanitizer 同时执行内存检测和竞争检测mssanitizer --toolmemcheck --toolracecheck \ --log-levelerror \ --kernel-nameAddExample \ -- build/test_aclnn_add_example mssanitizer_result.txt 21检测结果输出到mssanitizer_result.txt中。注意--kernel-name需与目标 Kernel 符号名一致例如示例算子为AddExample。更多 msSanitizer 使用方法请参见 msSanitizer 算子检测工具文档。性能调优算子运行过程中如果出现执行精度下降、内存占用异常等问题可通过 msProf 性能分析工具分析算子各运行阶段指标数据如吞吐率、内存占用、耗时等从而确定问题根源并针对性地优化。本章以AddExample自定义算子为例主要介绍算子调优中常用的算子上板性能采集和流水图仿真的方式。适用场景区别上板性能采集适用于在真实 NPU 硬件上运行算子快速获取算子整体性能指标如 Kernel 耗时、Block 数、流水占比等帮助判断算子是否存在性能问题。流水图仿真适用于无 NPU 硬件开发者或需要深入分析算子内部指令级流水瓶颈、优化指令排布的场景提供比上板更详细的指令级流水分析。方式一 上板性能采集前提条件完成算子开发和编译后假设采用 aclnn 接口方式调用生成的算子可执行文件test_aclnn_add_example所在目录为本项目examples/add_example/examples/build/bin/。aclnn 调用的完整流程可参考 test_aclnn_add_example.cpp先aclnnAddExampleGetWorkspaceSize获取 workspace 大小再aclnnAddExample执行最后aclrtSynchronizeStream同步等待。采集性能数据当需要采集算子上板运行各项流水指标时进入算子可执行文件所在目录执行如下命令msprof op ./test_aclnn_add_example采集结果在本项目examples/add_example/examples/build/bin/OPPROF_*目录采集完成后打印如下信息Op Name: AddExample_a1532827238e1555db7b997c7bce2928_high_performance_1 Op Type: vector Task Duration(us): 97.861954 Block Dim: 8 Mix Block Dim: Device Id: 0 Pid: 2776181 Current Freq: 1800 Rated Freq: 1800其中Task Duration是当前算子 Kernel 耗时Block Dim是当前算子执行核数。例如Block Dim: 8与 Host 侧 tiling 中 add_example_tiling.cpp 设置的BLOCK_DIM 8一一对应可直接交叉验证切核配置是否生效。算子各项流水详细指标可关注OPPROF_*下的ArithmeticUtilization文件包含了当前各项流水的占比具体介绍参见 msProf 中性能数据文件 msprof op ArithmeticUtilizationcube 及 vector 类型指令耗时和占比章节。方式二 仿真流水图采集前提条件完成算子开发和编译后假设采用 aclnn 接口方式调用生成的算子可执行文件test_aclnn_add_example所在目录为本项目examples/add_example/examples/build/bin/。针对 Ascend 950PR可使用 NPU Simulator 仿真工具执行仿真命令生成仿真数据执行仿真命令生成仿真数据npusim record ./test_aclnn_add_example -s Ascend950 --gen-report仿真结果在本项目examples/add_example/examples/build/bin/npusim_*/report/results/kernel_*/core_*目录流水相关文件为trace_core0.json在 Chrome 浏览器中输入chrome://tracing地址并将生成的指令流水图文件trace_core0.json拖到空白处打开具体参数介绍参考 NPU Simulator 仿真结果解析说明。NPU Simulator原 cannsim自 2026 年 7 月 30 号版本起正式更名是一款 SoC 级芯片仿真工具与板上运行保持二进制兼容同一 Kernel 可同时在仿真和 AI 处理器执行支持 bit 级精度仿真与指令流水性能仿真使用约束包括仅支持单卡代码中只能设置为 0 卡、仅支持 AI Core 计算类算子不支持 MC2 和 HCCL 类型算子、仅支持 Ascend950PR 与 Ascend950DT 芯片、不支持 arm 环境推荐运行环境为 16 核 CPU 与 32GB 以上内存。工具集成在 CANN toolkit 包中无需安装驱动和固件只需 source CANN 的set_env.sh。更多命令参数record的-s/-o/-g/-u/-n、report的-e/-o/-n/-f与使用示例见 NPU Simulator 使用文档。针对 Atlas A2/A3 系列产品可使用 msProf 工具执行仿真命令生成仿真数据msProf 工具进行算子仿真调优之前需执行如下命令配置环境变量export LD_LIBRARY_PATH${INSTALL_DIR}/tools/simulator/Ascendxxxyy/lib:$LD_LIBRARY_PATH请根据 CANN 软件包实际安装路径和 AI 处理器型号对以上环境变量进行修改。之后进入算子可执行文件所在目录执行如下命令msprof op simulator --output$PWD/pipeline_auto --kernel-name AddExample ./test_aclnn_add_example采集结果在本项目$PWD/pipeline_auto/OPPROF_**目录中其中流水相关文件路径为OPPROF_*/simulator/visualize_data.bin可以借助 MindStudio Insight 工具中基础操作 导入数据章节查看如何导入流水数据。流水图关键字段解读无论是 NPU Simulator 生成的trace_core0.json还是 msProf 仿真数据打开的指令流水图都按硬件流水单元分行展示指令时序关键字段含义如下与 NPU Simulator 文档 表 2 一致字段名字段含义VECTOR向量运算单元。SCALAR标量运算单元。Cube矩阵乘运算单元。MTE1数据搬运流水数据搬运方向为L1 - {L0A/L0B, UBUF}。MTE2数据搬运流水数据搬运方向为{DDR/GM, L2} - {L1, L0A/B, UBUF}。MTE3数据搬运流水数据搬运方向为UBUF - {DDR/GM, L2, L1}、L1-{DDR/L2}。FIXP数据搬运流水数据搬运方向为FIXPIPE L0C - OUT/L1。FLOWCTRL控制流指令。ICACHELOAD查看未命中的 ICache。在 Chrome 的chrome://tracing页面中打开流水文件后可使用键盘快捷键 W放大、S缩小、A左移、D右移进行浏览。通过观察各流水单元的指令时间条如 VECTOR 与 MTE2/MTE3 之间是否存在大量空隙即可判断双缓冲是否打满、搬运与计算是否重叠从而指导调整BUFFER_NUM、tile 大小等切分参数。总结调试调优方法选型速查场景推荐工具关键命令 / 配置Host 侧执行失败、参数异常plog aclGetRecentErrMsgexport ASCEND_SLOG_PRINT_TO_STDOUT1printf(%s, aclGetRecentErrMsg())Kernel 中间结果核对printf / DumpTensorKernel 内AscendC::PRINTF、DumpTensor(zLocal, 0, 128)算子卡死、GM/UB 越界定位msDebug--op_debug_config ccec_O0,ccec_g必要时加--tiling_key...msdebug ./test_aclnn_add_example越界访问、内存泄漏、并发竞争msSanitizer--op_debug_config sanitizermssanitizer --toolmemcheck --toolracecheck ...真实 NPU 整体性能指标msprof opmsprof op ./test_aclnn_add_example指令级流水瓶颈Ascend 950PRNPU Simulatornpusim record ./test_aclnn_add_example -s Ascend950 --gen-report指令级流水瓶颈Atlas A2/A3msProf simulatormsprof op simulator --kernel-name AddExample ./test_aclnn_add_example建议的调优闭环路径先用msprof op快速确认算子是否存在整体性能问题若存在则切换到流水图仿真逐流水单元分析指令排布与双缓冲利用率结合 tiling 参数调整后重新采集对比直至流水无显著空洞、ArithmeticUtilization中各流水占比趋于均衡。所有命令与示例均可在本仓库的 add_example 示例工程、NPU Simulator 文档 及 build.sh 构建脚本 中直接复现验证。【免费下载链接】ops-transformer本项目是CANN提供的transformer类大模型算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-transformer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考