人脸识别Android离线SDK
版本历史

1设计背景

1.1 场景特点

-- 网络：无网、局域网等情况均可使用。如政府单位、金融保险、教育机构等。

-- 安全：行业特点所带来的人脸数据敏感性，许多客户不希望将人脸数据传入百度服务器，即使连接公网也不会请求。

-- 速度：由于各地网络线路、机房部署等诸多原因，网络请求速度往往耗时较高，容易影响业务正常运转，离线SDK不会存在网络延迟问题。

-- 稳定：离线SDK不会受网络抖动、机房故障、线上连带bug等影响，进一步控制可用性影响因素

-- 海外人群：支持海外人脸识别，适用于以海外人群为主的通行、考勤、人证核验等场景下的1:1及1:N人脸比对和搜索

1.2 用户特点

-- 1：N-小型人脸库检索：多为通道通行、固定区域人群验证等需求，如写字楼闸机门禁、企业考勤打卡等，人脸库范围较小，且不易经常变动。

-- 1：1-自有数据源对比：有效应用于人证比对、身份核验等场景，将当前采集的人脸，与其他数据源中的人脸进行对比，如身份证芯片照、教务系统图片、档案图片等，进行快速的1：1对比验证。

1.3 核心功能

-- 离线人脸检测：可在设备端，离线实时检测视频流中的人脸。并对当前检测到的人脸进行持续跟踪、捕获、质量校验等，动态定位人脸轮廓，稳定贴合人脸。

-- RGB+NIR活体检测：可判断可见光RGB成像、NIR近红外成像是否为活体，可有效防止屏幕二次翻拍等作弊攻击

-- DERPTH深度图像(3D结构光)活体检测：通过3D建模判断目标对象是否为活体，基于3D结构光成像原理，可强效防御图片、视频、屏幕、模具等攻击。

-- 本地特征提取：所有在SDK中运行的人脸图片，都可以完成本地特征抽取，以便进行对比或识别操作。

-- 1:1对比：支持两张图片的相似度对比，可直接传入图片，获取图片中人脸特征进行比对、适应于人证核验等场景；

-- 1:N比对：可在指定人脸集合中，找到最相似的人脸，并返回相似度最高的人脸信息及对应分值。人脸库可存储于本地数据库，并支持通过视频流实时采集的人脸特征值比对实现人脸的1:N识别。

1.4 使用场景

-- 通用版SDK：适用于大部分Android5.0以上系统的手机和面板机，由于不同设备、摄像头和cpu等的差异，识别效果可能会存在细微差距。SDK专门针对如RK3399、RK3288主板和迪威泰、视派尔等摄像头进行了模型和识别效果上的优化

-- 3568专版SDK：适用于3568、 3566的npu主板，有npu算法加持，相对通用版SDK专版在处理和识别速度上有明显提升，提升范围在1.5到3倍左右。

2 SDK简介

2.1 SDK环境

2.2 功能架构

SDK具有人脸检测、跟踪、质量检测、特征提取、RGB、 NIR以及3D结构光静默活体、1：1比对、1：N识别、年龄、性别、是否戴口罩、戴眼镜和佩戴安全帽、左右眼球注意力等功能，架构图如下：

2.3 人脸识别流程

人脸识别流程如下图所示，通过SDK的授权激活且模型初始化成功后，根据输入的图片或视频帧进行人脸检测，同时对人脸进行质量、活体和属性等进行过滤判断（通常情况下质量合格的图在1:N人脸识别时候识别率更高），通过对质量通过后的高质量图片进行人脸特征提取后、可根据人脸特征进行人脸1:1的比对和1:N的识别（1:N识别前需要先进行人脸注册入本地库），通常以人脸特征的比对或识别阈值大于80分为比对成功或识别通过。

3 SDK及Demo工程结构说明

3.1SDK能力与接入流程

SDK 支持以下主要能力：

• 人脸检测、跟踪和关键点定位。
• 模糊、光照、姿态角、遮挡和最佳人脸等质量检测。
• RGB、NIR 和 Depth 静默活体检测。
• 人脸特征提取、1:1 比对和 1:N 检索。
• 年龄、性别、情绪、口罩、安全帽和注意力等可选属性能力。
• RGB、RGB+NIR、RGB+Depth 等输入组合。

推荐接入顺序：

1. 集成 SDK AAR 和所需模型文件。
2. 配置 ABI、权限和混淆。
3. 使用最终应用包名申请授权。
4. 启动时调用静默鉴权；未激活时进入离线、在线或批量激活流程。
5. 鉴权成功后初始化检测、活体、特征等所需模型。
6. 初始化业务人脸库，并将 1:N 特征同步到 SDK 内存缓存。
7. 创建图像、检测和流程配置，逐帧调用 onDetectCheck。
8. 在页面退出时停止摄像头、移除回调并释放图像资源。

授权、模型初始化和底库加载都完成后，才能开放注册、比对和识别功能。

3.2官网工程包结构说明

目前百度AI官网有集成SDK摄像头、人脸数据库统一封装的效果展示的SDK Demo工程，官网的下载地址为:

