Retinaface+CurricularFace模型部署避坑指南：C++环境配置详解-育师

Retinaface+CurricularFace模型部署避坑指南：C++环境配置详解

最近在折腾Retinaface+CurricularFace这个人脸识别组合，想用C++把它跑起来，结果发现网上的教程大多是Python的，C++这块的坑一个接一个。从OpenCV版本冲突到CMake配置报错，再到模型加载失败，真是踩了个遍。

如果你也是C++开发者，想把这个强大的人脸识别模型集成到自己的项目中，但又不想重复踩我走过的坑，那这篇指南就是为你准备的。我会把整个C++环境配置的过程掰开揉碎了讲，特别是那些容易出错的地方，让你能顺顺利利地把环境搭起来。

1. 环境准备：别小看这一步

很多人觉得环境准备就是装几个库，其实这里面的门道不少。配置不对，后面编译运行全是问题。

1.1 系统要求与基础环境

首先得确保你的系统环境是合适的。我是在Ubuntu 20.04 LTS上测试的，这个版本比较稳定，社区支持也好。Windows理论上也能跑，但依赖问题会更多，建议先用Linux环境上手。

# 检查系统版本 cat /etc/os-release # 更新系统包 sudo apt update sudo apt upgrade -y

C++编译器我用的是GCC 9.4.0，这个版本对C++17支持比较完整。太老的版本可能编译不过，太新的版本又可能有不兼容的问题。

# 安装GCC 9 sudo apt install gcc-9 g++-9 -y # 设置默认版本 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 100 sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-9 100 # 验证版本 gcc --version g++ --version

1.2 CMake版本选择

CMake的版本特别重要，太老的版本不支持一些现代CMake特性，太新的版本又可能和某些库不兼容。我试过3.16到3.24之间的多个版本，最后发现3.18到3.22这个范围最稳定。

# 安装CMake 3.20（比较折中的版本） wget https://github.com/Kitware/CMake/releases/download/v3.20.0/cmake-3.20.0.tar.gz tar -zxvf cmake-3.20.0.tar.gz cd cmake-3.20.0 ./bootstrap make -j$(nproc) sudo make install # 验证安装 cmake --version

如果系统里已经有其他版本的CMake，记得用sudo update-alternatives来管理多个版本，方便切换。

2. 核心依赖库安装：顺序很重要

依赖库的安装顺序和版本搭配是关键，装错了顺序或者版本不匹配，后面会出各种奇怪的错误。

2.1 OpenCV安装：最容易出问题的地方

OpenCV是基础中的基础，但也是坑最多的地方。Retinaface需要OpenCV来处理图像，但并不是版本越高越好。

我强烈建议用OpenCV 4.5.5这个版本，它既支持了必要的DNN模块，又比较稳定。不要用4.7.x或4.8.x，这些新版本在编译某些扩展模块时容易出问题。

# 安装依赖 sudo apt install build-essential cmake git pkg-config libgtk-3-dev \ libavcodec-dev libavformat-dev libswscale-dev libv4l-dev \ libxvidcore-dev libx264-dev libjpeg-dev libpng-dev libtiff-dev \ gfortran openexr libatlas-base-dev python3-dev python3-numpy \ libtbb2 libtbb-dev libdc1394-22-dev libopenexr-dev \ libgstreamer-plugins-base1.0-dev libgstreamer1.0-dev -y # 下载OpenCV 4.5.5 wget -O opencv.zip https://github.com/opencv/opencv/archive/4.5.5.zip wget -O opencv_contrib.zip https://github.com/opencv/opencv_contrib/archive/4.5.5.zip unzip opencv.zip unzip opencv_contrib.zip # 编译安装 cd opencv-4.5.5 mkdir build && cd build cmake -D CMAKE_BUILD_TYPE=RELEASE \ -D CMAKE_INSTALL_PREFIX=/usr/local \ -D INSTALL_PYTHON_EXAMPLES=OFF \ -D INSTALL_C_EXAMPLES=OFF \ -D OPENCV_ENABLE_NONFREE=ON \ -D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib-4.5.5/modules \ -D BUILD_EXAMPLES=OFF \ -D BUILD_opencv_python3=OFF \ -D WITH_CUDA=OFF \ -D WITH_FFMPEG=ON \ -D WITH_GTK=ON \ -D WITH_V4L=ON \ -D WITH_OPENGL=ON \ -D WITH_TBB=ON \ -D WITH_EIGEN=ON \ -D WITH_OPENCL=OFF \ -D BUILD_TESTS=OFF \ -D BUILD_PERF_TESTS=OFF .. make -j$(nproc) sudo make install sudo ldconfig # 验证安装 pkg-config --modversion opencv4

编译过程可能会比较久，取决于你的CPU核心数。如果遇到编译错误，最常见的原因是缺少某个依赖，根据错误信息安装对应的开发包就行。

2.2 ONNX Runtime安装：模型推理的核心

Retinaface和CurricularFace的预训练模型通常是ONNX格式的，所以需要ONNX Runtime来加载和推理。这里要注意CPU版本和GPU版本的选择。

如果你有NVIDIA显卡并且想用GPU加速，就装GPU版本。如果没有或者想先确保能跑起来，就用CPU版本。我建议先用CPU版本测试，确保整个流程没问题后再考虑GPU优化。

# 下载ONNX Runtime CPU版本（1.15.1比较稳定） wget https://github.com/microsoft/onnxruntime/releases/download/v1.15.1/onnxruntime-linux-x64-1.15.1.tgz tar -zxvf onnxruntime-linux-x64-1.15.1.tgz sudo cp -r onnxruntime-linux-x64-1.15.1/include/* /usr/local/include/ sudo cp -r onnxruntime-linux-x64-1.15.1/lib/* /usr/local/lib/ sudo ldconfig # 验证 ls /usr/local/lib | grep onnx

如果要用GPU版本，需要先确保CUDA和cuDNN已经正确安装，然后下载对应的GPU版本。不过GPU版本的依赖更多，出问题的概率也更大，新手建议先避开。

2.3 其他必要依赖

还有一些小但重要的依赖，少了它们编译会失败。

# Protobuf：模型序列化需要 sudo apt install libprotobuf-dev protobuf-compiler -y # Eigen3：线性代数运算 sudo apt install libeigen3-dev -y # OpenBLAS：矩阵运算加速 sudo apt install libopenblas-dev -y # 验证安装 protoc --version

3. 项目配置与编译：细节决定成败

环境装好了，接下来就是配置和编译项目。这里面的细节特别多，一个参数不对就可能编译失败。

3.1 获取Retinaface+CurricularFace代码

首先得把代码弄下来。我推荐用bubbliiiing维护的这个版本，它对C++支持比较好，而且文档相对完整。

# 克隆仓库 git clone https://github.com/bubbliiiing/cv_retinaface_recognition.git cd cv_retinaface_recognition/cpp # 下载预训练模型 mkdir -p models cd models # 这里需要下载Retinaface和CurricularFace的ONNX模型 # 通常可以从ModelScope或者作者提供的链接下载 wget [Retinaface模型下载链接] wget [CurricularFace模型下载链接] cd ..

如果找不到直接的下载链接，可以先用Python版本跑一下，让它自动下载模型，然后从缓存里复制出来。模型文件通常放在~/.insightface/models/目录下。

3.2 CMakeLists.txt配置要点

项目的CMake配置需要根据你的环境调整。下面是一个比较通用的配置示例：

cmake_minimum_required(VERSION 3.18) project(RetinafaceCurricularFace) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 寻找OpenCV find_package(OpenCV REQUIRED) include_directories(${OpenCV_INCLUDE_DIRS}) # 寻找ONNX Runtime find_path(ONNXRUNTIME_INCLUDE_DIR onnxruntime_c_api.h PATHS /usr/local/include /usr/include PATH_SUFFIXES onnxruntime) find_library(ONNXRUNTIME_LIB onnxruntime PATHS /usr/local/lib /usr/lib) if(NOT ONNXRUNTIME_INCLUDE_DIR OR NOT ONNXRUNTIME_LIB) message(FATAL_ERROR "ONNX Runtime not found") endif() include_directories(${ONNXRUNTIME_INCLUDE_DIR}) # 添加可执行文件 add_executable(retinaface_demo main.cpp retinaface.cpp curricularface.cpp) target_link_libraries(retinaface_demo ${OpenCV_LIBS} ${ONNXRUNTIME_LIB} pthread openblas stdc++fs) # 安装模型文件 install(DIRECTORY models/ DESTINATION share/retinaface/models)

这里有几个关键点：

C++标准要设成17：有些现代C++特性需要这个版本
OpenCV要正确找到：如果find_package失败，可能需要手动设置OpenCV_DIR
ONNX Runtime路径要对：特别是如果你自定义了安装位置
链接库要完整：pthread和stdc++fs经常被忽略，但很重要

3.3 编译与常见错误解决

配置好了就可以编译了，但很可能会遇到一些错误。

# 创建构建目录 mkdir build && cd build # 配置 cmake .. -DCMAKE_BUILD_TYPE=Release # 编译 make -j$(nproc)

常见错误1：OpenCV找不到

CMake Error at CMakeLists.txt:10 (find_package): Could not find a package configuration file provided by "OpenCV"

解决方法：手动指定OpenCV路径

cmake .. -DOpenCV_DIR=/usr/local/lib/cmake/opencv4

常见错误2：ONNX Runtime找不到

fatal error: onnxruntime_c_api.h: No such file or directory

解决方法：确保头文件路径正确，或者手动复制到系统目录

sudo cp /path/to/onnxruntime/include/* /usr/local/include/

常见错误3：链接错误

undefined reference to `OrtGetApiBase'

解决方法：确保链接了正确的库，并且库文件存在

# 检查库文件 ls /usr/local/lib/libonnxruntime* # 如果不存在，重新安装ONNX Runtime

4. 运行测试与验证

编译通过了，还得确保能正常运行。这里我准备了一个简单的测试程序，可以验证整个流程是否正常。

4.1 基础功能测试

先写个简单的测试程序，看看基本的检测和识别功能能不能跑起来。

#include <iostream> #include <opencv2/opencv.hpp> #include "retinaface.h" #include "curricularface.h" int main() { // 初始化Retinaface RetinaFace detector; if (!detector.init("models/retinaface.onnx")) { std::cerr << "Failed to init Retinaface" << std::endl; return -1; } // 初始化CurricularFace CurricularFace recognizer; if (!recognizer.init("models/curricularface.onnx")) { std::cerr << "Failed to init CurricularFace" << std::endl; return -1; } // 读取测试图片 cv::Mat image = cv::imread("test.jpg"); if (image.empty()) { std::cerr << "Failed to read test image" << std::endl; return -1; } // 人脸检测 std::vector<FaceBox> faces; detector.detect(image, faces); std::cout << "Detected " << faces.size() << " faces" << std::endl; // 对每个检测到的人脸进行识别 for (size_t i = 0; i < faces.size(); i++) { // 裁剪人脸区域 cv::Mat face_roi = image(faces[i].rect).clone(); // 对齐（如果需要） cv::Mat aligned_face; if (faces[i].landmarks.size() == 5) { aligned_face = align_face(face_roi, faces[i].landmarks); } else { aligned_face = face_roi; } // 提取特征 std::vector<float> feature; recognizer.extract(aligned_face, feature); std::cout << "Face " << i << " feature size: " << feature.size() << std::endl; // 这里可以添加特征比对逻辑 // ... } // 可视化结果 for (const auto& face : faces) { cv::rectangle(image, face.rect, cv::Scalar(0, 255, 0), 2); for (const auto& pt : face.landmarks) { cv::circle(image, pt, 2, cv::Scalar(0, 0, 255), -1); } } cv::imwrite("result.jpg", image); std::cout << "Result saved to result.jpg" << std::endl; return 0; }

这个测试程序做了几件事：

初始化两个模型
读取测试图片
检测人脸
对每个人脸提取特征
可视化结果并保存

4.2 性能测试与优化建议

如果能跑起来，接下来可以关注一下性能。人脸识别对实时性要求比较高，特别是视频流处理场景。

// 简单的性能测试 #include <chrono> // 测试检测速度 auto start = std::chrono::high_resolution_clock::now(); detector.detect(image, faces); auto end = std::chrono::high_resolution_clock::now(); auto duration = std::chrono::duration_cast<std::chrono::milliseconds>(end - start); std::cout << "Detection time: " << duration.count() << "ms" << std::endl; // 测试识别速度 start = std::chrono::high_resolution_clock::now(); recognizer.extract(aligned_face, feature); end = std::chrono::high_resolution_clock::now(); duration = std::chrono::duration_cast<std::chrono::milliseconds>(end - start); std::cout << "Recognition time: " << duration.count() << "ms" << std::endl;

在我的测试环境（Intel i7-10700，无GPU加速）下，检测一张1080p图片大概需要80-120ms，提取一个人脸特征需要20-30ms。这个性能对于图片处理还行，但对于实时视频可能还需要优化。

优化建议：

图片缩放：如果不是必须处理原图，可以先把图片缩放到合适大小
批量处理：如果有多个脸要识别，尽量批量处理
模型量化：考虑使用INT8量化模型，速度能提升不少
GPU加速：如果硬件支持，一定要用GPU版本

5. 常见问题与解决方案

在实际部署中，我遇到了一些典型问题，这里总结一下解决方案。

5.1 模型加载失败

问题：模型文件加载失败，报错"Invalid ONNX model"可能原因：

模型文件损坏或不完整
ONNX Runtime版本与模型不兼容
模型文件路径不对

解决：

# 首先检查模型文件大小 ls -lh models/*.onnx # 正常模型文件应该在几十MB到几百MB # 如果大小异常，重新下载 # 用Python验证模型是否能加载 python -c " import onnxruntime as ort import numpy as np session = ort.InferenceSession('models/retinaface.onnx') print('Model loaded successfully') "

5.2 内存泄漏问题

问题：长时间运行后内存占用不断增长可能原因：ONNX Runtime session没有正确释放

解决：

// 确保每次使用后清理 class FaceRecognizer { private: Ort::Session* session; public: ~FaceRecognizer() { if (session) { delete session; session = nullptr; } } // 或者使用智能指针 std::unique_ptr<Ort::Session> session; };

5.3 多线程问题

问题：多线程环境下崩溃可能原因：ONNX Runtime session不是线程安全的

解决：

// 方案1：每个线程创建自己的session class ThreadSafeRecognizer { std::unordered_map<std::thread::id, std::unique_ptr<Ort::Session>> sessions; Ort::Session* getSession() { auto tid = std::this_thread::get_id(); if (sessions.find(tid) == sessions.end()) { sessions[tid] = createNewSession(); } return sessions[tid].get(); } }; // 方案2：加锁保护 class LockedRecognizer { std::mutex mtx; Ort::Session* session; void extract(cv::Mat& face, std::vector<float>& feature) { std::lock_guard<std::mutex> lock(mtx); // 使用session进行推理 } };

5.4 跨平台编译问题

问题：在Linux上编译正常，换到Windows就各种错误可能原因：路径分隔符、库依赖、编译器差异

解决：

# 在CMakeLists.txt中处理平台差异 if(WIN32) # Windows特定设置 set(ONNXRUNTIME_LIB "onnxruntime.lib") set(OPENCV_DLL_PATH "${OpenCV_DIR}/bin") elseif(UNIX) # Linux特定设置 set(ONNXRUNTIME_LIB "onnxruntime") endif() # 处理路径分隔符 if(WIN32) set(MODEL_PATH "models\\retinaface.onnx") else() set(MODEL_PATH "models/retinaface.onnx") endif()