MNN 可选模块编译指南:转换、训练、LLM 与测试工具的 CMake 构建选项全解

原创2026-09-13 12:09:491,401 阅读
文章标签:人工智能推理引擎大模型本地部署深度学习模型量化模型优化

MNN 可选模块编译指南:转换、训练、LLM 与测试工具的 CMake 构建选项全解

本文基于 MNN 官方文档 docs/compile/other.md 编写,系统讲解 MNN 中各可选模块(模型转换、训练框架、LLM/扩散模型、测试/Benchmark/量化/评估工具、OpenCV/Audio 库、示例工程、单元测试)的 CMake 编译选项、编译命令与编译产物,并结合仓库中根级与各子模块的 CMakeLists.txt 说明每个开关在构建系统中实际生效的位置与默认值,帮助读者按需组合编译参数,构建出只包含所需功能的 MNN。

编译选项总览:绝大多数功能默认关闭

MNN 的构建体系是"核心引擎 + 大量可选模块"。根级 CMakeLists.txt 中集中定义了各功能开关,其中与本文主题直接相关的是:

CMake 选项 默认值 作用
MNN_BUILD_CONVERTER OFF 是否编译模型转换工具(MNNConvert 等)
MNN_BUILD_TRAIN OFF 是否编译训练框架
MNN_BUILD_DEMO OFF 是否编译 Demo 示例工程
MNN_BUILD_TOOLS ON 是否编译测试工具(默认打开)
MNN_BUILD_QUANTOOLS OFF 是否编译模型量化工具
MNN_EVALUATION OFF 是否编译图片分类结果评估工具
MNN_BUILD_BENCHMARK OFF 是否编译 Benchmark 工具
MNN_BUILD_TEST OFF 是否编译单元测试
MNN_BUILD_OPENCV OFF 是否编译 MNN 内置 OpenCV 函数接口
MNN_IMGCODECS OFF 是否编译图像编解码器(在 tools/cv/CMakeLists.txt 中定义)
MNN_BUILD_AUDIO OFF 是否编译 Audio 函数接口
MNN_BUILD_LLM OFF 是否编译大语言模型推理引擎
MNN_BUILD_DIFFUSION OFF 是否编译扩散模型推理示例
MNN_SUPPORT_TRANSFORMER_FUSE OFF 是否支持 transformer 相关融合算子

从根 CMakeLists.txt 的结构看,几个开关之间存在强制联动,编译前需要心中有数:

  • 打开 MNN_BUILD_LLM 会自动将 MNN_LOW_MEMORY 与 MNN_SUPPORT_TRANSFORMER_FUSE 置为 ON;若再打开 MNN_BUILD_LLM_OMNI(支持图像/音频输入),还会连带打开 MNN_BUILD_OPENCV、MNN_BUILD_AUDIO、MNN_IMGCODECS;
  • 打开 MNN_BUILD_DIFFUSION 会自动打开 MNN_LOW_MEMORY、MNN_SUPPORT_TRANSFORMER_FUSE 和 MNN_BUILD_OPENCV;
  • 在 tools/cv/CMakeLists.txt 中,MNN_BUILD_DIFFUSION 打开时会强制 MNN_IMGCODECS=ON,MNN_BUILD_LLM_OMNI 同理;
  • 打开 MNN_BUILD_TRAIN 或 MNN_BUILD_QUANTOOLS 都会把 tools/train 纳入构建(CMakeLists.txt),因为量化工具复用训练框架的代码。

理解这些联动关系后,下面各章节的编译命令只需按需复制即可。

模型转换工具

模型转换是把 TensorFlow、ONNX、Caffe、TFLite、PyTorch 等格式模型转换为 .mnn 格式的基础设施,由 tools/converter 目录构建。

相关编译选项

  • MNN_BUILD_CONVERTER:是否编译模型转换工具,默认 OFF;
  • MNN_BUILD_TORCH:是否支持 TorchScript 模型转换,定义在 tools/converter/CMakeLists.txt,默认 OFF。该选项开启后需要 PyTorch 依赖:MacOS 下需要本机安装 pytorch,Linux 下构建系统会下载 libtorch。

