MNN 可选模块编译指南:转换、训练、LLM 与测试工具的 CMake 构建选项全解
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
编译产物
quantized.out:模型量化工具(tools/quantization/CMakeLists.txt 中由tools/quantization下全部源文件构建)。
从根 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
编译产物
classficationTopkEval.out:图片分类结果评估工具(工具名沿用了仓库中的原始拼写,见 tools/evaluation/CMakeLists.txt),入口源码为 tools/evaluation/classficationTopkEval.cpp。
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)和强制联动关系,都建议在实际编译前对照对应文件确认。