虹软人脸服务器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，执行以下命令检查：

bash 复制代码

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：

bash 复制代码

strings /usr/lib/x86_64-linux-gnu/libstdc++.so.* | grep GLIBCXX | sort -V

期望输出示例：

⚠️ 若输出中无 GLIBCXX_3.4.19 及以上版本，需升级系统或更换兼容的 Linux 发行版。

2.3 查看 GCC 版本

css 复制代码

gcc --version

期望输出示例：

要求 GCC 4.8.2 及以上，推荐 7.x 版本。

2.4 查看 CMake 版本

css 复制代码

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 版本，解压后目录结构如下：

vbnet 复制代码

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/ 目录下：

bash 复制代码

mkdir -p ASFTestDemo/linux_so/
cp ArcSoft_ArcFacePro_linuxPro_V5.0/linux_x64/lib/*.so ASFTestDemo/linux_so/

步骤 b：更新头文件（建议）

将 SDK 包 inc/ 目录下的所有 .h 文件替换到 Demo 工程的 inc/ 目录下：

bash 复制代码

cp ArcSoft_ArcFacePro_linuxPro_V5.0/linux_x64/inc/*.h ASFTestDemo/inc/

步骤 c：配置激活密钥

打开 samplecode.cpp，将以下三个宏替换为从虹软官网获取的真实密钥：

arduino 复制代码

#define APPID "Bbvyu5GeUE8eaBhyLsNcp49HW6tuPx3sqWog8i9S41Q7"
#define SDKKEY "EvvwdWPFj7XjL1siCQiSD2qGb9XanUowPRYyVML8o3wL"
#define ACTIVEKEY "8281-1111-M125-XXKM"

⚠️ 上述为示例假数据，必须替换为真实密钥，否则激活会失败。

4. 编译与运行Demo

4.1 创建编译目录

bash 复制代码

cd ASFTestDemo
mkdir build
cd build

4.2 执行 CMake 编译

erlang 复制代码

cmake ..

期望输出：

4.3 执行 Make 编译

go 复制代码

make

期望输出：

4.4 运行Demo程序

在build文件夹下，配置虹软SDK库的环境变量并运行demo程序

bash 复制代码

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 激活与引擎初始化

ini 复制代码

// 在线激活（首次运行需要联网）
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 等格式：

scss 复制代码

// 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 人脸检测与特征提取

ini 复制代码

// 检测人脸
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 人脸特征注册与比对

ini 复制代码

// 注册人脸特征到引擎
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 属性检测（年龄/性别/活体/口罩）

ini 复制代码

// 处理人脸，获取多种属性
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 红外活体检测

scss 复制代码

// 红外图像使用 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 运行后，终端输出如下：

markdown 复制代码

************* ArcFace SDK Info *****************
ASFGetActiveDeviceInfo sucess: AaDLBlSLo1VsidZ8dwgn0NwTynmYQeEVpt4w+JvOkVdcgkt+v6DmghhPZe2FfolfbhNLnXRJwqn3Y/J7pRnExQ2xaji2TMjIbEoLSE4gt+4TC5TwqC9KjGbP17G1w7cz6Iunf4TLDnFtGuyv9kGMKqTKIlHTceojrgBk/PQUvGEwpxryfDuCHiJcatFrNZgYq3bWsIGhEeiJSe/ayt9ZvVm5d+8aGOBh5u22N2pUFwoIcevL3QgcpebqDiP8DLXuD0E/5+zjkNAgV8gPyQf0D2sT5Dbm8DL+nLO8hB7O0Ev33t/I7KEd4e6J3uRuf20FPT1gOHxVX8GO3XDWpFtoycAGRViM0LYtqfYq1khEKrbJ5+0nktU7rybkETjfwAfHChGTEadf4PTMyWSv0IY9KWz2r4TmIOOqgSmuI2fxnkiIk6U6TJ1XlxzZu5GkhsrP310gcMsxatM4Lxo+Muj+FhJ4VzmBdKMJGLwyuPUawN+HxMDde2k3u2a4JuUsV8OHc+PyXPVO+NGnthRpgA4IIOzfDs4cT1a2WF0Wd5iGZtmLEomJo+/nqsbEvnb4dVaijub1Hy1gDqqf5F/bEphR0QPvwaxM7MKUVCy2M9xGLTMw1QtED+94r1g2VDuVhDDu0zjN35Q+dXnh8fbdesACgvhNSioIV7JRQSfOTZPk4KMrjmNbQF3jhThYij0xvVey1gi+ho5uaCGR+6lFzS4xOvhldjfCnT934uKebl3O90rs40LXbDQ4y+pit8XC8HkJccc74PilDnfd7ADSqlL45ZELT1wUJhgIH3wLm0HccCbLHqTFvPzCbmbF2nx/DNctHCtVO7Hbb4wjtLo0J5F2bcS6z5cNq8jmUDjDHyXaQ/K2LG2ULyMMDHoQuj0IsAFiz4joyGdS+wedKCsVeKSgE5S0HuXlJSsYFnCSIjxEb7Fg6I8ShK73amCVquSOMxUQwlQqzdrdHD9LXbeZyCvqJ1OqulXrBZRczvKLsT/ftMyyN2kY++P9Ku+HR3r52sxCbssT0OIn+vZscoDXQ5FB889ml9uLH3e4V5DbErz1X4woe5ManTXAJC7koiqlV0rEI7g+ciI101nBv6Q6UgAG8cPPHYb0vR9A6VkeTeKwesPcMHPx31KMoQMpavq7WLoEmLA67dqlrzwzugEYo6+ZwnxPDL1OKxlS388+t50pGtM1Trszn5GPtM+o0J34hBHJ3NtCy6UzSkFwKcp8BQ19TcGEYMEA8NEaIEfa05l76k80IB0qlofWqoE3YReEcGCySicVbQ6uJ4wVkeNEGrpSzwDUkjVZp1UC6uNSBvdWtbNVfdYHbrGC/9kBfFJiYOkv8VqBNeH8tAiQW5aIgLN+AwHKxdUE8EcTIsceqWcXikvOHYz8KMUucoGrrHIIRAmrg/nOG641EtNDBRH+Ok0psESAVJpxnsJq/cXS/rPA6FpyjRzo+NtsLI258UBzCX8srcepzZzXg8SZoqRs03D8F6PWCxuPp6A9Pa+uuys3l4nLPos4QYdiWvtsl3NchY21y1JIpeafQ6Tf7F1TpXxil9W/zXEmpS2WFACVn+kWbbHH82pPvGYzaGfEaVd+EakbI/QxekgGMDIWfPxKU9cKuk4wv4nF1BeXJyX96Yd9/6dPyc3XFqLArYBkk+gjAAR0HCGKi6aPtnC0hB80mgsp6XcFVTMnH0mSVCIin3Zh55GVb9c3QN7cQiLSKQ9BnbUzb99s8rAL5d6x4iEEmbYliT2bfG0QKbRg1hnrLCiGHg1lHz2AiChjSrzZm5zSK8lpZdlOUtvk+9swvprOSh6T7Qs4SUCARuzRAqVc0taqlZr/wJbslyQHfpIXyXNiZkLPRcAbF9Ygs4B68uXpNQdp8AfCDAiJfx5mLSaP7zG/yhxXgHxvo795rfj88X3PTkzOW4IqLMpqxP+VQXxMjh2kbVjLKRqxsXxpqC8jj6tmo3+bHRFtI5M0Wg30PsT/l2MUzriDprPJPVvdhCxtEDJ6rHgANSFZCSNd2tplcY0ohhOE7fB/joM6QMKjyO1shedh
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 实现图像解码，构建完整的人脸识别服务器系统。