企业官网建设流程全解析

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

【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math

在 CANN 的数学算子库 ops-math 中，所有算子均以两段式 aclnn 接口（xxxGetWorkspaceSize+xxx）形式暴露，接口的返回值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 时，常见的接口返回码如下表所示（完整继承自官方返回码文档）：

从码值分布可以推断出清晰的排查分层思路：

• 161xxx（参数校验错误）：问题出在调用方传入的 tensor、workspace 指针或属性上，重点检查输入合法性；
• 361xxx（runtime 错误）：aclnn API 向下调用 NPU runtime 时异常，重点检查设备状态、stream 与内存申请；
• 561xxx（内部异常）：API 内部逻辑异常，细分含义见下一节，通常与算子二进制包安装、环境变量配置或 kernel json 元数据有关。

561xxx 内部异常状态码详解

ACLNN_ERR_INNER_XXX类状态码覆盖了从 shape 推导、tiling、kernel 匹配到算子元数据（json）加载的整条内部链路，完整列表如下：

按功能可以进一步把 561xxx 拆成几组：

• 561000～561003：计算主链路异常，覆盖 shape 推导、tiling、kernel 查找三个关键步骤，其中 561003 明确提示“可能因为算子二进制包未安装”，是环境缺失类问题的典型信号；
• 561101～561107：executor 生命周期与运行配置异常，包括 executor 创建失败、状态未正确迁移（未调用 ReleaseTo）、实现模式错误，以及缺少ASCEND_OPP_PATH环境变量；
• 561108～561117：算子 kernel 库元数据（json）解析异常，从文件加载失败、字段缺失，到 format/dtype 填写非法、属性个数不匹配、输入个数超过 32 上限，逐一指向算子二进制包元数据的某一种损坏形态；
• 561118～561119：静态二进制 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_NULLPTR（161001）与ACLNN_ERR_PARAM_INVALID（161002）两个码上。例如 shape 推导失败走OP_CHECK_INFERSHAPE宏返回ACLNN_ERR_INNER_INFERSHAPE_ERROR（561001），静态 workspace 校验失败走OP_CHECK_ADD_TO_LAUNCHER_LIST_AICORE宏返回ACLNN_ERR_INNER_STATIC_WORKSPACE_INVALID（561118）——这与上表中 561xxx 码的定义一一呼应。

算子实现侧的便捷校验宏

在 aclnn_check.h 中，ops-math 进一步封装了变参宏CHECK_NOT_NULL(...)与CHECK_SHAPE_ALL_EQUAL(...)，借助GET_ARGS_COUNT支持 1～8 个参数逐个做空指针/shape 相等与最大维度校验，算子在自己的GetWorkspaceSize开头一行即可完成多参数校验，失败即return ACLNN_ERR_PARAM_NULLPTR或ACLNN_ERR_PARAM_INVALID。

而 level2_base_caculation.h 中则体现了内部空指针错误码的用法，多个内部 tensor 参数用CHECK_RET(..., ACLNN_ERR_INNER_NULLPTR)校验，最后返回ACLNN_SUCCESS：

CHECK_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;

从源码结构看，可以这样区分两类空指针错误：调用方传入的入参为空 → 161001；API 内部创建/传递的中间对象为空 → 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/维度是否在支持范围内；日志中会给出具体参数名，可逐一对齐。
• 361001（runtime 异常）：检查 NPU runtime 初始化、device/stream 状态以及 workspace 内存申请是否成功。
• 561003 / 561112（kernel 查找/加载失败）：优先确认算子二进制包是否已安装、ASCEND_OPP_PATH等环境变量是否配置正确（对应 561107）。
• 561108～561117（json 元数据异常）：说明算子二进制包中算子信息 json 与调用方传入的 attr/输入个数不匹配或字段非法，通常意味着库版本与调用方式不一致，应核对算子包版本与调用参数。
• 561118 / 561119（静态二进制信息异常）：解析静态 kernel 的 workspace/核数信息失败，属于算子包元数据问题，可结合aclGetRecentErrMsg的具体字段信息进一步定位。

综合来看，ops-math 的 aclnn 返回码体系以“两段式接口 + 统一错误码 + 集中式校验宏”为基础：错误码是分类入口，aclGetRecentErrMsg的日志是定位入口，而 common/inc 下的公共校验头文件则揭示了每个错误码的确切抛出点，三者配合即可完成从“看到非 0 返回码”到“锁定具体根因”的完整排查闭环。

【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math