企业官网建设流程全解析

CANN opbase 错误码 EZ1001（AclNN_Parameter_Error）详解：从报错机制到排查实战

【免费下载链接】opbase本项目是CANN算子库的基础框架库，为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase

本篇技术指南围绕 CANN opbase 基础框架库（cann/opbase）中 Nnopbase 错误码体系下的EZ1001 AclNN_Parameter_Error展开，说明该错误码的报错格式、底层映射机制、典型触发场景与排查方法。读完本文，你将理解 EZ1001 与ACLNN_ERR_PARAM_INVALID（161002）之间的对应关系，掌握在调用 aclnn 接口出现参数校验失败时快速定位根因的实战手段。

一、EZ1001 是什么：AclNN 参数校验错误

EZ1001 是 opbase 预定义错误码中面向AclNN 接口参数校验的错误类别，官方全称为AclNN_Parameter_Error。当 aclnn 接口的入参（如aclTensor、aclOpExecutor、索引、地址等）不满足校验条件时，框架会通过日志与错误信息容器上报该错误码。

该错误码在源码中的注册信息位于 src/nnopbase/composite_op/log/op_error_manager.cpp，其元数据为：

{ "errClass": "AclNN Errors", "errTitle": "AclNN_Parameter_Error", "ErrCode": "EZ1001", "ErrMessage": "%s", "Arglist": "message" }

从注册表可以看出：

• errClass：AclNN Errors，与EZ9999（AclNN_Inner_Error）、EZ9903（AclNN_Runtime_Error）同属 AclNN 错误类别；
• ErrMessage：%s，即错误信息完全由调用方传入的自由文本组成；
• Arglist：message，仅有一个占位参数，对应报错时传入的具体说明文字。

二、报错格式与典型示例

EZ1001 的报错格式定义如下，占位符%s表示具体的报错信息：

%s

官方给出的报错示例如下：

Parameter validation failed. Please check the log.

也就是说，当你在日志或aclGetRecentErrMsg返回的错误信息中看到形如上述"Parameter validation failed"的文本、且关联错误码为 EZ1001 时，说明本次 aclnn 接口调用在参数校验阶段被拦截，并未进入算子执行流程。

三、底层机制：errno 前缀到错误码的映射

EZ1001 并非独立产生的错误码，而是由 aclnn 接口返回的 errno 经过前缀映射得到的。在 include/nnopbase/opdev/op_log.h 中定义了如下映射表：

const std::unordered_map<char, std::string> ERRNO_PREFIX_TO_ERROR_CODE = { {'1', "EZ1001"}, {'3', "EZ9903"}, {'5', "EZ9999"}};

映射规则为：取 errno 数值十进制的首位数字作为 key。

• 首位为1（参数类错误）→EZ1001（AclNN_Parameter_Error）
• 首位为3（运行时类错误）→EZ9903（AclNN_Runtime_Error）
• 首位为5（内部类错误）→EZ9999（AclNN_Inner_Error）

ReportErrorMessage模板函数实现该转换（op_log.h）：传入的 code 首字符命中映射表则采用对应错误码，否则兜底为EZ9999。

与 EZ1001 直接对应的 errno 定义在 include/nnopbase/opdev/op_errno.h：

#define ACLNN_SUCCESS 0 #define ACLNN_ERR_PARAM_NULLPTR 161001 #define ACLNN_ERR_PARAM_INVALID 161002 #define ACLNN_ERR_RUNTIME_ERROR 361001 #define ACLNN_ERR_INNER 561000

其中：

因此，凡 errno 为16xxxx系列（首位为 1）的返回码，最终上报错误码均为EZ1001。完整的返回码说明可参考 docs/zh/api/nnopbase/aclnn/public_interface_return_code.md。

四、典型触发场景：源码中的校验点

EZ1001 由算子库各模块在参数校验失败时统一上报。以下是从源码中梳理出的常见触发位置。

4.1 公共 API 层的参数刷新与越界检查

在 src/nnopbase/common/api/acl_op_api.cpp 中，多处参数校验失败返回ACLNN_ERR_PARAM_INVALID：

• aclSetInputTensorAddr/aclSetOutputTensorAddr中aclCheckPcieAddrRefresh(tensor, addr, "addr")校验失败时返回ACLNN_ERR_PARAM_INVALID（L352、L374）；
• aclSetDynamicInputTensorAddr中动态输入索引越界时返回ACLNN_ERR_PARAM_INVALID（L393-L396），报错信息为：

CHECK_COND((relativeIndex < tensors->Size()), ACLNN_ERR_PARAM_INVALID, "Set dynamic input tensor addr failed. " "relativeIndex[%zu] is out of tensors size[%lu].", relativeIndex, tensors->Size());

4.2 JSON 解析与任务参数

• src/nnopbase/aicpu/task_handler/ops_json_parse.cpp 中，算子 JSON 参数解析失败时返回ACLNN_ERR_PARAM_INVALID（L35、L46、L121-L123）；
• src/nnopbase/aicpu/task_handler/aicpu_task.cpp 中args为空指针时返回ACLNN_ERR_PARAM_INVALID。

4.3 张量视图校验

src/nnopbase/composite_op/utils/tensor_view_utils.cpp 中对张量视图进行合法性校验，不满足时上报ACLNN_ERR_PARAM_INVALID：

• ViewShape与ViewStride维度不匹配；
• ViewShape出现重叠（overlap）。