[https://console.bce.baidu.com/ai-engine/old/#/ai/face/offline/index](https://console.bce.baidu.com/ai-engine/old/" \l "/ai/face/offline/index)

该工程中分为Andorid通用项目、DEPTH 3D结构光项目、SDK、文档，四个板块，主要功能为：

3.3工程结构说明

3.3.1 Demo 工程

FaceSDKAndroid 主要包含： Demo示例工程针对百度离线人脸识别SDK调用，并且对sqlite人脸数据库和相机等功能进行封装，FaceSDKAndroid Demo工程结构如下:

3.3.2 SDK aar文件和模型文件说明

将交付模型按原目录结构放入：

app/src/main/assets/face-sdk-models/

当前 Demo 包含以下模型目录：

删除可选模型前，必须同时关闭 BDFaceModelConfig 中对应的初始化开关。模型文件名和版本以实际交付包为准，不要混用历史版本模型。

SDK分为aar(历史版本为jar so)和模型资源文件等几个部分、SDK aar库文件位于项目中的faceaar/faceSDK-9.0-*.aar目录下

模型文件储存在项目app\src\main\assets\face-sdk-models文件夹中，各模型文件说明如下：

4、Demo工程的编译和使用

4.1 环境要求

当前 Demo 的实际构建组合是：

Gradle: 7.4
Android Gradle Plugin: 7.3.1
Gradle 运行 JDK: 11 或 17
Java source/target compatibility: 1.8
compileSdkVersion: 31
targetSdkVersion: 31
minSdkVersion: 21

“Java 8 兼容级别”不等于“可以使用 JDK 8 运行当前 Gradle 构建”。使用 Android Studio 时，将 Gradle JDK 设置为 11 或 17。

4.2 通过 AAR 模块依赖

Demo 默认依赖 :faceaar：

// settings.gradle
include ':app'
include ':faceaar'

// app/build.gradle
dependencies {
    implementation project(':faceaar')
}

客户工程也可直接把 AAR 放入应用模块的 libs 目录：

dependencies {
    implementation files('libs/faceSDK-9.0-core-<date>.aar')
}

二选一即可，不要重复依赖同一 SDK。

4.3 ABI 配置

Demo 仅打包以下 ABI：

android {
    defaultConfig {
        ndk {
            abiFilters 'armeabi-v7a', 'arm64-v8a'
        }
    }

    packagingOptions {
        pickFirst 'lib/armeabi-v7a/libc++_shared.so'
        pickFirst 'lib/arm64-v8a/libc++_shared.so'
    }
}

最终支持范围取决于实际 AAR 中的 lib/<abi>/ 内容。不要声明 AAR 未提供的 ABI；常见表现是安装失败或运行时报 UnsatisfiedLinkError。

4.4 权限与应用配置

4.4.1 Manifest 配置

按业务实际需要声明权限。Demo 使用：

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_SETTINGS" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<uses-feature android:name="android.hardware.camera" />
<uses-feature
    android:name="android.hardware.camera.autofocus"
    android:required="false" />
<uses-feature
    android:name="android.hardware.camera.front"
    android:required="true" />

说明：

• CAMERA 用于图像采集，Android 6.0 及以上需要动态申请。
• INTERNET、ACCESS_NETWORK_STATE 用于在线和批量激活等联网能力。
• Demo 保留 WRITE_SETTINGS、READ_PHONE_STATE，用于授权 SDK 获取和备份设备指纹；客户应结合目标 Android 版本、设备 ROM 和授权方案实测。
• Demo 的存储权限及 requestLegacyExternalStorage=true 是历史兼容方案，不应直接作为新应用模板。Android 10 及以上应按实际授权文件路径、图片导入和调试存图需求设计存储访问。
• 只申请业务真正需要的权限，并在调用摄像头或读取用户文件前完成告知和授权。

如应用本地保存人脸特征或截图，建议关闭系统备份：

<application
    android:allowBackup="false"
    ... />

4.4.2 包名与授权

授权会校验设备指纹、包名、有效期和授权能力。申请 License 前，使用下面的值确认最终运行包名：

String packageName = context.getPackageName();

授权申请的包名必须与最终安装包一致。修改 applicationId、更换应用变体或重新打包后，应重新核对授权。Demo 的 Gradle applicationId 与 Manifest 源文件中的 package 不同，因此不要照抄 Manifest 的 package 作为授权依据。

> 9.0 更新了设备指纹提取方式。由 9.0 以前版本升级时，设备指纹可能变化，已激活设备可能需要使用新的授权重新激活。

4.5 编译与使用

SDK Demo工程下载解压后，FaceSDKAndroid工程如下：

使用android studio打开FaceSDKAndroid项目

注:部分版本的android studio在编译的时候会出现错误，或者提示需要升级gradle8.0以上版本，该问题为java jdk不适配导致，目前demo的gradle版本为7.4，可在android studio中设置11或17版本的java jdk，截图如下:

相关报错

解决方案

Jdk设置完成后，等待项目编译完成，运行项目

注：andorid手机需开启开发者模式和usb调试才可以正常运行，通常在手机设置-关于手机-找到系统版本连点7下即可开启开发者模式，不同型号手机位置不同

demo主要运行流程为，其中激活须设备能连接网络(离线激活不需要)，激活用到的序列号可在百度AI官网申请，官网具体位置和激活流程请参考[4.1 授权激活](#_4.1 授权激活)，demo主要流程如下:

4.6 授权激活

SDK分为离线激活、在线激活、批量激活三种激活方式(可使用其中任何一种进行激活)，SDK需要通过授权激活后才能正常使用，三种激活方式可从官网申请激活文件或激活序列号(三种激活方式均会对通过指纹对设备进行绑定，如果存在系统更新、硬件更新、固件刷新的情况会导致设备指纹改变从而激活失败)，官网申请激活序列号以及离线激活地址如下：

[https://console.bce.baidu.com/ai/?_=1670415860750&fromai=1#/ai/face/offline/index](https://console.bce.baidu.com/ai/?_=1670415860750&fromai=1" \l "/ai/face/offline/index)

注:9.0版本sdk更新了设备指纹提取方式，获取的指纹会与9.0以前的历史版本sdk不同，已经激活过的设备使用9.0版本sdk需使用新的序列号从新激活

4.6.1离线激活（适应于无网或弱网环境）

SDK Demo运行后，首先会进入激活界面，在离线激活选项中可找到当前设备的设备指纹，在官网填入指纹信息，可获取授权文件（License.zip）无需解压，将授权文件放到设备sdcard(/sdcard/License.zip)目录下，进入离线激活界面，点击激活，即可完成激活，百度官网的离线激活页面如下：

先获取设备指纹，再在授权平台生成与设备及包名匹配的 License：

BdFaceAuth faceAuth = new BdFaceAuth();
String deviceId = faceAuth.getDeviceId(context);

将 License.zip 放到 SDK 要求的位置后调用：

faceAuth.initLicenseOffLine(context, (code, response) -> {
    if (code == 0) {
        initFaceModels();
    } else {
        handleAuthError(code, response);
    }
});

Demo 使用 /sdcard/License.zip。在 Android 10 及以上系统上，应在目标设备验证该固定路径及存储权限是否可访问；不要在未验证时承诺所有系统版本均可直接读取。

4.6.2在线激活(需要设备能连网)

SDK Demo运行后(首次需联网)，首先会进入激活界面，点击在线激活，在激活选项中输入官网的16位序列号，点击激活，即可完成在线激活，激活授权序列号可参考如下页面（百度AI官网登录账号购买后可显示）：

在线激活需要首次联网，Demo 使用四组共 16 位激活码：

String licenseId = "XXXX-XXXX-XXXX-XXXX";
faceAuth.initLicenseOnLine(context, licenseId, (code, response) -> {
    if (code == 0) {
        initFaceModels();
    } else {
        handleAuthError(code, response);
    }
});

禁止把真实激活码提交到代码仓库或写入日志。

4.6.3批量激活(需要设备能联网)

SDK Demo运行后(首次需联网)，首先会进入激活界面，点击批量激活，该激活方法需要在代码中添加批量激活序列号，在官网-批量授权选项中可申请批量激活授权序列号，批量激活序列号可参考如下页面在百度AI官网获取、获取后填写到如下页面代码中（红色标记处）：

String batchLicenseId = obtainBatchLicenseIdSecurely();
faceAuth.initLicenseBatchLine(context, batchLicenseId, (code, response) -> {
    if (code == 0) {
        initFaceModels();
    } else {
        handleAuthError(code, response);
    }
});

当前 Demo 的 BatchFragment 传入空字符串，仅是待填写占位代码，不能直接用于交付。客户必须填写在授权平台申请的批量 License ID，并妥善保护该凭据。

4.6.4 激活过后启动时静默鉴权

已成功激活过的设备，应用启动时先调用：

FaceSDKManager.getInstance().startAuth(context, new SdkInitListener() {
    @Override
    public void initModelSuccess(int code) {
        // 鉴权成功，再初始化模型。
        initFaceModels();
    }

    @Override
    public void initModelFail(int errorCode, String msg) {
        // 跳转到首次激活页面或展示可恢复的错误信息。
        showActivationPage(errorCode, msg);
    }
});

Demo 的 FaceSDKManager.startAuth 是对 FaceSdkController.startAuth 的薄封装。

4.7 SDK Demo使用说明（可直接编译Demo生成apk体验）

4.7.1模型加载及初始化

鉴权成功后，按业务能力初始化模型。以下示例与 Demo 的初始化方式一致：

private void initFaceModels() {
    BDFaceModelConfig modelConfig = new BDFaceModelConfig();
    modelConfig.setInitCrop(true);
    modelConfig.setInitLive(true);
    modelConfig.setInitRGBLive(true);
    modelConfig.setInitNIRLive(false);
    modelConfig.setInitDepthLive(false);
    modelConfig.setInitDetect(true);
    modelConfig.setInitTrack(true);
    modelConfig.setInitFeature(true);
    modelConfig.setInitGaze(false);
    modelConfig.setInitMouthMask(false);
    modelConfig.setInitSafetyHat(false);
    modelConfig.setInitDark(false);
    modelConfig.setMultiIdentify(false);

    BDFaceSDKConfig sdkConfig = FaceUtils.getInstance().getBDFaceSDKConfig();

    FaceSDKManager.getInstance().initModel(
            getApplicationContext(),
            sdkConfig,
            modelConfig,
            new SdkInitListener() {
                @Override
                public void initModelSuccess(int code) {
                    loadFaceDatabase();
                }

                @Override
                public void initModelFail(int errorCode, String msg) {
                    handleModelError(errorCode, msg);
                }
            });
}

注意：

• 只开启业务需要的能力，并保留对应模型文件。
• setInitLive(false) 会关闭活体模型总开关。
• 1:1、1:N 和注册需要启用特征模型。
• 快速人脸框绘制需要启用跟踪模型。
• 不要在模型初始化成功前提交图像帧。
• 错误码 -12 表示能力已加载；是否可忽略应结合调用时机和实际 SDK 返回信息判断。

4.7.2模型加载及镜头角度设置

SDK激活成功后(激活可参考[4.1 授权激活](#_4.1 授权激活))会进入demo首页，此时会自动进行模型初始化加载操作，等待首页提示模型初始化成功后，再进行后续操作，模型初始化接口及弹窗提示效果如下：

模型初始化成功后，部分设备还不能进行注册和人脸识别，需在设置界面中调整人脸检测和摄像头的角度（须人脸正向），角度正确后可进行注册和人脸识别操作，界面如下：

在设置界面中找到镜头设置

镜头设置中分为:人脸检测图像设置为SDK对视频流进行解码的角度(识别角度)，视频流回显图像设置为摄像头在屏幕中显示的角度(显示角度),具体界面如下(如人脸不是正向的时候，可点击旋转按钮把人脸摆正):

4.7.3检测配置

Demo 的 FaceUtils.getBDFaceSDKConfig() 主要配置：

BDFaceSDKConfig config = new BDFaceSDKConfig();
config.maxDetectNum = 2;
config.trackInterval = Integer.MAX_VALUE;
config.minFaceSize = minimumFace;
config.notRGBFaceThreshold = faceThreshold;
config.notNIRFaceThreshold = faceThreshold;

其中：

• maxDetectNum：单帧最大检测人数。
• minFaceSize：最小人脸尺寸，Demo 注释建议大于 30 px，默认配置为 80 px。
• notRGBFaceThreshold、notNIRFaceThreshold：检测置信度，Demo 注释建议大于 0.3，默认配置为 0.5。
• trackInterval：跟踪过程重新全图检测的间隔策略。

多人脸模式下 Demo 使用：

modelConfig.setMultiIdentify(true);
sdkConfig.maxDetectNum = 5;
sdkConfig.trackInterval = 0f;

人数越多，CPU、内存和单帧耗时越高。应在目标硬件实测后确定上限，不建议直接沿用历史文档中的固定人数承诺。

4.7.4人脸库与特征缓存

4.7.4.1 两层数据的职责

Demo 同时维护：

• SQLite face.db：持久化人员 ID、姓名、特征和可选头像。
• SDK 内存缓存：用于运行时 1:N 高速检索。

写入数据库不会自动更新 SDK 缓存。新增、删除或全量替换人员时，必须同步更新两处数据。

4.7.4.2 启动加载

模型初始化成功后，在后台线程读取数据库。大底库应分批推送：

FaceSDKManager.getInstance().featureClean();

for (List<User> batch : batches) {
    FaceSDKManager.getInstance().pushPersons(batch);
}

当前 Demo 每批读取 1000 条，避免把全部对象同时保留在内存中。底库加载期间不要开放识别入口。

4.7.4.3 增删改同步

// 新增
FaceSDKManager.getInstance().pushPerson(user.getId(), user.getFeature());

// 删除
FaceSDKManager.getInstance().delFeature(userId);

// 全量替换
FaceSDKManager.getInstance().pushAllPersons(users);

// 清空
FaceSDKManager.getInstance().featureClean();

每个人员 ID 必须唯一，并与业务数据库一致。删除数据库记录时同步调用 delFeature；批量刷新时可先 featureClean 再分批 pushPersons。

4.7.5图片及视频流注册

设置好摄像头角度后，返回首页，在右上角按钮中可找到人脸注册和人脸库管理选项（进行人脸1:N识别，需要先进行人脸注册入库,1:N识别时候是实时检测的视频帧和人脸库里的已经注册入库的N个人进行比对识别），其中人脸注册功能支持将摄像头中检测的人脸数据注册到数据库（也支持图片批量导入注册入库），人脸库管理中可查看注册的人脸信息并且也可以对图片进行人脸注册，整体效果截图如下：

视频流注册：

选择人脸注册

检测到人脸后，输入用户信息，点击确认方可完成注册

图片注册：

图片注册需要手动拷贝将需要注册的人脸图片放到设备/sdcard/Face-Imort/文件夹中，在人脸库管理-批量导入中方可进行图片注册，效果如下：

在人脸库管理中还可以看到目前数据库中的人脸数据进行查询和删除的操作，点击右上角批量导入，方可进行图片注册（注：目前demo对图片名进行控制，不得超过5个字、另外可能会有部分不符合质量要求的人脸注册入库时候失败，具体可根据调试信息查看）

推荐注册流程：

1. 确保模型和摄像头已就绪。
2. 检测到且仅检测到一张人脸。
3. 校验人脸框位置、尺寸、姿态、模糊、光照和遮挡。
4. 按业务需要校验 RGB/NIR/Depth 活体。
5. 确认特征提取返回码为 128。
6. 保存人员信息和特征到业务数据库。
7. 保存成功后调用 pushPerson 更新 SDK 缓存。

视频流结果中可读取特征：

float featureCode = model.getFeatureCode();
if (featureCode == 128) {
    byte[] feature = model.getFeature();
    boolean saved = saveUserToDatabase(userName, feature);
    if (saved) {
        FaceSDKManager.getInstance().pushPerson(userId, feature);
    }
}

对单张 Bitmap 提取特征：

byte[] feature = new byte[512];
BDFaceCheckConfig config = FaceUtils.getInstance()
        .getBDFaceCheckConfig(new BDFaceUtilityConfig(false, enableQuality));

FeatureData result = FaceSDKManager.getInstance()
        .personDetect(bitmap, feature, config);

if (result.code == 128) {
    saveFeature(feature);
} else {
    handleFeatureError(result.code, result.msg);
}

通用 9.0 Demo 使用 512 字节特征数组。不同专版可能不同，必须以实际 SDK 交付说明为准。

4.7.6 图像输入与视频流识别

4.7.6.1 创建图像配置

Demo 摄像头输出 NV21：

BDFaceImageConfig rgbConfig = new BDFaceImageConfig(
        height,
        width,
        rgbDetectDirection,
        mirrorRgb,
        BDFaceSDKCommon.BDFaceImageType.BDFACE_IMAGE_TYPE_YUV_NV21);

NIR 图像使用独立的 BDFaceImageConfig，并配置对应旋转方向和镜像。传入的 height、width、方向、镜像和图像格式必须与实际帧一致，否则会出现检测失败、坐标偏移或图像旋转错误。

Bitmap 输入可使用：

BDFaceImageConfig imageConfig = new BDFaceImageConfig(bitmap);

4.7.6.2 创建流程配置

Demo 通过 BDFaceUtilityConfig 决定识别流程，再由 FaceUtils 组装质量、活体和业务阈值：

BDFaceUtilityConfig utilityConfig = new BDFaceUtilityConfig();
utilityConfig.isLive = enableLiveness;

BDFaceCheckConfig checkConfig =
        FaceUtils.getInstance().getBDFaceCheckConfig(utilityConfig);

阈值必须根据摄像头、距离、光照、目标设备和业务误识率要求调优。不要把“相似度大于 80”作为所有场景的通用结论。

4.7.6.3 调用识别接口

在摄像头帧回调中更新数据并调用：

rgbConfig.setData(rgbNv21);
if (nirNv21 != null) {
    nirConfig.setData(nirNv21);
}

FaceSDKManager.getInstance().onDetectCheck(
        rgbConfig,
        nirConfig,
        null,
        checkConfig,
        new FaceDetectCallBack() {
            @Override
            public void onFaceDetectCallback(List<LivenessModel> models) {
                handleFaceResults(models);
            }

            @Override
            public void onTip(int code, String msg) {
                handlePipelineTip(code, msg);
            }

            @Override
            public void onFaceDetectDarwCallback(List<LivenessModel> models) {
                drawFaceFrames(models);
            }
        });

回调职责：

回调线程不应被视为主线程。所有 UI 更新应显式切换到主线程；不要在逐帧回调中执行数据库全表查询、网络请求、同步文件写入或大量日志拼接。

4.7.7 1:N识别和1：1比对

1:N识别：

SDK Demo提供了闸机模式、支付模式、考勤模式，这几种场景化示例Demo均为1:N人脸识别功能，除界面不同外识别效果和接口基本相同，开发者可根据项目需求选择不同界面进行集成，通过操作可将人脸注册入库，并且在识别时候对视频流中的人脸进行人脸框绘制、活体、质量检测的判断、提取摄像头中人脸特征、最后跟前述已经注册入库的人脸特征值进行识别比对，返回相似度最高的人员信息和各个SDK原子接口的识别耗时以及总耗时，具体页面展示效果如下：

1:N 识别前必须完成底库缓存加载。识别回调中，从 LivenessModel 获取命中结果：

for (LivenessModel model : models) {
    Feature featureInfo = model.getFeatureInfo();
    if (featureInfo == null) {
        continue;
    }

    int userId = featureInfo.getId();
    float score = featureInfo.getScore();
    User user = findUserById(userId);
    handleIdentifyResult(user, score);
}

业务层还应同时判断：

• model.getFaceInfo() 是否为空。
• 质量检测是否通过。
• 已开启的活体分值是否达到对应阈值。
• 命中分值是否达到经过实测确定的识别阈值。
• 同一个跟踪 ID 是否需要去重或冷却，避免连续帧重复触发业务动作。

1:1比对：

SDK Demo中的人证核验模块为1:1比对展示界面，点击底部上传证件照按钮，进入相册选择证件照图片方可进行视频流1:1比对，比对展示效果如下：

先从底图提取第二特征：

byte[] secondFeature = new byte[512];
FeatureData featureData = FaceSDKManager.getInstance().personDetect(
        referenceBitmap,
        secondFeature,
        FaceUtils.getInstance().getBDFaceCheckConfig(
                new BDFaceUtilityConfig(false, enableQuality)));

if (featureData.code != 128) {
    handleFeatureError(featureData.code, featureData.msg);
    return;
}

checkConfig.setSecondFeature(secondFeature);

然后把实时视频帧或另一张 Bitmap 传给 onDetectCheck。比对结果从 LivenessModel 中读取，最终通过阈值必须按业务场景评测确定。

4.7.8 结果对象常用字段

以当前 Demo 实际使用为准：

SDK 实体字段可能随 AAR 小版本调整。编译时应以交付 AAR 的类定义和 IDE 提示为准，不要照搬旧版文档中的字段表。

5、SDK以及项目的集成

5.1 集成说明

集中需要将SDK核心库、SDK模型集成到项目中。（其中sdk核心库中包含了对sdk原子接口和识别流程的封装，对于本地数据库 摄像头等可自行调整）具体位置为：

模块以及核心库导入完成后，将1:N(gateLibrary)或1:1(identifylibrary)模块中的FaceUtils文件和FaceSDKManager文件放入到项目，该文件对SDK初始化以及阈值进行封装，可更好的设置SDK参数，具体可参考[5.3.1 FaceUtils类方法说明](#_5.3.1 FaceUtils类方法说明)

注:后续注册人脸特征需要进行本地或云端存储，以便重启apk后能够识别历史注册过的人脸，demo使用的是本地sqlite存储，可将db目录下的文件导入到项目，具体截图如下:

5.2项目集成流程说明

项目集成中根据自身不同业务场景，可自由定制化开发，其中SDK能力层主要流程和接口截图流程如下：

SDK核心库、FaceUtils、SDK模型集成到项目中后，

先调用激活接口initLicenseOffLine(离线激活)、initLicenseOnLine(在线激活)、initLicenseBatchLine(批量激活)，激活成功(OonResponse方法code参数为0则成功)后，才可以进行之后操作，具体代码如下:

激活成功后，需要进行SDK模型初始化和数据库初始化，模型初始化成功后才可以进行后续识别和注册操作，具体代码如下:

其中FaceSDKManager.getInstance().initModel接口包含人脸快速检测模型、人脸检测模型、属性模型、活体、特征提取模型、注意力模型、安全帽模型、口罩模型等能力的初始化，可根据项目需要设置对应能力

数据库初始化代码如下图所示:

模型初始化成功后，需要进行人脸注册才可以正常识别到人脸，

通过FaceSDKManager.getInstance().personDetect获取图片的人脸特征结果，

特征提取成功后，可通过FaceApi的registerUserIntoDBmanager或userAdd接口注册到数据库，

数据库保存成功后，在通过FaceSDKManager.getInstance().pushPerson，将数据库的人脸信息放到SDK缓存中

注册成功后，在识别界面创建识别阈值BDFaceCheckConfig和BDLiveConfig，其中包含识别、活体、质量等阈值的配置信息

识别阈值参数创建完成后，创建BDFaceImageConfig摄像头数据参数类，并使用CameraPreviewManager和GlMantleSurfacView打开摄像头，并展示摄像头界面

摄像头启动成功后，在CameraPreviewManager的setmCameraDataCallback接口可获取到摄像头每帧数据，将每帧数据放到BDFaceImageConfig摄像头数据参数类中，通过FaceSDKManager.getInstance().onDetectCheck对该数据进行人脸识别操作

其中FaceSDKManager.getInstance().onDetectCheck识别接口包含：

人脸快速检测(只返回人脸宽高位置，用于快速绘制人脸框，人脸跟踪)

质量检测(人脸角度 光照 模糊 遮挡)

活体检测(rgb nir depth活体)

属性检测(年龄 岁数 表情)

安全帽检测(是否带安全帽)

口罩检测(是否带口罩)

注意力检测(眼球上下左右位置 睁闭眼检测)

特征提取(人脸特征提取)

1:N识别(与内存中的批量人脸特征识别，返回满足条件得分最高的人脸)

1:1人脸比对(两个人脸特征进行人脸比对返回识别得分)

且可通过BDFaceUtilityConfig配置需要的功能

5.3工程核心类和方法说明

demo应用层对数据库、摄像头、SDK接口使用进行了封装，核心功能类分为；

5.3.1 FaceApi类方法说明

该类为业务层封装类，客户可根据自身业务调整内部逻辑，主要作用为人脸数据库的初始化，和人员信息的增删改查

FaceApi相关接口截图及说明如下:

初始化人脸数据库，会创建数据库并且获取数据库中的所有用户信息(该操作为耗时操作，需要在线程中进行)，获取到的所有用户信息建议储存在list（users）中，方便后续进行用户信息提取操作，优化每次获取用户全部信息耗时过高问题

将用户信息注册到数据库，进行识别前需要提取出该信息放入SDK缓存中进行识别，具体识别接口可参考[6.6 FaceSearch识别对象](#_6.6 FaceSearch识别对象)

根据姓名查询用户信息，该接口可用于在人脸信息特征提取成功准备注册到数据库时判断数据库中是否包含该用户

根据用户id查询用户，demo中将数据库id设置为自增的int值，以保证每个id之间不重复，使用该方法可以在人脸识别成功后，通过识别出的用户id在数据库中查询用户信息

根据姓名在数据库删除用户，若产出成功识别前需要在SDK缓存中也删除该接口，或者从新获取一次数据库信息刷新一遍SDK缓存，具体识别接口可参考[6.6 FaceSearch识别对象](#_6.6 FaceSearch识别对象)

5.3.2 CameraPreviewManager类方法说明

CameraPreviewManager相关接口截图及说明如下:

初始化摄像头接口，设置展示画面，设置绘制人脸框镜像信息，设置摄像头角度，摄像头宽高等信息

设置摄像头id，部分摄像头为双目摄像头，包含RGB和NIR两款摄像头，通常id为0是rgb，1为nir

开启摄像头，并且会返回摄像头的宽高（如果初始化摄像头时设置的宽高 摄像头不适配，会返回当前启动摄像头当前适配的宽高）

摄像头数据监听接口，通过该接口获取摄像头的每帧数据，通常为nv21类型，通过获取的摄像头每帧数据送到SDK进行人脸检测等工作

摄像头关闭接口，在界面关闭时调用，清空摄像头缓存(退出SDK或不使用摄像头的时候注意关闭释放资源)

5.3.3 PreviewTexture类方法说明

PreviewTexture相关接口截图及说明如下:

PreviewTexture为摄像头展示view，继承ViewGroup，可以通过setCamera启动摄像头，并将摄像头信息展示到该view中

5.3.4 FaceUtils类方法说明

该类對识别、质量(光照、遮挡、模糊、角度)、活体等参数的阈值进行了封装，可通过该类快速获取识别和SDK初始化时所需要的阈值信息

FaceUtile 相关接口截图及说明如下:

获取模型初始化所需配置

获取识别所需配置

5.3.5 FaceSDKManager类方法说明

faceSDKManager相关接口截图及说明如下:

模型初始化接口，针对人脸快速检测、人脸跟踪、活体检测、特征提取、口罩识别、属性检测、注意力检测、等功能进行模型初始化操作（只有初始化加载了模型、后续人脸检测等能力才能生效）

视频流逐帧检测接口，进行RGB和NIR的人脸检测、活体检测、质量检测、特征提取、1:N识别和1:1识别

特征提取接口，对图片进行人脸特征提取

pushAllPersons接口，主要作用为在识别前将人脸数据库中的信息同步到SDK缓存中(在缓存中比对识别速度更快)，在人脸识别时会将视频流中提取的人脸特征和SDK缓存中的特征进行比较，并返回得分最大的人脸

视频流人脸识别接口，可以识别摄像头中人脸信息，返回人脸坐标进行应用层快速人脸绘制跟踪，并对人脸进行质量检测、活体检测和识别

5.4工程数据库db文件路径自定义说明

dataLibrary中默认会将注册的用户信息默认储存在data/data/包名/database 数据库的face.db默认路径下，可在DBHelper文件夹中放开这部分代码，即可修改数据库文件存储路径

5.5在线特征提取接口调用方式

5.5.1 接口调用

百度AI官网提供了可从云端进行人脸特征值提取的接口功能（通过http调用传入图片base64，返回人脸特征值），可以实现人脸特征抽取和人脸库的构建，主要用于在服务端（云端）提取与人脸离线识别SDK通用的人脸特征值，通过该接口获取的特征值可直接注册到设备中进行人脸1:1或1:N识别，接口调用文档如下：https://ai.baidu.com/ai-doc/FACE/Okg7edktq

此外，demo工程中添加了该接口的调用方式，代码可以参考 dataLibrary模块中的OnLineFeatureManager类，位置如下:

注:该接口需输入对应SDK版本参数（该参数是为了对齐SDK的版本和云端提取版本的特征值通用、只有版本对齐了，SDK的特征值和云端提取的特征值才能通用），目前常用参数为:

如：8.0(8.0到9.0范围,比如8.1、8.2、8.5)的sdk对齐云端:Android_8001

3568 3.1专版sdk:RV1109_3000

5.5.2 特征字符串转换

在线特征提取接口会返回bsae64位的人脸特征字符串，可使用Base64.decode()方法转换为byte数组，截图如下:

5.6 摄像头模组集成方法说明

此章节为应用层的摄像头模组说明，会对不同摄像头进行简单的描述和调用方式，其中摄像头通常分为三类，类型如下、实际场景中，可根据自身需要选择使用那种摄像头配置:

5.6.1 RGB摄像头模组集成说明

RGB摄像头为标准摄像头，Android手机自带摄像头均可理解为RGB摄像头，使用Android原生自带的Camera类进行界面展示和视频流提取，项目工程可参照官网下载的工程包中的FaceSDKAndroid进行集成，工程文件可参照:3.2节 官网工程包结构说明，并且项目中对Camera进行了封装，具体可参照:4.3.5节 CameraPreviewManager类方法说明

5.6.2 RGB+NIR双目摄像头模组集成说明

RGB和NIR摄像头均可以使用android原生自带的Camera类进行界面展示和视频流提取，可以理解为这两种摄像头启动方式完全相同，唯一不同在一启动时传入id不同(id通常由系统决定，未插入其他usb设备情况下，通常为0是RGB、1是NIR)。项目工程可参照官网下载的工程包中的FaceSDKAndroid进行集成，工程文件可参照:3.2 官网工程包结构说明，集成说明如下:

RGB摄像头：同上，可参照5.6.1节 RGB摄像头模组集成说明

NIR摄像头：demo中使用PreviewTexture对NIR摄像头进行了封装(也可以开启RGB摄像头),具体可参考:[5.3.5 PreviewTexture类方法说明](#__x0001_5.2.5 PreviewTexture类方法说明)

Demo 使用 Android Camera API 获取 NV21 数据。摄像头 ID 由设备决定，不能假设所有设备都固定为 RGB=0、NIR=1。应枚举并校验实际设备。

在 onResume 中初始化摄像头和图像配置，在 onPause 中停止预览：

@Override
protected void onPause() {
    super.onPause();
    CameraPreviewManager.getInstance().stopPreview();

    if (nirCamera != null) {
        nirCamera.setPreviewCallback(null);
        nirCamera.stopPreview();
        nirCamera.release();
        nirCamera = null;
    }
}

@Override
protected void onDestroy() {
    CameraPreviewManager.getInstance().release();
    super.onDestroy();
}

检测方向与预览显示方向是两组不同配置。预览看起来正确不代表送入 SDK 的图像方向正确；应以人脸框、关键点和识别结果共同验证方向及镜像。

5.6.3 RGB+DEPTH摄像头模组集成说明

RGB+DEPTH的3D结构光摄像头会根据不同厂家生产的摄像头不同，调用方式各不相同，需要取对应厂家的官网下载摄像头启动的SDK集成到项目中，使用厂家规定的启动开启才行，目前官网项目种仅提供了奥比和华捷两款3D结构光的启动方式，项目工程可参照官网下载的工程包中的FaceSDKAndroid_depth项目进行集成，工程文件可参照:3.2 官网工程包结构说明,集成说明如下:

5.6.3.1 奥比摄像头

奥比摄像头SDK位于工程文件FaceLibrary/libs/orbbec_module-debug.aar下，将该SDK集成到项目可以调取奥比3D结构光摄像头接口

项目代码位于

aobilibrary\src\main\java\com\baidu\idl\main\facesdk\activity\aibi\FaceDepthGateActivity.java

中，提供了RGB和DEPTH的效果展示

RGB摄像头:

奥比RGB摄像头可以使用原生自带camera方式启动，可参照5.5.1 RGB摄像头模组集成说明

DEPTH摄像头:

奥比3D结构光摄像头需要用到奥比SDK中的OpenNIHelper(摄像头启动类) VideoStream(摄像头数据拉取类)和OpenNIView(数据展示类)

首先先在ui中创建摄像头展示view，创建深度摄像头回显

创建完成后，项目中创建OpenNIHelper摄像头启动类，并调用requestDeviceOpen方法开始，监听摄像头状态，

在requestDeviceOpen方法启动摄像头后，会拉起onDeviceOpened，表示摄像头已开启，失败则会拉起onDeviceOpenFailed(摄像头已经启动)或onDeviceNotFound(没有找到深度摄像头)

onDeviceOpened拉起成功后初始化VideoStream摄像头数据拉取类，且由于奥比摄像头种类不同，摄像头宽高比也不同，这里需要使用宽高判断摄像头模组，截图和奥比模组种类如下:

模组宽高设置后，开启一个独立线程，使用VideoStream进行摄像头逐帧数据的拉取，并展示到OpenNIView中，截图如下：

最后，退出界面时(onDestroy ,onPause )需关闭摄像头，关闭当前监听的线程，确保后续功能正确，截图如下

5.6.3.2 华捷摄像头

华捷摄像头SDK位于工程文件FaceLibrary/libs/orbbec_module-debug.aar下，将该SDK集成到项目可以调取奥比3D结构光摄像头接口

项目代码位于

huajielibrary\src\main\java\com\baidu\idl\main\huajie\activity\huajie\FaceLimActivity.java中，提供了RGB和DEPTH的效果展示，截图如下：

并且，需要将datalibrary\src\main\java\com\example\datalibrary\lim华捷摄像头工具类

导入到项目中，集成BaseLimActivity，创建showViewer抽象方法(showViewer会在摄像头启动后被调用)，具体截图如下

集成BaseLimActivity后调用BaseLimActivity的openLim方法，可以打开RGB和DEPTH摄像头，启动成功后会调用showViewer的方法，并返回RGB和DEPTH数据

RGB摄像头:

展示华捷RGB摄像头需要用到GLPanel摄像头展示view，在xml中创建该view实例,在activity中获取彩色图像预览对象，截图如下:

创建GLPanel彩色摄像头对象后，在showViewer抽象方法中将GLPanel赋值给RGB展示对象即可完成摄像头效果展示，截图如下：

DEPTH摄像头:

展示华捷DEPTH摄像头需要用到GLPanel摄像头展示view，在xml中创建该view实例,在activity中获取彩色图像预览对象，截图如下:

创建GLPanel深度摄像头对象后，在showViewer抽象方法中将GLPanel 赋值给深度展示对象即可完成摄像头效果展示，截图如下：

RGB和DEPTH摄像头数据获取:

showViewer方法被调用用可以开启独立线程，获取RGB和DEPTH视频流数据，使用华捷SDK的ImiDevice.ImiFrame类获取RGB和DEPTH的每帧数据，并对每帧数据进行过滤，最终获取正确的视频流数组，具体截图如下

5.7 多人脸识别说明

SDK支持多个人脸进行人脸面部ui绘制和识别，可调整SDK的maxDetectNum参数调整人脸识别数量(建议单次识别10个人脸以内)，并在FaceSDKManager类中开启多人脸识别测试识别效果，具体截图如下:

5.8 Log日志说明

项目中对激活、模型初始化、识别过程进行了日志打印，可通过LogUtils类设置是否打印日志，且可通过FaceModel(模型初始化)、FaceSDKManager(识别)、BdFaceAuth(激活)文字过滤日志，截图如下：

6 SDK功能接口说明

6.1 BDFaceAuth鉴权接口

6.1.1在线授权

6.1.2离线授权

6.1.3批量授权

6.1.4底层log日志接口

6.1.5 设置cpu核数

6.1.6 获取deviceId设备指纹

6.2 FaceSdkController对象

该类封装了对人脸全流程1:N 1:1识别比对 、视频流和图片人脸特征提取、模型初始化、静默激活功能

6.2.1 开启底层log日志

6.2.2 授权接口

6.2.3 模型初始化接口

6.2.4 人脸批量注册接口(全量更新)

6.2.5 人脸批量注册接口

6.2.6 单个特征注册接口

6.2.7 单个特征删除接口

6.2.8 特征全量删除接口

6.2.9 获取缓存中特征数量

6.2.10 人脸图片裁剪接口

6.2.11 人脸识别接口

6.2.11 图片特征提取接口

7 SDK实体类说明

7.1 FaceInfo实体类

7.2 BDFaceGazeInfo 实体类

7.3 Feature实体类

7.4 BDFaceSDKConfig 实体类

7.5 BDFaceModelConfig 实体类

7.6 BDFaceCheckConfig实体类

7.7 LivenessModel实体类

7.8 FeatureData实体类

7.9 BDQualityConfig实体类

7.10 BDLiveConfig实体类

7.11 BDFaceUtilityConfig实体类

8 升级指导

注意:不同版本的人脸特征模型不能同步，大版本更新（小版本不需要，如8.1更新到8.2则不需要,7.0到8.0需要）需要删除人脸库，重新导入人脸

8.1 7.v – 8.v

（更新版本要刷新人脸底库，重新导入人脸）

同上所述，版本更新后,SDK对应的识别 活体 人脸检测等模型，需更新GlobaSet文件下的所有模型路径

8.0开始，识别对象从FaceFeature改为了FaceSearch，添加了单个人脸特征注册功能，请添加最新识别对象

其他版本SDK 升级8.1+，需替换模型以及SDK

替换后更新模型路径文件

8.2 8.v – 9.v

注意:
1、9.0版本sdk更新了设备指纹提取方式，获取的指纹会与9.0以前的历史版本sdk不同，已经激活过的设备使用9.0版本sdk需使用新的序列号从新激活
2、9.0版本的特征值和8.0等之前的版本也不同，不能和之前版本混用

删除8.0版本deteLibrary识别模块和sdk与模型

添加9.0版本sdk模型

9激活和模型初始化错误码说明

9.1在线和离线初始化错误码说明

9.2模型初始化错误码说明

9.3图片特征提取错误码说明