尧图网页设计 
1. 为什么端侧跑 MTCNN 总在模型转换这步卡住MTCNN 是个三级级联的人脸检测网络PNet 负责在整张图上快速筛出候选框RNet 做第一次精筛ONet 输出最终的人脸框和五个关键点。这套结构在服务器上跑没什么问题但搬到端侧、尤其是用 ncnn 做推理时很多人第一次都会卡在同一个地方模型转不过去或者转过去了但推理结果全是乱框。我见过太多人在这上面耗掉一整天。原因通常不是代码写错了而是 MTCNN 的 caffe 模型有个历史遗留问题——它是用 caffe matlab 训练出来的权重存储是 col-major列优先而 ncnn 默认按 row-major行优先读取。你直接拿官方 caffe2ncnn 工具去转转出来的 param/bin 文件能加载但卷积核的排布是错的推理出来的特征图自然全乱。表现就是程序不崩但检测框位置飘忽、置信度异常或者干脆一个框都出不来。所以这篇不讲虚的直接按工程落地的顺序走一遍从拉代码、编译 ncnn、转换三级网络模型到写 CMake 工程、加载 param/bin、跑通推理并输出人脸框坐标。目标很明确——你在端侧Windows/Linux/Android 都行本文以 Windows VS 为例Linux 思路一致能跑出一个能用的 MTCNN 检测程序输入一张图或一帧摄像头画面输出[x1, y1, x2, y2]和五个关键点。适合谁看做过一点 C、知道 CMake 大概怎么回事、想在端侧部署人脸检测的开发者。如果你只是想在 Python 里调个库那用现成的 face_recognition 更省事但如果你要的是可控、可裁剪、能塞进移动端或嵌入式设备的推理工程ncnn MTCNN 这套组合依然很能打。先说清楚整体链路心里有个数拉取 mtcnn_ncnn 仓库更新子模块编译 protobuf模型转换工具依赖它编译 ncnn拿到caffe2ncnn工具和ncnn.lib用修正过的caffe2ncnn.cpp重新编译转换工具把 PNet/RNet/ONet 的 caffemodel 转成 param/bin写 CMake 工程链接 ncnn 和 OpenCV加载三级模型做输入预处理、前向推理、NMS 后处理验证输出打印人脸框坐标和关键点下面一步步来。每一步我都会给出可复制的命令或配置你照着敲就行。2. TaoToken 前置先把模型转换和推理要用的 Key 准备好在正式动手之前有个容易被忽略但很关键的点模型转换和推理验证过程中你大概率会需要调用一些在线服务来做对照测试比如用大模型帮你检查 param 文件结构、排查推理输出异常或者生成测试用例。这时候如果每次都要手动去配环境、找接口效率会很低。我的做法是提前把 TaoToken 的 API Key 配好后面遇到报错或者需要快速验证某个模型输出时直接调就行。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址后面不加 UTM 参数。具体操作进控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建好之后把 Key 复制出来后面在排查推理问题时可以直接用。如果你需要看接入文档文档入口在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。这里要强调一下TaoToken 不是用来替代你本地编译 ncnn 的它是在你遇到模型转换报错、param 文件结构看不懂、推理结果异常需要对照分析时提供一个快速验证和排查的通道。比如你转出来的 ONet param 文件里某个卷积层的num_output对不上你可以把 param 片段贴给模型对话让它帮你分析比你自己翻 ncnn 源码快得多。模型对话入口 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。如果你后面要长期做端侧模型部署涉及多个模型的转换和验证可以考虑 Coding Plan入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。API Keys 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。把 Key 准备好之后我们进入正题。先拉代码。3. 可复制配置ncnn 编译与 MTCNN 三级模型转换这一节是全文的核心配置和命令都给全你直接复制就能用。3.1 拉取仓库与子模块在桌面新建一个文件夹比如叫mtcnn_work进去之后右键打开 Git Bash执行git clone https://github.com/moli232777144/mtcnn_ncnn.git cd mtcnn_ncnn git submodule update --init子模块更新完你会看到3rdparty/src下面有ncnn、protobuf、opencv等目录。如果子模块拉不下来检查一下网络或者手动去对应仓库下载放到指定位置。3.2 编译 protobufncnn 的模型转换工具caffe2ncnn依赖 protobuf。先跑tools/protobuf.bat它会在3rdparty/src/protobuf/cmake/build下生成protobuf.sln。用 VS2015或你本地的 VS 版本打开这个 sln分别编译 Debug 和 Release 版本。编译完成后运行tools/copyProtobuf.bat把生成的库和头文件复制到3rdparty公共目录下。这一步别跳过不然后面编译 ncnn 会找不到 protobuf。3.3 编译 ncnn打开tools/ncnn.bat找到里面DProtobuf_*相关的几个参数把它们改成你本地 protobuf 的实际路径。比如-DProtobuf_INCLUDE_DIR../3rdparty/include -DProtobuf_LIBRARIES../3rdparty/lib/libprotobuf.lib -DProtobuf_PROTOC_EXECUTABLE../3rdparty/bin/protoc.exe改完保存运行ncnn.bat。它会在3rdparty/src/ncnn/build下生成ncnn.sln。用 VS 打开编译 Release 版本。编译完成后build/src下有ncnn.libbuild/tools/caffe下有caffe2ncnn.exe。运行tools/copyNcnn.bat把caffe2ncnn.exe、ncnn.lib和头文件统一复制到3rdparty目录方便后面工程引用。3.4 修正 caffe2ncnn 并转换模型前面说过MTCNN 的 caffe 模型是 col-majorncnn 默认 row-major直接转会出错。解决办法是用修正过的caffe2ncnn.cpp覆盖原文件。去 https://github.com/ElegantGod/ncnn 这个仓库把ncnn/mtcnn下三个网络的新版caffemodel和prototxt下载下来覆盖本仓库model目录下的对应文件。同时把该仓库tools/caffe2ncnn.cpp覆盖到本仓库3rdparty/src/ncnn/tools/caffe/caffe2ncnn.cpp然后重新编译 ncnn 的 tools拿到修正后的caffe2ncnn.exe。转换命令格式caffe2ncnn.exe xx.prototxt xx.caffemodel xx.param xx.bin或者直接运行tools/mtcnn2ncnn.bat它会自动把model目录下三个网络都转成 ncnn 格式。转换完成后你会在model目录下看到det1.param、det1.bin、det2.param、det2.bin、det3.param、det3.bin六个文件。这里给一个 param 文件的结构参考你可以对照检查转换是否正确7767517 10 10 Input input 0 1 data Convolution conv1 1 1 data conv1 010 13 21 31 41 51 6108 PReLU prelu1 1 1 conv1 conv1_prelu 010 Pooling pool1 1 1 conv1_prelu pool1 00 12 22 32 40 Convolution conv2 1 1 pool1 conv2 016 13 21 31 41 51 6144 PReLU prelu2 1 1 conv2 conv2_prelu 016 Convolution conv3 1 1 conv2_prelu conv3 032 13 21 31 41 51 6288 PReLU prelu3 1 1 conv3 conv3_prelu 032 Convolution conv4 1 1 conv3_prelu conv4 02 11 21 31 41 51 664 Softmax prob 1 1 conv4 prob 00注意第一行7767517是 ncnn param 的 magic number第二行是层数和 blob 数。如果你转出来的文件第一行不是这个数说明转换工具用错了。3.5 CMake 工程结构模型转好之后建一个干净的 CMake 工程。目录结构建议这样mtcnn_demo/ ├── CMakeLists.txt ├── src/ │ ├── main.cpp │ ├── mtcnn.cpp │ └── mtcnn.h ├── model/ │ ├── det1.param │ ├── det1.bin │ ├── det2.param │ ├── det2.bin │ ├── det3.param │ └── det3.bin └── 3rdparty/ ├── include/ ├── lib/ └── bin/CMakeLists.txt内容cmake_minimum_required(VERSION 3.10) project(mtcnn_demo) set(CMAKE_CXX_STANDARD 11) include_directories( ${CMAKE_SOURCE_DIR}/3rdparty/include ${CMAKE_SOURCE_DIR}/3rdparty/include/ncnn ${CMAKE_SOURCE_DIR}/3rdparty/include/opencv ${CMAKE_SOURCE_DIR}/3rdparty/include/opencv2 ) link_directories( ${CMAKE_SOURCE_DIR}/3rdparty/lib ) add_executable(mtcnn_demo src/main.cpp src/mtcnn.cpp ) target_link_libraries(mtcnn_demo ncnn opencv_core opencv_imgproc opencv_highgui opencv_imgcodecs )Windows 下如果用的是 VS 生成器可以加-G Visual Studio 14 2015 Win64。Linux 下直接cmake .. make即可。3.6 加载 param/bin 与推理核心代码mtcnn.h里定义好三级网络的加载和检测接口#ifndef MTCNN_H #define MTCNN_H #include vector #include string #include net.h #include opencv2/opencv.hpp struct Bbox { float x1, y1, x2, y2; float score; float ppoint[10]; }; class MTCNN { public: MTCNN(const std::string model_dir); void detect(const ncnn::Mat img, std::vectorBbox finalBbox); void SetMinFace(int minSize); private: ncnn::Net PNet, RNet, ONet; int minFaceSize; float nms_threshold; void runPNet(const ncnn::Mat img, std::vectorBbox boxes); void runRNet(const ncnn::Mat img, std::vectorBbox boxes); void runONet(const ncnn::Mat img, std::vectorBbox boxes); void nms(std::vectorBbox boxes, float threshold, int type); }; #endifmtcnn.cpp里加载模型MTCNN::MTCNN(const std::string model_dir) { std::string pnet_param model_dir /det1.param; std::string pnet_bin model_dir /det1.bin; std::string rnet_param model_dir /det2.param; std::string rnet_bin model_dir /det2.bin; std::string onet_param model_dir /det3.param; std::string onet_bin model_dir /det3.bin; PNet.load_param(pnet_param.c_str()); PNet.load_model(pnet_bin.c_str()); RNet.load_param(rnet_param.c_str()); RNet.load_model(rnet_bin.c_str()); ONet.load_param(onet_param.c_str()); ONet.load_model(onet_bin.c_str()); minFaceSize 40; nms_threshold 0.7f; }输入预处理要注意ncnn 的from_pixels支持PIXEL_BGR2RGBMTCNN 训练时用的是 RGB所以这里要转。另外 MTCNN 的输入需要归一化到[-1, 1]也就是(pixel - 127.5) / 128.0。ncnn 里可以用substract_mean_normalizencnn::Mat ncnn_img ncnn::Mat::from_pixels(frame.data, ncnn::Mat::PIXEL_BGR2RGB, frame.cols, frame.rows); const float mean_vals[3] {127.5f, 127.5f, 127.5f}; const float norm_vals[3] {1.0f/128.0f, 1.0f/128.0f, 1.0f/128.0f}; ncnn_img.substract_mean_normalize(mean_vals, norm_vals);PNet 的前向推理ncnn::Extractor ex PNet.create_extractor(); ex.set_num_threads(4); ex.input(data, img); ncnn::Mat score, location; ex.extract(prob, score); ex.extract(conv4, location);拿到 score 和 location 之后做阈值筛选和边框回归再送 RNet、ONet。NMS 用标准的 IoU 计算阈值设 0.7。4. 验证请求跑通推理并输出人脸框坐标代码写完之后编译工程。Windows 下用 CMake 生成 VS 工程编译 ReleaseLinux 下直接 make。编译产物mtcnn_demo放到工程根目录确保model目录和可执行文件在同一级。main.cpp里写一个最简单的验证逻辑#include mtcnn.h #include iostream int main() { MTCNN mtcnn(../model); mtcnn.SetMinFace(40); cv::Mat frame cv::imread(../test.jpg); if (frame.empty()) { std::cerr image load failed std::endl; return -1; } ncnn::Mat ncnn_img ncnn::Mat::from_pixels(frame.data, ncnn::Mat::PIXEL_BGR2RGB, frame.cols, frame.rows); const float mean_vals[3] {127.5f, 127.5f, 127.5f}; const float norm_vals[3] {1.0f/128.0f, 1.0f/128.0f, 1.0f/128.0f}; ncnn_img.substract_mean_normalize(mean_vals, norm_vals); std::vectorBbox finalBbox; mtcnn.detect(ncnn_img, finalBbox); for (size_t i 0; i finalBbox.size(); i) { std::cout face i : x1 finalBbox[i].x1 y1 finalBbox[i].y1 x2 finalBbox[i].x2 y2 finalBbox[i].y2 score finalBbox[i].score std::endl; cv::rectangle(frame, cv::Rect(finalBbox[i].x1, finalBbox[i].y1, finalBbox[i].x2 - finalBbox[i].x1 1, finalBbox[i].y2 - finalBbox[i].y1 1), cv::Scalar(0, 0, 255), 2); for (int j 0; j 5; j) { cv::circle(frame, cv::Point(finalBbox[i].ppoint[j], finalBbox[i].ppoint[j 5]), 2, cv::Scalar(0, 255, 0), -1); } } cv::imshow(mtcnn_result, frame); cv::waitKey(0); return 0; }跑起来之后终端会打印类似这样的输出face 0: x1112.5 y186.3 x2248.7 y2222.1 score0.998 face 1: x1320.2 y195.8 x2410.6 y2186.4 score0.976同时弹出一个窗口人脸框用红色矩形标出五个关键点用绿色圆点标出。如果框的位置准确、关键点落在眼睛鼻子嘴角附近说明整条链路是通的。如果检测不到人脸先检查输入图像是不是 RGB 顺序、归一化参数对不对。MTCNN 对输入尺度比较敏感minFaceSize设太大比如 80会导致小脸漏检设太小比如 20会引入大量误检。一般 40 是个比较稳的值。再给一个摄像头实时检测的片段方便你验证端侧性能cv::VideoCapture cap(0); if (!cap.isOpened()) return -1; cv::Mat frame; while (cap.read(frame)) { ncnn::Mat ncnn_img ncnn::Mat::from_pixels(frame.data, ncnn::Mat::PIXEL_BGR2RGB, frame.cols, frame.rows); ncnn_img.substract_mean_normalize(mean_vals, norm_vals); std::vectorBbox boxes; mtcnn.detect(ncnn_img, boxes); // 画框逻辑同上 cv::imshow(camera, frame); if (cv::waitKey(10) 27) break; }在普通笔记本上PNet 大概 10-20msRNet 5-10msONet 5-10ms整体一帧 30-50ms能跑到 20-30 FPS。端侧设备性能弱一些但通过set_num_threads和输入分辨率控制基本能实时。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节列几个实际部署中高频出现的报错以及对应的排查思路。有些是 ncnn 本身的有些是你在用在线服务辅助排查时可能遇到的。报错一load_param failed或load_model failed最常见的原因是路径不对。ncnn 的load_param接受的是文件路径相对路径是相对于可执行文件的工作目录不是源码目录。如果你在 VS 里直接 F5 调试工作目录默认是工程目录不是Release目录。解决办法是在 VS 工程属性里把「调试 - 工作目录」设成$(OutDir)或者用绝对路径加载模型。另一个原因是 param 文件第一行不是7767517。如果你用错了转换工具比如用了没修正过的 caffe2ncnn转出来的文件格式不对加载就会失败。重新用修正版工具转一遍。报错二local proxy failed或连接超时这个通常出现在你调用在线 API 做辅助排查时。如果你在代码里配置了代理但代理服务没起来就会报这个。检查你的网络配置确保 API 地址https://taotoken.net/api能正常访问。如果是在公司内网可能需要配置白名单。注意不要使用任何不合规的网络工具直接用官方提供的 API 地址即可。报错三reading choices相关错误这个一般出现在你调用模型对话接口时返回的 JSON 结构里choices字段解析失败。原因可能是请求体格式不对或者模型名称写错了。检查你的请求{ model: claude-sonnet-4-20250514, messages: [ {role: user, content: 帮我分析这个 ncnn param 文件的结构} ] }确保model字段是你实际可用的模型 IDmessages是数组格式。如果返回 401说明 API Key 无效或没带上。在请求头里加Authorization: Bearer YOUR_API_KEY报错四OAuth相关错误如果你用的是 Claude Code 或类似的编码工具接入可能会遇到 OAuth 认证失败。这类工具通常需要配置 Base URL、API Key 和 Model ID 三件套。以 Claude Code 为例配置文件里要写全{ base_url: https://taotoken.net/api, api_key: sk-xxxxxxxx, model: claude-sonnet-4-20250514 }三个字段缺一不可。只填 Base URL 不填 Key或者 Key 填了但 Model ID 写错都会报 OAuth 或认证失败。如果你用的是 Codex 的auth.json格式类似{ base_url: https://taotoken.net/api, api_key: sk-xxxxxxxx, model: claude-sonnet-4-20250514 }报错五推理结果全是乱框或置信度异常回到最开始说的 col-major 问题。如果你确认 param 文件第一行是7767517但推理结果还是不对检查一下caffe2ncnn.cpp是不是真的被覆盖并重新编译了。很多人覆盖了源码但忘了重新编译caffe2ncnn.exe用的还是旧的二进制转出来的模型自然还是错的。验证方法转出来的det1.bin文件大小应该和原始caffemodel接近如果差太多说明转换过程有问题。报错六CMake 找不到 ncnn 或 OpenCV检查CMakeLists.txt里的include_directories和link_directories路径是否和实际目录一致。Windows 下注意库文件名Debug 和 Release 的库不能混用。如果用的是 VS 生成器可以在 CMake 命令里指定-DCMAKE_BUILD_TYPERelease。6. 语义一致 CTA把模型转换和推理验证串成可复用的工程习惯整条链路走下来你会发现最耗时的不是写推理代码而是模型转换和依赖编译。一旦这两步跑通后面的检测逻辑其实是相对固定的模板。我的建议是把转换好的 param/bin 文件和编译好的 ncnn 库单独存一份后面换模型或者换设备时直接复用不用每次从头编译。如果你在转换过程中遇到 param 文件结构看不懂、某个层的参数对不上、或者推理输出异常需要快速定位可以直接用 TaoToken 的模型对话来辅助分析。把 param 片段或者报错日志贴进去让它帮你对照 ncnn 的层定义检查比翻源码快很多。入口在 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。需要管理多个 API Key 或者查看用量去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的请求示例和参数说明。如果你后面要长期做端侧模型部署涉及多个模型的转换、验证和迭代Coding Plan 会更合适入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。最后说一个实用技巧MTCNN 的三级网络里PNet 是全卷积结构输入尺寸可以动态变化。如果你在端侧发现大分辨率输入太慢可以把输入缩到 320x240 再送 PNet检测到候选框后再把原图对应区域裁出来送 RNet 和 ONet。这样能在几乎不损失精度的前提下把速度提上去。这个策略在移动端特别有用你可以根据设备性能动态调整。 基于ncnn框架搭建MTCNN人脸检测工程：从模型转换到端侧推理的完整实践
1. 为什么端侧跑 MTCNN 总在模型转换这步卡住MTCNN 是个三级级联的人脸检测网络PNet 负责在整张图上快速筛出候选框RNet 做第一次精筛ONet 输出最终的人脸框和五个关键点。这套结构在服务器上跑没什么问题但搬到端侧、尤其是用 ncnn 做推理时很多人第一次都会卡在同一个地方模型转不过去或者转过去了但推理结果全是乱框。我见过太多人在这上面耗掉一整天。原因通常不是代码写错了而是 MTCNN 的 caffe 模型有个历史遗留问题——它是用 caffe matlab 训练出来的权重存储是 col-major列优先而 ncnn 默认按 row-major行优先读取。你直接拿官方 caffe2ncnn 工具去转转出来的 param/bin 文件能加载但卷积核的排布是错的推理出来的特征图自然全乱。表现就是程序不崩但检测框位置飘忽、置信度异常或者干脆一个框都出不来。所以这篇不讲虚的直接按工程落地的顺序走一遍从拉代码、编译 ncnn、转换三级网络模型到写 CMake 工程、加载 param/bin、跑通推理并输出人脸框坐标。目标很明确——你在端侧Windows/Linux/Android 都行本文以 Windows VS 为例Linux 思路一致能跑出一个能用的 MTCNN 检测程序输入一张图或一帧摄像头画面输出[x1, y1, x2, y2]和五个关键点。适合谁看做过一点 C、知道 CMake 大概怎么回事、想在端侧部署人脸检测的开发者。如果你只是想在 Python 里调个库那用现成的 face_recognition 更省事但如果你要的是可控、可裁剪、能塞进移动端或嵌入式设备的推理工程ncnn MTCNN 这套组合依然很能打。先说清楚整体链路心里有个数拉取 mtcnn_ncnn 仓库更新子模块编译 protobuf模型转换工具依赖它编译 ncnn拿到caffe2ncnn工具和ncnn.lib用修正过的caffe2ncnn.cpp重新编译转换工具把 PNet/RNet/ONet 的 caffemodel 转成 param/bin写 CMake 工程链接 ncnn 和 OpenCV加载三级模型做输入预处理、前向推理、NMS 后处理验证输出打印人脸框坐标和关键点下面一步步来。每一步我都会给出可复制的命令或配置你照着敲就行。2. TaoToken 前置先把模型转换和推理要用的 Key 准备好在正式动手之前有个容易被忽略但很关键的点模型转换和推理验证过程中你大概率会需要调用一些在线服务来做对照测试比如用大模型帮你检查 param 文件结构、排查推理输出异常或者生成测试用例。这时候如果每次都要手动去配环境、找接口效率会很低。我的做法是提前把 TaoToken 的 API Key 配好后面遇到报错或者需要快速验证某个模型输出时直接调就行。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址后面不加 UTM 参数。具体操作进控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建好之后把 Key 复制出来后面在排查推理问题时可以直接用。如果你需要看接入文档文档入口在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。这里要强调一下TaoToken 不是用来替代你本地编译 ncnn 的它是在你遇到模型转换报错、param 文件结构看不懂、推理结果异常需要对照分析时提供一个快速验证和排查的通道。比如你转出来的 ONet param 文件里某个卷积层的num_output对不上你可以把 param 片段贴给模型对话让它帮你分析比你自己翻 ncnn 源码快得多。模型对话入口 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。如果你后面要长期做端侧模型部署涉及多个模型的转换和验证可以考虑 Coding Plan入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。API Keys 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。把 Key 准备好之后我们进入正题。先拉代码。3. 可复制配置ncnn 编译与 MTCNN 三级模型转换这一节是全文的核心配置和命令都给全你直接复制就能用。3.1 拉取仓库与子模块在桌面新建一个文件夹比如叫mtcnn_work进去之后右键打开 Git Bash执行git clone https://github.com/moli232777144/mtcnn_ncnn.git cd mtcnn_ncnn git submodule update --init子模块更新完你会看到3rdparty/src下面有ncnn、protobuf、opencv等目录。如果子模块拉不下来检查一下网络或者手动去对应仓库下载放到指定位置。3.2 编译 protobufncnn 的模型转换工具caffe2ncnn依赖 protobuf。先跑tools/protobuf.bat它会在3rdparty/src/protobuf/cmake/build下生成protobuf.sln。用 VS2015或你本地的 VS 版本打开这个 sln分别编译 Debug 和 Release 版本。编译完成后运行tools/copyProtobuf.bat把生成的库和头文件复制到3rdparty公共目录下。这一步别跳过不然后面编译 ncnn 会找不到 protobuf。3.3 编译 ncnn打开tools/ncnn.bat找到里面DProtobuf_*相关的几个参数把它们改成你本地 protobuf 的实际路径。比如-DProtobuf_INCLUDE_DIR../3rdparty/include -DProtobuf_LIBRARIES../3rdparty/lib/libprotobuf.lib -DProtobuf_PROTOC_EXECUTABLE../3rdparty/bin/protoc.exe改完保存运行ncnn.bat。它会在3rdparty/src/ncnn/build下生成ncnn.sln。用 VS 打开编译 Release 版本。编译完成后build/src下有ncnn.libbuild/tools/caffe下有caffe2ncnn.exe。运行tools/copyNcnn.bat把caffe2ncnn.exe、ncnn.lib和头文件统一复制到3rdparty目录方便后面工程引用。3.4 修正 caffe2ncnn 并转换模型前面说过MTCNN 的 caffe 模型是 col-majorncnn 默认 row-major直接转会出错。解决办法是用修正过的caffe2ncnn.cpp覆盖原文件。去 https://github.com/ElegantGod/ncnn 这个仓库把ncnn/mtcnn下三个网络的新版caffemodel和prototxt下载下来覆盖本仓库model目录下的对应文件。同时把该仓库tools/caffe2ncnn.cpp覆盖到本仓库3rdparty/src/ncnn/tools/caffe/caffe2ncnn.cpp然后重新编译 ncnn 的 tools拿到修正后的caffe2ncnn.exe。转换命令格式caffe2ncnn.exe xx.prototxt xx.caffemodel xx.param xx.bin或者直接运行tools/mtcnn2ncnn.bat它会自动把model目录下三个网络都转成 ncnn 格式。转换完成后你会在model目录下看到det1.param、det1.bin、det2.param、det2.bin、det3.param、det3.bin六个文件。这里给一个 param 文件的结构参考你可以对照检查转换是否正确7767517 10 10 Input input 0 1 data Convolution conv1 1 1 data conv1 010 13 21 31 41 51 6108 PReLU prelu1 1 1 conv1 conv1_prelu 010 Pooling pool1 1 1 conv1_prelu pool1 00 12 22 32 40 Convolution conv2 1 1 pool1 conv2 016 13 21 31 41 51 6144 PReLU prelu2 1 1 conv2 conv2_prelu 016 Convolution conv3 1 1 conv2_prelu conv3 032 13 21 31 41 51 6288 PReLU prelu3 1 1 conv3 conv3_prelu 032 Convolution conv4 1 1 conv3_prelu conv4 02 11 21 31 41 51 664 Softmax prob 1 1 conv4 prob 00注意第一行7767517是 ncnn param 的 magic number第二行是层数和 blob 数。如果你转出来的文件第一行不是这个数说明转换工具用错了。3.5 CMake 工程结构模型转好之后建一个干净的 CMake 工程。目录结构建议这样mtcnn_demo/ ├── CMakeLists.txt ├── src/ │ ├── main.cpp │ ├── mtcnn.cpp │ └── mtcnn.h ├── model/ │ ├── det1.param │ ├── det1.bin │ ├── det2.param │ ├── det2.bin │ ├── det3.param │ └── det3.bin └── 3rdparty/ ├── include/ ├── lib/ └── bin/CMakeLists.txt内容cmake_minimum_required(VERSION 3.10) project(mtcnn_demo) set(CMAKE_CXX_STANDARD 11) include_directories( ${CMAKE_SOURCE_DIR}/3rdparty/include ${CMAKE_SOURCE_DIR}/3rdparty/include/ncnn ${CMAKE_SOURCE_DIR}/3rdparty/include/opencv ${CMAKE_SOURCE_DIR}/3rdparty/include/opencv2 ) link_directories( ${CMAKE_SOURCE_DIR}/3rdparty/lib ) add_executable(mtcnn_demo src/main.cpp src/mtcnn.cpp ) target_link_libraries(mtcnn_demo ncnn opencv_core opencv_imgproc opencv_highgui opencv_imgcodecs )Windows 下如果用的是 VS 生成器可以加-G Visual Studio 14 2015 Win64。Linux 下直接cmake .. make即可。3.6 加载 param/bin 与推理核心代码mtcnn.h里定义好三级网络的加载和检测接口#ifndef MTCNN_H #define MTCNN_H #include vector #include string #include net.h #include opencv2/opencv.hpp struct Bbox { float x1, y1, x2, y2; float score; float ppoint[10]; }; class MTCNN { public: MTCNN(const std::string model_dir); void detect(const ncnn::Mat img, std::vectorBbox finalBbox); void SetMinFace(int minSize); private: ncnn::Net PNet, RNet, ONet; int minFaceSize; float nms_threshold; void runPNet(const ncnn::Mat img, std::vectorBbox boxes); void runRNet(const ncnn::Mat img, std::vectorBbox boxes); void runONet(const ncnn::Mat img, std::vectorBbox boxes); void nms(std::vectorBbox boxes, float threshold, int type); }; #endifmtcnn.cpp里加载模型MTCNN::MTCNN(const std::string model_dir) { std::string pnet_param model_dir /det1.param; std::string pnet_bin model_dir /det1.bin; std::string rnet_param model_dir /det2.param; std::string rnet_bin model_dir /det2.bin; std::string onet_param model_dir /det3.param; std::string onet_bin model_dir /det3.bin; PNet.load_param(pnet_param.c_str()); PNet.load_model(pnet_bin.c_str()); RNet.load_param(rnet_param.c_str()); RNet.load_model(rnet_bin.c_str()); ONet.load_param(onet_param.c_str()); ONet.load_model(onet_bin.c_str()); minFaceSize 40; nms_threshold 0.7f; }输入预处理要注意ncnn 的from_pixels支持PIXEL_BGR2RGBMTCNN 训练时用的是 RGB所以这里要转。另外 MTCNN 的输入需要归一化到[-1, 1]也就是(pixel - 127.5) / 128.0。ncnn 里可以用substract_mean_normalizencnn::Mat ncnn_img ncnn::Mat::from_pixels(frame.data, ncnn::Mat::PIXEL_BGR2RGB, frame.cols, frame.rows); const float mean_vals[3] {127.5f, 127.5f, 127.5f}; const float norm_vals[3] {1.0f/128.0f, 1.0f/128.0f, 1.0f/128.0f}; ncnn_img.substract_mean_normalize(mean_vals, norm_vals);PNet 的前向推理ncnn::Extractor ex PNet.create_extractor(); ex.set_num_threads(4); ex.input(data, img); ncnn::Mat score, location; ex.extract(prob, score); ex.extract(conv4, location);拿到 score 和 location 之后做阈值筛选和边框回归再送 RNet、ONet。NMS 用标准的 IoU 计算阈值设 0.7。4. 验证请求跑通推理并输出人脸框坐标代码写完之后编译工程。Windows 下用 CMake 生成 VS 工程编译 ReleaseLinux 下直接 make。编译产物mtcnn_demo放到工程根目录确保model目录和可执行文件在同一级。main.cpp里写一个最简单的验证逻辑#include mtcnn.h #include iostream int main() { MTCNN mtcnn(../model); mtcnn.SetMinFace(40); cv::Mat frame cv::imread(../test.jpg); if (frame.empty()) { std::cerr image load failed std::endl; return -1; } ncnn::Mat ncnn_img ncnn::Mat::from_pixels(frame.data, ncnn::Mat::PIXEL_BGR2RGB, frame.cols, frame.rows); const float mean_vals[3] {127.5f, 127.5f, 127.5f}; const float norm_vals[3] {1.0f/128.0f, 1.0f/128.0f, 1.0f/128.0f}; ncnn_img.substract_mean_normalize(mean_vals, norm_vals); std::vectorBbox finalBbox; mtcnn.detect(ncnn_img, finalBbox); for (size_t i 0; i finalBbox.size(); i) { std::cout face i : x1 finalBbox[i].x1 y1 finalBbox[i].y1 x2 finalBbox[i].x2 y2 finalBbox[i].y2 score finalBbox[i].score std::endl; cv::rectangle(frame, cv::Rect(finalBbox[i].x1, finalBbox[i].y1, finalBbox[i].x2 - finalBbox[i].x1 1, finalBbox[i].y2 - finalBbox[i].y1 1), cv::Scalar(0, 0, 255), 2); for (int j 0; j 5; j) { cv::circle(frame, cv::Point(finalBbox[i].ppoint[j], finalBbox[i].ppoint[j 5]), 2, cv::Scalar(0, 255, 0), -1); } } cv::imshow(mtcnn_result, frame); cv::waitKey(0); return 0; }跑起来之后终端会打印类似这样的输出face 0: x1112.5 y186.3 x2248.7 y2222.1 score0.998 face 1: x1320.2 y195.8 x2410.6 y2186.4 score0.976同时弹出一个窗口人脸框用红色矩形标出五个关键点用绿色圆点标出。如果框的位置准确、关键点落在眼睛鼻子嘴角附近说明整条链路是通的。如果检测不到人脸先检查输入图像是不是 RGB 顺序、归一化参数对不对。MTCNN 对输入尺度比较敏感minFaceSize设太大比如 80会导致小脸漏检设太小比如 20会引入大量误检。一般 40 是个比较稳的值。再给一个摄像头实时检测的片段方便你验证端侧性能cv::VideoCapture cap(0); if (!cap.isOpened()) return -1; cv::Mat frame; while (cap.read(frame)) { ncnn::Mat ncnn_img ncnn::Mat::from_pixels(frame.data, ncnn::Mat::PIXEL_BGR2RGB, frame.cols, frame.rows); ncnn_img.substract_mean_normalize(mean_vals, norm_vals); std::vectorBbox boxes; mtcnn.detect(ncnn_img, boxes); // 画框逻辑同上 cv::imshow(camera, frame); if (cv::waitKey(10) 27) break; }在普通笔记本上PNet 大概 10-20msRNet 5-10msONet 5-10ms整体一帧 30-50ms能跑到 20-30 FPS。端侧设备性能弱一些但通过set_num_threads和输入分辨率控制基本能实时。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节列几个实际部署中高频出现的报错以及对应的排查思路。有些是 ncnn 本身的有些是你在用在线服务辅助排查时可能遇到的。报错一load_param failed或load_model failed最常见的原因是路径不对。ncnn 的load_param接受的是文件路径相对路径是相对于可执行文件的工作目录不是源码目录。如果你在 VS 里直接 F5 调试工作目录默认是工程目录不是Release目录。解决办法是在 VS 工程属性里把「调试 - 工作目录」设成$(OutDir)或者用绝对路径加载模型。另一个原因是 param 文件第一行不是7767517。如果你用错了转换工具比如用了没修正过的 caffe2ncnn转出来的文件格式不对加载就会失败。重新用修正版工具转一遍。报错二local proxy failed或连接超时这个通常出现在你调用在线 API 做辅助排查时。如果你在代码里配置了代理但代理服务没起来就会报这个。检查你的网络配置确保 API 地址https://taotoken.net/api能正常访问。如果是在公司内网可能需要配置白名单。注意不要使用任何不合规的网络工具直接用官方提供的 API 地址即可。报错三reading choices相关错误这个一般出现在你调用模型对话接口时返回的 JSON 结构里choices字段解析失败。原因可能是请求体格式不对或者模型名称写错了。检查你的请求{ model: claude-sonnet-4-20250514, messages: [ {role: user, content: 帮我分析这个 ncnn param 文件的结构} ] }确保model字段是你实际可用的模型 IDmessages是数组格式。如果返回 401说明 API Key 无效或没带上。在请求头里加Authorization: Bearer YOUR_API_KEY报错四OAuth相关错误如果你用的是 Claude Code 或类似的编码工具接入可能会遇到 OAuth 认证失败。这类工具通常需要配置 Base URL、API Key 和 Model ID 三件套。以 Claude Code 为例配置文件里要写全{ base_url: https://taotoken.net/api, api_key: sk-xxxxxxxx, model: claude-sonnet-4-20250514 }三个字段缺一不可。只填 Base URL 不填 Key或者 Key 填了但 Model ID 写错都会报 OAuth 或认证失败。如果你用的是 Codex 的auth.json格式类似{ base_url: https://taotoken.net/api, api_key: sk-xxxxxxxx, model: claude-sonnet-4-20250514 }报错五推理结果全是乱框或置信度异常回到最开始说的 col-major 问题。如果你确认 param 文件第一行是7767517但推理结果还是不对检查一下caffe2ncnn.cpp是不是真的被覆盖并重新编译了。很多人覆盖了源码但忘了重新编译caffe2ncnn.exe用的还是旧的二进制转出来的模型自然还是错的。验证方法转出来的det1.bin文件大小应该和原始caffemodel接近如果差太多说明转换过程有问题。报错六CMake 找不到 ncnn 或 OpenCV检查CMakeLists.txt里的include_directories和link_directories路径是否和实际目录一致。Windows 下注意库文件名Debug 和 Release 的库不能混用。如果用的是 VS 生成器可以在 CMake 命令里指定-DCMAKE_BUILD_TYPERelease。6. 语义一致 CTA把模型转换和推理验证串成可复用的工程习惯整条链路走下来你会发现最耗时的不是写推理代码而是模型转换和依赖编译。一旦这两步跑通后面的检测逻辑其实是相对固定的模板。我的建议是把转换好的 param/bin 文件和编译好的 ncnn 库单独存一份后面换模型或者换设备时直接复用不用每次从头编译。如果你在转换过程中遇到 param 文件结构看不懂、某个层的参数对不上、或者推理输出异常需要快速定位可以直接用 TaoToken 的模型对话来辅助分析。把 param 片段或者报错日志贴进去让它帮你对照 ncnn 的层定义检查比翻源码快很多。入口在 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。需要管理多个 API Key 或者查看用量去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的请求示例和参数说明。如果你后面要长期做端侧模型部署涉及多个模型的转换、验证和迭代Coding Plan 会更合适入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。最后说一个实用技巧MTCNN 的三级网络里PNet 是全卷积结构输入尺寸可以动态变化。如果你在端侧发现大分辨率输入太慢可以把输入缩到 320x240 再送 PNet检测到候选框后再把原图对应区域裁出来送 RNet 和 ONet。这样能在几乎不损失精度的前提下把速度提上去。这个策略在移动端特别有用你可以根据设备性能动态调整。