CANN opbase 错误码 EZ1001AclNN_Parameter_Error详解从报错机制到排查实战【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase本篇技术指南围绕 CANN opbase 基础框架库cann/opbase中 Nnopbase 错误码体系下的EZ1001 AclNN_Parameter_Error展开说明该错误码的报错格式、底层映射机制、典型触发场景与排查方法。读完本文你将理解 EZ1001 与ACLNN_ERR_PARAM_INVALID161002之间的对应关系掌握在调用 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 }从注册表可以看出errClassAclNN Errors与EZ9999AclNN_Inner_Error、EZ9903AclNN_Runtime_Error同属 AclNN 错误类别ErrMessage%s即错误信息完全由调用方传入的自由文本组成Arglistmessage仅有一个占位参数对应报错时传入的具体说明文字。二、报错格式与典型示例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_mapchar, std::string ERRNO_PREFIX_TO_ERROR_CODE { {1, EZ1001}, {3, EZ9903}, {5, EZ9999}};映射规则为取 errno 数值十进制的首位数字作为 key。首位为1参数类错误→EZ1001AclNN_Parameter_Error首位为3运行时类错误→EZ9903AclNN_Runtime_Error首位为5内部类错误→EZ9999AclNN_Inner_ErrorReportErrorMessage模板函数实现该转换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其中状态码名称状态码值说明ACLNN_SUCCESS0成功ACLNN_ERR_PARAM_NULLPTR161001参数校验错误存在非法 nullptrACLNN_ERR_PARAM_INVALID161002参数校验错误如输入数据类型不满足类型推导关系ACLNN_ERR_RUNTIME_ERROR361001API 调用 runtime 接口异常ACLNN_ERR_INNER_XXX561xxxAPI 内部异常因此凡 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_INVALIDaclSetInputTensorAddr/aclSetOutputTensorAddr中aclCheckPcieAddrRefresh(tensor, addr, addr)校验失败时返回ACLNN_ERR_PARAM_INVALIDL352、L374aclSetDynamicInputTensorAddr中动态输入索引越界时返回ACLNN_ERR_PARAM_INVALIDL393-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_INVALIDL35、L46、L121-L123src/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_INVALIDViewShape与ViewStride维度不匹配ViewShape出现重叠overlap。由此可见EZ1001 并不仅指单个接口的类型不对而是覆盖了空指针、索引越界、形状/步长不匹配、JSON 解析失败、地址刷新失败等一整套输入参数合法性问题。五、报错信息的上报与获取当校验失败后错误信息通过OP_LOGE宏与REPORT_ERROR_MESSAGE宏写入错误信息容器。底层实现在 src/nnopbase/composite_op/log/op_error_manager.cppconstexpr size_t LIMIT_PREDEFINED_MESSAGE 1024U; void ReportErrorMessageInner(const std::string code, const char* fmt, ...) { std::vectorchar 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::vectorconst char* msgKey {message}; const std::vectorconst 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。结合源码建议按以下清单逐项排查空指针检查确认传入的aclTensor、aclOpExecutor、aclTensorList等指针均非空对应返回码ACLNN_ERR_PARAM_NULLPTR161001索引范围检查使用动态输入相关接口如aclSetDynamicInputTensorAddr时确认relativeIndex/irIndex未超出张量列表大小形状与步长检查确认输入张量的ViewShape、ViewStride维度一致且无重叠storageDims与视图关系正确数据类型检查确认输入数据类型满足算子类型推导关系如两个输入的数据类型匹配地址有效性检查确认通过aclSetInputTensorAddr/aclSetOutputTensorAddr传入的地址合法满足aclCheckPcieAddrRefresh的校验要求配置文件检查若错误发生在 JSON 解析阶段如算子描述文件损坏检查算子包安装与环境变量ASCEND_OPP_PATH/ASCEND_CUSTOM_OPP_PATH配置是否正确获取详细错误调用aclGetRecentErrMsg获取最近一次错误的完整文本通常包含失败的具体参数名与原因。此外错误日志会通过OP_LOGE等宏记录包含文件名、行号、线程号与算子名OpName可按日志定位到具体校验点例如 acl_op_api.cpp 中的越界信息会明确指出relativeIndex与tensors size的实际值。七、与其他 Nnopbase 错误码的区别EZ1001 属于 AclNN Errors 类别与 Nnopbase 错误码体系中的其他成员见 Nnopbase-Errors.md分工不同排查时注意区分错误码错误标题适用场景EZ1001AclNN_Parameter_Erroraclnn 接口入参校验失败errno 首位为 1EZ1002Config_Error_Invalid_Environment_Variable环境变量未配置EZ1006Not_Supported_Data_Type算子不支持某数据类型EZ1008 / EZ1009 / EZ1014Execution_Error算子执行、tiling、inferShape 阶段失败EZ1010Invalid_Argument参数值非法EZ1011Invalid_Argument_Null_Pointer参数不能为空指针EZ1012Invalid_Argument参数值超出范围简言之EZ1001 是参数没通过校验的通用信号具体是哪种参数问题需要结合报错文本与上述定位路径进一步确认而 EZ1010~EZ1012 等则对应更细分的参数问题其 ErrMessage 模板带参数名与原因说明。八、测试验证opbase 仓库通过单元/集成测试验证 EZ1001 的上报行为见 tests/nnopbase/st/composite_op/test_error_manager.cppTEST_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_INVALID161002触发上报并断言错误信息容器中同时包含错误码EZ1001与传入的消息内容直接验证了16xxxx 参数类 errno → EZ1001的完整链路。总结EZ1001AclNN_Parameter_Error是 CANN opbase 中最常见的参数校验错误码之一其本质是 aclnn 接口返回码中 16xxxx 参数类错误的统一对外呈现。理解 errno 前缀映射、错误信息注册表与各校验点的源码实现可以帮助开发者在遇到 Parameter validation failed. Please check the log. 时快速定位到具体的参数问题并给出正确的修复方案。【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考