从 tools/converter/CMakeLists.txt 的结构看,转换器依赖 protobuf:默认使用 MNN 自带的 3rd_party/protobuf(由 MNN_BUILD_PROTOBUFFER=ON 控制并静态构建),也可以关掉它改用系统 protobuf(find_package(Protobuf REQUIRED))。此外,转换器会把 tensorflow、onnx、caffe、MNN、optimizer、tflite 各后端的转换实现分别纳入(tools/converter/CMakeLists.txt)。

编译命令

cmake .. -DMNN_BUILD_CONVERTER=ON -DMNN_BUILD_TORCH=ON

编译产物

  • MNNConvert:模型转换主工具;
  • TestConvertResult:模型转换正确性测试工具(Windows 下没有此产物,用 MNNConvert 对应功能替代);
  • TestPassManager:模型转换工具的图变换 Pass 测试用例;
  • MNNDump2Json:将 MNN 模型导出为 JSON 查看;
  • MNNRevert2Buffer:将 JSON 转回 MNN 模型;
  • OnnxClip:ONNX 模型裁剪工具,在 tools/converter/source/onnx/CMakeLists.txt 中构建。

需要注意的一个构建细节:从 tools/converter/CMakeLists.txt 的结构看,MNNRevert2Buffer、MNNDump2Json、TestConvertResult、TestPassManager 这几个辅助可执行文件只在 MNN_BUILD_SHARED_LIBS=ON(默认值)的分支中被添加;静态库构建下只有 MNNConvert 本体会生成,这也是"Windows 下没有 TestConvertResult 产物、用 MNNConvert 替代"这一说法的来源。

MNN 模型转 QNN 模型工具

该工具用于把 MNN 模型转换为高通 QNN(Hexagon NPU)可直接执行的模型,是 QNN 后端的配套转换能力,源码位于 source/backend/qnn/convertor。

