3. 算子定义规范：OpSet版本机制、算子注册与查找、输入输出张量类型、属性定义规则
好，咱们今天聊聊算子定义规范。说实话，这块内容是ONNX模型部署里最容易踩坑的地方。我见过太多人，模型导出来跑不通，最后发现是算子版本没对齐。你想想看，一个模型里几十个算子，版本差一个数字，整个推理链就断了。
3.1 OpSet版本机制：为什么版本号这么重要？
ONNX的OpSet，说白了就是算子版本的集合。每个版本号对应一套固定的算子定义。比如OpSet 11和OpSet 12，同一个算子可能行为完全不同。
我记得有一次，客户说模型在ONNX Runtime上跑不通。我排查了半天，发现他用的是OpSet 10的Resize算子，但推理引擎只支持OpSet 11以上的版本。嗯，这里要注意：版本不兼容是部署失败的头号杀手。
核心原则：导出模型时，尽量使用较新的OpSet版本。但别太新——要确保你的推理引擎支持。
版本机制其实很简单：
- 每个OpSet版本会新增或修改算子
- 旧版本算子不会删除，但可能被标记为deprecated
- 算子行为变更时，会通过版本号区分
举个例子，Resize算子在OpSet 11之前和之后，坐标变换方式完全不同。我之前有个项目，用PyTorch导出时默认用了OpSet 9，结果在TensorRT上推理，图像缩放全错了。后来改成OpSet 11才解决。
3.2 算子注册与查找：ONNX怎么找到你的算子？
每个ONNX算子都有一个唯一的名称，比如"Conv"、"Relu"、"Gemm"。注册机制就是把这些算子名和对应的实现函数绑定起来。
我个人习惯把算子注册想象成一个字典：
// 伪代码，理解即可
OperatorRegistry["Conv"] = ConvImpl;
OperatorRegistry["Relu"] = ReluImpl;查找过程也很直接：
- 解析模型中的算子节点，拿到算子名
- 在注册表中查找对应的实现
- 如果找不到，报错"Unsupported operator"
避坑指南：我曾经遇到一个情况，模型里用了自定义算子"MyConv"，但推理引擎里没注册。结果整个模型都跑不了。解决办法是：要么在推理引擎里注册这个算子，要么导出时用标准算子替代。
这里有个小技巧：如果你用ONNX Runtime，可以通过OrtSessionOptions注册自定义算子。但说实话，我建议尽量用标准算子，省心。
3.3 输入输出张量类型：类型不匹配就崩
每个算子都定义了输入输出的张量类型。比如Conv算子的输入必须是4D张量，数据类型可以是float32或float16。
常见的张量类型包括：
| 类型 | 描述 | 常见场景 |
|---|---|---|
| tensor(float) | 32位浮点 | 大多数模型 |
| tensor(float16) | 16位浮点 | GPU加速 |
| tensor(int64) | 64位整数 | 索引、形状 |
| tensor(bool) | 布尔型 | 条件判断 |
你想想看，如果Conv算子的输入是int32，但定义要求float32，推理引擎会直接报错。我遇到过最离谱的一次，是模型里有个Cast算子没加，导致类型不匹配，排查了整整一天。
个人经验：导出模型后，先用onnx.checker.check_model()检查一遍。这个函数会帮你验证所有算子的输入输出类型是否匹配。我每次导出都会跑一遍，省了很多麻烦。
3.4 属性定义规则：算子的"参数"怎么传？
属性是算子的静态参数，在模型构建时就确定好了，不会在推理时改变。比如Conv算子的kernel_shape、strides、pads都是属性。
属性有几种类型：
- INTS：整数列表，比如kernel_shape=[3, 3]
- FLOATS：浮点数列表，比如pads=[1, 1, 1, 1]
- STRING：字符串，比如auto_pad="SAME_UPPER"
- TENSOR：张量，比如权重数据
嗯，这里要注意：属性是静态的，不能动态改变。如果你需要在推理时改变参数，那应该用输入张量，而不是属性。
举个例子，Conv算子的权重是属性（TENSOR类型），而输入图像是输入张量。权重在模型构建时就固定了，但输入图像每次推理都可以不同。
关键点：属性定义必须严格遵循ONNX规范。少一个属性、多一个属性，或者类型不对，都会导致算子无法注册。
我曾经犯过一个低级错误：给Conv算子加了一个自定义属性"my_param"，结果ONNX Runtime直接报错说"Unknown attribute"。后来我才知道，标准算子只能有规范里定义的属性，不能随便加。
3.5 实战建议：如何避免算子兼容性问题？
说了这么多，总结几条我自己的经验：
- 版本对齐：导出时用的OpSet版本，必须和推理引擎支持的版本一致。查文档！
- 类型检查：导出后跑一遍
onnx.checker，能发现大部分类型问题。 - 属性合规：别自作聪明加自定义属性，除非你注册了对应的算子实现。
- 测试先行：写个简单的测试脚本，用ONNX Runtime跑一遍模型，确认没问题再部署。
说实话，算子兼容性排查是个细致活。但只要掌握了OpSet版本机制、注册查找流程、类型和属性规则，大部分问题都能快速定位。我刚开始做ONNX部署时也经常翻车，但踩的坑多了，自然就熟了。
好，这一章就到这里。下一章咱们聊聊更具体的算子实现细节，到时候我会分享一些实际项目中的调试技巧。