MNN 模型转换指南使用 MNNConvert 将 TF / Caffe / ONNX / TFLite / PyTorch 模型转为 .mnn 格式【免费下载链接】MNNMNN: A blazing-fast, lightweight inference engine battle-tested by Alibaba, powering high-performance on-device LLMs and Edge AI.项目地址: https://gitcode.com/GitHub_Trending/mn/MNNMNNConvert 是 MNN 仓库自带的模型转换工具位于 tools/converter负责把 TensorFlowPB、Caffe、ONNX、TFLite 乃至 MNN 自身的模型文件统一转换为 MNN 的.mnn二进制模型格式是 MNN 落地到端侧推理前的必经环节。本文基于仓库内tools/converter/README.md与转换器源码完整讲解工具编译、全部命令行参数、各框架转换命令与 PyTorch 转换全流程并补充源码级原理说明帮助你在实际项目中一次转换成功。一、编译模型转换工具gcc 4.91. 前置依赖安装 protobuf版本 3.0MNNConvert 依赖 Google Protobuf 来解析 TF / Caffe 等格式的模型描述。macOS 下可直接通过 Homebrew 安装brew install protobuf其他平台请参考 protobuf 官方安装文档。从转换器的构建配置tools/converter/CMakeLists.txt可以看到当未启用仓库内置的MNN_BUILD_PROTOBUFFER时构建系统会通过find_package(Protobuf REQUIRED)查找系统安装的 protobuf因此确保protoc与libprotobuf可用且版本大于 3.0 是编译成功的前提。2. 使用 CMake 编译在 MNN 仓库根目录执行cd MNN mkdir build cd build cmake .. -DMNN_BUILD_CONVERTERtrue make其中-DMNN_BUILD_CONVERTERtrue是编译转换工具的关键开关。tools/converter/CMakeLists.txt中MNNConvert可执行文件由 tools/converter/source/MNNConverter.cpp 编译而成其入口逻辑十分简洁先调用MNN::Cli::initializeMNNConvertArgs解析命令行参数再调用MNN::Cli::convertModel执行转换失败时返回非零退出码见 MNNConverter.cpp。构建产物MNNConvert可执行文件默认输出到build目录下。补充说明官方还提供一键打包脚本 package_scripts/linux/build_tools.sh其中使用的关键参数为-DMNN_BUILD_CONVERTERON可作为 CI 或一键构建时的参考。3. 构建的可选功能在tools/converter/CMakeLists.txt中可以看到构建系统还支持以下可选开关MNN_BUILD_TORCH开启后-f参数额外支持TORCHTorchScript模型格式见 cli.cppMNN_RKNN开启 RKNN 转换模式对应-DENABLE_RKNN_CONVERT_MODE宏MNN_BUILD_SHARED_LIBS以共享库方式链接此时会额外编译MNNDump2Json、MNNRevert2Buffer、TestConvertResult等辅助工具见 tools/converter/CMakeLists.txt。二、MNNConvert 命令行参数详解在build目录下运行./MNNConvert可查看完整帮助。转换器支持的参数由 cli.cpp 中的 cxxopts 定义对应结构体 config.hpp 中的modelConfig字段。各参数含义如下参数说明备注-h, --help显示帮助信息退出码为 0-v, --version显示当前版本号输出MNN_VERSION见 cli.cpp-f, --framework模型类型[TF, CAFFE, ONNX, TFLITE, MNN, JSON]开启MNN_BUILD_TORCH后还有TORCH必填--modelFile模型文件路径TensorFlow 的*.pb、Caffe 的*.caffemodel、ONNX 的*.onnx、TFLite 的*.tflite、MNN 的*.mnn等必填--prototxt仅 Caffe 使用网络结构文件*.prototxtCaffe 必填--MNNModel输出 MNN 模型路径如model.mnn必填--bizCodeMNN 模型标志业务标识默认值MNN见 config.hpp建议显式指定--benchmarkModel不保存大尺寸参数如卷积权重、BN 的 gamma/beta/mean/var运行时随机初始化仅用于性能测试见下方说明--debug开启调试模式—重要提示benchmarkModel选项会从模型中移除卷积权重、BN 的 mean/var 等大尺寸参数以大幅减小转换后文件体积并在运行时随机初始化参数。它只适合做耗时/性能测试不能用于实际推理。除了 README 中列出的参数从 cli.cpp 还可以看到一组面向高级场景的参数它们在modelConfig中都有对应字段按用途归类如下量化与压缩--weightQuantBits2-8 bit 权重量化默认 0 表示不量化、--weightQuantAsymmetric非对称量化精度更好但旧版 MNN 不兼容、--weightQuantBlock分块量化 block size默认 -1 为 channel-wise、--hqqHQQ 量化开启后自动置 weightQuantAsymmetric 为 true、--weightQuantScaleBitscale/zero-point 存储位宽32fp32 默认16fp16、--compressionParamsFile激活/权重量化参数或稀疏信息文件、--detectSparseSpeedUp检测权重稀疏度并尝试稀疏加速图优化--optimizeLevel0 不优化/1 常规优化/2 激进优化默认 1、--optimizePrefer0 常规 / 1 最小体积 / 2 最快速度、--keepInputFormat是否保持输入维度格式默认 true、--convertMatmulToConv常量输入 MatMul 转为卷积默认 1、--useGeluApproximation用近似计算代替 ERF、--transformerFuse及--transformerFuseC4LLM Transformer 张量融合为 C4 布局默认 true、--transformerFuseQkvProj/--transformerFuseGateUpProj/--transformerFuseLnProj转换期构造 FusedLinear 投影组、--groupConvNative保留原生分组卷积、--useOriginRNNImplLSTM/GRU 使用原始算子而非 While Module开启后不可量化模型处理--fp16卷积权重/偏置以 half_float 保存、--forTraining保留 BN 与 Dropout 训练算子、--saveStaticModel固定 shape 的静态模型、--targetVersion兼容旧版 MNN 引擎默认与转换器版本一致、--defaultBatchSize未指定 batch 时设置默认值、--saveExternalData权重保存到外部 bin 文件、--externalTreshold外部数据阈值默认 64KB、--alignDenormalizedValue对齐非规格化浮点数默认 1、--allowCustomOp允许自定义算子、--customOpLibs自定义算子库如libmy_add.so;libmy_sub.so、--authCode模型鉴权码、--infodump MNN 模型信息输入输出名、维度、类型、版本、MetaData、--OP打印指定框架支持的全部算子、--dumpPass逐 pass 输出优化过程验证与测试--testdir转换后自动校验结果、--testconfig测试配置 JSON示例见 tools/converter/forward.json、--thredhold转换前后最大允许误差率默认 0.01MNN/JSON 互转--JsonFile输入为 MNN 时将模型 dump 到该 JSON 文件。其中--info对应的实现在 cli.cpp通过MNN::Express::Module::load加载模型后打印默认dimensionFormat、每个输入的名称/格式/维度/数据类型、输出名称、模型版本号与 MetaData是排查模型文件是否转换正确的快捷手段。三、各框架模型转换命令转换器的模型来源由modelConfig::MODEL_SOURCE枚举定义包含TENSORFLOW / CAFFE / ONNX / MNN / TFLITE / TORCH / JSON见 config.hpp-f参数会在 cli.cpp 中被映射为对应枚举值。1. TensorFlow / ONNX / TFLite./MNNConvert -f TF/ONNX/TFLITE --modelFile XXX.pb/XXX.onnx/XXX.tflite --MNNModel XXX.XX --bizCode XXX其中--framework、--modelFile、--MNNModel三个选项是必须的。以 TensorFlow 的 MobileNetV1 为例./MNNConvert -f TF --modelFile path/to/mobilenetv1.pb --MNNModel model.mnn --bizCode MNN从转换源码看这三个框架分别由 tensorflowConverter.hpp、onnxConverter.hpp、liteConverter.hpp 对应的解析器实现解析结果统一写入 flatbuffer 结构的.mnn文件见 writeFb.hpp。2. CaffeCaffe 模型由结构文件prototxt与权重文件caffemodel两部分组成因此需要四个必填选项./MNNConvert -f CAFFE --modelFile XXX.caffemodel --prototxt XXX.prototxt --MNNModel XXX.XX --bizCode XXX示例./MNNConvert -f CAFFE --modelFile path/to/mobilenetv1.caffemodel --prototxt path/to/mobilenetv1.prototxt --MNNModel model.mnn --bizCode MNNCaffe 解析器位于 tools/converter/source/caffe其中 OpConverter.cpp 负责将 Caffe 算子逐个映射为 MNN 算子如 Convolution、Pool、LRN、PriorBox、ROIPooling 等均有独立转换文件。3. MNNMNN 到 MNNMNN 模型也可以作为输入再次转换常用于升级、加 bizCode 或配合--JsonFile进行模型可视化/检查./MNNConvert -f MNN --modelFile XXX.mnn --MNNModel XXX.XX --bizCode XXX4. 查看版本./MNNConvert --version该命令直接输出MNN_VERSION宏见 cli.cpp可用于确认转换器版本与 MNN 引擎版本的匹配关系。四、MNNDump2Json模型文件可视化MNN 模型是二进制 flatbuffer 格式难以直接阅读。MNNDump2Json工具可以把.mnn二进制模型 dump 成可读的类 JSON 格式文件方便与原始模型参数进行对比、检查算子结构。使用方法该工具与MNNConvert一同构建位于build目录下./MNNDump2Json.out XXX.MNN XXX.json其入口实现见 MNNDump2Json.cpp接收两个参数输入.mnn与输出.json内部调用MNN::Cli::mnn2json完成转换。在转换命令中配合--JsonFile参数可以在转换的同时输出 JSON一条命令同时完成转换与 dump。五、PyTorch 模型转换全流程MNNConvert 本身不直接解析 PyTorch 的.pth权重官方推荐的标准路径是PyTorch → ONNX → MNN两步走。第一步用torch.onnx.export导出 ONNX以 torchvision 中的 AlexNet 为例import torch import torchvision dummy_input torch.randn(10, 3, 224, 224, devicecuda) model torchvision.models.alexnet(pretrainedTrue).cuda() # 提供输入/输出名称仅用于增强可读性不改变图语义 input_names [ actual_input_1 ] [ learned_%d % i for i in range(16) ] output_names [ output1 ] torch.onnx.export(model, dummy_input, alexnet.onnx, verboseTrue, input_namesinput_names, output_namesoutput_names, do_constant_foldingTrue)要点说明dummy_input的 shape此处为10x3x224x224决定了 ONNX 图中的输入张量形状应与实际推理时保持一致input_names/output_names只影响图中显示名称不改变语义do_constant_foldingTrue会提前折叠常量减小导出图规模更多导出细节可参考 PyTorch 官方 ONNX 导出文档。第二步ONNX 转 MNN./MNNConvert -f ONNX --modelFile alexnet.onnx --MNNModel alexnet.mnn --bizCode MNN转换成功后即可得到alexnet.mnn后续可通过 demo/exec/pictureRecognition.cpp 等示例或InterpreterAPI 加载推理。进阶提示如果目标模型来自 PyTorch 且需要保留训练算子或做量化可以结合本文第二节的参数--forTraining、--weightQuantBits、--compressionParamsFile等在转换阶段一并完成仓库还提供 tools/converter/tools/auto_quant.py 与 user_provide_quant_params.json 辅助量化参数准备。六、转换后的验证与排错算子支持检查用./MNNConvert -f ONNX --OP可打印该框架当前支持的全部算子清单转换前先确认模型中算子均有覆盖模型信息检查用./MNNConvert -f MNN --modelFile model.mnn --info打印输入输出名称、维度、数据类型与版本确认结构与预期一致数值一致性验证使用--testdir指定测试目录、--testconfig指定测试配置模板见 tools/converter/forward.json、--thredhold设置误差阈值默认 0.01转换后自动对比 MNN 与原框架输出官方测试脚本可参考 tools/converter/tools/testConvertor.py性能摸底若只需要评估推理耗时使用--benchmarkModel生成去除权重的小体积模型配合 benchmark/benchmark.cpp 进行耗时测试。七、常见问题小结问题处理建议编译时找不到 protobuf确认已安装 protobuf 且版本 3.0或改用仓库内置 protobuf 编译MNN_BUILD_PROTOBUFFER-f指定 TORCH 报错TorchScript 支持需在编译时开启MNN_BUILD_TORCHONCaffe 转换缺少--prototxtCaffe 必须同时提供--modelFile与--prototxt共四个必填项转换出的模型无法推理检查是否误用了--benchmarkModel该模式不含真实权重仅用于性能测试旧版本 MNN 引擎无法加载新模型用--targetVersion指定目标引擎版本或升级推理端 MNN【免费下载链接】MNNMNN: A blazing-fast, lightweight inference engine battle-tested by Alibaba, powering high-performance on-device LLMs and Edge AI.项目地址: https://gitcode.com/GitHub_Trending/mn/MNN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考