相关编译选项

  • MNN_QNN_CONVERT_MODE:在打开 MNN_QNN 宏的前提下,是否把 MNN 转 QNN 模型的转换功能库一并编译。该选项在 source/backend/qnn/CMakeLists.txt 中定义,开启后会额外编译 convertor/*.cpp 源码并定义 ENABLE_QNN_CONVERT_MODE 宏(source/backend/qnn/CMakeLists.txt)。QNN SDK 路径优先取 CMake 变量 QNN_SDK_ROOT,否则回退到同名环境变量。

编译命令

cmake .. -DMNN_QNN=ON -DMNN_QNN_CONVERT_MODE=ON

编译产物

  • MNN2QNNModel:模型转换工具。从 tools/cpp/CMakeLists.txt 看,MNN2QNNModel(以及 NPU 输入输出工具 generateIO)只在 MNN_QNN=ON 时构建,因此该工具同时依赖测试工具开关。

训练框架

MNN 的训练框架支持在推理引擎之上做前向、反向传播与参数更新,源码位于 tools/train。

相关编译选项

  • MNN_BUILD_TRAIN:是否编译训练框架,默认 OFF;
  • MNN_BUILD_TRAIN_MINI:文档针对移动端/嵌入式设备的建议项——设置为 ON 时不编译内置的 Dataset、Models,因为这类数据加载与内置模型在移动端/嵌入式设备上通常有其他解决方案;
  • MNN_USE_OPENCV:在 tools/train/CMakeLists.txt 中定义,部分 PC 上的 demo 用到系统 OpenCV,与 Dataset 处理相关。从源码看,打开该选项后 runTrainDemo.out 会 find_package(OpenCV REQUIRED) 并链接 ${OpenCV_LIBS},即需要本机已安装 OpenCV。

需要说明的是:从当前仓库的 CMake 结构看,MNN_TRAIN_MINI/MNN_BUILD_TRAIN_MINI 这一开关并未在 tools/train/CMakeLists.txt 中暴露,models 与 datasets 源码始终被编译进 MNNTrainUtils 对象库;如实际构建时遇到该选项不生效,请以当前 CMake 定义为准。

编译命令

mkdir build && cd build
cmake .. -DMNN_BUILD_TRAIN=ON -DMNN_USE_OPENCV=ON
make -j4

编译产物

  • MNNTrain:训练框架库(在 MNN_SEP_BUILD=ON 时独立成共享库,见 tools/train/CMakeLists.txt);
  • runTrainDemo.out:运行训练框架 demo 的入口程序,链接了内置 demo 源码(source/demo/*);
  • transformer:训练模型转换器,将推理用的 MNN 模型转换为执行训练的 MNN 模型(含反向传播图);
  • extractForInfer:从执行训练的 MNN 模型中提取参数,对应更新推理用的 MNN 模型。

这两个工具配合构成"训练-回写"闭环:先用 transformer 生成可训练模型,训练后用 extractForInfer 把学到的权重写回推理模型。根 CMakeLists.txt 中还有 MNN_TRAIN_DEBUG 选项(tools/train/CMakeLists.txt)可用于开启梯度调试信息。

生成式模型:LLM 与扩散模型

这是 MNN 面向端侧生成式 AI 的两条产品线:大语言模型推理引擎(transformers/llm)与扩散模型推理示例(transformers/diffusion)。

相关编译选项

  • MNN_BUILD_DIFFUSION:是否编译扩散模型推理示例,默认 OFF;
  • MNN_BUILD_LLM:是否编译大语言模型推理引擎,默认 OFF;
  • MNN_SUPPORT_TRANSFORMER_FUSE:是否支持 transformer 相关的融合算子,主要加速 transformer 模型。根 CMakeLists.txt 中该宏开启后会定义 MNN_SUPPORT_TRANSFORMER_FUSE,并可在 Metal 后端上进一步启用原生 GatedRMSNorm 内核(MNN_GATED_RMS_NORM)。

编译命令

编译扩散模型推理示例:

mkdir build && cd build
cmake .. -DMNN_BUILD_OPENCV=ON -DMNN_IMGCODECS=ON -DMNN_BUILD_DIFFUSION=ON -DMNN_SUPPORT_TRANSFORMER_FUSE=ON
make -j4

编译大语言模型推理引擎:

mkdir build && cd build
cmake .. -DMNN_BUILD_LLM=ON -DMNN_SUPPORT_TRANSFORMER_FUSE=ON
make -j4

结合根 CMakeLists 的联动逻辑,第二条命令其实不需要显式写 MNN_SUPPORT_TRANSFORMER_FUSE(会被强制打开);而扩散模型的 MNN_BUILD_OPENCV 同样是强制项,显式写出主要是为了同时打开图像编解码 MNN_IMGCODECS。

编译产物

  • libllm.so:大语言模型推理库(transformers/llm/engine/CMakeLists.txt 中构建 llm 目标);
  • llm_demo:大语言模型推理示例程序;
  • diffusion_demo:扩散模型示例程序;
  • llm_bench:大语言模型测评工具;
  • rollback_demo:大语言模型 kvcache 回调示例工具;
  • quantize_llm:大语言模型 feature map 量化工具。

从 transformers/llm/engine/CMakeLists.txt 和 transformers/llm/engine/tools/CMakeLists.txt 的结构看,实际构建的可执行文件比文档列出的更多,可按需使用:

  • demo 系列(MNN_LLM_BUILD_DEMO=ON 为默认值):llm_demo、llm_logits_diff(logits 差异对比)、multi_lora_demo(多 LoRA)、embedding_demo、reranker_demo、rollback_demo、tokenizer_demo,以及打开 MNN_BUILD_AUDIO 时的 qwen3_tts_demo;
  • 工具系列:llm_bench、quantize_llm、ppl_eval(困惑度评估)、generateLlmIO、apply_template(jinja 模板应用);
  • 另有 BUILD_MLS=ON 可构建 PC 端命令行工具 mls(需要 OpenSSL,transformers/llm/engine/CMakeLists.txt)。

扩散侧除 diffusion_demo 外,还会生成 diffusion_sd35_demo(SD3.5 示例);同时开启 MNN_BUILD_LLM 时还会生成 sana_diffusion_demo 与 wan_diffusion_demo(transformers/diffusion/engine/CMakeLists.txt)。

测试工具

MNN_BUILD_TOOLS 默认即为 ON,编译产物集中定义在 tools/cpp/CMakeLists.txt。

相关编译选项

  • MNN_BUILD_TOOLS:是否编译测试工具。

编译命令

mkdir build && cd build
cmake .. -DMNN_BUILD_TOOLS=ON
make -j4

编译产物

  • GetMNNInfo:获取 MNN 模型信息;
  • ModuleBasic.out:使用 V3 API(Module)对模型执行基础推理测试;
  • SequenceModuleTest.out:测试 Sequence 模型推理;
  • MNNV2Basic.out:使用 V2 API(Session)对模型执行基础推理测试;
  • mobilenetTest.out:测试 mobilenet 模型推理;
  • backendTest.out:测试模型在指定后端上执行的结果是否与 CPU 一致;
  • modelCompare.out:原始模型与量化模型推理结果比较;
  • testModel.out:给定输入输出测试模型推理正确性;
  • testModel_expr.out:给定输入输出测试模型推理正确性(表达式接口);
  • testModelWithDescribe.out:给定输入输出和 shape 描述测试模型推理正确性;
  • getPerformance.out:获取当前设备的 CPU 性能;
  • checkInvalidValue.out:检测输出目录里的数据(如 NaN/Inf);
  • timeProfile.out:测试模型在指定后端上执行的时间,并获取每层的执行时间占比(依赖 tools/cpp/Profiler.cpp);
  • testTrain.out:测试训练功能;
  • checkDir.out:测试两个文件夹是否一致(非 Windows);
  • checkFile.out:测试两个文件是否一致(非 Windows);
  • winogradExample.out:winograd 示例(非 Windows);
  • fuseTest:测试 GPU 自定义算子的功能,目前仅支持 Vulkan Buffer 模式;
  • GpuInterTest.out:测试 GPU 内存输入的功能,目前仅支持 OpenCL Buffer 模式与 OpenGL texture 模式,编译时需打开 MNN_OPENCL 与 MNN_OPENGL。从 tools/cpp/CMakeLists.txt 看,该目标仅在 Android 平台构建,并链接 android 库;
  • LoRA:将 LoRA 权重添加到模型权重中;
  • compilefornpu:将 NPU 要运行的部分转换为 Plugin 算子(tools/cpp/CMakeLists.txt);
  • generateIO:用于为 NPU 模型转换提供输入输出工具,与 MNN2QNNModel 一样在 MNN_QNN=ON 时构建。

Benchmark 工具

相关编译选项

  • MNN_BUILD_BENCHMARK:是否编译 Benchmark 工具,默认 OFF。

编译命令

mkdir build && cd build
cmake .. -DMNN_BUILD_BENCHMARK=ON
make -j4

编译产物(定义见 benchmark/CMakeLists.txt)

  • benchmark.out:benchmark 工具,基于 benchmark/benchmark.cpp,配合 benchmark/models 目录下的 MobileNet、ResNet、SqueezeNet 等预置模型使用;
  • benchmarkExprModels.out:表达式构图模型测试 benchmark 工具,编译时纳入 benchmark/exprModels 下的 GoogLeNet、MobileNet、ResNet、ShuffleNet、SqueezeNet 表达式构图模型。

另外 benchmark/CMakeLists.txt 支持 MNN_CUDA_PROFILE:在 Linux+CUDA 环境下打开后会链接 nvToolsExt,便于在 CUDA 后端做 profiling。

模型量化工具

相关编译选项

  • MNN_BUILD_QUANTOOLS:是否编译模型量化工具,默认 OFF。

编译命令

mkdir build && cd build
cmake .. -DMNN_BUILD_QUANTOOLS=ON
make -j4

编译产物

从根 CMakeLists.txt 的结构看,MNN_BUILD_QUANTOOLS=ON 会连带把 tools/train 纳入构建(量化工具复用训练框架的对象库 MNNTrain/MNNTrainUtils),因此量化工具的构建依赖训练框架代码,这解释了两者在 CMake 中共享同一个 add_subdirectory 的原因。

评估工具

相关编译选项

  • MNN_EVALUATION:是否编译图片分类结果评估工具,默认 OFF。

编译命令

mkdir build && cd build
cmake .. -DMNN_EVALUATION=ON
make -j4

编译产物

MNN OpenCV 库

MNN 内置了一套轻量 OpenCV 兼容接口(核心、imgproc、calib3d、imgcodecs),可用于在不引入完整 OpenCV 的前提下做图像预处理。相关定义集中在 tools/cv/CMakeLists.txt。

相关编译选项

  • MNN_BUILD_OPENCV:是否编译 OpenCV 函数接口,默认 OFF;
  • MNN_IMGCODECS:是否编译 OpenCV 图像编解码器,默认 OFF(LLM 全模态与扩散模型构建时会强制打开);
  • MNN_OPENCV_TEST:是否编译 OpenCV 单元测试,默认 OFF;
  • MNN_OPENCV_BENCH:是否编译 OpenCV 性能测试,默认 OFF。

此外 imgproc 各子模块还可通过 MNN_IMGPROC_COLOR、MNN_IMGPROC_GEOMETRIC、MNN_IMGPROC_DRAW、MNN_IMGPROC_FILTER、MNN_IMGPROC_MISCELLANEOUS、MNN_IMGPROC_STRUCTRAL、MNN_IMGPROC_HISTOGRAMS、MNN_CVCORE、MNN_CALIB3D 细分开关(均默认 ON)进一步裁剪(tools/cv/CMakeLists.txt)。

编译命令

mkdir build && cd build
cmake .. -DMNN_BUILD_OPENCV=ON -DMNN_IMGCODECS=ON -DMNN_OPENCV_TEST=ON -DMNN_OPENCV_BENCH=ON
make -j4

编译产物

  • libMNNOpenCV.so:MNN OpenCV 函数库(MNN_SEP_BUILD=ON 时独立成共享库并链接 MNN、MNN_Express,见 tools/cv/CMakeLists.txt);
  • opencv_test:MNN OpenCV 单元测试(tools/cv/test 子目录);
  • opencv_bench:MNN OpenCV 性能测试(tools/cv/benchmark 子目录)。

打开测试或性能测试开关时,构建系统会把 tools/cv/imgs 目录下的测试图片复制到构建输出目录(tools/cv/CMakeLists.txt),运行时可直接引用。

MNN Audio 库

与 OpenCV 库结构类似,MNN 提供轻量音频处理接口,源码位于 tools/audio。

相关编译选项

  • MNN_BUILD_AUDIO:是否编译 Audio 函数接口,默认 OFF;
  • MNN_AUDIO_TEST:是否编译 Audio 单元测试,默认 OFF。

编译命令

mkdir build && cd build
cmake .. -DMNN_BUILD_AUDIO=ON -DMNN_AUDIO_TEST=ON
make -j4

编译产物

  • libMNNAudio.so:MNN Audio 函数库;
  • audio_test:MNN Audio 单元测试。

Audio 库是 LLM 全模态(MNN_BUILD_LLM_OMNI)的组成部分:打开全模态开关时 CMake 会强制打开 MNN_BUILD_AUDIO 与 MNN_IMGCODECS(CMakeLists.txt),并在 LLM 引擎中定义 LLM_SUPPORT_AUDIO(transformers/llm/engine/CMakeLists.txt)。

示例工程

Demo 示例集中了 MNN 各层 API 的典型用法,构建入口在 demo/exec/CMakeLists.txt。

相关编译选项

  • MNN_BUILD_DEMO:是否编译 MNN Demo,默认 OFF。

编译命令

mkdir build && cd build
cmake .. -DMNN_BUILD_DEMO=ON
make -j4

编译产物

  • pictureRecognition.out:V2 接口(Session)图片识别示例;
  • pictureRecognition_module.out:V3 接口(Module)图片识别示例;
  • pictureRecognition_batch.out:自定义 batchsize 图片识别示例;
  • multithread_imgrecog.out:多线程图片识别示例;
  • pictureRotate.out:图片旋转示例;
  • multiPose.out:姿态检测示例;
  • segment.out:图像实例分割示例;
  • expressDemo.out:表达式接口推理示例;
  • expressMakeModel.out:使用表达式构建模型示例;
  • transformerDemo.out:Transformer 模型示例;
  • nluDemo.out:nlu 模型示例;
  • mergeInplaceForCPU:将模型中可以 Inplace 计算的算子改成 Inplace 计算,可以减少内存占用,但限定 CPU 后端运行(tools/cpp/CMakeLists.txt);
  • OpenCLProgramBuildTest.out:测试 OpenCL 后端的 Program 在设备上是否能编译成功(tools/cpp/CMakeLists.txt)。

需要说明:原文档还列出了 rasterDemo.out(Raster 示例),但当前 demo/exec/CMakeLists.txt 中未定义该目标,实际产物以 CMake 定义为准。示例运行所需的模型文件位于 demo/model(MobileNet、SqueezeNet)。

单元测试

相关编译选项

  • MNN_BUILD_TEST:是否编译 MNN 单元测试,默认 OFF。

编译命令

mkdir build && cd build
cmake .. -DMNN_BUILD_TEST=ON
make -j4

编译产物

  • run_test.out:单元测试程序,由 test/CMakeLists.txt 将 test/ 目录下全部测试源码(算子、后端、表达式、grad 等)编译成单一可执行文件,运行时通过参数选择用例。

从 test/CMakeLists.txt 的结构看,test/grad 与 test/nn 下的梯度/神经网络测试只在 MNN_BUILD_TRAIN=ON 时参与编译,因此完整验证训练相关测试需要同时打开训练开关。仓库根目录的 test.sh 也给出了 CI 场景下的测试运行方式参考。

常用编译参数组合速查

场景 建议参数
只做模型转换(含 PyTorch) -DMNN_BUILD_CONVERTER=ON -DMNN_BUILD_TORCH=ON
MNN 转 QNN 模型 -DMNN_QNN=ON -DMNN_QNN_CONVERT_MODE=ON(需 QNN_SDK_ROOT)
训练 + 系统 OpenCV -DMNN_BUILD_TRAIN=ON -DMNN_USE_OPENCV=ON
端侧 LLM 引擎 -DMNN_BUILD_LLM=ON(LOW_MEMORY 与融合算子自动打开)
扩散模型示例 -DMNN_BUILD_DIFFUSION=ON -DMNN_IMGCODECS=ON
量化 + 评估 + 测试工具 -DMNN_BUILD_QUANTOOLS=ON -DMNN_EVALUATION=ON -DMNN_BUILD_TEST=ON
性能压测 -DMNN_BUILD_BENCHMARK=ON
裁剪体积的轻量构建 -DMNN_BUILD_MINI=ON(联动 MNN_SKIPBUILD_GEOMETRY 与 MNN_REDUCE_SIZE,CMakeLists.txt)

以上选项均以当前仓库根级 CMakeLists.txt 与各子模块 CMakeLists.txt 的实际定义为准:默认值、平台限制(如 GpuInterTest.out 仅限 Android、checkDir.out/checkFile.out/winogradExample.out 不构建于 Windows)和强制联动关系,都建议在实际编译前对照对应文件确认。

登录后查看全文
MNN