ONNX 维度标注（Dimension Denotation）机制解析：为张量轴赋予语义的类型检查方案

人工智能深度学习机器学习【免费下载链接】onnxOpen standard for machine learning interoperability项目地址https://gitcode.com/gh_mirrors/onn/onnx点击查看免费下载维度标注Dimension Denotation是 ONNX 中一套实验性的机制用于为张量的每一个轴axis附加语义描述进而为模型提供基于语义的类型检查能力。本文以 docs/DimensionDenotation.md 为主体结合 ONNX 的 proto 定义、Python 辅助 API 与算子注册源码完整讲解其动机、七种标准标注的定义、传播与验证流程以及在模型构建中的实际用法。为什么需要维度标注一个 NCHW 布局错误的典型案例在当前的神经网络描述范式中张量轴通常只携带长度信息shape而不携带含义信息。考虑如下线性神经网络片段假设模型输入为 NCHW 格式input_in_NCHW - Transpose(input, perm[0, 2, 1, 3]) - AveragePool(input, ...)该网络将 NCHW 输入转置成了怪异的 NHCW 格式随后却将其送入一个假定输入为 NCHW 的空间池化算子。这显然是一个错误——用户误以为 Transpose 不会破坏 NCHW 布局但实际上perm[0, 2, 1, 3]将通道维C与高度维H互换了位置。然而现有基础设施不会向用户报告任何错误Transpose 和 AveragePool 都只检查张量秩与元素类型不关心第 1 维是通道还是空间特征。对依赖类型检查作为程序正确性保证的开发者而言这种真空令人不安。维度标注机制正是为了填补这一空白而提出的通过给每个轴打上语义标签使 ONNX 能够检测并报告此类布局错误。七种标准维度标注Denotation Definition维度标注的定义遵循三条原则足够细粒度以消除潜在陷阱必须区分通道维与空间特征维才能保证 AveragePool 这类算子执行正确见上文动机示例足够粗粒度以减轻用户心智负担例如池化、卷积等操作通常不区分宽W与高H因此将所有空间维度统一归纳为特征维度模型无关作为第 2 条的推论RNN 中特征维与 CNN 中空间维的语义几乎不可区分因此允许用户和开发者将二者都描述为特征维度。基于以上原则ONNX 在首个提案中定义了如下七种标准标注标注语义对应关系DATA_BATCH训练数据的 batch 维度对应NCHW记法中的NDATA_CHANNEL训练数据的通道维度对应NCHW记法中的CDATA_TIME时间维度时间序列数据的时序轴DATA_FEATURE特征维度对应H、W维或 RNN 中的特征维FILTER_IN_CHANNEL卷积核输入通道维度其大小与输入特征图的通道维相同FILTER_OUT_CHANNEL卷积核输出通道维度其大小与输出特征图的通道维相同FILTER_SPATIAL卷积核空间维度卷积核的 kH、kW 等空间轴这些标准标注在源码中被定义为字符串常量见 onnx/common/constants.h// For dimension denotation. constexpr const char* DATA_BATCH DATA_BATCH; constexpr const char* DATA_CHANNEL DATA_CHANNEL; constexpr const char* DATA_TIME DATA_TIME; constexpr const char* DATA_FEATURE DATA_FEATURE; constexpr const char* FILTER_IN_CHANNEL FILTER_IN_CHANNEL; constexpr const char* FILTER_OUT_CHANNEL FILTER_OUT_CHANNEL; constexpr const char* FILTER_SPATIAL FILTER_SPATIAL;值得注意的设计细节是这些标注采用与NCHW等布局记法解耦的命名方式标注表达的是语义而不是物理位置这正是实现模型无关性的关键。维度标注在模型文件中的落点维度标注存储在每个维度Dimension之上。在 ONNX 的 protobuf 定义中TensorShapeProto.Dimension除了dim_value具体数值和dim_param符号变量之外还包含一个可选的字符串字段denotation见 onnx/onnx-ml.protomessage TensorShapeProto { message Dimension { oneof value { int64 dim_value 1; string dim_param 2; // namespace Shape }; // Standard denotation can optionally be used to denote tensor // dimensions with standard semantic descriptions to ensure // that operations are applied to the correct axis of a tensor. // Refer to docs/DimensionDenotation.md#denotation-definition // for pre-defined dimension denotations. optional string denotation 3; }; repeated Dimension dim 1; }同一份onnx-ml.proto中还定义了类型标注Type Denotation字段TypeProto.denotationfield 6用于描述整个输入/输出是什么如IMAGE、TEXT与维度标注形成互补类型标注回答这是什么维度标注回答每个轴的含义是什么。两者常配合使用详见 docs/TypeDenotation.md。标注传播Denotation Propagation当某个算子对输入张量执行置换permute、销毁或创建维度时输出的维度标注需要根据输入标注重新推断这一过程称为标注传播。其核心思想是为每个涉及维度变换的算子实现定制化的、与操作相关的推断函数根据输入张量的维度标注推导输出张量的维度标注。以 Transpose 算子为例输出维度标注的推断伪代码可直接表示为输入维度标注的映射函数for i, j in enumerate(perm): out_dim_denotaion[i] in_dim_denotation[j]即输出第i个轴的标注等于输入第perm[i]个轴的标注。这样[DATA_BATCH, DATA_CHANNEL, DATA_FEATURE, DATA_FEATURE]的输入在perm[0, 2, 1, 3]转置后会得到[DATA_BATCH, DATA_FEATURE, DATA_CHANNEL, DATA_FEATURE]标注忠实跟随轴的运动轨迹为后续的验证步骤保留语义线索。标注验证Denotation Verification当某个算子期望输入以特定格式到达时需要对输入标注进行校验这一过程称为标注验证。若期望标注与实际标注不匹配则应报告错误。以 AveragePool 为例该算子在 2D 情况下期望输入标注为[DATA_BATCH, DATA_CHANNEL, DATA_FEATURE, DATA_FEATURE]。结合上文动机示例转置后的张量标注变为[DATA_BATCH, DATA_FEATURE, DATA_CHANNEL, DATA_FEATURE]验证阶段即可据此判定通道维被放到了特征维的位置从而向用户报告错误——这正是原始 NCHW 布局错误示例中缺失的能力。这种期望标注在算子 schema 文档中亦有明文约定。在 onnx/defs/nn/defs.cc 中AveragePool 的输入X文档写道Optionally, if dimension denotation is in effect, the operation expects the input data tensor to arrive with the dimension denotation of[DATA_BATCH, DATA_CHANNEL, DATA_FEATURE, DATA_FEATURE ...].卷积算子Conv的 schema 则同时约定了输入与权重的期望标注见 onnx/defs/nn/defs.cc输入X期望标注[DATA_BATCH, DATA_CHANNEL, DATA_FEATURE, DATA_FEATURE ...]权重W期望标注[FILTER_OUT_CHANNEL, FILTER_IN_CHANNEL, FILTER_SPATIAL, FILTER_SPATIAL ...]。这与FILTER_IN_CHANNEL、FILTER_OUT_CHANNEL的定义与输入/输出特征图通道维大小相同形成闭环当标注生效时卷积不仅检查形状数值关系如X.shape[1] W.shape[1] * group还可以在语义层面确认通道对通道、空间对空间的轴对齐。从源码结构看标注传播与标注验证机制目前仍处于实验阶段——它们在算子 schema 中体现为可选生效if dimension denotation is in effect的约定尚未在全部算子中得到强制实施docs/DimensionDenotation.md亦将其定位为实验性尝试experimental attempt。在 Python 中为模型添加维度标注ONNX 的 Python API 提供了便捷的构建辅助函数来设置维度标注。核心入口是 onnx/helper.py 中的make_tensor_type_proto它接受可选的shape_denotation参数def make_tensor_type_proto( elem_type: int, shape: Sequence[str | int | None] | None, shape_denotation: list[str] | None None, ) - TypeProto:该函数的约束与行为shape_denotation与shape必须等长否则抛出ValueError(Invalid shape_denotation. Must be of the same length as shape.)见 onnx/helper.py在构建每个dim时若提供了标注则将dim.denotation shape_denotation[i]逐一写入见 onnx/helper.py。一个典型的 NCHW 图像输入声明如下import onnx from onnx import helper, TensorProto # shape 与 shape_denotation 一一对应 tensor_type helper.make_tensor_type_proto( elem_typeTensorProto.FLOAT, shape[1, 3, 224, 224], # N, C, H, W shape_denotation[ DATA_BATCH, # N DATA_CHANNEL, # C DATA_FEATURE, # H空间特征维 DATA_FEATURE, # W空间特征维 ], ) value_info helper.make_value_info( namedata_0, type_prototensor_type, doc_stringNCHW image input, )make_value_info、make_tensor_value_info等上层辅助函数均透传shape_denotation参数见 onnx/helper.py因此在实际建模中只需在声明输入输出时附带标注列表即可将语义信息写入ValueInfoProto的形状中。若需要为输入输出声明更完整的语义例如声明这是一个 BGR 8 位、0-255 像素范围、sRGB 色彩空间的图像应进一步结合类型标注Type Denotation与模型元数据metadata_props详见 docs/TypeDenotation.md 与 docs/MetadataProps.md。小结与展望维度标注为 ONNX 模型提供了一条通往轴级类型检查的路径定义层七种标准标注DATA_BATCH、DATA_CHANNEL、DATA_TIME、DATA_FEATURE、FILTER_IN_CHANNEL、FILTER_OUT_CHANNEL、FILTER_SPATIAL在 onnx/common/constants.h 中统一定义并落位到TensorShapeProto.Dimension.denotation字段传播层对 Transpose 等维度变换算子按out_dim_denotation[i] in_dim_denotation[perm[i]]的规则传递标注验证层对 AveragePool、Conv 等对轴语义有要求的算子按其 schema 中声明的期望标注如[DATA_BATCH, DATA_CHANNEL, DATA_FEATURE, DATA_FEATURE]校验输入不匹配即报错。作为实验性机制维度标注目前更多体现为一种可选约束但其价值在于它让 ONNX 生态中的工具链转换器、推理引擎、模型检查器第一次有了在语义层面发现轴被放错位置这类错误的可能性。配合 docs/TypeDenotation.md 中描述的IMAGE、TEXT等类型标注模型作者可以为输入输出提供是什么 每个轴是什么的完整描述让模型消费者无需猜测即可正确地喂入数据。赞分享人工智能深度学习机器学习【免费下载链接】onnxOpen standard for machine learning interoperability项目地址https://gitcode.com/gh_mirrors/onn/onnx点击查看免费下载相关推荐ONNX 类型标注Type Denotation完全指南用语义类型与元数据描述模型输入输出ONNX 类型标注Type Denotation完全指南用语义类型与元数据描述模型输入输出 导读 ONNXOpen Neural Network Exc人工智能深度学习机器学习如何在5分钟内掌握Mermaid在线图表编辑器面向初学者的终极指南如何在5分钟内掌握Mermaid在线图表编辑器面向初学者的终极指南 你是否厌倦了复杂的图表制作工具想要快速创建流程图、时序图或甘特图却不想学习复杂的软件前端开发者工具数据可视化CANN PyPTO Tensor 类型标注完全指南GM 多维张量声明、动态/静态维度与别名语义CANN PyPTO Tensor 类型标注完全指南GM 多维张量声明、动态/静态维度与别名语义 导读 pypto_pro.language.Tensor 是人工智能编译器模型编译高性能计算深度学习CANN上一篇手把手教你训练R2CNN_Faster-RCNN_Tensorflow单GPU到多GPU分布式训练完整实战下一篇Ultimate Vocal Remover 完整上手指南10 分钟免费分离人声与伴奏创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考