前阵子帮人将一个图像分类模型塞进移动端跑模型在服务器上精度明明没问题一换推理框架就开始出各种幺蛾子。Pytorch模型转成ONNX和MNN这件事听起来就是两行命令的事实际推进时要把图的导出机制、算子兼容、精度对齐全走一遍少一步都会在部署阶段暴露出来。这篇文章把我自己踩过的坑和验证过的流程整理出来给准备做端侧推理、又不想啃完官方文档再动手的同学一条能直接照着走的路。事情的本质其实很简单训练用 PyTorch部署用 MNN中间的 ONNX 当翻译官。但翻译官也有能力边界有些话它能翻得很准有些话它会自作聪明提前知道边界在哪后面能省很多时间。1. 部署场景下的选择逻辑为什么是ONNX加MNN1.1 训练框架与推理框架的边界PyTorch 的设计目标是让研究人员能快速把想法跑起来动态图、自动求导、随时打印中间结果这些在训练阶段都是加分项。但到了端侧部署视角完全反过来模型要变成一张固定的计算图参数量要尽量小推理要用上设备的底层加速能力内存占用要低。直接拿 PyTorch 的产物去移动端跑不现实主要原因有两个一是运行时依赖太大光是把 torch 的 Python 层和底层库搬上去就够呛二是动态图的灵活在执行期是有代价的图结构不确定底层调度就没法做激进的算子融合和内存复用。所以才会有一批专门用于推理的框架出现。它们接收一个静态图描述在自己的运行时里做调度优化、算子加速、量化压缩。MNN 是这类框架里我个人用得比较顺手的一个它对多端硬件支持得比较全移动端、嵌入式、甚至纯 CPU 环境都有对应的后端实现。1.2 为什么让ONNX做中间人MNN 官方文档里支持直接转换的格式不止一种但大多数人的路线都是先转 ONNX 再转 MNN这不是绕路而是图省事。PyTorch 的模型本质上是一段 Python 代码逻辑加一堆参数张量框架要把它解析成静态图需要跟踪运行轨迹。如果让 MNN 直接解析 PyTorch 的导出产物要考虑的边界情况太多了自定义算子、Python 控制流、动态 shape任何一个都能让解析器头疼。ONNX 解决了这个问题它把模型统一成标准化的计算图描述节点类型有固定 schema输入输出信息齐全相当于大家约定了一个通用语言。这个过程可以类比成写文档。你手里是一份带复杂格式的原始文件要发给不同环境的人看最稳妥的办法是先导出 PDF而不是让每个接收方都装你的排版软件。ONNX 就是那份 PDF你只需要保证它排版正确后续接手的工具能不能解析那是标准规范的事。1.3 MNN相比ONNX Runtime的优势场景可能有人会问既然都转了 ONNX直接用 ONNX Runtime 推理不就行了分场景。ONNX Runtime 在云端和桌面端确实很强但它对标的不是端侧场景。端侧设备的特点是算力有限、内存有限、对首帧耗时敏感还需要跨平台部署。MNN 这类框架的价值在于它针对不支持 GPU 的环境也做了充分优化CPU 后端有汇编级加速支持低精度推理模型加载和图初始化做了专门的轻量化。我实测在 iPhone 和 Android 手机上跑同一个分割模型用 MNN 的耗时和内存表现都优于直接用 ONNX Runtime 包一层。所以选型结论很直接研究阶段用 PyTorch中间产物统一走 ONNX最终交给 MNN 去落地。整个链路里 ONNX 不会直接参与部署但它的质量直接决定了 MNN 能不能顺利接手。2. 转换前的环境准备与模型边界自检2.1 依赖安装与版本匹配转换流程需要的工具并不多一个干净的环境就能装完。我习惯用虚拟环境隔离避免和日常训练环境互相污染依赖。pip install torch onnx onnxruntime pip install MNNtorch 的版本会影响导出结果同一个模型在不同版本下导出的 ONNX 图可能不完全一样因为内置算子映射表还在持续更新。如果你手上有最终部署的固定环境尽量让导出环境和大版本保持一致至少大版本不要差太多。MNN 装好后通常会自带一个 mnnconvert 的转换命令行工具。不同版本的命令参数略有差别我后面会用当前我这边验证过的写法你拿到手后先跑一下mnnconvert --help确认字段名这个习惯能帮你省掉很多低级报错。2.2 模型输入输出的边界确认导出模型前先把你模型 forward 的真实结构理清楚这一步很多人偷懒直接拿一个大矩阵塞进去后面遇到问题才回头补。有几件事必须确认模型有几个输入每个输入的 shape 和 dtype 是什么。最容易被忽略的是那些不是 tensor 的输入比如推理时才指定的置信度阈值、是否做 NMS 的标志位。这类输入在追踪导出时会被当作常量固定下来如果你的部署逻辑需要动态调整它们得在设计上提前处理比如把它们在模型内部改成默认值。输出有几个是单 tensor、tuple 还是 dict。导出逻辑对输出类型有要求建议统一成 tuple 或者简单 tensor花半小时改一下模型结构比在导出报错时猜原因划算得多。模型内部有没有依赖输入 shape 的循环、条件跳转。这类写法在动态图里很自然但到了静态导出阶段就会出问题因为 ONNX 图是固定结构没法表达“模型会根据运行时数据决定走哪条分支”这种逻辑。2.3 转换前的“干净”基线推理脚本正式导出之前我会先写一个基线脚本加载权重切到 eval 模式关掉梯度用固定随机种子生成一组输入把模型输出保存成 npy 文件。import torch import numpy as np model MyModel() model.load_state_dict(torch.load(best.pt, map_locationcpu)) model.eval() dummy_input torch.randn(1, 3, 224, 224) with torch.no_grad(): reference_output model(dummy_input) np.save(reference_input.npy, dummy_input.numpy()) np.save(reference_output.npy, reference_output.numpy())这里面有两个细节容易被新手混在一起。model.eval() 和 torch.no_grad() 不是一个东西前者管的是 Dropout 和 BatchNorm 的行为后者管的是不构建计算图。导出时两者都要少了哪一个导出的 ONNX 都可能在推理时行为异常。这个基线输出的价值在导出后的每一步对比中都会体现。没有它你转出来的模型跑出了一个结果你都说不清这个结果对不对后面的精度排查也就无从下手。3. PyTorch导出ONNX参数细节与第一个坑3.1 torch.onnx.export的调用姿势PyTorch 官方提供了 torch.onnx.export 作为导出入口基本调用方式如下import torch torch.onnx.export( model, (dummy_input,), model.onnx, input_names[input], output_names[output], opset_version11, dynamic_axesNone, )这里的几个参数都不是摆设。opset_version 决定 ONNX 的算子集版本版本越高支持的算子越新但也取决于下游工具的支持度。我一般优先用 11 或者 12平衡性比较好太低会导致某些 PyTorch 算子找不到映射太高又可能在 MNN 侧遇到版本识别问题。input_names 和 output_names 很多人觉得无所谓但建议养成命名的习惯。这两个名字会出现在 ONNX 图上后面你在 onnxruntime 或者 MNN 里去取输入输出张量时都靠名字定位。不命名的结果就是得到一串看不出含义的代号排查问题时对着图找节点会很痛苦。有个关键认知要提前说清楚torch.onnx.export 用的是 tracing 机制。它不是分析你的源码结构而是真实跑一遍模型把执行过的算子记录下来。这意味着写在条件分支里但是这次没有执行到的代码不会出现在 ONNX 图里。所以 dummy_input 必须尽量贴近真实输入的分支路径否则导出的图会缺一小块。3.2 dynamic_axes到底该不该开dynamic_axes 控制导出的模型是否允许输入维度可变。默认情况下所有维度都是静态的dummy_input 是多少部署时就必须是多少。端侧部署我对动态维度的态度是能不开就不开。原因有两个。第一动态维度会让图里出现很多 shape 相关的计算节点这类算子性能一般都比较差还可能触发 MNN 里一些未覆盖的边界路径。第二动态维度会限制后端做内存预分配和算子融合优化固定 shape 的图能在初始化阶段就把中间张量内存规划好动态图只能运行时再算。如果只是希望 batch 维可变我建议单独开一个维度而不是所有维度全放开。比如图像分类场景输入依赖的只是 batch 和 height、width我会写成dynamic_axes{ input: {0: batch, 2: height, 3: width}, output: {0: batch} }实际测试中开 batch 和 hw 动态导出时最容易在图像尺寸相关的 resize 或 interpolation 节点上报错因为某些算子实现里含有依赖 shape 的循环逻辑tracing 时没法展开。如果你部署时输入固定是 224x224就不要给自己找这个麻烦把 dynamic_axes 设为 None导出最简单。3.3 导出的“及格线”检查导出成功只是万里长征的第一步。模型转出来之后我习惯立刻做三轮检查全部通过才算及格。第一轮是结构检查。用 onnx 自带的 checker 检查模型结构合法性。import onnx model_onnx onnx.load(model.onnx) onnx.checker.check_model(model_onnx)这一轮主要抓低级错误比如节点输入输出对不上、重复的 tensor 名称。报错的话基本可以确定模型导出过程出了问题先回头查模型 forward 里的写法。第二轮是图上人工抽查。把 ONNX 模型用可视化工具打开或者打印出节点列表重点确认几个关键结构的走向输入张量到第一层卷积的路径是否合理输出头是否和你模型的出口对应有没有出现你没预期到的超大常量节点。第三轮是数值对比。用 onnxruntime 跑一遍刚才保存的参考输入和 PyTorch 输出做比对。import onnxruntime as ort import numpy as np sess ort.InferenceSession(model.onnx, providers[CPUExecutionProvider]) ort_output sess.run(None, {input: reference_input})[0] diff np.abs(ort_output - reference_output).max() print(fmax diff: {diff:.2e})fp32 模型在这个环节的误差通常在 1e-5 量级如果你发现差异到了 1e-2 甚至更大不要怀疑浮点误差先回去查导出过程哪里出了问题。常见的原因包括 model.eval() 没调用、某些算子在不同库中实现的精度差异过大、或者是动态维度导致的计算路径不一致。4. ONNX到MNN命令行转换的实操与算子取舍4.1 mnnconvert的实操命令ONNX 检查通过后就可以进入 MNN 侧了。mnnconvert 是 MNN 自带的转换工具我这边验证过的转换命令是这样mnnconvert -f ONNX --modelFile model.onnx --MNNModel model.mnn-f 指定输入格式是 ONNX--modelFile 是输入的 onnx 文件路径--MNNModel 是输出的模型名。不同 MNN 版本可能还有额外的参数建议跑之前看一眼 help。转换过程通常很快几十 MB 的模型也就是一两秒的事。转换成功后MNN 会根据它的图优化策略对结构做调整包括算子融合、常量折叠、去掉一些冗余的 reshape 节点。这一步是框架内部自动完成的我不需要干预但要知道它发生这件事因为转换前后的节点数、体积可能都不一样。有个值得注意的现象如果你的网络里有很多 BatchNorm且处于推理模式MNN 转换器通常会把 Conv 和 BN 融合成一个带复合参数的卷积。效果是两个算子合并成一个参数量不变但前向计算量减少模型文件体积也可能略微变化。这是正常优化不用慌。4.2 看起来简单的算子也可能成为转换拦路虎ONNX 到 MNN 的转换不是百分百畅通的尤其当你模型里用了一些冷门算子。我自己在这条路上遇过几次比较典型的卡点。第一个是高维排序和 topk 类操作。torch.topk 在 ONNX 里能导出但 MNN 对某些维度的 topk 支持并不完整转换时可能直接报错不支持或者转换成功但运行结果不对。我的处理办法是尽量在网络里避免这类算子比如用卷积加 argmax 加 reshape 的组合去替代一部分排序逻辑。第二个是动态索引和布尔 mask。PyTorch 里写x[mask]非常顺手但在静态图里这是一大坑。mask 生成的索引序列是运行时才确定的没法预先把输出 shape 算出来ONNX 导出时要么被固定成常量要么产生支持不全面的非连续索引节点。遇到只能改成固定尺寸的 slice 或者把 mask 逻辑移到前后处理里去写。第三个是 resize 的坐标变换模式。PyTorch 的 F.interpolate 和 MNN 里的 resize 算子在对齐方式上可能有细微差异对坐标取整的方式不同输出就差一点点。分类网络对这一点点不敏感但目标检测框坐标就很容易偏。这个问题的解法是转换前把 MNN 文档里关于 resize 的说明看清楚在 PyTorch 侧匹配对应的 mode。遇到不支持的算子我的处理顺序是先看能不能改写模型结构用基本算子组合替代再看能不能把计算移到前后处理比如某些归一化参数算好再喂进去最后才考虑自定义算子方案因为自定义算子意味着脱离纯静态转换流程部署成本一下就上去了。4.3 转MNN后的第一眼检查转换完成后别急着往下走先用简单脚本把 MNN 模型加载起来跑一次确认图本身没有问题。最简单的做法是生成一个和 ONNX 导出时的 dummy 输入相同位置参数的随机输入让 MNN 跑起来看能否正常执行完输出有没有 NaN 或 Inf。这个冒烟测试不需要很精确的数值对比先保证推理链路能跑通。如果第一步就报错通常可以缩小范围检查是不是某个算子在 MNN 中真的缺失。MNN 有道命令可以列出模型中的算子类型但不同版本输出方式不一样我这边就不死记了你查询一下当前版本的模型工具即可。关键是思路先定位到具体层再决定是改图还是换算子。5. 部署验证与精度对齐最容易翻车的一步5.1 格式正确不等于逻辑正确模型转出来能跑、输出形状也对很多人就以为大功告成了直到实际应用发现结果不对才开始排查。这里要强调的是MNN 推理结果和 PyTorch 推理结果的精度对齐是整个流程里最容易被低估的一步。先把对齐流程跑起来。你需要准备同一份输入数据分别走 PyTorch、ONNX Runtime、MNN 三个通道拿到三份输出然后逐一比较。这个流程听起来简单实际执行时最大的干扰项是数据本身没有保持一致。5.2 对齐三件套同一输入、同一预处理、同一评价口径我把精度对齐的规则总结为三件套缺一个都别谈对比。第一输入必须是同一个。最简单的做法是直接用 npy 文件加载同一份张量数据避免每次重新跑图像预处理带来的随机差异。第二预处理必须完全一致。这一点真的经常出问题我前后处理里把图像归一化参数写错小数点导致肉眼看起来模型完全失灵排查了一天半。图像任务的预处理无非是 resize 方式、通道顺序、归一化系数但每一环都必须和训练时保持一致。PyTorch 侧用的是 BGR 还是 RGBMNN 侧也得一样shape 是 CHW 还是 NHWC 也要确认。第三评价口径要一致。分类模型看 top-1 准确率还是 top-5检测模型看 IoU 还是 mAP必须定义清楚。有时 MNN 输出分数比 PyTorch 低一点点但 argmax 结果没变那对分类任务就等于没影响不必为了小数点后四位焦虑。5.3 误差阈值与常见根因不同 op 的实现精度差异会导致端侧推理结果和 PyTorch 有微小的数值差异这个很正常。fp32 下我见过的情况分类网络总体差异在 1e-6 到 1e-3 之间。如果你发现差异达到 1e-2 量级或者 argmax 结果偶尔翻转就需要认真排查了。排查时有一个很高效的定位方法分段对比。先比较 PyTorch 和 ONNX Runtime 的输出这一步如果差异就很大问题出在导出阶段回第 3 章去验证导出参数和算子映射。如果 PyTorch 和 ONNX 一致、但 MNN 和 ONNX 差异明显则问题集中在 MNN 的算子实现上。MNN 侧精度问题最常见的触发点是半精度。如果你转换时参数里配置了 fp16 或模型内部有 autocast 留下半精度权重输出精度一定会下降。分类模型在小数据集上可能还能用目标检测的回归分支就很容易爆。我的建议是除非你对速度和内存有硬性要求否则先跑 fp32 打通全流程再考虑低精度优化。另外有一个容易踩的隐性坑模型内部如果存在超大常量的计算路径某些转换器在常量折叠后用低精度存储常量却忘了这个操作会改变计算语义。肉眼在图上不太容易发现但输出会莫名其妙的出现小幅漂移。遇到这种情况最快的办法是把常量相关路径摘出来在 PyTorch 里单独算一遍和端侧输出做对比。5.4 输入输出命名在排查中的作用排查精度问题时定位靠的是节点名字。我在导出时命名的 input 和 output 节点到 MNN 侧会自然保留。MNN 提供接口可以直接靠节点名取张量你不用去猜哪个位置才是输入。实际操作中我写了一个小的调试函数能把模型某一层的中间输出抓出来和 PyTorch 里对应层的输出做对比。这样一旦精度对不上很快能二分定位到是哪几层出了问题。这个经验对于转大型网络特别有用硬着头皮看整体差异是猜不到答案的。6. 端侧调用模板与高频问题排查复盘6.1 Python侧调用骨架完整的端侧调用会写 C但在开发阶段和验证阶段先用 Python 把逻辑跑通是最快的。MNN 的 Python 接口足以覆盖调试场景。import MNN import numpy as np interpreter MNN.Interpreter(model.mnn) session interpreter.createSession() input_tensor interpreter.getSessionInput(session) # 准备好的输入数据shape要和导出时一致 data np.random.randn(1, 3, 224, 224).astype(np.float32) tmp MNN.Tensor((1, 3, 224, 224), MNN.Halide_Type_Float, data, MNN.Tensor_DimensionType_Caffe) input_tensor.copyFromHostTensor(tmp) interpreter.runSession(session) output_tensor interpreter.getSessionOutput(session) result output_tensor.copyToHostTensor()接口细节以你装的版本为准思路是固定的创建解释器、创建会话、往输入张量里塞数据、跑会话、从输出张量里拿到数据。跑之前可以先让 MNN 把输入输出的维度信息打印出来确认和 ONNX 里命名节点完全对上能避免很多莫名其妙的 shape 报错。6.2 C侧需要提前知道的事从 Python 切到 C逻辑主体没有本质区别但有几个边界问题建议提前关注。首先是内存管理C 侧张量的数据底层可能是设备内存拷贝回 CPU 侧再访问的值才是你熟悉的数值。其次,创建会话和首次推理可能要比后续推理耗时长因为涉及后端初始化、内存预分配、算子编译这个在开发阶段看着像卡死其实是正常现象正式计时时要做一次 warmup。预处理在 C 侧经常出问题因为图像解码、颜色通道转换、缩放这些操作分散在不同第三方库里每一层都可能和 Python 侧有细微差异。我用过一个笨但有效的办法在 C 里直接加载 npy 数据作为输入绕过整个图像解码链路先把模型算对再回头处理图像读取的问题。这个技巧帮我分离了两类 bug非常推荐。6.3 高频问题排查复盘把自己实际遇到的高频问题列出来做成一份排查清单后续换新项目也能复用。第一个问题是导出时 batch1 的模型部署时真要用 batch8。这种问题在导出阶段最好就处理好统一用 batch1 的静态图到了端侧用循环推理虽然效率差一点但稳定。反过来如果你明确要 batch8那 dynamic_axes 至少要开 batch 维且入口到第一个全连接之间的 shape 推导要自检。第二个问题是 ONNX 一切正常MNN 某一层输出出现 NaN。这种要先归类是某类特殊算子的问题还是前一层数值溢出的传染。定位方式是把该层前后单独摘出来做数据对比缩小范围后就能查到是哪一层在作妖。第三个问题是首次推理特别慢。这个多半是初始化开销不是转换出了问题。我一般会在正式计时前先跑两次等内部缓存和算子预热结束再开始测量真实耗时。第四个问题是模型体积异常大。如果转出来的 MNN 模型比 ONNX 大或者远大于预期先查里面是不是包含了重复的常量子图。某些结构在 tracing 展开后会复制多份占空间还不影响精度。解决方式是在 PyTorch 里把那部分共享结构提出来或者用 MNN 提供的模型剪枝工具处理冗余节点。这个操作稍微绕一点但遇到大模型时基本避不开。6.4 关于后续量化的一点建议转了 MNN 之后很多人会想着趁热打铁把模型转成 int8 量化版本换更小的体积和更快的速度。量化前请先把 fp32 精度和速度基线测准没有基线做对比量化后出了问题你都不知道该朝哪个方向收敛。量化要准备一组有代表性的校准数据覆盖部署时真实出现的输入分布。我见过有人用 10 张训练集图片做校准换到真实场景精度就崩了原因就是校准集太单调、分布偏移。建议至少准备几百张多样化的输入跑一遍量化校准流程再在真实输入上验证精度差。另外量化对不同类型的任务影响差异很大。分类网络通常能压住精度损失目标检测里框的坐标回归对量化误差更敏感。如果检测任务用了量化精度明显下滑先退回 fp16 试试再考虑感知量化等进阶方案。最后再分享一条我自己的经验整个转换流程最值得花时间的是第一步和第五步也就是转换前的边界确认、转换后的精度对齐。中间 ONNX 和 MNN 的转换命令反而只是几下操作。很多人一开始就着急跑命令真正耗时的排查其实都发生在输出对不上的时候。先把基线脚本和对比流程搭好这套动作做完后面不管换哪个模型路径都是稳的。
前阵子帮人将一个图像分类模型塞进移动端跑模型在服务器上精度明明没问题一换推理框架就开始出各种幺蛾子。Pytorch模型转成ONNX和MNN这件事听起来就是两行命令的事实际推进时要把图的导出机制、算子兼容、精度对齐全走一遍少一步都会在部署阶段暴露出来。这篇文章把我自己踩过的坑和验证过的流程整理出来给准备做端侧推理、又不想啃完官方文档再动手的同学一条能直接照着走的路。事情的本质其实很简单训练用 PyTorch部署用 MNN中间的 ONNX 当翻译官。但翻译官也有能力边界有些话它能翻得很准有些话它会自作聪明提前知道边界在哪后面能省很多时间。1. 部署场景下的选择逻辑为什么是ONNX加MNN1.1 训练框架与推理框架的边界PyTorch 的设计目标是让研究人员能快速把想法跑起来动态图、自动求导、随时打印中间结果这些在训练阶段都是加分项。但到了端侧部署视角完全反过来模型要变成一张固定的计算图参数量要尽量小推理要用上设备的底层加速能力内存占用要低。直接拿 PyTorch 的产物去移动端跑不现实主要原因有两个一是运行时依赖太大光是把 torch 的 Python 层和底层库搬上去就够呛二是动态图的灵活在执行期是有代价的图结构不确定底层调度就没法做激进的算子融合和内存复用。所以才会有一批专门用于推理的框架出现。它们接收一个静态图描述在自己的运行时里做调度优化、算子加速、量化压缩。MNN 是这类框架里我个人用得比较顺手的一个它对多端硬件支持得比较全移动端、嵌入式、甚至纯 CPU 环境都有对应的后端实现。1.2 为什么让ONNX做中间人MNN 官方文档里支持直接转换的格式不止一种但大多数人的路线都是先转 ONNX 再转 MNN这不是绕路而是图省事。PyTorch 的模型本质上是一段 Python 代码逻辑加一堆参数张量框架要把它解析成静态图需要跟踪运行轨迹。如果让 MNN 直接解析 PyTorch 的导出产物要考虑的边界情况太多了自定义算子、Python 控制流、动态 shape任何一个都能让解析器头疼。ONNX 解决了这个问题它把模型统一成标准化的计算图描述节点类型有固定 schema输入输出信息齐全相当于大家约定了一个通用语言。这个过程可以类比成写文档。你手里是一份带复杂格式的原始文件要发给不同环境的人看最稳妥的办法是先导出 PDF而不是让每个接收方都装你的排版软件。ONNX 就是那份 PDF你只需要保证它排版正确后续接手的工具能不能解析那是标准规范的事。1.3 MNN相比ONNX Runtime的优势场景可能有人会问既然都转了 ONNX直接用 ONNX Runtime 推理不就行了分场景。ONNX Runtime 在云端和桌面端确实很强但它对标的不是端侧场景。端侧设备的特点是算力有限、内存有限、对首帧耗时敏感还需要跨平台部署。MNN 这类框架的价值在于它针对不支持 GPU 的环境也做了充分优化CPU 后端有汇编级加速支持低精度推理模型加载和图初始化做了专门的轻量化。我实测在 iPhone 和 Android 手机上跑同一个分割模型用 MNN 的耗时和内存表现都优于直接用 ONNX Runtime 包一层。所以选型结论很直接研究阶段用 PyTorch中间产物统一走 ONNX最终交给 MNN 去落地。整个链路里 ONNX 不会直接参与部署但它的质量直接决定了 MNN 能不能顺利接手。2. 转换前的环境准备与模型边界自检2.1 依赖安装与版本匹配转换流程需要的工具并不多一个干净的环境就能装完。我习惯用虚拟环境隔离避免和日常训练环境互相污染依赖。pip install torch onnx onnxruntime pip install MNNtorch 的版本会影响导出结果同一个模型在不同版本下导出的 ONNX 图可能不完全一样因为内置算子映射表还在持续更新。如果你手上有最终部署的固定环境尽量让导出环境和大版本保持一致至少大版本不要差太多。MNN 装好后通常会自带一个 mnnconvert 的转换命令行工具。不同版本的命令参数略有差别我后面会用当前我这边验证过的写法你拿到手后先跑一下mnnconvert --help确认字段名这个习惯能帮你省掉很多低级报错。2.2 模型输入输出的边界确认导出模型前先把你模型 forward 的真实结构理清楚这一步很多人偷懒直接拿一个大矩阵塞进去后面遇到问题才回头补。有几件事必须确认模型有几个输入每个输入的 shape 和 dtype 是什么。最容易被忽略的是那些不是 tensor 的输入比如推理时才指定的置信度阈值、是否做 NMS 的标志位。这类输入在追踪导出时会被当作常量固定下来如果你的部署逻辑需要动态调整它们得在设计上提前处理比如把它们在模型内部改成默认值。输出有几个是单 tensor、tuple 还是 dict。导出逻辑对输出类型有要求建议统一成 tuple 或者简单 tensor花半小时改一下模型结构比在导出报错时猜原因划算得多。模型内部有没有依赖输入 shape 的循环、条件跳转。这类写法在动态图里很自然但到了静态导出阶段就会出问题因为 ONNX 图是固定结构没法表达“模型会根据运行时数据决定走哪条分支”这种逻辑。2.3 转换前的“干净”基线推理脚本正式导出之前我会先写一个基线脚本加载权重切到 eval 模式关掉梯度用固定随机种子生成一组输入把模型输出保存成 npy 文件。import torch import numpy as np model MyModel() model.load_state_dict(torch.load(best.pt, map_locationcpu)) model.eval() dummy_input torch.randn(1, 3, 224, 224) with torch.no_grad(): reference_output model(dummy_input) np.save(reference_input.npy, dummy_input.numpy()) np.save(reference_output.npy, reference_output.numpy())这里面有两个细节容易被新手混在一起。model.eval() 和 torch.no_grad() 不是一个东西前者管的是 Dropout 和 BatchNorm 的行为后者管的是不构建计算图。导出时两者都要少了哪一个导出的 ONNX 都可能在推理时行为异常。这个基线输出的价值在导出后的每一步对比中都会体现。没有它你转出来的模型跑出了一个结果你都说不清这个结果对不对后面的精度排查也就无从下手。3. PyTorch导出ONNX参数细节与第一个坑3.1 torch.onnx.export的调用姿势PyTorch 官方提供了 torch.onnx.export 作为导出入口基本调用方式如下import torch torch.onnx.export( model, (dummy_input,), model.onnx, input_names[input], output_names[output], opset_version11, dynamic_axesNone, )这里的几个参数都不是摆设。opset_version 决定 ONNX 的算子集版本版本越高支持的算子越新但也取决于下游工具的支持度。我一般优先用 11 或者 12平衡性比较好太低会导致某些 PyTorch 算子找不到映射太高又可能在 MNN 侧遇到版本识别问题。input_names 和 output_names 很多人觉得无所谓但建议养成命名的习惯。这两个名字会出现在 ONNX 图上后面你在 onnxruntime 或者 MNN 里去取输入输出张量时都靠名字定位。不命名的结果就是得到一串看不出含义的代号排查问题时对着图找节点会很痛苦。有个关键认知要提前说清楚torch.onnx.export 用的是 tracing 机制。它不是分析你的源码结构而是真实跑一遍模型把执行过的算子记录下来。这意味着写在条件分支里但是这次没有执行到的代码不会出现在 ONNX 图里。所以 dummy_input 必须尽量贴近真实输入的分支路径否则导出的图会缺一小块。3.2 dynamic_axes到底该不该开dynamic_axes 控制导出的模型是否允许输入维度可变。默认情况下所有维度都是静态的dummy_input 是多少部署时就必须是多少。端侧部署我对动态维度的态度是能不开就不开。原因有两个。第一动态维度会让图里出现很多 shape 相关的计算节点这类算子性能一般都比较差还可能触发 MNN 里一些未覆盖的边界路径。第二动态维度会限制后端做内存预分配和算子融合优化固定 shape 的图能在初始化阶段就把中间张量内存规划好动态图只能运行时再算。如果只是希望 batch 维可变我建议单独开一个维度而不是所有维度全放开。比如图像分类场景输入依赖的只是 batch 和 height、width我会写成dynamic_axes{ input: {0: batch, 2: height, 3: width}, output: {0: batch} }实际测试中开 batch 和 hw 动态导出时最容易在图像尺寸相关的 resize 或 interpolation 节点上报错因为某些算子实现里含有依赖 shape 的循环逻辑tracing 时没法展开。如果你部署时输入固定是 224x224就不要给自己找这个麻烦把 dynamic_axes 设为 None导出最简单。3.3 导出的“及格线”检查导出成功只是万里长征的第一步。模型转出来之后我习惯立刻做三轮检查全部通过才算及格。第一轮是结构检查。用 onnx 自带的 checker 检查模型结构合法性。import onnx model_onnx onnx.load(model.onnx) onnx.checker.check_model(model_onnx)这一轮主要抓低级错误比如节点输入输出对不上、重复的 tensor 名称。报错的话基本可以确定模型导出过程出了问题先回头查模型 forward 里的写法。第二轮是图上人工抽查。把 ONNX 模型用可视化工具打开或者打印出节点列表重点确认几个关键结构的走向输入张量到第一层卷积的路径是否合理输出头是否和你模型的出口对应有没有出现你没预期到的超大常量节点。第三轮是数值对比。用 onnxruntime 跑一遍刚才保存的参考输入和 PyTorch 输出做比对。import onnxruntime as ort import numpy as np sess ort.InferenceSession(model.onnx, providers[CPUExecutionProvider]) ort_output sess.run(None, {input: reference_input})[0] diff np.abs(ort_output - reference_output).max() print(fmax diff: {diff:.2e})fp32 模型在这个环节的误差通常在 1e-5 量级如果你发现差异到了 1e-2 甚至更大不要怀疑浮点误差先回去查导出过程哪里出了问题。常见的原因包括 model.eval() 没调用、某些算子在不同库中实现的精度差异过大、或者是动态维度导致的计算路径不一致。4. ONNX到MNN命令行转换的实操与算子取舍4.1 mnnconvert的实操命令ONNX 检查通过后就可以进入 MNN 侧了。mnnconvert 是 MNN 自带的转换工具我这边验证过的转换命令是这样mnnconvert -f ONNX --modelFile model.onnx --MNNModel model.mnn-f 指定输入格式是 ONNX--modelFile 是输入的 onnx 文件路径--MNNModel 是输出的模型名。不同 MNN 版本可能还有额外的参数建议跑之前看一眼 help。转换过程通常很快几十 MB 的模型也就是一两秒的事。转换成功后MNN 会根据它的图优化策略对结构做调整包括算子融合、常量折叠、去掉一些冗余的 reshape 节点。这一步是框架内部自动完成的我不需要干预但要知道它发生这件事因为转换前后的节点数、体积可能都不一样。有个值得注意的现象如果你的网络里有很多 BatchNorm且处于推理模式MNN 转换器通常会把 Conv 和 BN 融合成一个带复合参数的卷积。效果是两个算子合并成一个参数量不变但前向计算量减少模型文件体积也可能略微变化。这是正常优化不用慌。4.2 看起来简单的算子也可能成为转换拦路虎ONNX 到 MNN 的转换不是百分百畅通的尤其当你模型里用了一些冷门算子。我自己在这条路上遇过几次比较典型的卡点。第一个是高维排序和 topk 类操作。torch.topk 在 ONNX 里能导出但 MNN 对某些维度的 topk 支持并不完整转换时可能直接报错不支持或者转换成功但运行结果不对。我的处理办法是尽量在网络里避免这类算子比如用卷积加 argmax 加 reshape 的组合去替代一部分排序逻辑。第二个是动态索引和布尔 mask。PyTorch 里写x[mask]非常顺手但在静态图里这是一大坑。mask 生成的索引序列是运行时才确定的没法预先把输出 shape 算出来ONNX 导出时要么被固定成常量要么产生支持不全面的非连续索引节点。遇到只能改成固定尺寸的 slice 或者把 mask 逻辑移到前后处理里去写。第三个是 resize 的坐标变换模式。PyTorch 的 F.interpolate 和 MNN 里的 resize 算子在对齐方式上可能有细微差异对坐标取整的方式不同输出就差一点点。分类网络对这一点点不敏感但目标检测框坐标就很容易偏。这个问题的解法是转换前把 MNN 文档里关于 resize 的说明看清楚在 PyTorch 侧匹配对应的 mode。遇到不支持的算子我的处理顺序是先看能不能改写模型结构用基本算子组合替代再看能不能把计算移到前后处理比如某些归一化参数算好再喂进去最后才考虑自定义算子方案因为自定义算子意味着脱离纯静态转换流程部署成本一下就上去了。4.3 转MNN后的第一眼检查转换完成后别急着往下走先用简单脚本把 MNN 模型加载起来跑一次确认图本身没有问题。最简单的做法是生成一个和 ONNX 导出时的 dummy 输入相同位置参数的随机输入让 MNN 跑起来看能否正常执行完输出有没有 NaN 或 Inf。这个冒烟测试不需要很精确的数值对比先保证推理链路能跑通。如果第一步就报错通常可以缩小范围检查是不是某个算子在 MNN 中真的缺失。MNN 有道命令可以列出模型中的算子类型但不同版本输出方式不一样我这边就不死记了你查询一下当前版本的模型工具即可。关键是思路先定位到具体层再决定是改图还是换算子。5. 部署验证与精度对齐最容易翻车的一步5.1 格式正确不等于逻辑正确模型转出来能跑、输出形状也对很多人就以为大功告成了直到实际应用发现结果不对才开始排查。这里要强调的是MNN 推理结果和 PyTorch 推理结果的精度对齐是整个流程里最容易被低估的一步。先把对齐流程跑起来。你需要准备同一份输入数据分别走 PyTorch、ONNX Runtime、MNN 三个通道拿到三份输出然后逐一比较。这个流程听起来简单实际执行时最大的干扰项是数据本身没有保持一致。5.2 对齐三件套同一输入、同一预处理、同一评价口径我把精度对齐的规则总结为三件套缺一个都别谈对比。第一输入必须是同一个。最简单的做法是直接用 npy 文件加载同一份张量数据避免每次重新跑图像预处理带来的随机差异。第二预处理必须完全一致。这一点真的经常出问题我前后处理里把图像归一化参数写错小数点导致肉眼看起来模型完全失灵排查了一天半。图像任务的预处理无非是 resize 方式、通道顺序、归一化系数但每一环都必须和训练时保持一致。PyTorch 侧用的是 BGR 还是 RGBMNN 侧也得一样shape 是 CHW 还是 NHWC 也要确认。第三评价口径要一致。分类模型看 top-1 准确率还是 top-5检测模型看 IoU 还是 mAP必须定义清楚。有时 MNN 输出分数比 PyTorch 低一点点但 argmax 结果没变那对分类任务就等于没影响不必为了小数点后四位焦虑。5.3 误差阈值与常见根因不同 op 的实现精度差异会导致端侧推理结果和 PyTorch 有微小的数值差异这个很正常。fp32 下我见过的情况分类网络总体差异在 1e-6 到 1e-3 之间。如果你发现差异达到 1e-2 量级或者 argmax 结果偶尔翻转就需要认真排查了。排查时有一个很高效的定位方法分段对比。先比较 PyTorch 和 ONNX Runtime 的输出这一步如果差异就很大问题出在导出阶段回第 3 章去验证导出参数和算子映射。如果 PyTorch 和 ONNX 一致、但 MNN 和 ONNX 差异明显则问题集中在 MNN 的算子实现上。MNN 侧精度问题最常见的触发点是半精度。如果你转换时参数里配置了 fp16 或模型内部有 autocast 留下半精度权重输出精度一定会下降。分类模型在小数据集上可能还能用目标检测的回归分支就很容易爆。我的建议是除非你对速度和内存有硬性要求否则先跑 fp32 打通全流程再考虑低精度优化。另外有一个容易踩的隐性坑模型内部如果存在超大常量的计算路径某些转换器在常量折叠后用低精度存储常量却忘了这个操作会改变计算语义。肉眼在图上不太容易发现但输出会莫名其妙的出现小幅漂移。遇到这种情况最快的办法是把常量相关路径摘出来在 PyTorch 里单独算一遍和端侧输出做对比。5.4 输入输出命名在排查中的作用排查精度问题时定位靠的是节点名字。我在导出时命名的 input 和 output 节点到 MNN 侧会自然保留。MNN 提供接口可以直接靠节点名取张量你不用去猜哪个位置才是输入。实际操作中我写了一个小的调试函数能把模型某一层的中间输出抓出来和 PyTorch 里对应层的输出做对比。这样一旦精度对不上很快能二分定位到是哪几层出了问题。这个经验对于转大型网络特别有用硬着头皮看整体差异是猜不到答案的。6. 端侧调用模板与高频问题排查复盘6.1 Python侧调用骨架完整的端侧调用会写 C但在开发阶段和验证阶段先用 Python 把逻辑跑通是最快的。MNN 的 Python 接口足以覆盖调试场景。import MNN import numpy as np interpreter MNN.Interpreter(model.mnn) session interpreter.createSession() input_tensor interpreter.getSessionInput(session) # 准备好的输入数据shape要和导出时一致 data np.random.randn(1, 3, 224, 224).astype(np.float32) tmp MNN.Tensor((1, 3, 224, 224), MNN.Halide_Type_Float, data, MNN.Tensor_DimensionType_Caffe) input_tensor.copyFromHostTensor(tmp) interpreter.runSession(session) output_tensor interpreter.getSessionOutput(session) result output_tensor.copyToHostTensor()接口细节以你装的版本为准思路是固定的创建解释器、创建会话、往输入张量里塞数据、跑会话、从输出张量里拿到数据。跑之前可以先让 MNN 把输入输出的维度信息打印出来确认和 ONNX 里命名节点完全对上能避免很多莫名其妙的 shape 报错。6.2 C侧需要提前知道的事从 Python 切到 C逻辑主体没有本质区别但有几个边界问题建议提前关注。首先是内存管理C 侧张量的数据底层可能是设备内存拷贝回 CPU 侧再访问的值才是你熟悉的数值。其次,创建会话和首次推理可能要比后续推理耗时长因为涉及后端初始化、内存预分配、算子编译这个在开发阶段看着像卡死其实是正常现象正式计时时要做一次 warmup。预处理在 C 侧经常出问题因为图像解码、颜色通道转换、缩放这些操作分散在不同第三方库里每一层都可能和 Python 侧有细微差异。我用过一个笨但有效的办法在 C 里直接加载 npy 数据作为输入绕过整个图像解码链路先把模型算对再回头处理图像读取的问题。这个技巧帮我分离了两类 bug非常推荐。6.3 高频问题排查复盘把自己实际遇到的高频问题列出来做成一份排查清单后续换新项目也能复用。第一个问题是导出时 batch1 的模型部署时真要用 batch8。这种问题在导出阶段最好就处理好统一用 batch1 的静态图到了端侧用循环推理虽然效率差一点但稳定。反过来如果你明确要 batch8那 dynamic_axes 至少要开 batch 维且入口到第一个全连接之间的 shape 推导要自检。第二个问题是 ONNX 一切正常MNN 某一层输出出现 NaN。这种要先归类是某类特殊算子的问题还是前一层数值溢出的传染。定位方式是把该层前后单独摘出来做数据对比缩小范围后就能查到是哪一层在作妖。第三个问题是首次推理特别慢。这个多半是初始化开销不是转换出了问题。我一般会在正式计时前先跑两次等内部缓存和算子预热结束再开始测量真实耗时。第四个问题是模型体积异常大。如果转出来的 MNN 模型比 ONNX 大或者远大于预期先查里面是不是包含了重复的常量子图。某些结构在 tracing 展开后会复制多份占空间还不影响精度。解决方式是在 PyTorch 里把那部分共享结构提出来或者用 MNN 提供的模型剪枝工具处理冗余节点。这个操作稍微绕一点但遇到大模型时基本避不开。6.4 关于后续量化的一点建议转了 MNN 之后很多人会想着趁热打铁把模型转成 int8 量化版本换更小的体积和更快的速度。量化前请先把 fp32 精度和速度基线测准没有基线做对比量化后出了问题你都不知道该朝哪个方向收敛。量化要准备一组有代表性的校准数据覆盖部署时真实出现的输入分布。我见过有人用 10 张训练集图片做校准换到真实场景精度就崩了原因就是校准集太单调、分布偏移。建议至少准备几百张多样化的输入跑一遍量化校准流程再在真实输入上验证精度差。另外量化对不同类型的任务影响差异很大。分类网络通常能压住精度损失目标检测里框的坐标回归对量化误差更敏感。如果检测任务用了量化精度明显下滑先退回 fp16 试试再考虑感知量化等进阶方案。最后再分享一条我自己的经验整个转换流程最值得花时间的是第一步和第五步也就是转换前的边界确认、转换后的精度对齐。中间 ONNX 和 MNN 的转换命令反而只是几下操作。很多人一开始就着急跑命令真正耗时的排查其实都发生在输出对不上的时候。先把基线脚本和对比流程搭好这套动作做完后面不管换哪个模型路径都是稳的。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
