CANN opbase 算子开发错误码 EZ0017 解析Tensor Format 校验失败的定位与修复【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase导读EZ0017 是 CANN opbase 算子基础框架库中针对 Tensor 数据排布格式format参数校验失败定义的标准错误码。当调用某个算子或 aclnn 接口时如果传入 Tensor 的实际 format 不在该接口允许的范围内框架就会抛出形如Parameter x of ResizeBilinearV2 has incorrect format ND. It should be NCHW or NHWC.的报错。本文以 EZ0017 错误码文档 为核心骨架结合 opbase 仓库中日志宏、错误码注册表与 format 工具类的源码实现帮助你完整理解 EZ0017 的报错格式、占位符含义、触发场景并掌握在自研算子或 aclnn 接口中如何主动上报该错误、如何快速定位并修复 format 参数问题。EZ0017 错误码定位它属于哪一类算子错误在 CANN opbase 的错误码体系中错误码按错误域errClass分类EZ0017 属于Operator Errors算子错误错误标题errTitle为Invalid_Argument_Tensor_Format即“Tensor 参数 format 非法”。该错误码与算子参数校验体系中的其他错误码EZ0001~EZ0038并列专门用于描述 Tensor 的 format 维度上的参数问题。从 错误码注册表源码 可以看到EZ0017 在框架内部注册的完整定义为{ errClass: Operator Errors, errTitle: Invalid_Argument_Tensor_Format, ErrCode: EZ0017, ErrMessage: Parameter %s of %s has incorrect format %s. It should be %s., Arglist: param_name, op_name, incorrect_format, correct_format, suggestion: { Possible Cause: N/A, Solution: Check whether the format of input/output tensor is correct. } }Arglist定义了报错文案中 4 个%s占位符依次对应的参数名param_name参数名、op_name算子名或接口名、incorrect_format错误的 format 值、correct_format正确的 format 值。suggestion.Solution给出了官方建议的解决方向检查输入或输出 tensor 的 format 是否正确。在格式类错误中EZ0017 属于“单个参数、给出正确格式”的语义变体与它相邻的还有两个同主题错误码EZ0035单个参数 format 错误但带具体原因Reason: %sEZ0018多个参数 format 同时错误Parameters %s ... have incorrect formats %s. Reason: %s.。三者共同构成完整的 format 参数校验错误上报矩阵。错误信息逐字解析报错模板与占位符EZ0017 的报错模板原文如下Parameter %s of %s has incorrect format %s. It should be %s.四个占位符%s的含义按出现顺序依次为占位符序号含义对应 Arglist1参数名如输入/输出 tensor 的名称xparam_name2算子名称或 aclnn 接口名称如ResizeBilinearV2op_name3format 错误值即实际传入的非法 format如NDincorrect_format4format 正确值即接口允许的 format如NCHW or NHWCcorrect_format报错示例文档给出的典型报错示例为Parameter x of ResizeBilinearV2 has incorrect format ND. It should be NCHW or NHWC.逐段解读这条报错Parameter x发生错误的参数名为x通常是算子的某个输入或输出 tensorof ResizeBilinearV2报错来源算子为ResizeBilinearV2双线性插值算子has incorrect format ND该 tensor 当前实际 format 为NDIt should be NCHW or NHWC该算子要求 format 必须是NCHW或NHWC二者之一。也就是说调用方为x传入了ND格式的 tensor而ResizeBilinearV2只接受NCHW/NHWC因此框架拒绝执行并抛出 EZ0017。算子侧如何产生 EZ0017OP_LOGE_FOR_INVALID_FORMAT 宏EZ0017 并不是由框架隐式抛出的而是由算子或 aclnn 实现主动调用日志上报宏触发的。opbase 在 log.h 中提供了专门宏OP_LOGE_FOR_INVALID_FORMAT其源码实现如下#define OP_LOGE_FOR_INVALID_FORMAT(entityName, paramName, incorrectFormat, correctFormat) \ do { \ std::string _safe_entityName_(entityName); \ std::string _safe_paramName_(paramName); \ std::string _safe_incorrectFormat_(incorrectFormat); \ std::string _safe_correctFormat_(correctFormat); \ OP_LOGE_LIBOPAPI_REPORT(_safe_entityName_.c_str(), \ Parameter %s of %s has incorrect format %s. It should be %s., \ _safe_paramName_.c_str(), _safe_entityName_.c_str(), _safe_incorrectFormat_.c_str(), \ _safe_correctFormat_.c_str()); \ const std::vectorconst char* msgKey {param_name, op_name, incorrect_format, correct_format}; \ const std::vectorconst char* msgvalue {_safe_paramName_.c_str(), _safe_entityName_.c_str(), \ _safe_incorrectFormat_.c_str(), _safe_correctFormat_.c_str()}; \ REPORT_PREDEFINED_ERR_MSG(EZ0017, msgKey, msgvalue); \ } while (0)宏的内部行为可以拆成三步参数安全化先把 4 个入参拷贝为std::string局部变量_safe_entityName_等避免字符串指针生命周期问题打 ERROR 日志通过OP_LOGE_LIBOPAPI_REPORT输出一条 ERROR 级别日志日志文案与 EZ0017 报错模板完全一致结构化上报通过REPORT_PREDEFINED_ERR_MSG(EZ0017, msgKey, msgvalue)将错误码、键值对msgKey与msgvalue一一对应上报给上层供框架做统一错误码映射与问题诊断。参数说明参数名说明entityName算子名称或 aclnn 接口名称支持const char*或std::stringparamName参数名如x支持const char*或std::stringincorrectFormat实际传入的错误 format 值如ND支持const char*或std::stringcorrectFormat预期正确的 format 值或取值列表如NCHW or NHWC支持const char*或std::string调用示例来自 opbase 日志 API 文档OP_LOGE_FOR_INVALID_FORMAT 使用文档 给出了与 EZ0017 文档示例完全对应的实现代码// 预期输出: Parameter x of ResizeBilinearV2 has incorrect format ND. It should be // NCHW or NHWC. if (format_ ! ge::FORMAT_NCHW format_ ! ge::FORMAT_NHWC) { OP_LOGE_FOR_INVALID_FORMAT(ResizeBilinearV2, x, Ops::Base::ToString(format_).c_str(), NCHW or NHWC); return ge::GRAPH_FAILED; }可见典型用法是在算子的格式校验逻辑中判断 format 是否属于允许集合不满足时调用宏上报 EZ0017 并返回失败码。示例中Ops::Base::ToString(format_)用于把枚举类型 format 转成字符串如ND第三个参数即文档报错示例中的ND。同类 format 错误宏对照错误码宏语义EZ0017OP_LOGE_FOR_INVALID_FORMAT单参数 format 错误给出正确格式EZ0035OP_LOGE_FOR_INVALID_FORMAT_WITH_REASON单参数 format 错误附报错原因EZ0018OP_LOGE_FOR_INVALID_FORMATS_WITH_REASON多参数 format 错误附报错原因这三个宏均定义于 include/op_common/log/log.h与 错误码注册表 中的定义一一对应。若需要带原因说明的报错例如“所有输入的 format 必须一致”应优先使用..._WITH_REASON系列宏若仅需指示单个参数的正确取值使用 EZ0017 对应的宏即可。format 的来源算子侧如何拿到 format 字符串报错信息中出现的ND、NCHW、NHWC等字符串来自 opbase 的 format 工具类 format_utils.cpp。该文件维护了一张Format枚举到字符串的映射表kFormatToStringMap例如{Format::FORMAT_NCHW, NCHW}, {Format::FORMAT_NHWC, NHWC}, {Format::FORMAT_ND, ND},ToString(Format)函数在内部还会先调用GetPrimaryFormat取出主 format 再查表说明该工具对含附加信息的复合 format如 5D/NC1HWC0 系列做了归一化处理。这意味着 EZ0017 报错中展示的incorrect_format与correct_format都应是主 format 的规范化字符串便于开发者对照算子规格文档如 ResizeBilinearV2 的NCHW/NHWC约束快速定位问题。触发场景与排查步骤EZ0017 通常由以下几类情况触发调用方传错了 format例如将默认的ND格式 tensor 直接传给只接受NCHW/NHWC的算子未做 format 转换如TransData算子或未按接口要求显式指定 format。算子规格核对遗漏开发者在使用自定义算子或 aclnn 接口前未查阅该接口支持的 format 列表直接沿用其他框架的格式假设。图中 format 推导不一致在网络构图阶段上游算子输出的 format 与下游算子期望的 format 不匹配且缺少 format 转换节点。按官方文档给出的解决方法建议按以下步骤排查核对报错中的关键字段从报错文案中提取paramName哪个参数、opName哪个算子/接口、incorrectFormat实际值与correctFormat期望值。检查输入或输出 tensor 的 format 是否正确确认调用侧构造 tensor 时指定的 format 与期望值一致若不一致要么在调用前完成 format 转换要么显式设置符合要求的 format。对照算子规格文档确认correctFormat列出的取值如NCHW or NHWC是否与目标算子的官方约束一致避免规格理解偏差。若为图执行场景检查图中是否存在缺失的 format 转换算子或上游算子的 format 设置是否被错误覆盖。总结EZ0017 是 CANN opbase 算子参数校验体系中专门描述“单个 tensor 参数 format 非法并给出正确取值”的标准错误码。开发者既可以把它作为排障索引——通过报错中的参数名、算子名、错误值与期望值四元组快速定位 format 不匹配点也可以在自研算子或 aclnn 接口中通过OP_LOGE_FOR_INVALID_FORMAT宏主动上报该错误码与框架的REPORT_PREDEFINED_ERR_MSG结构化上报机制打通从而在算子侧实现与官方错误码体系一致、可被上层统一解析的 format 校验反馈。更多相邻错误码可参考 Operator-Errors 错误码总览。【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考