1126B的Demo实操——虹软ArcFace SDK(RV1126BP ARM64 V5.0)交叉编译与运行指南

0 阅读6分钟

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 中已配置好):

/opt/toolchain/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu-gcc

确认工具链已安装:

aarch64-linux-gnu-gcc --version

⚠️ 若你的工具链路径不同,需要修改 CMakeLists.txt(详见 4.1 节),否则 cmake .. 会报找不到编译器。

2.2 板端 GLIBC / GLIBCXX 版本检查

SDK 要求板端 GLIBC 不低于 2.17、GLIBCXX 不低于 3.4.21。在板端执行:

strings /lib/aarch64-linux-gnu/libc.so.* | grep GLIBC_ | sort -V
strings /lib/aarch64-linux-gnu/libstdc++.so.* | grep GLIBCXX | sort -V

期望输出示例:

GLIBC_2.17
...
GLIBCXX_3.4.21
...

⚠️ 若输出中无 GLIBC_2.17、GLIBCXX_3.4.21 及以上版本,需升级板端系统或更换兼容的固件。

2.3 CMake 版本检查(主机侧)

cmake --version

要求 CMake 3.0 及以上。版本过低可参考 Linux 安装或升级 cmake。

2.4 NPU 运行时 librknnrt.so 检查(板端)

RV1126B 版算法的核心特点是依赖 RKNN NPU 运行时。通过 readelf 查看动态库依赖可以确认:

readelf -d libarcsoft_face.so | grep NEEDED

输出示例:

0x0000000000000001 (NEEDED)  Shared library: [librknnrt.so]
0x0000000000000001 (NEEDED)  Shared library: [libpthread.so.0]
0x0000000000000001 (NEEDED)  Shared library: [libstdc++.so.6]
...

在板端确认运行时存在:

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,目录结构如下:

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 也拷入(供链接使用):

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

cp ARCSOFT_ARCFACE_LINUX_ARM64_RV1126BP_V5.0/inc/*.h ASFTestDemo/inc/

步骤 c:配置激活密钥

打开 samplecode.cpp,将以下三个宏替换为从虹软开发者中心获取的真实密钥(SDK 包中自带的是测试数据):

#define APPID "EXnv3N55pz6Sz1HJz2jqYmAcJNEPVVEbieqFQ7sjRzLq"
#define SDKKEY "EgJh9s1ZsKs9qjDxYsUcinbVFUu7k51Kk7AfY83NXvJT"
#define ACTIVEKEY "U9W1-11TW-911A-6JJC"

⚠️ 包内为示例假数据,必须替换为真实密钥,否则激活会失败(见 8. 常见问题排查)。


4. 交叉编译与运行 Demo

4.1 适配 CMakeLists.txt 工具链路径

CMakeLists.txt 中交叉编译工具链路径是写死的,若你的工具链不在 /opt/toolchain 下,需先修改:

#这里配置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 编译

cd ASFTestDemo
mkdir build
cd build
cmake ..

期望输出:

-- 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 编译

make

期望输出:

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 程序:

file arcsoft_face_engine_test
# ELF 64-bit LSB executable, ARM aarch64, ...

4.4 部署到板端运行

将整个工程目录(可执行文件 + images/ + linux_so/)拷贝到板端(scp / adb / NFS 均可):

# 以 scp 为例
scp -r ASFTestDemo root@<板端IP>:/root/

在板端进入 build 目录,配置虹软 SDK 库与 RKNN 运行时路径,运行 demo:

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 核心功能流程

1126B的demo实操_流程.png

5.2 关键代码解析

5.2.1 SDK 激活与引擎初始化

// 在线激活(首次运行需要板端联网)
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 等格式:

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

// 检测人脸
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 比对

// 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 属性检测(年龄/性别/活体/口罩)

// 处理人脸,获取多种属性
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 图像质量检测与红外活体检测

// 图像质量检测,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 活体阈值设置与资源释放

// 设置活体置信度,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 运行成功后,板端终端输出如下(数值因图片/设备而异):

************* 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. 注意事项

序号注意事项
aDemo 提供的测试图片为 NV21 格式裸数据(640x480,大小 460800 字节),保存在 images/ 目录下;JPG/PNG 等标准格式需先解码转换
b图片宽度必须是 4 的倍数;I420/NV21/NV12/GRAY 格式高度为 2 的倍数;BGR24 格式高度不限制
cJPG 等格式读图需做图像解码,推荐使用 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 库
iDemo 末尾有 getchar() 阻塞等待,自动化测试时需注意(可重定向输入)

8. 常见问题排查

8.1 执行 demo 时报无法找到 so 库

./arcsoft_face_engine_test: error while loading shared libraries:
libarcsoft_face_engine.so: cannot open shared object file

原因是运行前未配置环境变量,需要将虹软 SDK 库(以及 librknnrt.so)路径配置到环境中:

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 报错找不到交叉编译器

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

/usr/bin/ld: cannot find -lrknnrt

CMakeLists.txt 中链接了 rknnrt,需要将板端 /usr/lib/librknnrt.so(或 RKNN SDK 包中的版本)拷贝到 linux_so/ 目录下再编译。

8.5 板端运行时报 rknn_init 失败

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 图像处理,构建完整的边缘人脸识别设备系统。