由此可见，EZ1001 并不仅指单个接口的"类型不对"，而是覆盖了空指针、索引越界、形状/步长不匹配、JSON 解析失败、地址刷新失败等一整套输入参数合法性问题。

五、报错信息的上报与获取

当校验失败后，错误信息通过OP_LOGE宏与REPORT_ERROR_MESSAGE宏写入错误信息容器。底层实现在 src/nnopbase/composite_op/log/op_error_manager.cpp：

constexpr size_t LIMIT_PREDEFINED_MESSAGE = 1024U; void ReportErrorMessageInner(const std::string& code, const char* fmt, ...) { std::vector<char> buf(LIMIT_PREDEFINED_MESSAGE, '\0'); va_list argList; va_start(argList, fmt); auto ret = vsnprintf_s(buf.data(), LIMIT_PREDEFINED_MESSAGE, LIMIT_PREDEFINED_MESSAGE - 1U, fmt, argList); if (ret == -1) { OP_LOGW("Construct report error message failed, maybe the length of error message exceeds limits: %zu", LIMIT_PREDEFINED_MESSAGE); } va_end(argList); const std::vector<const char*> msgKey = {"message"}; const std::vector<const char*> msgvalue = {buf.data()}; REPORT_PREDEFINED_ERR_MSG(code.c_str(), msgKey, msgvalue); }

值得注意的实现细节：

• 单条错误消息缓冲区上限为1024 字节，超长消息会截断并产生告警日志；
• 上报消息的关键字固定为message，与 EZ1001 注册表中的"Arglist": "message"一一对应；
• 错误信息最终可通过aclGetRecentErrMsg接口获取（见 public_interface_return_code.md）。

六、解决方法与排查路径

官方给出的解决方法是：检查 aclnn 接口输入参数是否正确（原文见 EZ1001-AclNN_Parameter_Error.md）。结合源码，建议按以下清单逐项排查：

1. 空指针检查：确认传入的aclTensor、aclOpExecutor、aclTensorList等指针均非空，对应返回码ACLNN_ERR_PARAM_NULLPTR（161001）；
2. 索引范围检查：使用动态输入相关接口（如aclSetDynamicInputTensorAddr）时，确认relativeIndex/irIndex未超出张量列表大小；
3. 形状与步长检查：确认输入张量的ViewShape、ViewStride维度一致且无重叠，storageDims与视图关系正确；
4. 数据类型检查：确认输入数据类型满足算子类型推导关系（如两个输入的数据类型匹配）；
5. 地址有效性检查：确认通过aclSetInputTensorAddr/aclSetOutputTensorAddr传入的地址合法，满足aclCheckPcieAddrRefresh的校验要求；
6. 配置文件检查：若错误发生在 JSON 解析阶段（如算子描述文件损坏），检查算子包安装与环境变量（ASCEND_OPP_PATH/ASCEND_CUSTOM_OPP_PATH）配置是否正确；
7. 获取详细错误：调用aclGetRecentErrMsg获取最近一次错误的完整文本，通常包含失败的具体参数名与原因。

此外，错误日志会通过OP_LOGE等宏记录，包含文件名、行号、线程号与算子名（OpName），可按日志定位到具体校验点，例如 acl_op_api.cpp 中的越界信息会明确指出relativeIndex与tensors size的实际值。

七、与其他 Nnopbase 错误码的区别

EZ1001 属于 "AclNN Errors" 类别，与 Nnopbase 错误码体系中的其他成员（见 Nnopbase-Errors.md）分工不同，排查时注意区分：

简言之：EZ1001 是"参数没通过校验"的通用信号，具体是哪种参数问题，需要结合报错文本与上述定位路径进一步确认；而 EZ1010~EZ1012 等则对应更细分的参数问题，其 ErrMessage 模板带参数名与原因说明。

八、测试验证

opbase 仓库通过单元/集成测试验证 EZ1001 的上报行为，见 tests/nnopbase/st/composite_op/test_error_manager.cpp：

TEST_F(ErrorManagerUt, ErrorManagerTestCase2) { std::string errorCode = "EZ1001"; std::string errorMsg = "ErrorManagerTestCase2"; int32_t errorNo = ACLNN_ERR_PARAM_INVALID; REPORT_ERROR_MESSAGE_UT(errorNo, errorMsg.c_str()); auto errMsg = error_message::GetErrMgrErrorMessage(); OP_LOGI("error msg:\n%s", errMsg.get()); EXPECT_NE(errMsg, nullptr); EXPECT_TRUE(std::string(errMsg.get()).find(errorCode) != std::string::npos); EXPECT_TRUE(std::string(errMsg.get()).find(errorMsg) != std::string::npos); }

该用例使用ACLNN_ERR_PARAM_INVALID（161002）触发上报，并断言错误信息容器中同时包含错误码EZ1001与传入的消息内容，直接验证了"16xxxx 参数类 errno → EZ1001"的完整链路。

总结

EZ1001（AclNN_Parameter_Error）是 CANN opbase 中最常见的参数校验错误码之一，其本质是 aclnn 接口返回码中 16xxxx 参数类错误的统一对外呈现。理解 errno 前缀映射、错误信息注册表与各校验点的源码实现，可以帮助开发者在遇到 "Parameter validation failed. Please check the log." 时，快速定位到具体的参数问题并给出正确的修复方案。

【免费下载链接】opbase本项目是CANN算子库的基础框架库，为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase