虹软人脸服务器SDK-C++语言Demo实操指南
1. 部署背景与环境概述
1.1 部署背景
在开发基于Linux服务器的人脸识别系统时，虹软ArcFaceServer SDK 提供了高性能的离线人脸识别能力。本文将带你从零开始，在 Linux x64 环境 中完成 C++ Demo 的编译与运行，涵盖人脸检测、特征提取、人脸比对、活体检测、年龄/性别识别、口罩检测等核心功能。
1.2 环境架构说明
| 层级 | 说明 |
|---|---|
| 操作系统 | Linux x64（推荐 Ubuntu 18.04 / CentOS 7 及以上） |
| 编译工具 | GCC 4.8.2+ / CMake 3.0+ |
| 运行库 | GLIBC 2.17+ / GLIBCXX 3.4.19+ |
| SDK版本 | ArcSoft_ArcFacePro_linuxPro_V5.0 |
2. 环境依赖与版本检查
在正式部署前，务必确认系统满足以下依赖要求。
2.1 查看 GLIBC 版本
SDK 要求 GLIBC 不低于 2.17，执行以下命令检查：
strings /usr/lib/x86_64-linux-gnu/libc.so.* | grep GLIBC_ | sort -V
期望输出示例：
⚠️ 若输出中无
GLIBC_2.17及以上版本，需升级系统或更换兼容的 Linux 发行版。
2.2 查看 GLIBCXX 版本
SDK 要求 GLIBCXX 不低于 3.4.19：
strings /usr/lib/x86_64-linux-gnu/libstdc++.so.* | grep GLIBCXX | sort -V
期望输出示例：
⚠️ 若输出中无 GLIBCXX_3.4.19 及以上版本，需升级系统或更换兼容的 Linux 发行版。
2.3 查看 GCC 版本
gcc --version
期望输出示例：
要求 GCC 4.8.2 及以上，推荐 7.x 版本。
2.4 查看 CMake 版本
cmake --version
期望输出示例：
要求 CMake 3.0 及以上，cmake版本的升级和安装可以参考：Linux安装或者升级cmake，例子为v3.10.2升级到v3.25.0(自己指定版本)_linux 升级cmake-CSDN博客。
3. SDK 部署与Demo工程准备
3.1 下载SDK包
从虹软开发者中心下载 ArcSoft_ArcFacePro_linuxPro_V5.0 版本，解压后目录结构如下：
ArcSoft_ArcFacePro_linuxPro_V5.0/
├── doc
│ ├── ARCSOFT_ARC_FACE_DEVELOPER'S_GUIDE.pdf
│ ├── 虹软视觉开放平台服务协议.pdf
│ └── 隐私政策.pdf
├── inc
│ ├── amcomdef.h
│ ├── arcsoft_face_sdk.h
│ ├── asvloffscreen.h
│ └── merror.h
├── lib
│ └── linux_x64
│ ├── libarcsoft_face_engine.so
│ └── libarcsoft_face.so
├── releasenotes.txt
└── samplecode
├── ASFTestDemo
│ ├── CMakeLists.txt
│ ├── images
│ │ ├── 640x480_1.NV21
│ │ ├── 640x480_2.NV21
│ │ └── 640x480_3.NV21
│ ├── inc
│ │ ├── amcomdef.h
│ │ ├── arcsoft_face_sdk.h
│ │ ├── asvloffscreen.h
│ │ └── merror.h
│ └── samplecode.cpp
└── ReadMe.txt
3.2 配置Demo工程
步骤 a：拷贝动态库
在Demo工程下新建一个linux_so文件夹，并将 SDK 包 lib/ 目录下的两个 .so 文件拷贝到 Demo 工程的 linux_so/ 目录下：
mkdir -p ASFTestDemo/linux_so/
cp ArcSoft_ArcFacePro_linuxPro_V5.0/linux_x64/lib/*.so ASFTestDemo/linux_so/
步骤 b：更新头文件（建议）
将 SDK 包 inc/ 目录下的所有 .h 文件替换到 Demo 工程的 inc/ 目录下：
cp ArcSoft_ArcFacePro_linuxPro_V5.0/linux_x64/inc/*.h ASFTestDemo/inc/
步骤 c：配置激活密钥
打开 samplecode.cpp，将以下三个宏替换为从虹软官网获取的真实密钥：
define APPID "Bbvyu5GeUE8eaBhyLsNcp49HW6tuPx3sqWog8i9S41Q7"
define SDKKEY "EvvwdWPFj7XjL1siCQiSD2qGb9XanUowPRYyVML8o3wL"
define ACTIVEKEY "8281-1111-M125-XXKM"
⚠️ 上述为示例假数据，必须替换为真实密钥，否则激活会失败。
4. 编译与运行Demo
4.1 创建编译目录
cd ASFTestDemo
mkdir build
cd build
4.2 执行 CMake 编译
cmake ..
期望输出：
4.3 执行 Make 编译
make
期望输出：
4.4 运行Demo程序
在build文件夹下，配置虹软SDK库的环境变量并运行demo程序
export LD_LIBRARY_PATH=$PWD/../linux_so/:$LD_LIBRARY_PATH
./arcsoft_face_engine_test
当出现以下打印输出后，代表demo程序运行成功，demo中实现了人脸特征提取，年龄，性别等属性的检测
5. Demo功能详解与代码解析
5.1 核心功能流程图
┌─────────────────────────────────────────────────────────────┐
│ ArcFaceServer Demo 流程 │
├─────────────────────────────────────────────────────────────┤
│ 1. 获取SDK信息（设备信息/激活文件/版本号） │
│ 2. 在线激活（ASFOnlineActivation） │
│ 3. 初始化引擎（ASFInitEngine） │
│ 4. 加载图像数据（NV21格式裸数据） │
│ 5. 人脸检测（ASFDetectFacesEx） │
│ 6. 特征提取与注册（ASFFaceFeatureExtractEx + 注册） │
│ 7. 人脸比对（ASFFaceFeatureCompare_Search） │
│ 8. 属性检测（年龄/性别/活体/口罩） │
│ 9. 红外活体检测（ASFProcessEx_IR） │
│ 10. 释放资源（ASFUninitEngine） │
└─────────────────────────────────────────────────────────────┘
5.2 关键代码解析
5.2.1 SDK 激活与引擎初始化
// 在线激活（首次运行需要联网）
MRESULT res = ASFOnlineActivation(APPID, SDKKEY, ACTIVEKEY);
if (MOK != res && MERR_ASF_ALREADY_ACTIVATED != res) {
printf("ASFOnlineActivation fail: %d\n", res);
}
// 初始化引擎，启用多种功能
MInt32 mask = ASF_FACE_DETECT | ASF_FACERECOGNITION | ASF_AGE | ASF_GENDER |
ASF_LIVENESS | ASF_IR_LIVENESS | ASF_MASKDETECT | ASF_IMAGEQUALITY;
res = ASFInitEngine(ASF_DETECT_MODE_IMAGE, ASF_OP_0_ONLY,
ASF_MAX_DETECTFACENUM, mask, ASF_REC_LARGE, &handle);
5.2.2 图像颜色格式转换
Demo 支持多种图像格式，核心函数 ColorSpaceConversion 处理 NV21、I420、RGB24、GRAY 等格式：
// NV21 格式：YUV 420 SP，广泛应用于Android摄像头采集
case ASVL_PAF_NV21:
offscreen.pi32Pitch[0] = offscreen.i32Width; // Y 分量步长
offscreen.pi32Pitch[1] = offscreen.pi32Pitch[0]; // UV 分量步长
offscreen.ppu8Plane[0] = imgData; // Y 数据起始
offscreen.ppu8Plane[1] = imgData + Width * Height; // UV 数据起始
break;
5.2.3 人脸检测与特征提取
// 检测人脸
ASF_MultiFaceInfo detectedFaces = { 0 };
res = ASFDetectFacesEx(handle, &offscreen, &detectedFaces);
// 提取单个人脸特征（注册模式）
ASF_SingleFaceInfo singleFace = { 0 };
singleFace.faceRect = detectedFaces.faceRect[0];
singleFace.faceOrient = detectedFaces.faceOrient[0];
ASF_FaceFeature feature = { 0 };
res = ASFFaceFeatureExtractEx(handle, &offscreen, &singleFace,
ASF_REGISTER, 0, &feature);
5.2.4 人脸特征注册与比对
// 注册人脸特征到引擎
ASF_FaceFeatureInfo faceFeatureInfo = {0};
faceFeatureInfo.searchId = 1; // 人脸ID
faceFeatureInfo.feature = &feature; // 特征数据
ASFRegisterFaceFeature(handle, &faceFeatureInfo, 1);
// 1:N 搜索比对
ASF_FaceFeatureInfo matchedInfo = {0};
MFloat confidenceLevel = 0.0f;
res = ASFFaceFeatureCompare_Search(handle, &feature2, &confidenceLevel, &matchedInfo);
// confidenceLevel 为相似度得分，阈值通常设为 0.8
5.2.5 属性检测（年龄/性别/活体/口罩）
// 处理人脸，获取多种属性
MInt32 processMask = ASF_AGE | ASF_GENDER | ASF_LIVENESS | ASF_MASKDETECT;
res = ASFProcessEx(handle, &offscreen, &detectedFaces, processMask);
// 获取年龄
ASF_AgeInfo ageInfo = { 0 };
ASFGetAge(handle, &ageInfo);
printf("Age: %d\n", ageInfo.ageArray[0]);
// 获取性别
ASF_GenderInfo genderInfo = { 0 };
ASFGetGender(handle, &genderInfo);
printf("Gender: %d\n", genderInfo.genderArray[0]); // 0-男, 1-女
// 获取活体信息
ASF_LivenessInfo livenessInfo = { 0 };
ASFGetLivenessScore(handle, &livenessInfo);
printf("Liveness: %d\n", livenessInfo.isLive[0]); // 0-非活体, 1-活体
// 获取口罩信息
ASF_MaskInfo maskInfo = { 0 };
ASFGetMask(handle, &maskInfo);
printf("Mask: %d\n", maskInfo.maskArray[0]); // 0-未戴口罩, 1-戴口罩
5.2.6 红外活体检测
// 红外图像使用 GRAY 格式
ColorSpaceConversion(Width, Height, ASVL_PAF_GRAY, imageData, offscreen);
// 检测红外图像中的人脸
ASFDetectFacesEx(handle, &offscreen, &detectedFaces);
// 红外活体检测
ASFProcessEx_IR(handle, &offscreen, &detectedFaces, ASF_IR_LIVENESS);
// 获取红外活体结果
ASF_LivenessInfo irLivenessInfo = { 0 };
ASFGetLivenessScore_IR(handle, &irLivenessInfo);
printf("IR Liveness: %d\n", irLivenessInfo.isLive[0]);
6. 运行结果示例
Demo 运行后，终端输出如下：
************* ArcFace SDK Info *****************
ASFGetActiveDeviceInfo sucess: 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
startTime: 2026-04-14 09:48:43
endTime: 2026-07-13 09:48:43
Version:5.0.12402010210.17
BuildDate:09/11/2025
CopyRight:Copyright 2025 ArcSoft Corporation Limited. All rights reserved.
************* Face Recognition *****************
ASFOnlineActivation sucess: 90114
ASFInitEngine sucess: 0
ASFGetMask sucessed: 0
ASFImageQualityDetectEx sucessed: 0.623884
ASFFaceFeatureCompare_Search success: 0.113103
************* Face Process *****************
ASFProcessEx sucess: 0
../images/640x480_2.NV21 First face age: 23
../images/640x480_2.NV21 First face gender: 1
ASFGetLivenessScore sucess: 1
Mask: 0
IR LIVENESS***
Face num: 1
ASFProcessEx_IR sucess: 0
IR Liveness: 1
ASFUninitEngine sucess: 0
7. 注意事项
| 序号 | 注意事项 |
|---|---|
| a | Demo 提供的测试图片为 NV21 格式裸数据，保存在 images/ 目录下，非标准图片格式（如 JPG/PNG）需先解码转换 |
| b | 图片宽度必须是 4 的倍数；I420/NV21/NV12/GRAY 格式高度为 2 的倍数；BGR24 格式高度不限制 |
| c | JPG 等格式读图需做图像解码，推荐使用 OpenCV 第三方库进行读取和格式转换 |
| d | 特征提取后务必拷贝 feature 数据，否则第二次提取会覆盖第一次的数据，导致比对结果异常 |
| e | 注册照（ASF_REGISTER）要求不戴口罩，识别照（ASF_RECOGNITION）支持戴口罩 |
| f | 活体检测置信度可通过 ASFSetLivenessParam 设置，SDK 内部默认值 RGB: 0.5 / IR: 0.5 |
| g | 离线激活需先调用 ASFGetActiveDeviceInfo 获取设备信息，在官网生成激活文件后使用 ASFOfflineActivation |
8. 常见问题排查
执行demo时报无法找到so库
出现该问题的原因是运行前未配置环境变量，需要将虹软SDK的路径配置到环境中去，再执行就可以正常运行。
demo运行在线激活时返回98310（0x18006）
查阅错误码发现，该错误意味着ACTIVEKEY信息异常，阅读samplecode发现为对应的APPID, SDKKEY, ACTIVEKEY没有替换到官网获取的授权密钥，替换后可以正常激活。
9. 总结
本文完整演示了虹软 ArcFaceServer 1.0 SDK Linux_x64 版本的 C++ Demo 部署流程，涵盖：
- 环境依赖检查（GLIBC/GLIBCXX/GCC/CMake）
- SDK 激活与引擎初始化
- 人脸检测、特征提取、1:N 比对
- 年龄/性别/活体/口罩属性检测
- 红外活体检测
- 资源释放与注意事项
在实际项目中，可将 Demo 中的核心逻辑封装为服务端 API，结合 OpenCV 实现图像解码，构建完整的人脸识别服务器系统。
浙公网安备 33010602011771号