1. 部署背景与环境概述
1.1 部署背景
RV1126B 是瑞芯微(Rockchip)面向 AIoT 视觉应用推出的 SoC,集成 ARM Cortex-A7 四核 CPU + 2 TOPS NPU,凭借其低成本、低功耗的优势,被广泛用于 IPC、门禁、考勤机、刷脸支付等边缘人脸识别设备。
虹软 ArcFace SDK(ARCSOFT_ARCFACE_LINUX_ARM64_RV1126BP_V5.0) 提供了高性能的离线人脸识别能力,算法通过 RKNN(Rockchip NPU 运行时) 在 RV1126B 的 NPU 上加速推理。本文将带你从零开始,完成该 SDK 自带 C++ Demo(ASFTestDemo)的交叉编译 与板端运行,涵盖人脸检测、特征提取、人脸注册与 1:N 比对、年龄/性别/活体/口罩检测、红外活体检测等核心功能。
1.2 环境架构说明
与 x64 服务器版 SDK 不同,RV1126B 版 SDK 面向嵌入式目标板,必须在 x86 主机上交叉编译,再把产物拷贝到板端运行:
| 层级 | 说明 |
|---|---|
| 编译主机 | Linux x86_64(推荐 Ubuntu 18.04 / CentOS 7 及以上) |
| 交叉编译工具链 | aarch64-linux-gnu-gcc(SDK 配套 gcc-linaro-6.3.1-2017.05,GCC 4.8.2+) |
| 构建工具 | CMake 3.0 及以上 |
| 目标板 | Linux arm64(RV1126B 平台),GLIBC 2.17+ / GLIBCXX 3.4.21+ |
| NPU 运行时 | librknnrt.so(板端 RKNN 运行时,libarcsoft_face.so 的强依赖) |
| SDK 版本 | ArcSoft ArcFace V5.0(5.0.29325010218.25,2026-05-28 发布) |
2. 环境依赖与版本检查
在正式部署前,务必确认主机 与板端两侧环境都满足依赖要求。
2.1 交叉编译工具链检查(主机侧)
SDK 的 CMakeLists.txt 默认使用以下工具链(Demo 中已配置好):
bash
/opt/toolchain/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu-gcc
确认工具链已安装:
bash
aarch64-linux-gnu-gcc --version
⚠️ 若你的工具链路径不同,需要修改
CMakeLists.txt(详见 4.1 节),否则cmake ..会报找不到编译器。
2.2 板端 GLIBC / GLIBCXX 版本检查
SDK 要求板端 GLIBC 不低于 2.17、GLIBCXX 不低于 3.4.21。在板端执行:
bash
strings /lib/aarch64-linux-gnu/libc.so.* | grep GLIBC_ | sort -V
strings /lib/aarch64-linux-gnu/libstdc++.so.* | grep GLIBCXX | sort -V
期望输出示例:
erlang
GLIBC_2.17
...
GLIBCXX_3.4.21
...
⚠️ 若输出中无
GLIBC_2.17、GLIBCXX_3.4.21及以上版本,需升级板端系统或更换兼容的固件。
2.3 CMake 版本检查(主机侧)
bash
cmake --version
要求 CMake 3.0 及以上。版本过低可参考 Linux 安装或升级 cmake。
2.4 NPU 运行时 librknnrt.so 检查(板端)
RV1126B 版算法的核心特点是依赖 RKNN NPU 运行时 。通过 readelf 查看动态库依赖可以确认:
bash
readelf -d libarcsoft_face.so | grep NEEDED
输出示例:
ini
0x0000000000000001 (NEEDED) Shared library: [librknnrt.so]
0x0000000000000001 (NEEDED) Shared library: [libpthread.so.0]
0x0000000000000001 (NEEDED) Shared library: [libstdc++.so.6]
...
在板端确认运行时存在:
bash
ls -l /usr/lib/librknnrt.so
⚠️
librknnrt.so由瑞芯微 SDK/固件提供(通常在板端/usr/lib/下)。它既是编译期链接依赖 (CMakeLists.txt中链接了rknnrt),也是运行期依赖,缺失会导致 demo 无法运行(详见 8. 常见问题排查)。
3. SDK 部署与 Demo 工程准备
3.1 SDK 包结构
解压 ARCSOFT_ARCFACE_LINUX_ARM64_RV1126BP_V5.0.zip,目录结构如下:
ini
ARCSOFT_ARCFACE_LINUX_ARM64_RV1126BP_V5.0/
├── doc
│ ├── ARCSOFT_ARC_FACE_DEVELOPER'S_GUIDE.pdf
│ └── 隐私政策.pdf
├── inc
│ ├── amcomdef.h
│ ├── arcsoft_face_sdk.h
│ ├── asvloffscreen.h
│ └── merror.h
├── lib
│ └── rv1126bp_arm64
│ ├── libarcsoft_face_engine.so # 引擎库
│ └── libarcsoft_face.so # 算法库(依赖 librknnrt.so)
├── releasenotes.txt
└── samplecode
├── ASFTestDemo
│ ├── CMakeLists.txt # 已内置交叉编译配置
│ ├── images
│ │ ├── 640x480_1.NV21 # 可见光注册照
│ │ ├── 640x480_2.NV21 # 可见光识别照
│ │ └── 640x480_3.NV21 # 红外照(取前 2/3 作为灰度图)
│ ├── inc
│ └── samplecode.cpp
└── ReadMe.txt
注意库目录是
lib/rv1126bp_arm64/(ARM64 架构),而非 x64 版的linux_x64/。
3.2 配置 Demo 工程
步骤 a:拷贝动态库
在 Demo 工程下新建 linux_so 文件夹,将 SDK 包 lib/rv1126bp_arm64/ 下的两个 .so 文件拷贝进去,同时把板端的 librknnrt.so 也拷入(供链接使用):
bash
mkdir -p ASFTestDemo/linux_so/
cp ARCSOFT_ARCFACE_LINUX_ARM64_RV1126BP_V5.0/lib/rv1126bp_arm64/*.so ASFTestDemo/linux_so/
cp /板端获取的路径/librknnrt.so ASFTestDemo/linux_so/
步骤 b:更新头文件(建议)
将 SDK 包 inc/ 目录下的 .h 文件替换到 Demo 工程的 inc/ 目录下:
bash
cp ARCSOFT_ARCFACE_LINUX_ARM64_RV1126BP_V5.0/inc/*.h ASFTestDemo/inc/
步骤 c:配置激活密钥
打开 samplecode.cpp,将以下三个宏替换为从虹软开发者中心获取的真实密钥(SDK 包中自带的是测试数据):
cpp
#define APPID "EXnv3N55pz6Sz1HJz2jqYmAcJNEPVVEbieqFQ7sjRzLq"
#define SDKKEY "EgJh9s1ZsKs9qjDxYsUcinbVFUu7k51Kk7AfY83NXvJT"
#define ACTIVEKEY "U9W1-11TW-911A-6JJC"
⚠️ 包内为示例假数据,必须替换为真实密钥,否则激活会失败(见 8. 常见问题排查)。
4. 交叉编译与运行 Demo
4.1 适配 CMakeLists.txt 工具链路径
CMakeLists.txt 中交叉编译工具链路径是写死的,若你的工具链不在 /opt/toolchain 下,需先修改:
cmake
#这里配置rv1126bp交叉编译环境
set(TOOLCHAIN "/opt/toolchain/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu/bin")
set(PREFIX "${TOOLCHAIN}/aarch64-linux-gnu")
set(TOOLCHAIN_CC "${PREFIX}-gcc")
set(TOOLCHAIN_CXX "${PREFIX}-g++")
将其改为你本机的工具链实际路径(如 /home/kongluchao/toolchain/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu/bin)。
4.2 执行 CMake 编译
bash
cd ASFTestDemo
mkdir build
cd build
cmake ..
期望输出:
lua
-- The C compiler identification is GNU 6.3.1
-- The CXX compiler identification is GNU 6.3.1
-- Check for working C compiler: .../aarch64-linux-gnu-gcc
-- Check for working C compiler: .../aarch64-linux-gnu-gcc -- works
...
-- Configuring done
-- Generating done
4.3 执行 Make 编译
bash
make
期望输出:
css
Scanning dependencies of target arcsoft_face_engine_test
[ 50%] Building CXX object CMakeFiles/arcsoft_face_engine_test.dir/samplecode.cpp.o
[100%] Linking CXX executable arcsoft_face_engine_test
生成的可执行文件为 arcsoft_face_engine_test,用 file 确认是 ARM64 程序:
bash
file arcsoft_face_engine_test
# ELF 64-bit LSB executable, ARM aarch64, ...
4.4 部署到板端运行
将整个工程目录(可执行文件 + images/ + linux_so/)拷贝到板端(scp / adb / NFS 均可):
bash
# 以 scp 为例
scp -r ASFTestDemo root@<板端IP>:/root/
在板端进入 build 目录,配置虹软 SDK 库与 RKNN 运行时路径,运行 demo:
bash
cd /root/ASFTestDemo/build
export LD_LIBRARY_PATH=$PWD/../linux_so/:/usr/lib/:$LD_LIBRARY_PATH
./arcsoft_face_engine_test
LD_LIBRARY_PATH必须同时包含linux_so/(虹软库)与板端librknnrt.so所在目录,二者缺一不可。另外注意:demo 末尾有
getchar(),程序会等待输入回车后才退出 (板端无键盘时可先echo重定向输入)。
当出现类似 6 节的打印输出后,代表 demo 程序运行成功。
5. Demo 功能详解与代码解析
5.1 核心功能流程

5.2 关键代码解析
5.2.1 SDK 激活与引擎初始化
cpp
// 在线激活(首次运行需要板端联网)
MRESULT res = ASFOnlineActivation(APPID, SDKKEY, ACTIVEKEY);
// 已激活(MERR_ASF_ALREADY_ACTIVATED)不算错误
if (MOK != res && MERR_ASF_ALREADY_ACTIVATED != res)
printf("ASFOnlineActivation failed: %x\n", res);
// 初始化引擎,启用检测/识别/图像质量/年龄/性别/活体/红外活体/口罩
MInt32 initMask = ASF_FACE_DETECT | ASF_FACERECOGNITION | ASF_IMAGEQUALITY |
ASF_AGE | ASF_GENDER | ASF_LIVENESS | ASF_IR_LIVENESS |
ASF_MASKDETECT;
res = ASFInitEngine(ASF_DETECT_MODE_IMAGE, ASF_OP_0_ONLY, FACENUM, initMask, &handle);
5.2.2 图像颜色格式转换
Demo 核心函数 ColorSpaceConversion 负责把裸数据包装成 SDK 需要的 ASVLOFFSCREEN 结构,支持 NV21、I420、RGB24、GRAY 等格式:
cpp
case ASVL_PAF_NV12:
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] = offscreen.ppu8Plane[0] +
offscreen.pi32Pitch[0] * offscreen.i32Height; // UV 数据起始
break;
5.2.3 人脸检测与特征提取
cpp
// 检测人脸
ASF_MultiFaceInfo detectedFaces = { 0 };
res = ASFDetectFacesEx(handle, &offscreen, &detectedFaces);
// 取第一张人脸,用于特征提取
ASF_SingleFaceInfo singleFace = { 0 };
singleFace.faceRect = detectedFaces.faceRect[0];
singleFace.faceOrient = detectedFaces.faceOrient[0];
singleFace.faceDataInfo = detectedFaces.faceDataInfoList[0];
// 注册模式提取特征:ASF_REGISTER(注册)与 ASF_RECOGNITION(识别)
// 是两种不同的特征提取模式,注册要求不戴口罩(mask 标志传 0)
ASF_FaceFeature feature = { 0 };
res = ASFFaceFeatureExtractEx(handle, &offscreen, &singleFace,
ASF_REGISTER, 0, &feature);
⚠️ 注册与识别的特征提取存在区别 :
ASFFaceFeatureExtractEx的最后一个模式参数决定了特征提取的方式,注册(ASF_REGISTER)和识别(ASF_RECOGNITION)是两种不同的特征提取模式,不能混用:
- 注册模式(ASF_REGISTER):注册照入库时使用,要求不戴口罩,mask 标志传 0;
- 识别模式(ASF_RECOGNITION) :识别照提取时使用,需传入口罩检测结果
maskInfo.maskArray[0](识别照允许戴口罩)。两种模式提取的特征均为 2048 维,但提取方式不同,比对时必须用识别模式(ASF_RECOGNITION)提取的特征,去匹配注册库中注册模式(ASF_REGISTER)入库的特征,二者不能颠倒或混用。
5.2.4 人脸特征注册与 1:N 比对
cpp
// feature2 为识别模式(ASF_RECOGNITION)提取的识别特征,
// 与上述注册模式入库的特征进行 1:N 比对
// 注册人脸特征到引擎(searchId 唯一标识、tag 为备注)
ASF_FaceFeatureInfo faceFeatureInfo = { 0 };
faceFeatureInfo.searchId = g_search_id++;
faceFeatureInfo.feature = &feature;
faceFeatureInfo.tag = "1111111";
ASFRegisterFaceFeature(handle, &faceFeatureInfo, 1);
// 1:N 搜索比对
MFloat confidenceLevel = 0.0f;
ASF_FaceFeatureInfo matchedInfo = { 0 };
res = ASFFaceFeatureCompare_Search(handle, &feature2, &confidenceLevel, &matchedInfo);
// TopN 比对,返回按置信度排序的前 faceNum 条结果
LPASF_FaceFeatureSearchResult pSearchRes = new ASF_FaceFeatureSearchResult[faceNum];
res = ASFFaceFeatureCompare_Search_TopN(handle, &feature2, faceNum,
pSearchRes, ASF_LIFE_PHOTO);
confidenceLevel 为相似度得分(0~1),实际项目中通常按业务需求设阈值(如 0.8)。
5.2.5 属性检测(年龄/性别/活体/口罩)
cpp
// 处理人脸,获取多种属性
MInt32 processMask = ASF_AGE | ASF_GENDER | ASF_LIVENESS | ASF_MASKDETECT;
res = ASFProcessEx(handle, &offscreen, &detectedFaces, processMask);
// 获取年龄
ASF_AgeInfo ageInfo = { 0 };
ASFGetAge(handle, &ageInfo);
printf("First face age: %d\n", ageInfo.ageArray[0]);
// 获取性别(0-男,1-女)
ASF_GenderInfo genderInfo = { 0 };
ASFGetGender(handle, &genderInfo);
printf("First face 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]);
5.2.6 图像质量检测与红外活体检测
cpp
// 图像质量检测,confidenceLevel 为质量得分
MFloat confidenceLevel = 0.0f;
res = ASFImageQualityDetectEx(handle, &offscreen, &singleFace, &confidenceLevel);
// 红外图像读取 NV21 前 2/3 数据作为 GRAY 灰度图
fread(imageData3, 1, Height3 * Width3, fp3); // 只读 NV21 的 Y 分量
ColorSpaceConversion(Width3, Height3, ASVL_PAF_GRAY, imageData3, 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]);
5.2.7 活体阈值设置与资源释放
cpp
// 设置活体置信度,SDK 内部默认值 IR:0.5 RGB:0.5(无特殊需要可不设置)
ASF_LivenessThreshold threshold = { 0 };
threshold.thresholdmodel_BGR = 0.5;
threshold.thresholdmodel_IR = 0.5;
ASFSetLivenessParam(handle, &threshold);
// 反初始化引擎
ASFUninitEngine(handle);
6. 运行结果示例
Demo 运行成功后,板端终端输出如下(数值因图片/设备而异):
markdown
************* ArcFace SDK Info *****************
ASFOnlineActivation sucess************: 0
ASFGetActiveDeviceInfo sucess: <设备信息字符串>
startTime: 2026-05-28 10:00:00
endTime: 2026-08-28 10:00:00
Version:5.0.29325010218.25
BuildDate:2026/05/28
CopyRight:Copyright 2026 ArcSoft Corporation Limited. All rights reserved.
************* Face Recognition *****************
ASFOnlineActivation sucess: 0
ASFInitEngine sucess: 0
figure 1 feature size: 2048
face num: 1
ASFGetMask sucessed: 0
ASFImageQualityDetectEx sucessed: 0.623884
ASFFaceFeatureCompare_Search success: 0.867125
confidence:0.867125
tag:1111111
search id:0
feature size :2048
-------------------------
************* 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
其中 ASFFaceFeatureCompare_Search success: 0.867125 表示识别照与注册照的相似度得分,越接近 1 说明是同一个人。
7. 注意事项
| 序号 | 注意事项 |
|---|---|
| a | Demo 提供的测试图片为 NV21 格式裸数据(640x480,大小 460800 字节),保存在 images/ 目录下;JPG/PNG 等标准格式需先解码转换 |
| b | 图片宽度必须是 4 的倍数;I420/NV21/NV12/GRAY 格式高度为 2 的倍数;BGR24 格式高度不限制 |
| c | JPG 等格式读图需做图像解码,推荐使用 OpenCV 第三方库读取并转换为 NV21/I420 后送入 SDK |
| d | 特征提取后务必立即拷贝或注册 feature 数据,否则第二次特征提取会覆盖第一次的数据,导致比对结果异常(恒为 1) |
| e | 注册与识别的特征提取是两种不同模式,不能混用 :注册照用 ASF_REGISTER 模式提取(要求不戴口罩);识别照用 ASF_RECOGNITION 模式提取(支持戴口罩,提取时传入 maskInfo.maskArray[0]),比对时用识别特征匹配注册库 |
| f | 活体检测置信度可通过 ASFSetLivenessParam 设置,SDK 内部默认值 RGB: 0.5 / IR: 0.5 |
| g | 在线激活需要板端联网;离线激活需先调用 ASFGetActiveDeviceInfo 采集设备信息,在官网生成激活文件后使用 ASFOfflineActivation |
| h | 运行时 LD_LIBRARY_PATH 必须同时包含 linux_so/ 与板端 librknnrt.so 所在目录,否则报找不到 so 库 |
| i | Demo 末尾有 getchar() 阻塞等待,自动化测试时需注意(可重定向输入) |
8. 常见问题排查
8.1 执行 demo 时报无法找到 so 库
vbnet
./arcsoft_face_engine_test: error while loading shared libraries:
libarcsoft_face_engine.so: cannot open shared object file
原因是运行前未配置环境变量,需要将虹软 SDK 库(以及 librknnrt.so)路径配置到环境中:
bash
export LD_LIBRARY_PATH=$PWD/../linux_so/:/usr/lib/:$LD_LIBRARY_PATH
./arcsoft_face_engine_test
8.2 在线激活返回 98310(0x18006)
查阅 merror.h 发现 0x18006 = MERR_ASF_ACTIVEKEY_ACTIVEKEY_FORMAT_ERROR,即 ACTIVEKEY 信息异常 。原因是 samplecode.cpp 中的 APPID/SDKKEY/ACTIVEKEY 仍是 SDK 包自带的测试数据,未替换为官网获取的授权密钥。替换后即可正常激活。
8.3 cmake 报错找不到交叉编译器
swift
CMake Error: CMAKE_C_COMPILER not set, after EnableLanguage
原因是 CMakeLists.txt 中写死的工具链路径 /opt/toolchain/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu/bin 与本机实际路径不符,修改为本机工具链路径后重新 cmake .. 即可。
8.4 链接时报找不到 librknnrt.so
arduino
/usr/bin/ld: cannot find -lrknnrt
CMakeLists.txt 中链接了 rknnrt,需要将板端 /usr/lib/librknnrt.so(或 RKNN SDK 包中的版本)拷贝到 linux_so/ 目录下再编译。
8.5 板端运行时报 rknn_init 失败
yaml
rknn_init fail: -1
libarcsoft_face.so 通过 RKNN 在 NPU 上跑算法,该错误通常意味着板端 NPU 驱动异常、固件与 librknnrt.so 版本不匹配,或 NPU 已被其他进程占用。请核对板端 RKNN 驱动(/dev/rknpu)与运行时版本是否匹配瑞芯微 SDK 的要求。
8.6 在线激活失败且板端无法联网
在线激活要求板端能访问虹软激活服务器。若设备在隔离网络环境,应改用离线激活:先运行 demo 获取 ASFGetActiveDeviceInfo 输出的设备信息,到开发者中心生成激活文件(.dat),再在 samplecode.cpp 中启用 ASFOfflineActivation("xxx.dat") 并将激活文件拷贝到板端。
9. 总结
本文完整演示了虹软 ArcFace SDK(RV1126BP ARM64 V5.0) C++ Demo 的实操流程,涵盖:
- 交叉编译环境准备(工具链 / GLIBC / GLIBCXX / CMake / librknnrt.so 检查)
- SDK 目录结构与 Demo 工程配置(库拷贝、头文件更新、密钥替换)
- CMake 交叉编译与板端部署运行
- 人脸检测、特征提取、注册入库、1:N / TopN 比对
- 注册(ASF_REGISTER)与识别(ASF_RECOGNITION)两种特征提取模式的区别与正确用法
- 年龄/性别/活体/口罩属性检测、图像质量检测、红外活体检测
- 常见问题排查与注意事项
与 x64 服务器版相比,RV1126B 版的关键差异在于:交叉编译 而非本机编译、算法依赖 RKNN NPU 运行时 (librknnrt.so)、运行环境为嵌入式 Linux 板端。在实际项目中,可将 Demo 中的核心逻辑封装为业务 API,接入摄像头采集(V4L2/ISP 出 NV21 裸数据)与 OpenCV 图像处理,构建完整的边缘人脸识别设备系统。