ops-math 中 aclnn 接口返回码解析：从 161xxx 参数错误到 561xxx 内部异常的排查指南

ops-math 中 aclnn 接口返回码解析从 161xxx 参数错误到 561xxx 内部异常的排查指南【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math在 CANN 的数学算子库 ops-math 中所有算子均以两段式 aclnn 接口xxxGetWorkspaceSizexxx形式暴露接口的返回值aclnnStatus是判断调用成功与否的唯一依据。本文基于仓库文档 aclnn返回码完整梳理 aclnn API 的常见返回状态码与 561xxx 系列内部异常码并结合 op_error_check.h、aclnn_check.h 等公共校验头文件说明每个错误码的源码级来源帮助你在调用失败时快速定位是调用方参数问题、NPU 运行时空洞还是算子二进制包/环境配置问题。返回码在两段式接口中的位置ops-math 的每个算子都遵循两段式接口规范两个阶段都会返回aclnnStatus类型状态码aclnnStatus aclxxXxxGetWorkspaceSize(const aclTensor *src, ..., aclTensor *out, ..., uint64_t *workspaceSize, aclOpExecutor **executor); aclnnStatus aclxxXxx(void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream);第一阶段GetWorkspaceSize负责参数校验、输出 shape 推导与 workspace 大小计算绝大多数参数类错误码161xxx在这一阶段抛出第二阶段负责在指定 NPU stream 上执行计算runtime 类错误码361xxx与 kernel 查找/加载类内部异常561xxx可能在这一阶段暴露。对任意非 0 的异常状态码都可以通过aclGetRecentErrMsg接口Runtime 运行时 API 提供获取人类可读的异常详情。仓库中算子调试文档给出的基本用法是printf(%s, aclGetRecentErrMsg());常见接口返回状态码调用 aclnn API 时常见的接口返回码如下表所示完整继承自官方返回码文档状态码名称状态码值状态码说明ACLNN_SUCCESS0成功。ACLNN_ERR_PARAM_NULLPTR161001参数校验错误参数中存在非法的 nullptr。ACLNN_ERR_PARAM_INVALID161002参数校验错误如输入的两个数据类型不满足输入类型推导关系。ACLNN_ERR_RUNTIME_ERROR361001API 内部调用 npu runtime 的接口异常。ACLNN_ERR_INNER_XXX561xxxAPI 内部发生异常。从码值分布可以推断出清晰的排查分层思路161xxx参数校验错误问题出在调用方传入的 tensor、workspace 指针或属性上重点检查输入合法性361xxxruntime 错误aclnn API 向下调用 NPU runtime 时异常重点检查设备状态、stream 与内存申请561xxx内部异常API 内部逻辑异常细分含义见下一节通常与算子二进制包安装、环境变量配置或 kernel json 元数据有关。561xxx 内部异常状态码详解ACLNN_ERR_INNER_XXX类状态码覆盖了从 shape 推导、tiling、kernel 匹配到算子元数据json加载的整条内部链路完整列表如下状态码名称状态码值状态码说明ACLNN_ERR_INNER561000内部异常API 发生内部异常。ACLNN_ERR_INNER_INFERSHAPE_ERROR561001内部异常API 内部进行输出 shape 推导发生错误。ACLNN_ERR_INNER_TILING_ERROR561002内部异常API 内部做 npu kernel 的 tiling 时发生异常。ACLNN_ERR_INNER_FIND_KERNEL_ERROR561003内部异常API 内部做查找 npu kernel 异常可能因为算子二进制包未安装。ACLNN_ERR_INNER_CREATE_EXECUTOR561101内部异常API 内部创建 aclOpExecutor 失败可能因为操作系统异常。ACLNN_ERR_INNER_NOT_TRANS_EXECUTOR561102内部异常API 内部未调用 uniqueExecutor ReleaseTo。ACLNN_ERR_INNER_NULLPTR561103内部异常aclnn API 内部发生异常出现了 nullptr 的异常。ACLNN_ERR_INNER_WRONG_ATTR_INFO_SIZE561104内部异常aclnn API 内部发生异常算子的属性个数异常。ACLNN_ERR_INNER_KEY_CONFILICT废弃561105已废弃请使用最新 ACLNN_ERR_INNER_KEY_CONFLICT。ACLNN_ERR_INNER_KEY_CONFLICT561105内部异常aclnn API 内部发生异常算子的 kernel 匹配的 hash key 发生冲突。ACLNN_ERR_INNER_INVALID_IMPL_MODE561106内部异常aclnn API 内部发生异常算子的实现模式参数错误。ACLNN_ERR_INNER_OPP_PATH_NOT_FOUND561107内部异常aclnn API 内部发生异常没有检测到需要配置的环境变量 ASCEND_OPP_PATH。ACLNN_ERR_INNER_LOAD_JSON_FAILED561108内部异常aclnn API 内部发生异常加载算子 kernel 库中算子信息 json 文件失败。ACLNN_ERR_INNER_JSON_VALUE_NOT_FOUND561109内部异常aclnn API 内部发生异常加载算子 kernel 库中算子信息 json 文件的某个字段失败。ACLNN_ERR_INNER_JSON_FORMAT_INVALID561110内部异常aclnn API 内部发生异常算子 kernel 库中算子信息 json 文件的 format 填写为非法值。ACLNN_ERR_INNER_JSON_DTYPE_INVALID561111内部异常aclnn API 内部发生异常算子 kernel 库中算子信息 json 文件的 dtype 填写为非法值。ACLNN_ERR_INNER_OPP_KERNEL_PKG_NOT_FOUND561112内部异常aclnn API 内部发生异常没有加载到算子的二进制 kernel 库。ACLNN_ERR_INNER_OP_FILE_INVALID561113内部异常aclnn API 内部发生异常加载算子 json 文件字段时发生异常。ACLNN_ERR_INNER_ATTR_NUM_OUT_OF_BOUND561114内部异常aclnn API 内部发生异常算子的属性个数与算子信息 json 中不一致超过了 json 中指定的 attr 个数。ACLNN_ERR_INNER_ATTR_LEN_NOT_ENOUGH561115内部异常aclnn API 内部发生异常算子的属性个数与算子信息 json 中不一致少于 json 中指定的 attr 个数。ACLNN_ERR_INNER_INPUT_NUM_IN_JSON_TOO_LARGE561116内部异常aclnn API 内部发生异常算子的输入个数超出 32 的限制。ACLNN_ERR_INNER_INPUT_JSON_IS_NULL561117内部异常aclnn API 内部发生异常算子信息 json 文件信息描述有缺失。ACLNN_ERR_INNER_STATIC_WORKSPACE_INVALID561118内部异常aclnn API 内部发生异常解析静态二进制 json 文件中的 workspace 信息时发生异常。ACLNN_ERR_INNER_STATIC_BLOCK_DIM_INVALID561119内部异常aclnn API 内部发生异常解析静态二进制 json 文件中的核数使用信息时发生异常。按功能可以进一步把 561xxx 拆成几组561000561003计算主链路异常覆盖 shape 推导、tiling、kernel 查找三个关键步骤其中 561003 明确提示“可能因为算子二进制包未安装”是环境缺失类问题的典型信号561101561107executor 生命周期与运行配置异常包括 executor 创建失败、状态未正确迁移未调用 ReleaseTo、实现模式错误以及缺少ASCEND_OPP_PATH环境变量561108561117算子 kernel 库元数据json解析异常从文件加载失败、字段缺失到 format/dtype 填写非法、属性个数不匹配、输入个数超过 32 上限逐一指向算子二进制包元数据的某一种损坏形态561118561119静态二进制 json 中的 workspace 与核数使用信息解析异常。源码视角错误码在 ops-math 中如何产生理解错误码的产生位置能把“返回值”翻译成“哪一步校验失败了”。参数校验宏161xxx 的直接来源ops-math 的公共参数校验集中在 op_error_check.h。其中IsNullptr模板函数负责空指针检查校验失败时通过OP_LOGE记录带类型信息的错误日志并返回对应错误码template typename T bool IsNullptr(const T* param, const char* name) { if (param nullptr) { // 通过 abi::__cxa_demangle 将 typeid 名称还原为可读类型后记录日志 OP_LOGE(ACLNN_ERR_PARAM_NULLPTR, Expected a value of type [%s] for argument [%s] but instead found nullptr., readableName, name); return true; } return false; }与之配套的OP_CHECK_NULL、OP_CHECK_DTYPE_NOT_SUPPORT、OP_CHECK_BROADCAST、OP_CHECK_SHAPE_NOT_EQUAL、OP_CHECK_MAX_DIM等宏把空指针、dtype 支持、shape 广播/相等、维度上限等校验统一收敛到ACLNN_ERR_PARAM_NULLPTR161001与ACLNN_ERR_PARAM_INVALID161002两个码上。例如 shape 推导失败走OP_CHECK_INFERSHAPE宏返回ACLNN_ERR_INNER_INFERSHAPE_ERROR561001静态 workspace 校验失败走OP_CHECK_ADD_TO_LAUNCHER_LIST_AICORE宏返回ACLNN_ERR_INNER_STATIC_WORKSPACE_INVALID561118——这与上表中 561xxx 码的定义一一呼应。算子实现侧的便捷校验宏在 aclnn_check.h 中ops-math 进一步封装了变参宏CHECK_NOT_NULL(...)与CHECK_SHAPE_ALL_EQUAL(...)借助GET_ARGS_COUNT支持 18 个参数逐个做空指针/shape 相等与最大维度校验算子在自己的GetWorkspaceSize开头一行即可完成多参数校验失败即return ACLNN_ERR_PARAM_NULLPTR或ACLNN_ERR_PARAM_INVALID。而 level2_base_caculation.h 中则体现了内部空指针错误码的用法多个内部 tensor 参数用CHECK_RET(..., ACLNN_ERR_INNER_NULLPTR)校验最后返回ACLNN_SUCCESSCHECK_RET(dims ! nullptr, ACLNN_ERR_INNER_NULLPTR); CHECK_RET(shapeArray ! nullptr, ACLNN_ERR_INNER_NULLPTR); CHECK_RET(valTensor ! nullptr, ACLNN_ERR_INNER_NULLPTR); CHECK_RET(fillOut ! nullptr, ACLNN_ERR_INNER_NULLPTR); CHECK_RET(viewCopyResult ! nullptr, ACLNN_ERR_INNER_NULLPTR); return ACLNN_SUCCESS;从源码结构看可以这样区分两类空指针错误调用方传入的入参为空 → 161001API 内部创建/传递的中间对象为空 → 561103。实战排查以 161001 空指针错误为例仓库的编译与运行示例文档给出了一个可复现的报错场景在调用aclnnAbsGetWorkspaceSize时故意传入空指针并用aclGetRecentErrMsg打印异常信息// self is nullptr ret aclnnAbsGetWorkspaceSize(self, out, workspaceSize, executor); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclnnAbsGetWorkspaceSize failed. ERROR: %d.\n[ERROR msg]%s, ret, aclGetRecentErrMsg()); return ret);运行输出示例如下aclnnAbsGetWorkspaceSize failed. ERROR: 161001 [ERROR msg][PID:xxxx] xxx(timestamp) AclNN_Parameter_Error(EZ1001): Expected a value of type [aclTensor] for argument [self] but instead found nullptr.这条日志与 op_error_check.h 中IsNullptr的日志模板完全一致Expected a value of type [%s] for argument [%s] but instead found nullptr可以直接定位到出问题的是self这个入参。排查时的标准动作就是先取返回码定级161/361/561再用aclGetRecentErrMsg的日志确认具体参数或内部环节。按错误码组织的排查建议161001 / 161002参数校验错误核对所有aclTensor、aclIntArray指针非空输入 dtype 是否满足该算子的推导关系参考 数据类型推导 与 数据格式shape/维度是否在支持范围内日志中会给出具体参数名可逐一对齐。361001runtime 异常检查 NPU runtime 初始化、device/stream 状态以及 workspace 内存申请是否成功。561003 / 561112kernel 查找/加载失败优先确认算子二进制包是否已安装、ASCEND_OPP_PATH等环境变量是否配置正确对应 561107。561108561117json 元数据异常说明算子二进制包中算子信息 json 与调用方传入的 attr/输入个数不匹配或字段非法通常意味着库版本与调用方式不一致应核对算子包版本与调用参数。561118 / 561119静态二进制信息异常解析静态 kernel 的 workspace/核数信息失败属于算子包元数据问题可结合aclGetRecentErrMsg的具体字段信息进一步定位。综合来看ops-math 的 aclnn 返回码体系以“两段式接口 统一错误码 集中式校验宏”为基础错误码是分类入口aclGetRecentErrMsg的日志是定位入口而 common/inc 下的公共校验头文件则揭示了每个错误码的确切抛出点三者配合即可完成从“看到非 0 返回码”到“锁定具体根因”的完整排查闭环。【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考