CANN opbase 错误码 EZ0027 详解多参数值校验失败Invalid Argument的识别、上报与排查【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase本篇技术指南聚焦 CANN opbase算子库基础框架库中算子错误码 EZ0027Invalid Argument的完整链路从错误信息格式与占位符含义的准确解读到算子/ACLNN 接口中通过OP_LOGE_FOR_INVALID_VALUES_WITH_REASON宏进行多参数值校验上报的源码级实现再到日志底层上报机制与实战排查方法。读者读完本篇将掌握 EZ0027 错误的触发场景、如何在自研算子中规范地产生该错误码以及面对该报错时如何快速定位并修复参数取值问题。一、EZ0027 错误码定位与语义EZ0027 属于 CANN opbase 中Operator Errors算子错误类别的预定义错误码全称Invalid_Argument用于描述算子或 aclnn 接口的多个参数取值同时不满足约束条件的异常场景。在 错误码总览 中EZ0027 与 EZ0022~EZ0026 同属 Invalid Argument 系列其区分要点在于EZ0022 / EZ0023张量数量错误单参数 / 多参数EZ0024单参数取值错误附带期望值EZ0025参数列表大小错误EZ0026单参数取值错误附带原因说明EZ0027多个参数取值错误且附带原因说明对应多参数之间的取值组合互斥或联动约束场景。EZ0027 是多参数 带原因这一维度下的专门错误码其语义由 日志模块头文件 中的宏注释明确定义。二、错误信息格式与占位符含义根据 EZ0027 官方文档EZ0027 的报错格式如下Parameters %s of %s have incorrect values %s. Reason: %s.四个占位符%s依序的含义为占位符顺序含义典型内容示例第 1 个%s参数名称列表align_corners and half_pixel_centers第 2 个%s算子名称或 API 名称ResizeNearestNeighborV2Grad第 3 个%s错误的参数取值列表true and true第 4 个%s报错原因The values of attributes align_corners and half_pixel_centers cannot be true at the same time.结合 错误码注册表 中的元数据EZ0027 的Arglist参数列表为param_names, op_name, incorrect_values, reason与上述占位符一一对应印证了该错误码携带四个结构化字段的设计。三、典型报错示例解析官方文档给出的完整报错示例如下Parameters align_corners and half_pixel_centers of ResizeNearestNeighborV2Grad have incorrect values true and true. Reason: The values of attributes align_corners and half_pixel_centers cannot be true at the same time.该示例揭示了 EZ0027 的典型触发场景——参数取值组合互斥算子ResizeNearestNeighborV2Grad最近邻插值的反向梯度算子涉及参数align_corners对齐角点与half_pixel_centers半像素中心问题取值两者同时为true原因这两个属性在语义上不允许同时为true同时开启会导致插值坐标映射规则冲突因此校验逻辑判定参数组合非法并上报 EZ0027。这类多参数之间存在互斥或联动约束的校验正是 EZ0027 相较于单参数错误码的核心价值它一次上报能够同时给出所有违规参数及其各自取值配合原因说明排查者无需二次猜测。四、源码级实现OP_LOGE_FOR_INVALID_VALUES_WITH_REASON 宏EZ0027 在算子侧由日志宏OP_LOGE_FOR_INVALID_VALUES_WITH_REASON产生其完整定义位于 include/op_common/log/log.h#L809-L823#define OP_LOGE_FOR_INVALID_VALUES_WITH_REASON(entityName, paramNames, incorrectValues, reason) \ do { \ std::string _safe_entityName_(entityName); \ std::string _safe_paramNames_(paramNames); \ std::string _safe_incorrectValues_(incorrectValues); \ std::string _safe_reason_(reason); \ OP_LOGE_LIBOPAPI_REPORT(_safe_entityName_.c_str(), \ Parameters %s of %s have incorrect values %s. Reason: %s., \ _safe_paramNames_.c_str(), _safe_entityName_.c_str(), _safe_incorrectValues_.c_str(), \ _safe_reason_.c_str()); \ const std::vectorconst char* msgKey {param_names, op_name, incorrect_values, reason}; \ const std::vectorconst char* msgvalue {_safe_paramNames_.c_str(), _safe_entityName_.c_str(), \ _safe_incorrectValues_.c_str(), _safe_reason_.c_str()}; \ REPORT_PREDEFINED_ERR_MSG(EZ0027, msgKey, msgvalue); \ } while (0)从宏实现可以看出 EZ0027 上报的双通道设计日志通道通过OP_LOGE_LIBOPAPI_REPORT输出 ERROR 级别日志格式串Parameters %s of %s have incorrect values %s. Reason: %s.与官方文档中的错误格式完全一致结构化错误码通道将{param_names, op_name, incorrect_values, reason}作为 msgKey、实际取值为 msgvalue通过REPORT_PREDEFINED_ERR_MSG(EZ0027, msgKey, msgvalue)上报 EZ0027 预定义错误码该宏来自log.h引入的base/err_msg.h头文件负责错误码与结构化参数的分发。宏内部先将四个入参统一转换为std::string再取c_str()保证const char*与std::string两种入参类型均能安全使用。宏参数说明参数说明支持类型entityName算子名称或 aclnn 接口名称const char*/std::stringparamNames出错的参数名称列表多个参数名用and连接const char*/std::stringincorrectValues实际的错误参数取值列表const char*/std::stringreason错误原因描述const char*/std::string完整的宏参数规格与调用约定可参考 OP_LOGE_FOR_INVALID_VALUES_WITH_REASON 接口文档。五、在算子代码中上报 EZ0027 的标准写法在算子的 InferShape 或参数校验阶段一旦发现多参数取值组合非法即可调用该宏上报。官方接口文档给出的关键代码示例如下示例取自 docs/zh/api/op_common/log/OP_LOGE_FOR_INVALID_VALUES_WITH_REASON.md#L30-L43// 预期输出: Parameters align_corners and half_pixel_centers of ResizeNearestNeighborV2Grad have // incorrect values true and true. Reason: The values of attributes align_corners and // half_pixel_centers cannot be true at the same time. if (alignCorners_ halfPixelCenters_) { OP_LOGE_FOR_INVALID_VALUES_WITH_REASON(ResizeNearestNeighborV2Grad, align_corners and half_pixel_centers, true and true, The values of attributes align_corners and half_pixel_centers cannot be true at the same time.); return ge::GRAPH_FAILED; }编写规范要点参数名列表多个参数名用and连接与错误格式串中的单复数语义保持一致取值列表按相同顺序给出每个参数的实际取值同样用and连接原因描述写明参数间的约束关系如cannot be true at the same time这是排查者最重要的指引返回值上报后通常返回ge::GRAPH_FAILED以终止图编译或算子执行流程避免携带非法参数继续运行。六、错误码注册表EZ0027 的元数据定义EZ0027 的正式注册信息位于 src/op_common/log/log.cpp#L544-L554以 JSON 结构登记于算子错误码表中{ errClass: Operator Errors, errTitle: Invalid_Argument, ErrCode: EZ0027, ErrMessage: Parameters %s of %s have incorrect values %s. Reason: %s., Arglist: param_names, op_name, incorrect_values, reason, suggestion: { Possible Cause: N/A, Solution: Check whether the parameter values meet the condition. } }该注册表同时登记了错误码的官方建议解决方案Check whether the parameter values meet the condition.与 英文文档 的 Solution 章节一致可供错误码查询、文档生成与自动化定位工具消费。七、底层日志链路错误如何被记录EZ0027 上报的日志部分最终经由OP_LOGE_LIBOPAPI_REPORT落地其定义位于 include/op_common/log/log.h#L106-L115#define OP_LOGE_LIBOPAPI_REPORT(opName, fmt, ...) \ do { \ if (CheckLogLevel(static_castint(OP_MODULE_ID), DLOG_ERROR) 1) { \ DlogRecord(static_castint(OP_MODULE_ID), DLOG_ERROR, \ [%s:%d][%s] \ [%s][% PRIu64 ] OpName:[%s] fmt, \ __FILE__, __LINE__, OP_SUBMOD_NAME, __FUNCTION__, Ops::Base::GetTid(), \ Ops::Base::GetSafeStr(Ops::Base::GetOpInfo(opName)), ##__VA_ARGS__); \ } \ } while (0)关键机制从源码结构看日志级别门控先调用CheckLogLevel(OP_MODULE_ID, DLOG_ERROR)判断算子模块OP_MODULE_ID 63见 log.h#L42的 ERROR 级日志是否开启只有开启时才调用DlogRecord写入避免无效格式化开销线程与上下文信息日志前缀包含源文件/行号__FILE__:__LINE__、子模块名OP_SUBMOD_NAME默认OPS_BASE、所在函数__FUNCTION__以及线程 ID通过syscall(__NR_gettid)获取的GetTid()便于多线程场景下按线程维度检索算子名归一化GetOpInfo对const char*、std::string与上下文对象做了类型适配空指针输出nilGetSafeStr进一步保证入参为安全字符串。因此一条完整的 EZ0027 日志会携带模块号、错误级别、代码位置与线程 ID同时结构化错误码 EZ0027 会与param_names / op_name / incorrect_values / reason四个字段一并分发日志与错误码双通道信息互相对应。八、收到 EZ0027 报错后的排查思路官方文档给出的解决方法为根据报错原因检查参数值是否满足条件。结合本文的分析完整排查路径如下识别涉及参数从第 1 个占位符param_names确认是哪几个参数组合出错例如示例中的align_corners与half_pixel_centers核对实际取值从第 3 个占位符incorrect_values确认各参数当前传入的值如true and true理解约束关系从第 4 个占位符reason读取原因说明明确参数之间的互斥/联动规则如两者不能同时为 true修正入参依据算子文档或约束定义将参数调整为合法组合例如保证align_corners与half_pixel_centers不同时为true重新下发计算任务。由于 EZ0027 的报错信息已完整携带参数名 算子名 取值 原因四要素绝大多数场景下无需翻查算子源码即可定位根因若需深入可在对应算子实现的参数校验分支中查找OP_LOGE_FOR_INVALID_VALUES_WITH_REASON调用点确认触发该错误的校验条件。九、与相邻错误码的选择建议在编写算子参数校验时应根据违规形态选择合适的错误码场景推荐错误码单参数取值错误且有明确期望值EZ0024单参数取值错误需要说明原因EZ0026多参数取值错误需要说明原因互斥/联动约束EZ0027参数列表大小错误EZ0025输入张量数量错误EZ0022 / EZ0023多参数组合校验如两个布尔属性不能同时为真多个维度取值之和超限是 EZ0027 的典型应用面。使用统一的预定义错误码体系既能保证日志与错误码格式的规范性也让上层框架、工具链与用户能够基于稳定的ErrCode与结构化字段自动识别错误类型这正是 log.h 中整套OP_LOGE_*宏设计的核心价值。延伸阅读算子错误码总览Operator ErrorsOP_LOGE_FOR_INVALID_VALUES_WITH_REASON 接口文档日志接口说明错误码注册与上报实现【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考