
CANN opbase 算子库错误码 EZ0015 排查指南Tensor Shape Size 校验失败的原因分析与修复实践【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase本篇技术指南以 CANN opbase 开源仓库的错误码文档为骨架系统讲解算子库错误码EZ0015Invalid_Argument_Tensor_Shape_Size的报错格式、占位符语义与触发场景并结合 日志宏定义、错误码注册表 与 真实算子源码 说明该错误码的生成机制与排查方法。读完本文你将能快速定位 Tensor 形状大小校验失败的具体参数、理解Reason字段的成因含义并在算子开发中正确使用OP_LOGE_FOR_INVALID_SHAPESIZE_WITH_REASON等日志宏来上报与修复此类错误。一、错误码概览EZ0015 在算子错误体系中的位置在 CANN opbase 算子库中算子运行时的参数校验错误统一通过**预定义错误码Predefined Error Code**体系上报。该体系的错误注册表集中维护在 src/op_common/log/log.cpp以 JSON 结构描述每个错误码的类别errClass、标题errTitle、错误码ErrCode、消息模板ErrMessage、参数列表Arglist和建议suggestion。EZ0015 属于Operator Errors类别、Invalid_Argument_Tensor_Shape_Size标题其完整注册信息如下见 log.cpp{ errClass: Operator Errors, errTitle: Invalid_Argument_Tensor_Shape_Size, ErrCode: EZ0015, ErrMessage: Parameter %s of %s has incorrect shape size %s. Reason: %s., Arglist: param_name, op_name, incorrect_size, reason, suggestion: { Possible Cause: N/A, Solution: Check whether the shape size of input/output tensor meets the condition. } }从注册表可以看出EZ0015 是Shape Size形状大小类错误的三种细分之一。整个家族还包括错误码报错消息模板适用场景EZ0014Parameter %s of %s has incorrect shape size %s. It should be %s.单个参数形状大小错误且可给出期望值correct sizeEZ0015Parameter %s of %s has incorrect shape size %s. Reason: %s.单个参数形状大小错误附报错原因reasonEZ0016Parameters %s of %s have incorrect shape sizes %s. Reason: %s.多个参数形状大小同时错误附报错原因三者共同点在于报错对象都是形状大小shape size即 Tensor 各维度乘积对应的总元素个数total element count区别于 EZ0008EZ0013 系列针对形状维度shape dim的错误以及 EZ0017/EZ0018 针对数据格式format、EZ0019EZ0021 针对数据类型dtype的错误。排查时先区分错误的落点是维度个数还是各维乘积的大小即可快速定位到正确的错误码族。二、报错格式与占位符语义EZ0015 的报错格式即 ErrMessage 模板为Parameter %s of %s has incorrect shape size %s. Reason: %s.其中四个%s占位符按顺序的含义分别是占位符含义对应 Arglist 字段第 1 个%s参数名parameter nameparam_name第 2 个%s算子名称或 API 名称operator name or API nameop_name第 3 个%s形状大小的错误值incorrect shape sizeincorrect_size第 4 个%s报错原因error cause / reasonreason官方报错示例原文档给出的完整报错示例如下Parameter y of ResizeLinear has incorrect shape size [144,144,1]. Reason: The linear-dimension of output y must be equal to value (256) of input parameter size.逐字段拆解这段日志Parameter y出错的参数是输出张量yof ResizeLinear报错算子为ResizeLinear线性插值缩放算子incorrect shape size [144,144,1]y当前的实际形状大小为[144,144,1]此处展示的是形状而非纯数值用于直观展示各维度Reason: The linear-dimension of output y must be equal to value (256) of input parameter size.错误原因明确指向——输出y的线性维度必须等于输入参数size所给定的值256当前实际值与约束条件不符。从该示例可以看出EZ0015 的Reason字段是整个报错中最具诊断价值的部分它直接告诉开发者应该满足什么约束、实际值偏离了多少因此排查时应当优先阅读Reason后的描述。三、源码级实现EZ0015 是如何被生成的EZ0015 并非由系统自动抛出而是算子在形状校验逻辑中显式调用日志宏触发上报。仓库中对应的上报宏定义在 include/op_common/log/log.h#define OP_LOGE_FOR_INVALID_SHAPESIZE_WITH_REASON(entityName, paramName, incorrectSize, reason) \ do { \ std::string _safe_entityName_(entityName); \ std::string _safe_paramName_(paramName); \ std::string _safe_incorrectSize_(incorrectSize); \ std::string _safe_reason_(reason); \ OP_LOGE_LIBOPAPI_REPORT( \ _safe_entityName_.c_str(), Parameter %s of %s has incorrect shape size %s. Reason: %s., \ _safe_paramName_.c_str(), _safe_entityName_.c_str(), _safe_incorrectSize_.c_str(), _safe_reason_.c_str()); \ const std::vectorconst char* msgKey {param_name, op_name, incorrect_size, reason}; \ const std::vectorconst char* msgvalue {_safe_paramName_.c_str(), _safe_entityName_.c_str(), \ _safe_incorrectSize_.c_str(), _safe_reason_.c_str()}; \ REPORT_PREDEFINED_ERR_MSG(EZ0015, msgKey, msgvalue); \ } while (0)该宏的调用机制可拆解为两条通道日志通道通过OP_LOGE_LIBOPAPI_REPORT输出 ERROR 级别的可读日志文本即第一节展示的模板消息错误码通道通过REPORT_PREDEFINED_ERR_MSG(EZ0015, msgKey, msgvalue)将错误码EZ0015与结构化字段param_name、op_name、incorrect_size、reason绑定上报供上层框架做统一的错误码归类与处理。宏内部对所有入参先做std::string拷贝_safe_*变量再用于日志与上报因此传参可以是const char*或std::string类型且在宏展开过程中不会因为临时对象生命周期问题产生悬垂指针。宏参数说明参数输入/输出说明entityName输入算子名称或 aclnn 接口名称支持const char*或std::stringparamName输入出错的参数名称支持const char*或std::stringincorrectSize输入实际形状大小通常为总元素数或形状字符串支持const char*或std::stringreason输入错误原因描述支持const char*或std::string宏无返回值调用后通常配合return ge::GRAPH_FAILED;终止算子的形状推导或 tiling 流程。四、仓库中的真实调用范例4.1 官方文档示例ResizeLinear 输出形状校验OP_LOGE_FOR_INVALID_SHAPESIZE_WITH_REASON 接口文档 给出了关键代码示例// 预期输出: Parameter y of ResizeLinear has incorrect shape size [144,144,1]. // Reason: The linear-dimension of output y must be equal to value (256) of input parameter size. if (yShape.GetShapeSize() ! expectedSize) { OP_LOGE_FOR_INVALID_SHAPESIZE_WITH_REASON(ResizeLinear, y, Ops::Base::ToString(yShape), The linear-dimension of output y must be equal to value (256) of input parameter size.); return ge::GRAPH_FAILED; }这段示例清晰展示了 EZ0015 的完整使用范式用yShape.GetShapeSize()获取输出张量当前的总元素数与期望值expectedSize比较不满足约束时调用OP_LOGE_FOR_INVALID_SHAPESIZE_WITH_REASON上报incorrectSize参数传入Ops::Base::ToString(yShape)将形状格式化为[144,144,1]这样的可读字符串上报后返回ge::GRAPH_FAILED结束流程阻止非法形状继续参与计算。这也解释了文档示例日志中第三个占位符显示为[144,144,1]而非纯数值的原因——开发者选择将整个形状向量序列化后传入。4.2 仓库源码实例Reduce 算子 axes 合法性校验在 src/op_common/atvoss/reduce/reduce_tiling.cpp 的ReduceOpTiling::AxesCheck中存在一个真实的 EZ0015 上报场景// check axes value range in [-dimNum, dimNum) ge::graphStatus ReduceOpTiling::AxesCheck(const std::vectorint64_t shape, const std::vectorint64_t axes) { int64_t shapeSize static_castint64_t(shape.size()); int64_t axesSize static_castint64_t(axes.size()); OP_CHECK_IF( (axesSize shapeSize), OP_LOGE_FOR_INVALID_SHAPESIZE_WITH_REASON(context_-GetNodeName(), axes, std::to_string(axesSize).c_str(), axes size over x shape size is illegal), return ge::GRAPH_FAILED); ... }此处校验的是 Reduce 算子axes参数的**个数即元素数**不能超过输入张量x的维度数。当axes的元素个数大于x的维度数时即上报Parameter axes of Reduce算子名 has incorrect shape size axesSize. Reason: axes size over x shape size is illegal.从该实例可以看到几个工程细节incorrectSize在这里是std::to_string(axesSize)生成的纯数值字符串说明第三个占位符既可以传形状字符串如[144,144,1]也可以传标量数值entityName使用context_-GetNodeName()动态获取当前算子节点名而非硬编码字符串在多算子场景下定位更准确同一宏在 pkg_inc/op_common/atvoss/reduce/reduce_tiling.h 的头文件内联实现中也有对应使用说明该宏可同时用于 tiling 的头文件模板实现与源文件实现。五、常见触发场景与排查步骤5.1 常见触发场景结合错误码语义与仓库实现EZ0015 通常出现在以下场景输出形状与输入参数强约束不符如 ResizeLinear 中输出线性维度必须严格等于size参数指定值axes / 索引类参数数量越界如 Reduce 的axes元素个数超过输入维度数形状大小总元素数不满足算子约束如某些算子要求某维大小必须与另一张量对齐、必须是特定值的整数倍或完全相等广播broadcast场景下张量形状大小不匹配参与广播的输入形状大小违反算子的广播规则。5.2 系统化排查步骤读ReasonEZ0015 报错日志的Reason字段直接说明了约束条件与实际值的差异这是最快的定位入口核对参数名与算子名确认报错对象paramName属于哪个输入/输出参数、entityName对应哪个算子或 aclnn 接口回到调用代码中检查该参数的 shape 来源对比期望值与实际值将日志中的incorrect_size或形状与算子规格文档、上游框架传入的 shape 做比对确认是上游传参错误还是算子自身 shape 推导逻辑缺陷按错误码族细分如果报错描述的是维度个数问题而非总元素数/维度乘积问题应转向 EZ0011EZ0013 系列若为格式、dtype 问题则对应 EZ0017/EZ0018、EZ0019EZ0021 系列避免在错误码族内误排查修正后复测调整输入 shape 或修正算子 shape 推导逻辑后重新执行确认日志不再触发且算子形状校验分支正常通过。5.3 算子开发者的修复与上报建议上报时机仅在形状校验确实失败的if分支内调用宏并在上报后return ge::GRAPH_FAILED;避免非法 shape 继续流入后续 tiling/计算阶段Reason要可读可查原因描述应包含期望值或约束关系如must be equal to value (256) of input parameter size便于上层用户与开发者一眼定位根因entityName优先动态获取参考 reduce_tiling.cpp 使用context_-GetNodeName()而非硬编码提升多算子场景下的可定位性incorrectSize的展示形式展示整个形状如Ops::Base::ToString(yShape)得到[144,144,1]比单纯元素数更直观适合维度信息重要的场景仅关注个数时也可传std::to_string(...)的标量字符串。六、错误码文档导航本错误码完整说明文档英文docs/en/error_code/Operator-Errors/EZ0015-Invalid_Argument_Tensor_Shape_Size.md本错误码完整说明文档中文docs/zh/error_code/Operator-Errors/EZ0015-Invalid_Argument_Tensor_Shape_Size.md算子错误码总览docs/en/error_code/Operator-Errors/Operator-Errors.md上报宏接口文档docs/zh/api/op_common/log/OP_LOGE_FOR_INVALID_SHAPESIZE_WITH_REASON.md宏定义源码include/op_common/log/log.h错误码注册表src/op_common/log/log.cpp真实调用示例src/op_common/atvoss/reduce/reduce_tiling.cpp、pkg_inc/op_common/atvoss/reduce/reduce_tiling.h七、总结EZ0015 是 CANN opbase 算子库中用于上报单个 Tensor 形状大小校验失败并附带原因的标准错误码。掌握其报错格式中四个占位符的语义、理解OP_LOGE_FOR_INVALID_SHAPESIZE_WITH_REASON宏的日志 错误码双通道上报机制并参照 ResizeLinear、Reduce 等真实算子的调用范式即可在算子开发与故障排查中快速定位 shape size 类问题先读Reason明确约束再核对参数名与期望值最终修正 shape 或推导逻辑即可解决。【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考