人工智能深度学习机器学习【免费下载链接】onnxOpen standard for machine learning interoperability项目地址https://gitcode.com/gh_mirrors/onn/onnx点击查看免费下载本文围绕 ONNX 仓库中的 docs/MetadataProps.md 展开系统讲解 ONNX 为模型输入/输出张量设计的实验性元数据机制如何在模型层面声明张量的语义类别当前仅定义Image图像类别以及Image.BitmapPixelFormat、Image.ColorSpaceGamma、Image.NominalPixelRange三个键的完整取值与含义。读完本文你将掌握在 ONNX 模型文件中正确标注图像输入/输出格式的完整方法能够与 Type Denotation、Dimension Denotation 配合让模型消费者推理引擎、工具链无需猜测即可完成正确的预处理featurization与后处理。一、背景与动机为什么模型需要输入输出格式元数据ONNX 的核心价值是模型互操作性模型作者导出模型模型消费者各类推理框架、转换工具、部署平台加载并执行它。但一个现实问题是模型只声明了张量的形状与数据类型如float[1,3,244,244]却没有声明这些数据的语义格式。以图像输入为例同样的一个float[1,3,224,224]张量在不同模型背后可能是完全不同的约定通道顺序是 RGB 还是 BGR像素位深是 8 bit 还是其他像素值是[0, 255]整数范围还是归一化后的[0, 1]或[-1, 1]颜色空间是 sRGBgamma ≈ 2.2还是 Lineargamma 1.0。这些选项在模型训练阶段就已经被固化进模型内部——模型是在某一组特定预处理约定下训练出来的推理时也必须使用相同的约定否则输出会失真甚至完全错误。仅凭形状和数据类型模型消费者无从得知该用哪一组约定。正如 docs/MetadataProps.md 所述该机制的动机是让模型作者向模型消费者传达足够的信息使其能够自行完成推理前的特征化featurization处理并理解推理输出的格式。这样消费者就能知道如何把一个正确的输入喂给模型也能在拿到输出后知道它的格式含义。需要强调的是本文介绍的元数据是在 docs/IR.md#optional-metadata 定义的核心标准可选元数据如model_author、model_license基础之上额外增加的一组实验性experimental元数据专门用于提供模型输入和输出的语义信息。二、机制设计元数据 Denotation 的组合方案这套图像语义描述机制不是孤立存在的它由三部分协同组成详见 docs/TypeDenotation.mdType Denotation类型标注标注张量整体的语义类型如TENSOR、IMAGE、AUDIO、TEXT。它存储在TypeProto消息上见 docs/TypeDenotation.md。Dimension Denotation维度标注标注张量每个轴的语义如DATA_BATCH对应N、DATA_CHANNEL对应C、DATA_FEATURE对应H、W用于描述NCHW等布局见 docs/DimensionDenotation.md。Model Metadata模型元数据即本文主题在ModelProto.metadata_props中存放键值对声明该类别张量所采用的具体编码约定。三者的分工可以这样理解Type Denotation 回答这是什么图像Dimension Denotation 回答维度怎么排NCHWModel Metadata 回答像素怎么编码BGR、8bit、0-255、sRGB。在 Type Denotation 的标准定义中docs/TypeDenotation.mdIMAGE类型明确指引使用者可以使用 dimension denotation 了解图像的布局也可以使用可选的模型 metadata_props——这正是 MetadataProps 机制的挂载点。2.1 全局作用域类别级而非张量级一个关键设计约束是任何通过该机制提供的元数据都是全局的适用于模型中所有带有对应 denotation 的类型。即Image.*系列键一旦在模型级metadata_props中声明就作用于模型中所有denotation IMAGE的张量输入和输出。因此不要在同一模型中混用两种不同的图像编码约定——元数据机制本身不支持按张量区分。2.2 大小写不敏感Image.*系列的键key与值value均不区分大小写。这降低了模型作者与消费者之间因大小写差异导致的兼容性问题但也意味着同一语义不应以不同大小写重复声明。三、Image 类别完整元数据定义Image是第一个被定义的类别目前也是唯一一个。对于模型中每一个通过 Type Denotation 声明为IMAGE的张量模型作者SHOULD应当提供以下元数据来帮助模型消费者。目前共定义 3 个键全部为字符串值。3.1Image.BitmapPixelFormat像素数据格式指定像素数据的格式。每个枚举值定义了通道顺序与位深。取值说明Gray8单通道图像像素数据为 8 bppbits per pixel灰度Rgb83 通道图像通道顺序为 RGB像素数据 8 bpp无 alphaBgr83 通道图像通道顺序为 BGR像素数据 8 bpp无 alphaRgba84 通道图像通道顺序为 RGBA像素数据 8 bppStraight alpha直通 alphaBgra84 通道图像通道顺序为 BGRA像素数据 8 bppStraight alpha直通 alpha要点该键同时编码了通道顺序如 RGB 与 BGR 是不同取值与位深当前所有枚举均为 8 bpp是否带 alpha 也由该键区分3 通道取值无 alpha4 通道取值带 straight alpha注意Rgb8与Bgr8的区分对许多以 BGR 为内部约定的框架如 OpenCV 惯例至关重要二者不可混用。3.2Image.ColorSpaceGamma颜色空间 / Gamma指定使用的 gamma 颜色空间。取值说明Linear线性颜色空间gamma 1.0SRGBsRGB 颜色空间gamma 2.2要点颜色空间决定了像素值的物理含义sRGB 中的数值经过了 gamma 编码线性空间中则是原始辐射量。对依赖颜色感知的任务如图像分类、风格迁移预处理时是否做 sRGB→Linear 的 gamma 解码必须与训练时一致只有两个取值且语义明确gamma 1.0 与 2.2。3.3Image.NominalPixelRange像素值范围指定像素值的存储范围。取值说明NominalRange_0_255对于 8 bpp 样本像素值范围为[0...255]Normalized_0_1像素数据归一化存储范围为[0...1]Normalized_1_1像素数据归一化存储范围为[-1...1]NominalRange_16_235对于 8 bpp 样本像素值范围为[16...235]视频/广播标准中的有限范围要点前两类是深度学习中最常见的整数域[0, 255]与浮点归一化域[0, 1]、[-1, 1]NominalRange_16_235对应视频领域的 limited rangestudio swing常见于 YUV/HD 视频处理链路一般图像分类场景较少使用该键与Image.BitmapPixelFormat的位深信息共同决定原始数值 ↔ 物理亮度的换算关系。3.4 组合示例一个典型的 SqueezeNet 图像输入将三个键组合使用即可完整描述一个图像输入。以 docs/TypeDenotation.md 中的 SqueezeNet 示例为例其输入为float[1,3,244,244]完整标注方案为# ModelProto.metadata_props 中声明 3 条元数据 Image.BitmapPixelFormat Bgr8 # BGR 通道顺序、8 bit、无 alpha Image.ColorSpaceGamma SRGB # sRGB 颜色空间gamma 2.2 Image.NominalPixelRange NominalRange_0_255 # 像素值范围 [0, 255]配合同一ValueInfoProto上的 Type Denotation 与 Dimension Denotation# ValueInfoProto data_0 TypeProto.denotation IMAGE # TensorShapeProto 各维度的 denotation Dimension[0].denotation DATA_BATCH # N Dimension[1].denotation DATA_CHANNEL # C Dimension[2].denotation DATA_FEATURE # H Dimension[3].denotation DATA_FEATURE # W至此模型文件中蕴含了让消费者正确喂图所需的全部信息这是一个NCHW 布局、BGR 通道顺序、8 bit、值域 [0,255]、sRGB 颜色空间的彩色图像。四、在 ONNX 中的底层实现与 API 支持4.1 存储载体ModelProto.metadata_props模型级元数据存储在ModelProto.metadata_props字段中。在 proto 定义中见 onnx/onnx-ml.protometadata_props是repeated StringStringEntryProto类型而StringStringEntryProto是一个简单的键值对消息onnx/onnx-ml.proto#L545-L548message StringStringEntryProto { optional string key 1; optional string value 2; };在 docs/IR.md 的模型属性表中metadata_props的类型被描述为mapstring,string并注明键应保持互异keys should be distinct。4.2 校验器对 metadata_props 的约束ONNX 官方校验器checker会检查元数据键的唯一性。在 onnx/checker.cc#L1307-L1315 中if (model.metadata_props_size() 1) { std::unordered_setstd::string keys; for (const StringStringEntryProto entry : model.metadata_props()) { auto i keys.insert(entry.key()); if (!i.second) { fail_check(Your model has duplicate keys in metadata_props.); } } }即同一模型内不允许出现重复的metadata_props键重复时校验直接失败。需要说明的是从源码看校验器仅约束键的唯一性并不对Image.*键的取值做枚举合法性校验——枚举值的语义约定由本文档规范约束工具/消费者按文档解释。4.3 Python APIset_metadata_props与make_tensor_value_info在 Python 侧onnx.helper提供了便捷 APIonnx/helper.py#L343-L358 的set_metadata_props(proto, dict_value)接受ModelProto、GraphProto、FunctionProto、NodeProto、TensorProto、ValueInfoProto等对象先用字典整体替换其metadata_props字段先清空再逐个追加键值对。其用法为import onnx from onnx import helper model helper.make_model(graph) helper.set_metadata_props(model, { Image.BitmapPixelFormat: Bgr8, Image.ColorSpaceGamma: SRGB, Image.NominalPixelRange: NominalRange_0_255, })onnx/helper.py#L841-L856 的make_tensor_value_info(name, elem_type, shape, doc_string, shape_denotationNone)用于构造输入/输出的ValueInfoProto其中shape_denotation参数列表形式长度与shape一致正是用来填充各维度的 Dimension Denotation如[DATA_BATCH, DATA_CHANNEL, DATA_FEATURE, DATA_FEATURE]。Type Denotationdenotation字段与 Dimension Denotationdim[i].denotation字段在 proto 中均以字符串形式存储见 onnx/onnx-ml.proto#L848、onnx/onnx-ml.proto#L940。4.4 文本格式的解析与打印ONNX 的文本格式ONNX text format解析器与打印机也对metadata_props提供支持解析器支持metadata_props关键字onnx/defs/parser.cc#L1071 与 onnx/defs/parser.h#L162打印器会在模型包含元数据时输出键值对onnx/defs/printer.cc#L541-L542因此你可以在 ONNX 文本格式的模型描述中直接书写这些元数据。4.5 与其他消息类型的通用性值得注意metadata_props字段不仅存在于ModelProto还存在于GraphProto、FunctionProto、NodeProto、TensorProto、ValueInfoProto等多个消息上见 onnx/onnx-ml.proto 中多处repeated StringStringEntryProto metadata_props声明IR version 10 起这些类型均可用。不过本文档定义的Image.*语义是模型级ModelProto全局声明作用于所有IMAGEdenotation 张量——请勿将其与各消息上通用的元数据存储能力混淆。五、消费端视角元数据如何被使用从模型消费者的角度看这套元数据的价值体现在两个方向输入方向pre-processing / featurization消费者读入模型后若发现某个输入张量的 Type Denotation 为IMAGE即可继续从模型metadata_props中读取Image.BitmapPixelFormat、Image.ColorSpaceGamma、Image.NominalPixelRange三个键据此将任意来源的图像可能是任意通道顺序、任意值域的原始像素转换为模型期望的格式例如按Bgr8将 RGB 像素重排为 BGR按NominalRange_0_255决定不归一化、或按Normalized_0_1将整数像素除以 255按SRGB/Linear决定是否执行 gamma 解码。输出方向post-processing对于输出张量同样可以根据元数据反推其像素格式正确解释模型输出的含义例如知道某个 4 通道输出是Rgba8直通 alpha。这正是文档所述目标的落地提供足够的元数据使模型消费者能够在运行模型之前自行完成特征化处理并提供兼容的输入或在获取输出后知道其格式是什么。六、使用建议与注意事项综合文档定义与仓库实现给出以下实践建议三步配套使用为图像输入/输出张量同时声明 Type DenotationIMAGE、各维度的 Dimension DenotationDATA_BATCH/DATA_CHANNEL/DATA_FEATURE以及模型级Image.*元数据三者缺一不可共同构成完整的图像语义描述。严格遵循枚举值Image.*三键的值应使用本文档列出的枚举字符串。虽然当前校验器只检查键的唯一性而不校验取值但使用非标准取值无法被规范兼容的消费者正确解释。注意全局作用域由于元数据作用于所有IMAGE张量请保证模型中所有图像输入/输出确实采用同一套编码约定若存在多种约定该机制暂无法在同一模型内表达需要拆分为多个模型或通过其他方式如模型文档补充说明。大小写不敏感但建议统一规范声明键与值大小写不敏感但为了保证可读性与工具兼容性建议统一使用本文档中的标准写法如Bgr8、SRGB。区分两类元数据本文的Image.*属于实验性语义元数据model_author、model_license等属于 docs/IR.md#optional-metadata 定义的标准可选元数据。两者都存放在metadata_props中但用途不同不要混淆。七、小结ONNX 的 MetadataProps 机制为模型作者提供了一种标准化、可机器读取的方式把图像输入/输出到底长什么样这一关键信息写进模型文件本身。通过Image.BitmapPixelFormat、Image.ColorSpaceGamma、Image.NominalPixelRange三个键配合 Type Denotation 与 Dimension Denotation模型消费者可以确定性地完成预处理与后处理无需猜测或依赖训练代码。随着该实验性机制的演进未来还有可能定义Image之外的更多类别如音频、文本相关的编码元数据为跨框架的模型互操作提供更完备的语义基础。进一步阅读docs/TypeDenotation.mdIMAGE等类型标注的完整定义与 SqueezeNet 示例docs/DimensionDenotation.mdDATA_BATCH、DATA_CHANNEL、DATA_FEATURE等维度标注及传播/校验机制docs/IR.md#optional-metadata模型级标准可选元数据model_author、model_licenseonnx/helper.pyset_metadata_props、make_tensor_value_info等 Python APIonnx/checker.cc模型校验中对metadata_props键唯一性的检查赞分享人工智能深度学习机器学习【免费下载链接】onnxOpen standard for machine learning interoperability项目地址https://gitcode.com/gh_mirrors/onn/onnx点击查看免费下载相关推荐ONNX 类型标注Type Denotation完全指南用语义类型与元数据描述模型输入输出ONNX 类型标注Type Denotation完全指南用语义类型与元数据描述模型输入输出 导读 ONNXOpen Neural Network Exc人工智能深度学习机器学习HanLP项目数据格式详解输入输出规范指南HanLP项目数据格式详解输入输出规范指南 前言 HanLP作为一款强大的自然语言处理工具包其数据处理能力在业界广受好评。本文将深入解析HanLP项目中的数人工智能NLP深度学习Core ML模型数据预处理Awesome-CoreML-Models输入输出格式详解Core ML模型数据预处理Awesome CoreML Models输入输出格式详解 想要在iOS应用中成功集成机器学习模型Core ML框架为你提供了完文档教程上一篇推荐项目Lapin - 高性能Rust语言的AMQP客户端库下一篇开源项目Fusion 深度集成指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ONNX 模型输入输出元数据（MetadataProps）规范详解：用 `Image` 类别向模型消费者传递像素格式信息
人工智能深度学习机器学习【免费下载链接】onnxOpen standard for machine learning interoperability项目地址https://gitcode.com/gh_mirrors/onn/onnx点击查看免费下载本文围绕 ONNX 仓库中的 docs/MetadataProps.md 展开系统讲解 ONNX 为模型输入/输出张量设计的实验性元数据机制如何在模型层面声明张量的语义类别当前仅定义Image图像类别以及Image.BitmapPixelFormat、Image.ColorSpaceGamma、Image.NominalPixelRange三个键的完整取值与含义。读完本文你将掌握在 ONNX 模型文件中正确标注图像输入/输出格式的完整方法能够与 Type Denotation、Dimension Denotation 配合让模型消费者推理引擎、工具链无需猜测即可完成正确的预处理featurization与后处理。一、背景与动机为什么模型需要输入输出格式元数据ONNX 的核心价值是模型互操作性模型作者导出模型模型消费者各类推理框架、转换工具、部署平台加载并执行它。但一个现实问题是模型只声明了张量的形状与数据类型如float[1,3,244,244]却没有声明这些数据的语义格式。以图像输入为例同样的一个float[1,3,224,224]张量在不同模型背后可能是完全不同的约定通道顺序是 RGB 还是 BGR像素位深是 8 bit 还是其他像素值是[0, 255]整数范围还是归一化后的[0, 1]或[-1, 1]颜色空间是 sRGBgamma ≈ 2.2还是 Lineargamma 1.0。这些选项在模型训练阶段就已经被固化进模型内部——模型是在某一组特定预处理约定下训练出来的推理时也必须使用相同的约定否则输出会失真甚至完全错误。仅凭形状和数据类型模型消费者无从得知该用哪一组约定。正如 docs/MetadataProps.md 所述该机制的动机是让模型作者向模型消费者传达足够的信息使其能够自行完成推理前的特征化featurization处理并理解推理输出的格式。这样消费者就能知道如何把一个正确的输入喂给模型也能在拿到输出后知道它的格式含义。需要强调的是本文介绍的元数据是在 docs/IR.md#optional-metadata 定义的核心标准可选元数据如model_author、model_license基础之上额外增加的一组实验性experimental元数据专门用于提供模型输入和输出的语义信息。二、机制设计元数据 Denotation 的组合方案这套图像语义描述机制不是孤立存在的它由三部分协同组成详见 docs/TypeDenotation.mdType Denotation类型标注标注张量整体的语义类型如TENSOR、IMAGE、AUDIO、TEXT。它存储在TypeProto消息上见 docs/TypeDenotation.md。Dimension Denotation维度标注标注张量每个轴的语义如DATA_BATCH对应N、DATA_CHANNEL对应C、DATA_FEATURE对应H、W用于描述NCHW等布局见 docs/DimensionDenotation.md。Model Metadata模型元数据即本文主题在ModelProto.metadata_props中存放键值对声明该类别张量所采用的具体编码约定。三者的分工可以这样理解Type Denotation 回答这是什么图像Dimension Denotation 回答维度怎么排NCHWModel Metadata 回答像素怎么编码BGR、8bit、0-255、sRGB。在 Type Denotation 的标准定义中docs/TypeDenotation.mdIMAGE类型明确指引使用者可以使用 dimension denotation 了解图像的布局也可以使用可选的模型 metadata_props——这正是 MetadataProps 机制的挂载点。2.1 全局作用域类别级而非张量级一个关键设计约束是任何通过该机制提供的元数据都是全局的适用于模型中所有带有对应 denotation 的类型。即Image.*系列键一旦在模型级metadata_props中声明就作用于模型中所有denotation IMAGE的张量输入和输出。因此不要在同一模型中混用两种不同的图像编码约定——元数据机制本身不支持按张量区分。2.2 大小写不敏感Image.*系列的键key与值value均不区分大小写。这降低了模型作者与消费者之间因大小写差异导致的兼容性问题但也意味着同一语义不应以不同大小写重复声明。三、Image 类别完整元数据定义Image是第一个被定义的类别目前也是唯一一个。对于模型中每一个通过 Type Denotation 声明为IMAGE的张量模型作者SHOULD应当提供以下元数据来帮助模型消费者。目前共定义 3 个键全部为字符串值。3.1Image.BitmapPixelFormat像素数据格式指定像素数据的格式。每个枚举值定义了通道顺序与位深。取值说明Gray8单通道图像像素数据为 8 bppbits per pixel灰度Rgb83 通道图像通道顺序为 RGB像素数据 8 bpp无 alphaBgr83 通道图像通道顺序为 BGR像素数据 8 bpp无 alphaRgba84 通道图像通道顺序为 RGBA像素数据 8 bppStraight alpha直通 alphaBgra84 通道图像通道顺序为 BGRA像素数据 8 bppStraight alpha直通 alpha要点该键同时编码了通道顺序如 RGB 与 BGR 是不同取值与位深当前所有枚举均为 8 bpp是否带 alpha 也由该键区分3 通道取值无 alpha4 通道取值带 straight alpha注意Rgb8与Bgr8的区分对许多以 BGR 为内部约定的框架如 OpenCV 惯例至关重要二者不可混用。3.2Image.ColorSpaceGamma颜色空间 / Gamma指定使用的 gamma 颜色空间。取值说明Linear线性颜色空间gamma 1.0SRGBsRGB 颜色空间gamma 2.2要点颜色空间决定了像素值的物理含义sRGB 中的数值经过了 gamma 编码线性空间中则是原始辐射量。对依赖颜色感知的任务如图像分类、风格迁移预处理时是否做 sRGB→Linear 的 gamma 解码必须与训练时一致只有两个取值且语义明确gamma 1.0 与 2.2。3.3Image.NominalPixelRange像素值范围指定像素值的存储范围。取值说明NominalRange_0_255对于 8 bpp 样本像素值范围为[0...255]Normalized_0_1像素数据归一化存储范围为[0...1]Normalized_1_1像素数据归一化存储范围为[-1...1]NominalRange_16_235对于 8 bpp 样本像素值范围为[16...235]视频/广播标准中的有限范围要点前两类是深度学习中最常见的整数域[0, 255]与浮点归一化域[0, 1]、[-1, 1]NominalRange_16_235对应视频领域的 limited rangestudio swing常见于 YUV/HD 视频处理链路一般图像分类场景较少使用该键与Image.BitmapPixelFormat的位深信息共同决定原始数值 ↔ 物理亮度的换算关系。3.4 组合示例一个典型的 SqueezeNet 图像输入将三个键组合使用即可完整描述一个图像输入。以 docs/TypeDenotation.md 中的 SqueezeNet 示例为例其输入为float[1,3,244,244]完整标注方案为# ModelProto.metadata_props 中声明 3 条元数据 Image.BitmapPixelFormat Bgr8 # BGR 通道顺序、8 bit、无 alpha Image.ColorSpaceGamma SRGB # sRGB 颜色空间gamma 2.2 Image.NominalPixelRange NominalRange_0_255 # 像素值范围 [0, 255]配合同一ValueInfoProto上的 Type Denotation 与 Dimension Denotation# ValueInfoProto data_0 TypeProto.denotation IMAGE # TensorShapeProto 各维度的 denotation Dimension[0].denotation DATA_BATCH # N Dimension[1].denotation DATA_CHANNEL # C Dimension[2].denotation DATA_FEATURE # H Dimension[3].denotation DATA_FEATURE # W至此模型文件中蕴含了让消费者正确喂图所需的全部信息这是一个NCHW 布局、BGR 通道顺序、8 bit、值域 [0,255]、sRGB 颜色空间的彩色图像。四、在 ONNX 中的底层实现与 API 支持4.1 存储载体ModelProto.metadata_props模型级元数据存储在ModelProto.metadata_props字段中。在 proto 定义中见 onnx/onnx-ml.protometadata_props是repeated StringStringEntryProto类型而StringStringEntryProto是一个简单的键值对消息onnx/onnx-ml.proto#L545-L548message StringStringEntryProto { optional string key 1; optional string value 2; };在 docs/IR.md 的模型属性表中metadata_props的类型被描述为mapstring,string并注明键应保持互异keys should be distinct。4.2 校验器对 metadata_props 的约束ONNX 官方校验器checker会检查元数据键的唯一性。在 onnx/checker.cc#L1307-L1315 中if (model.metadata_props_size() 1) { std::unordered_setstd::string keys; for (const StringStringEntryProto entry : model.metadata_props()) { auto i keys.insert(entry.key()); if (!i.second) { fail_check(Your model has duplicate keys in metadata_props.); } } }即同一模型内不允许出现重复的metadata_props键重复时校验直接失败。需要说明的是从源码看校验器仅约束键的唯一性并不对Image.*键的取值做枚举合法性校验——枚举值的语义约定由本文档规范约束工具/消费者按文档解释。4.3 Python APIset_metadata_props与make_tensor_value_info在 Python 侧onnx.helper提供了便捷 APIonnx/helper.py#L343-L358 的set_metadata_props(proto, dict_value)接受ModelProto、GraphProto、FunctionProto、NodeProto、TensorProto、ValueInfoProto等对象先用字典整体替换其metadata_props字段先清空再逐个追加键值对。其用法为import onnx from onnx import helper model helper.make_model(graph) helper.set_metadata_props(model, { Image.BitmapPixelFormat: Bgr8, Image.ColorSpaceGamma: SRGB, Image.NominalPixelRange: NominalRange_0_255, })onnx/helper.py#L841-L856 的make_tensor_value_info(name, elem_type, shape, doc_string, shape_denotationNone)用于构造输入/输出的ValueInfoProto其中shape_denotation参数列表形式长度与shape一致正是用来填充各维度的 Dimension Denotation如[DATA_BATCH, DATA_CHANNEL, DATA_FEATURE, DATA_FEATURE]。Type Denotationdenotation字段与 Dimension Denotationdim[i].denotation字段在 proto 中均以字符串形式存储见 onnx/onnx-ml.proto#L848、onnx/onnx-ml.proto#L940。4.4 文本格式的解析与打印ONNX 的文本格式ONNX text format解析器与打印机也对metadata_props提供支持解析器支持metadata_props关键字onnx/defs/parser.cc#L1071 与 onnx/defs/parser.h#L162打印器会在模型包含元数据时输出键值对onnx/defs/printer.cc#L541-L542因此你可以在 ONNX 文本格式的模型描述中直接书写这些元数据。4.5 与其他消息类型的通用性值得注意metadata_props字段不仅存在于ModelProto还存在于GraphProto、FunctionProto、NodeProto、TensorProto、ValueInfoProto等多个消息上见 onnx/onnx-ml.proto 中多处repeated StringStringEntryProto metadata_props声明IR version 10 起这些类型均可用。不过本文档定义的Image.*语义是模型级ModelProto全局声明作用于所有IMAGEdenotation 张量——请勿将其与各消息上通用的元数据存储能力混淆。五、消费端视角元数据如何被使用从模型消费者的角度看这套元数据的价值体现在两个方向输入方向pre-processing / featurization消费者读入模型后若发现某个输入张量的 Type Denotation 为IMAGE即可继续从模型metadata_props中读取Image.BitmapPixelFormat、Image.ColorSpaceGamma、Image.NominalPixelRange三个键据此将任意来源的图像可能是任意通道顺序、任意值域的原始像素转换为模型期望的格式例如按Bgr8将 RGB 像素重排为 BGR按NominalRange_0_255决定不归一化、或按Normalized_0_1将整数像素除以 255按SRGB/Linear决定是否执行 gamma 解码。输出方向post-processing对于输出张量同样可以根据元数据反推其像素格式正确解释模型输出的含义例如知道某个 4 通道输出是Rgba8直通 alpha。这正是文档所述目标的落地提供足够的元数据使模型消费者能够在运行模型之前自行完成特征化处理并提供兼容的输入或在获取输出后知道其格式是什么。六、使用建议与注意事项综合文档定义与仓库实现给出以下实践建议三步配套使用为图像输入/输出张量同时声明 Type DenotationIMAGE、各维度的 Dimension DenotationDATA_BATCH/DATA_CHANNEL/DATA_FEATURE以及模型级Image.*元数据三者缺一不可共同构成完整的图像语义描述。严格遵循枚举值Image.*三键的值应使用本文档列出的枚举字符串。虽然当前校验器只检查键的唯一性而不校验取值但使用非标准取值无法被规范兼容的消费者正确解释。注意全局作用域由于元数据作用于所有IMAGE张量请保证模型中所有图像输入/输出确实采用同一套编码约定若存在多种约定该机制暂无法在同一模型内表达需要拆分为多个模型或通过其他方式如模型文档补充说明。大小写不敏感但建议统一规范声明键与值大小写不敏感但为了保证可读性与工具兼容性建议统一使用本文档中的标准写法如Bgr8、SRGB。区分两类元数据本文的Image.*属于实验性语义元数据model_author、model_license等属于 docs/IR.md#optional-metadata 定义的标准可选元数据。两者都存放在metadata_props中但用途不同不要混淆。七、小结ONNX 的 MetadataProps 机制为模型作者提供了一种标准化、可机器读取的方式把图像输入/输出到底长什么样这一关键信息写进模型文件本身。通过Image.BitmapPixelFormat、Image.ColorSpaceGamma、Image.NominalPixelRange三个键配合 Type Denotation 与 Dimension Denotation模型消费者可以确定性地完成预处理与后处理无需猜测或依赖训练代码。随着该实验性机制的演进未来还有可能定义Image之外的更多类别如音频、文本相关的编码元数据为跨框架的模型互操作提供更完备的语义基础。进一步阅读docs/TypeDenotation.mdIMAGE等类型标注的完整定义与 SqueezeNet 示例docs/DimensionDenotation.mdDATA_BATCH、DATA_CHANNEL、DATA_FEATURE等维度标注及传播/校验机制docs/IR.md#optional-metadata模型级标准可选元数据model_author、model_licenseonnx/helper.pyset_metadata_props、make_tensor_value_info等 Python APIonnx/checker.cc模型校验中对metadata_props键唯一性的检查赞分享人工智能深度学习机器学习【免费下载链接】onnxOpen standard for machine learning interoperability项目地址https://gitcode.com/gh_mirrors/onn/onnx点击查看免费下载相关推荐ONNX 类型标注Type Denotation完全指南用语义类型与元数据描述模型输入输出ONNX 类型标注Type Denotation完全指南用语义类型与元数据描述模型输入输出 导读 ONNXOpen Neural Network Exc人工智能深度学习机器学习HanLP项目数据格式详解输入输出规范指南HanLP项目数据格式详解输入输出规范指南 前言 HanLP作为一款强大的自然语言处理工具包其数据处理能力在业界广受好评。本文将深入解析HanLP项目中的数人工智能NLP深度学习Core ML模型数据预处理Awesome-CoreML-Models输入输出格式详解Core ML模型数据预处理Awesome CoreML Models输入输出格式详解 想要在iOS应用中成功集成机器学习模型Core ML框架为你提供了完文档教程上一篇推荐项目Lapin - 高性能Rust语言的AMQP客户端库下一篇开源项目Fusion 深度集成指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 RELATED READING
延伸阅读
更多一线实战笔记与深度复盘，助您持续精进
