人脸识别离线 SDK

用户接入文档

文档名称	人脸识别Android离线SDK用户接入文档
所属平台	Open鸿蒙 1.0+
适用版本	鸿蒙 5.0系统+
开发语言	ArkTS
文档提交日期	2025.09.26

更新记录

No	版本号	修改内容简介	修改日期
1	V1.1	初版，包括离线人脸采集、离线活体检测、离线对比识别、离线人脸库管理等功能	2025.09.26

1 SDK及Demo工程结构说明

1.1 官网工程包结构说明

目前百度AI官网有集成SDK摄像头、人脸数据库统一封装的效果展示的SDK Demo工程，官网的下载地址为： https://console.bce.baidu.com/ai-engine/old/#/ai/face/offline/index

该工程中分为鸿蒙通用项目、SDK、文档，三个板块，主要功能和截图如下：

文件夹名	说明
SDK	SDK核心库，包含SDK的aar以及模型文件
FaceSDKHarmony	鸿蒙通用项目，支持RGB摄像头和鸿蒙5.0系统的设备，具体功能可参考1.2工程结构说明
开发文档	项目开发文档

1.2 SDK和模型结构说明

SDK分为.har和模型资源文件，结构截图和说明如下：

SDK:

模型文件:

模型文件储存在项目FaceSDKHarmony\entry\src\main\resources\rawfile文件夹中，各模型文件说明如下：

模型文件名称	说明	是否可删	删减说明
align_rgb_customized_pa _fast_model_float32_0_7_5_5	人脸快速对其模型	否	使用人脸跟踪能力可快速进行人脸检测
detect_rgb-customized_pa _192_model_float32_0_0_18_1	人脸检测模型	否	通常与人脸对其模型同时加载，可检测出人脸宽高位置及人脸关键点信息，且后续人脸特征、人脸识别、人脸活体检测中需要用到该模型输出结果，不建议删除
align_rgb_customized_pa _80_model_float32_6_4_14_4	人脸对其模型	否	相比快速对其模型，通常与人脸检测模型同步使用。在检测过程中更加稳定的模型，且后续的活体检测和识别都需要依赖人脸检测的输出结果，不建议删除
blur_customized_pa_addcloud _quant_e19_model_float32_3_0_13_3	人脸质量模糊度检测	否	过滤模糊的图片，选择清晰的图片，可提高识别通过率
liveness_rgb_customized_pa _DCQsdk80_model_float32_1_1_82_1	RGB活体检测模型	是	用于RGB可见光单目静默活体，若只使用rgb静默活体，则该文件夹下除该文件外均可删除
liveness_nir_customized_pa _DCQ_80_model_float32_1_1_78_1	NIR活体检测模型	是	用于NIR可见光单目静默活体，若没有NIR摄像头或不使用NIR活体可删除
liveness_depth-customized_pa _paddle_60_model_float32_1_1_13_2	DEPTH活体检测模型	是	用于3D结构光静默活体检测，不使用3D结构光摄像头情况下可删除
liveness_rgb_customized_pa _model_freeze_2dmask_20211210 _sdk_224_epoch7_model_float32_1_1_80_1	RGB活体多音子检测模型	是	用于增强RGB可见光静默活体防攻击效果的模型，更好的防御电子设备中人脸图片的攻破效果，不需要可删除
liveness_rgb_customized_pa _hand_sdk_224_model_float32_1_1_69_1	RGB活体多音子检测模型	是	用于增强RGB可见光静默活体防攻击效果的模型，更好的防御电子设备中人脸图片的攻破效果，不需要可删除
liveness_rgb_customized_pa _reflection_model_float32_1_1_81_1	RGB活体多音子检测模型	是	用于增强RGB可见光静默活体防攻击效果的模型，更好的防御电子设备中人脸图片的攻破效果，不需要可删除

2 Demo工程的编译和使用

SDK Demo工程下载解压后，使用devecost studio启动工程，FaceSDKHarmony 工程如下：

注：该工程目前仅支持鸿蒙5.0以上系统，且首次启动可能会出现类似下面错误，该错误为签名不同导致。

解决方案：

设置完成后，使用数据线链接设备（部分设备需要在设置中开启开发者模式），点击上方运行项目。

demo主要运行流程为，其中激活须设备能连接网络（离线激活不需要），激活用到的序列号可在百度AI官网申请，官网具体位置和激活流程请参考2.1授权激活，demo主要流程图如下：

2.1 授权激活

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

https://console.bce.baidu.com/ai/?_=1670415860750&fromai=1#/ai/face/offline/index

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

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

2.1.2 在线激活（需要设备能连网）

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

2.1.3 批量激活（需要设备能联网）

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

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

2.2.1 图片及视频流注册

SDK激活成功后（激活可参考2.1授权激活）会进入demo首页，此时会自动进行模型初始化加载操作，等待首页提示模型初始化成功后，再进行后续操作，百度官网的离线激活页面如下：

视频流注册： 首页，点击右上角按钮，选择人脸注册。

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

图片注册： 图片注册需要手动拷贝将需要注册的人脸图片放到设备沙盒路径/data/app/el2/100/base/包名/files文件夹中，在人脸库管理-批量导入中方可进行图片注册，效果如下：

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

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

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

3 SDK及项目集成

3.1 集成说明

项目集成分为业务层（鸿蒙原生）和SDK能力层（原子接口）的集成，集中需要将SDK核心库、SDK模型集成到项目中。（demo项目中还包含了CameraModel类相机封装、FaceManager类 SDK识别功能的封装、AuthUtil类激活接口封装，可根据需求集成到项目中）

3.2 项目集成流程说明

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

SDK核心库、CameraModel相机类、FaceManager识别类集成到项目中后，先调用激活接口initOffLicense（离线激活）、authFromFile（在线激活）、initLicenseBatchLine（批量激活），其中在线激活接口目前需要先自行提那就网络请求获取license激活信息，激活成功（OnResponse方法code参数为0则成功）后，才可以进行之后操作， 才可以进行之后操作，具体代码如下:

激活成功后，需要进行SDK模型初始化和数据库初始化，模型初始化成功后才可以进行后续识别和注册操作。

在线激活

其中AuthUtil.auth_online方法中接口包含http请求和授权文件存储功能，代码如下

AuthUtil.auth_online_initLicense中包含使用授权文件和激活码激活功能，代码如下

离线激活

批量激活

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

FaceSDKManager.getInstance().initModel接口包含:

FaceDetect类中人脸检测模型的初始化

FaceDetect类中质量检测模型的初始化

FaceLive类中活体检测模型的初始化

FaceFeature类中人脸特征提取模型的初始化

FaceSearch人脸识别模型的初始化

单个模型初始化接口可参考下图:

模型初始化成功后，需要进行人脸注册才可以正常识别到人脸， 通过FaceManager.getInstance().getPixelMapFeature获取的人脸特征结果，具体可参考下图:

其中，FaceManager.getInstance().getPixelMapFeature特征提取接口中包含:

FaceDetect的detect人脸检测接口调用

FaceFeature的feature人脸特征提取接口调用

具体截图如下:

数据库保存成功后，在通过FaceSDKManager.getInstance().dbFeaturePush方法，将数据库的人脸信息放到SDK缓存中(在数据库中的人脸特征需要通过该接口放到sdk缓存后，在1:N识别中才可以正常识别到)

注册成功后，在识别界面创建CameraModel和XComponent启动相机，并展示相机画面，获取相机逐帧数据，具体截图如下：

摄像头启动成功后，在CameraDataCallback的接口可获取到摄像头每帧数据。

再识别页面启动后，通过 FaceManager.getInstance().setFaceDataCallback注册识别监听。将视频流每帧数据通过FaceManager.getInstance().onDetectCheck对该数据进行人脸识别操作

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

FaceDetect类中的track人脸快速检测接口调用

FaceDetect类中的detect人脸检测接口调用

FaceLive类中的silentLive人脸活体检测接口调用

FaceFeature类中的feature人脸特征提取接口调用

FaceSearch类中的注册接口调用

FaceSearch类中的1:N识别接口调用

FaceSearch类中的1:1识别接口调用

代码截图如下:

3.3 工程核心类和方法说明

Demo工程中的封装了数据库、摄像头以及SDK识别、激活功能的使用，核心功能类分为：

类名	功能说明
AuthUtil	SDK激活类，封装了在在线、离线、批量激活、网络请求等功能，只需一个接口方可获取激活信息，具体可参考3.3.1 AuthUtil类方法说明
FaceManager	封装SDK接口，通过一个方法可进行人脸检测、活体检测、质量检测、1：1比对、1：N识别效果，且封装了人脸模型的初始化，人脸特征注册接口，具体可参考3.3.2 FaceManager类方法说明
CameraModel	摄像头启动类，可通过该类进行RGB摄像头的展示，并获取摄像头逐帧数据，具体可参考3.3.3 CameraModel类方法说明
DBManager	数据库类，封装了数据库的增删改查接口，可以高效存储SDK获取的人脸特征，具体可参考3.3.4 DBManager类方法说明

3.3.1 AuthUtil类方法说明

该类为SDK激活封装类，客户可根据自身业务调整，主要作用为快速进行在线、离线、批量激活接口的调用。

方法名	所需参数	功能说明
getDeviceId(): Promise	无	获取设备oaid（设备唯一标识）
auth_offline(callBack:AuthCallBack): number	callBack: 激活结果	离线激活
auth_online(license_key:string,device_id:string): Promise	license_key: 激活序列号 device_id: oaid设备指纹	拉取在线激活激活文件
auth_online_initLicense(license_key: string ,callBack:AuthCallBack): number	license_key: 在线激活序列号 callBack:激活结果	在线激活
auth_batch(callBack:AuthCallBack, licenseKey: string): number	license_key: 批量激活序列号 callBack:激活结果	批量激活

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

获取设备唯一标识，这个接口会根据硬件和软件唯一标识和SDK内部算法返回一个不变的设备指纹（刷机情况下设备指纹会改变），通过该指纹进行设备一对一激活

离线激活，需要在官网获取的激活信息解压后放到项目entry\src\main\resources\rawfile目录下，进行激活，具体可参考2.1.1离线激活（适应于无网或弱网环境） ，接口截图如下:

拉取在线激活 激活文件，在线激活接口调用前，需要先拉取服务器在线激活信息并保存到本地，具体截图如下:

在线激活，成功拉取在线激活信息后，调用在线激活接口进行激活，可参考2.1.2在线激活(需要设备能连网)，接口截图如下:

批量激活，demo中需在代码中调整批量激活序列号，可参考2.1.3批量激活(需要设备能联网)，接口截图如下:

3.3.2 FaceManager类方法说明

该类是对SDK识别功能的封装，主要包含注册、1:N识别、1:1比对、活体检测、人脸特征提取、质量检测等，客户可根据自身业务调整，主要作用为快速对摄像头数据进行识别和注册。

方法名	所需参数	功能说明
onDetectCheck(rgbData:ArrayBuffer, type:number, compareFeature: Uint8Array | null,w: number,h: number)	rgbData:RGB视频流 type:识别参数FaceManager.SEARCH识别FaceManager.COMPARE 1:1比对 compareFeature: 1:1比对功能，需要比对的人脸特征 w: 视频流数据宽 h: 视频流数据高	视频流1:1识别、1:N识别的封装接口，可获取人脸大小位置信息、质量检测、活体检测、识别、耗时等信息
dbFeaturePush()	无	注册数据库中的人脸特征
initModel(context:Context, initLicenseSuccess:()=> void,initLicenseFail:(modeInitCode:number, modeInitResponse: string) => void)	Context:上下文 initLicenseSuccess:模型初始化成功回调 InitLicenseFail:模型初始话失败回调	初始化模型
getPixelMapFeature(searchImage:image.PixelMap,isGetHeadImage: boolean = false): PixelMapFeatureModel	searchImage:人脸图片 isGetHeadImage:是否需要裁剪人脸图片	提取图片人脸特征并裁剪人脸图像
setFaceDataCallback(faceDataCallback: FaceDataCallback | null)	FaceDataCallback:人脸识别结果回调	识别监听接口，注册该接口可获取onDetectCheck中人脸识别的结果

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

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

setFaceDataCallback识别监听接口，onDetectCheck接口获取的人脸信息最终会传递到该接口的faceDataCallback参数中

onDetectCheck视频流逐帧检测接口，对RGB摄像头进行人脸检测、活体检测、质量检测、特征提取、1:N识别或1:1识别

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

dbFeaturePush接口，主要作用为在识别前将人脸数据库中的信息注册到SDK缓存中，在人脸识别时会将视频流中提取的人脸特征和注册到SDK缓存中的特征进行比较，并返回得分最大的人脸

3.3.3 CameraModel类方法说明

方法名	所需参数	功能说明
openCamera(context:Context, surfaceId: string)	context:上下文 SurfaceId:摄像头id	开启摄像头

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

构造方法，创建摄像头对象，并注册摄像头数据监听接口

开启摄像头

3.3.4 DBManager类方法说明

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

方法名	所需参数	功能说明
userAdd(user: User,addCallback:(isAdd: boolean) => void)	user:用户信息 addCallback:添加结果	添加用户
queryAllUserLists(): ArrayList	无	查询所有用户信息
isHaveUser(userName: string)	userName：用户名	判断用户名在数据库是否存在
queryFirstUser(id: number): User | null	id：用户id	根据用户id查询用户
queryDeleteUserById(ids: Array): boolean	ids ：用户id数组	根据id删除用户

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

添加用户，将用户信息注册到数据库，进行识别前需要提取出该信息放入SDK缓存中进行识别

查询所有用户，通常在识别前需要先将SDK缓存中的数据删除后获取数据库所有信息，在注册到SDK缓存中

查询所有用户，通常在识别前需要先将SDK缓存中的数据删除后获取数据库所有信息，在注册到SDK缓存中

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

4 SDK功能接口说明

4.1 FaceAuth鉴权接口

构造方法	参数	类型	说明
FaceAuth()	无		创建一个FaceAuth

4.1.1 开启底层Log输出

方法名	setActiveLog
说明	用于Debug时候输出LOG详细信息
方法	setActiveLog(logInfo: BDFaceLogInfo, isLog: number): void;
请求参数	说明
logInfo	底层log打印 BDFACE_LOG_VALUE_MESSAGE // 打印输出值日志 BDFACE_LOG_ERROR_MESSAGE // 打印输出错误日志 BDFACE_LOG_ALL_MESSAGE, // 打印所有日志
isLog	是否开启日志

4.1.2 设置核数

方法名	setCoreConfigure
说明	根据开发板类型，设置加速对Cpu核数依赖，调整参数，提高性能
方法	setCoreConfigure(runMode: BDFaceCoreRunMode, coreNum: number): void
请求参数	说明
runMode	推荐使用0，1，3；如果有需要绑核的话，用0和1；如果不需要绑核，系统自动调度的话，用3 BDFACE_LITE_POWER_HIGH=0, 绑定大核运行模式。如果ARM CPU支持big.LITTLE，则优先使用并绑定Big cluster。如果设置的线程数大于大核数量，则会将线程数自动缩放到大核数量。如果系统不存在大核或者在一些手机的低电量情况下会出现绑核失败，如果失败则进入不绑核模式。 BDFACE_LITE_POWER_LOW=1,绑定小核运行模式。如果ARM CPU支持big.LITTLE，则优先使用并绑定Little cluster。如果设置的线程数大于小核数量，则会将线程数自动缩放到小核数量。如果找不到小核，则自动进入不绑核模式。 BDFACE_LITE_POWER_FULL=2,大小核混用模式。线程数可以大于大核数量。当线程数大于核心数量时，则会自动将线程数缩放到核心数量。 BDFACE_LITE_POWER_NO_BIND=3,不绑核运行模式（推荐）。系统根据负载自动调度任务到空闲的CPU核心上。 BDFACE_LITE_POWER_RAND_HIGH=4,轮流绑定大核模式。如果Big cluster有多个核心，则每预测10次后切换绑定到下一个核心。 BDFACE_LITE_POWER_RAND_LOW=5,轮流绑定小核模式。如果Little cluster有多个核心，则每预测10次后切换绑定到下一个核心。
coreNum	cpu选择线程数，建议不超过2

4.1.3 离线激活接口

方法名	initOffLicense
说明	用户通过读取resoures/rawfile目录下的鉴权文件鉴权
方法	initOffLicense(context: Context, licenseId: string, licenseFileName: string, isRemote: boolean, callback: Callback): void
请求参数	说明
context	当前上下文
licenseId	鉴权key
licenseFileName	鉴权文件名称
isRemote	是否远程拉取
callback	鉴权结果 void onResponse(int code, String response) code 0 : 成功；code 1 加载失败

4.1.4 激活接口

方法名	authFromFile
说明	读取自定义路径下的鉴权文件鉴权
方法	authFromFile(licenseId: string, licensePath: string, isRemote: boolean): nativeModule.ErrorCode
请求参数	说明
licenseId	鉴权key
licenseFileName	鉴权文件路径
isRemote	是否远程拉取

4.1.5 批量激活接口

方法名	initLicenseBatchLine
说明	用户通过申请在线批量licenseID进行激活，可直接网络请求获取鉴权文件
方法	initLicenseBatchLine(context: Context, licenseId: string, callback: Callback): void
请求参数	说明
context	当前上下文
licenseId	官网在线批量授权码
callback	鉴权结果 void onResponse(int code, String response) code 0 : 成功；code 1 加载失败

4.2 FaceDetect检测接口

构造方法	参数	类型	说明
FaceDetect ()	无		创建一个FaceDetect
FaceDetect(BDFaceInstance thisBdFaceInstance)	BDFaceInstance		绑定指定的BDFaceInstance实例，否则使用默认的BDFaceInstance实例

4.2.1 检测对齐模型加载

方法名	initModel
说明	检测模型加载，目前支持可见光模型，近红外检测模型（非必要参数，可以为空），对齐模型
方法	initModel(context: Context, visModel: string,nirModel: string,alignModel: string,callback: Callback): void
请求参数	说明
context	上下文context
visModel	可见光图片检测模型
nirModel	红外图片检测模型
alignModel	对齐模型
callback	模型加载结果void onResponse(int code, String response) code : 请参照此文档6.2模型初始化错误码说明

4.2.2 检测对齐模型加载

方法名	initModelWithType
说明	检测模型加载，近红外检测模型（非必要参数，可以为空），对齐模型
方法	initModelWithType(context:Context,detectModel:string,alignModel:string,detectType: DetectType,alignType: AlignType,callback: Callback): void
请求参数	说明
context	上下文context
detectModel	检测模型
alignModel	对齐模型
detectType	检测类型 DETECT_VIS 为可见光；DETECT_NIR为近红外
alignType	对齐类型 BDFACE_ALIGN_TYPE_RGB_ACCURATE 为可见光对齐类型; BDFACE_ALIGN_TYPE_NIR_ACCURATE 为 近红外对齐类型
callback	模型加载结果void onResponse(int code, String response) code : 请参照此文档6.2模型初始化错误码说明

4.2.3 质量检测模型加载

方法名	initQuality
说明	质量检测模型加载，判断人脸遮挡信息，光照信息，模糊信息，模型包含模糊模型，遮挡信息，作用于质量检测接口
方法	initQuality(context: Context, blurModel: string, occluModel: string, callback: Callback): void
请求参数	说明
context	上下文context
blurModel	模糊检测模型
occluModel	遮挡检测模型
callback	模型加载结果void onResponse(int code, String response) code : 请参照此文档6.2模型初始化错误码说明

4.2.4 属性模型加载

方法名	initAttribute
说明	人脸属性（年龄，性别，戴眼镜等），情绪（喜怒哀乐）模型初始化
方法	initAttribute(context: Context, attributeModel: string, callback: Callback): void
请求参数	说明
context	上下文context
attributeModel	属性检测模型
callback	模型加载结果void onResponse(int code, String response) code : 请参照此文档6.2模型初始化错误码说明

4.2.5 眼睛闭合，嘴巴闭合模型加载

方法名	initFaceClose
说明	人脸眼睛闭合，嘴巴闭合模型初始化
方法	initFaceClose(context: Context, eyecloseModel: string, mouthcloseModel: string, callback: Callback): void
请求参数	说明
context	上下文context
eyecloseModel	人脸眼睛闭合模型
mouthcloseModel	人脸嘴巴闭合模型
callback	模型加载结果void onResponse(int code, String response) code : 请参照此文档6.2模型初始化错误码说明

4.2.6 最优人脸模型加载

方法名	initBestImage
说明	最优人脸模型初始化
方法	initBestImage(context: Context, bestModel: string, callback: Callback): void
请求参数	说明
context	上下文context
bestModel	最优人脸模型地址
callback	模型加载结果void onResponse(int code, String response) code : 请参照此文档6.2模型初始化错误码说明

4.2.7 配置信息加载

方法名	loadConfig
说明	检测最小人脸，是否开启内部质量检测，检测或者追踪时间间隔等配置
方法	loadConfig(config: BDFaceSDKConfig): void
请求参数	说明
config	参数5.1 BDFaceSDKConfig配置实体类

4.2.8 人脸框检测

4.2.8.1 根据图片进行检测

方法名	detect
说明	人脸框检测，每一帧图片都会检测，返回基本人脸信息和72关键点，可以绘制人脸框，描绘眼耳鼻嘴关键点，也可作用于后续活体，特征抽取入参。
方法	detect(detectType: DetectType, imageInstance: BDFaceImageInstance): FaceInfo[]
请求参数	说明
detectType	检测类型
imageInstance	图片数据信息

4.2.8.2 根据传入的人脸框信息进行检测

方法名	flexibleDetect
说明	可灵活配置的人脸检测接口，使用输入的faceInfos通过配置bdFaceDetectListConfig可以控制是否进行一下能力的预测：人脸检测，关键点提取，头部姿态角，光照，模糊，属性，情绪，闭眼，闭嘴。输出返回值为预测后的faceInfos，可作用于后续活体，特征抽取入参。
方法	flexibleDetect(detectType:DetectType,imageInstance: BDFaceImageInstance,alignType: AlignType,faceInfos: FaceInfo[] |null,bdFaceDetectListConfig:BDFaceDetectListConf): FaceInfo[] | null
请求参数	说明
detectType	检测类型
imageInstance	图片数据信息
alignType	对齐类型
faceInfos	人脸框数据（可以通过人脸追踪能力获取人脸框）
bdFaceDetectListConfig	功能开关

4.2.9 人脸跟踪-多人脸检测（接口只支持RGB跟踪）

方法名	track
说明	视频人脸跟踪检测，追踪图片中多个人脸信息，通过参数num配置，接口包含检测和跟踪功能，返回基本人脸信息和72关键点，可以绘制人脸框，描绘眼耳鼻嘴关键点，也可作用于后续活体，特征抽取入参。
方法	track(detectType: DetectType, imageInstance: BDFaceImageInstance): FaceInfo[] | null
请求参数	说明
detectType	检测类型
imageInstance	图片数据信息

4.2.10 人脸跟踪-多人脸检测

方法名	fastTrack
说明	视频人脸跟踪检测，追踪图片中多个人脸信息，通过参数num配置，接口包含检测和跟踪功能，返回基本人脸信息和72关键点，可以绘制人脸框，描绘眼耳鼻嘴关键点，也可作用于后续活体，特征抽取入参。
方法	fastTrack(detectType: DetectType, alignType: AlignType,imageInstance: BDFaceImageInstance): FaceInfo[] | null
请求参数	说明
detectType	检测类型
alignType	对齐类型
imageInstance	图片数据信息

4.2.11 检测模型卸载

方法名	uninitModel
说明	卸载模型
方法	unInitModel(): number
请求参数	说明
无	无

4.3 FaceLive活体接口

构造方法	参数	类型	说明
FaceLive()	无		创建一个FaceLive
FaceLive(BDFaceInstance thisBdFaceInstance)	BDFaceInstance		绑定指定的BDFaceInstance实例，否则使用默认的BDFaceInstance实例

4.3.1 活体模型加载

方法名	initModel
说明	静默活体检测模型初始化，可见光活体模型，深度活体，近红外活体模型初始化
方法	initModel(context:Context,visModel: string,vis2dmaskModel:string,visHandModel: string,visReflectionModel: string,nirModel: string,depthModel: string,callback: Callback): void
请求参数	说明
context	上下文
visModel	可见光图片活体模型
vis2dmaskModel	2d_mask多因子活体模型
visHandModel	屏幕多因子活体模型
visReflectionModel	手部多因子活体模型
nirModel	红外图片活体模型
depthModel	深度图片活体模型
Callback	模型加载结果void onResponse(int code, String response) code : 请参照此文档6.2模型初始化错误码说明

4.3.2 人脸静默活体检测

方法名	silentLive
说明	静默活体分值检测，返回0-1结果，建议超过0.9为活体
方法	silentLive(type: LiveType, bdFaceImageInstance: BDFaceImageInstance, landmarks: number[]): number
请求参数	说明
type	LIVEID_VIS 可见光图像静默活体检测 LIVEID_NIR 红外图像静默活体检测
bdFaceImageInstance	图片数据信息
landmarks	人脸检测后的landmark

4.3.3 人脸静默活体检测（可控制多因子阈值）

方法名	silentLiveWithThreshold
说明	静默活体分值检测，返回0-1结果，建议超过0.9为活体
方法	silentLive(type: LiveType, bdFaceImageInstance: BDFaceImageInstance, landmarks: number[]): number
请求参数	说明
type	LIVEID_VIS 可见光图像静默活体检测 LIVEID_NIR 红外图像静默活体检测
bdFaceImageInstance	图片数据信息
landmarks	人脸检测后的landmark
liveThreshold	活体阈值，通过该阈值控制多因子阈值，0 ~ 0.6：0.05；0.61 ~ 0.0.8：0.1； 0.81 ~ 1.0：0.5

4.3.4 人脸静默多帧活体检测

方法名	strategySilentLive
说明	静默活体检测，是否为活体， true： 活体， false： 非活体
方法	strategySilentLive(type:LiveType,bdFaceImageInstance: BDFaceImageInstance,faceInfo:FaceInfo,strategyCount: number,liveThreshold: number): boolean
请求参数	说明
type	LIVEID_VIS 可见光图像静默活体检测 LIVEID_NIR 红外图像静默活体检测
bdFaceImageInstance	图片数据信息
faceInfo	人脸信息
strategyCount	多帧次数
liveThreshold	活体阈值

4.3.5 静默活体模型卸载

方法名	uninitModel
说明	卸载模型
方法	unInitModel(): number
请求参数	说明
无	无

4.4 FaceFeature特征接口

构造方法	参数	类型	说明
FaceFeature()	无		创建一个FaceLive
FaceFeature(BDFaceInstance thisBdFaceInstance)	BDFaceInstance		绑定指定的BDFaceInstance实例，否则使用默认的BDFaceInstance实例

4.4.1 特征模型加载

方法名	initModel
说明	离线特征获取模型加载，目前支持可见光模型，近红外检测模型（非必要参数，可以为空），证件照模型；用户根据自己场景，选择相应场景模型
方法	initModel(context: Context,idPhotoModel: string,visModel: string,nirModel: string,callback: Callback): void
请求参数	说明
context	上下文
idPhotoModel	证件照图片模型
visModel	可见光图片模型
nirModel	红外图片模型
Callback	模型加载结果void onResponse(int code, String response) code : 请参照此文档6.2模型初始化错误码说明

4.4.2 新版本模型加载

（文档中此部分内容与4.4.1重复，故不重复列出）

4.4.3 人脸特征提取

方法名	feature
说明	离线特征提取接口，通过featureType提取不同图片特征数据，函数返回特征个数，特征存储在feature参数中
方法	feature(featureType:FeatureType,imageInstance: BDFaceImageInstance,landmarks: number[], feature: Uint8Array): number
请求参数	说明
featureType	BDFACE_FEATURE_TYPE_LIVE_PHOTO 生活照 BDFACE_FEATURE_TYPE_ID_PHOTO 证件照 BDFACE_FEATURE_TYPE_NIR 红外
imageInstance	图像信息
landmarks	检测后产出的数据
feature	红外图片模型

4.4.4 有RGBD特征提取

方法名	featureRGBD
说明	离线特征提取接口，通过featureType提取不同图片特征数据，函数返回特征个数，特征存储在feature参数中
方法	featureRGBD(featureType:FeatureType,imageInstance: BDFaceImageInstance,imageInstanceDepth: BDFaceImageInstance, landmarks: number[], feature: Uint8Array): number | null
请求参数	说明
featureType	BDFACE_FEATURE_TYPE_LIVE_PHOTO 生活照 BDFACE_FEATURE_TYPE_ID_PHOTO 证件照 BDFACE_FEATURE_TYPE_NIR 红外
imageInstance	图像信息
imageInstance	Depth图像信息
landmarks	检测后产出的数据
feature	红外图片模型

4.4.5 卸载特征模型

方法名	uninitModel
说明	卸载模型
方法	unInitModel(): number
请求参数	说明
无	无

4.5 BDFaceImageInstance图片接口

构造方法	参数	类型	说明
BDFaceImageInstance (data?: number | PixelMap | ArrayBuffer, height?: number, width?: number,imageTypeInt?: number, angle?: number, isMbyteArrayror?: number)	data图片字节数 height图片高 Width 图片宽 imageType图片类型 angle图片旋转角度 isMbyteArrayror是否镜像		创建图片对象
BDFaceImageInstance (pixelMap: PixelMap)	BDFaceInstance		创建图片对象

4.5.1 获取图片对象

方法名	getImage
说明	获取图片对象
方法	getImage(): BDFaceImageInstance | null
请求参数	说明
无	无

4.5.2 销毁图片对象

方法名	destroy_img
说明	获取图片对象
方法	destroy_img(): number
请求参数	说明
无	无

4.6 FaceCrop抠图能力

可以根据人脸框或者人脸关键点进行抠图。

构造方法	参数	类型	说明
FaceCrop()	无		创建一个FaceLive
FaceCrop(BDFaceInstance thisBdFaceInstance)	BDFaceInstance		绑定指定的BDFaceInstance实例，否则使用默认的BDFaceInstance实例

4.6.1 initFaceCrop抠图能力加载

方法名	initFaceCrop
说明	initFaceCrop抠图能力加载
方法	initFaceCrop(callback: Callback): void
请求参数	说明
Callback	模型加载结果void onResponse(int code, String response) code : 请参照此文档6.2模型初始化错误码说明

4.6.2 cropFaceByLandmark使用人脸关键点进行人脸扣图

方法名	cropFaceByLandmark
说明	根据人脸检测结果扣图，扣图结果为矫正之后的人脸信息
方法	cropFaceByLandmark(imageInstance: BDFaceImageInstance,landmark:number[],enlargeRatio: number,correction:boolean,isOutOfBoundary:number[]): BDFaceImageInstance | null
请求参数	说明
imageInstance	图片数据信息
landmark	检测后产出数据
enlargeRatio	抠图放大倍数
correction	是否进行人脸矫正
isOutofBoundary	是否进行人脸矫正

4.6.3 uninitFaceCrop抠图能力卸载

方法名	unInitFaceCrop
说明	卸载模型
方法	unInitFaceCrop(): number
请求参数	说明
无	无

4.7 FaceMouthMask口罩检测

可以根据人脸框或者人脸关键点进行抠图。

构造方法	参数	类型	说明
FaceMouthMask()	无		创建一个FaceLive
FaceMouthMask(BDFaceInstance thisBdFaceInstance)	BDFaceInstance		绑定指定的BDFaceInstance实例，否则使用默认的BDFaceInstance实例

4.7.1 口罩检测结果获取

方法名	checkMask
说明	通过图片和人脸框数据获取口罩检测置信度数据
方法	checkMask(bdFaceImageInstance: BDFaceImageInstance, faceInfos: FaceInfo[]): number[] | null
请求参数	说明
bdFaceImageInstance	图像信息
faceInfos	人脸框数据

4.7.2 口罩检测模型卸载

方法名	unInitModel
说明	卸载模型
方法	unInitModel(): number
请求参数	说明
无	无

4.8 FaceSearch口罩检测

可以根据人脸框或者人脸关键点进行抠图。

构造方法	参数	类型	说明
FaceSearch()	无		创建一个FaceLive
FaceSearch(BDFaceInstance thisBdFaceInstance)	BDFaceInstance		绑定指定的BDFaceInstance实例，否则使用默认的BDFaceInstance实例

4.8.1 1:N特征设置注册

特征集合预加载接口，继承Feature，必须初始化id和feature字段，用于1：N内部实现和数据返回。

4.8.1.1 单个特征注册接口

方法名	pushPersonById
说明	添加单个数据，主要用于人脸注册以及其他单个人脸添加
方法	pushPersonById(pointID: number, feature: Uint8Array): number
请求参数	说明
pointID	人员id，不可重复
feature	人员特征feature数组，默认初始化512空字节（3568专版SDK为1024字节）

4.8.1.2 批量特征注册接口

方法名	pushPersonFeatureList
说明	批量添加数据，主要用于程序启动时
方法	pushPersonFeatureList(features: ArrayList): number
请求参数	说明
features	多张人脸特征信息

4.8.1.3 单个特征删除接口

方法名	delPersonById
说明	根据人员ID删除单个特征数据，主要用于人脸库删除操作时使用
方法	delPersonById(pointID: number): number
请求参数	说明
pointID	注册时传入的id

4.8.1.4 全部特征删除接口

方法名	featureClear
说明	删除所有注册的特征
请求参数	featureClear(): number
请求参数	说明
无

4.8.2 识别多帧检测接口

该接口会筛选识别过程中的识别成功且满足条件优质人脸最为底图重新入库，且可自由设置每个人员的优质人脸数量和条件阈值，建议8.5以上的通用版SDK中使用。

4.8.2.1 最大更新数量接口

方法名	setMaxUpdateSize
说明	最大更新数量 默认：10
方法	setInputDBThreshold(setInputDBThreshold: number): void
请求参数	说明
maxUpdateSize	入库数量,0为不使用多帧

4.8.2.2 入库间隔时长接口

方法名	setInputDBIntervalTime
说明	入库间隔时长 默认：24小时
方法	setInputDBIntervalTime(intervalTime: number): void
请求参数	说明
intervalTime	间隔多久可从继续让识别人脸冲新入库

4.8.2.3 注册照比对阈值设置接口

方法名	setRegisterCompareThreshold
说明	注册照比对阈值 取值范围：0-1，默认：0.8
方法	setRegisterCompareThreshold(registerCompareThreshold: number): void
请求参数	说明
registerCompareThreshold	多帧检测识别入库阈值

4.8.2.4 更新照比对接口

方法名	setUpdateCompareThreshold
说明	// 更新照比对阈值 取值范围：0-1， 默认：0.9
方法	setUpdateCompareThreshold(updateCompareThreshold: number): void
请求参数	说明
updateCompareThreshold	多帧检测识别入库阈值

4.8.2.5 入库阈值设置

方法名	setInputDBThreshold
说明	入库阈值 取值范围：0-1 默认：0.92
方法	setInputDBThreshold(setInputDBThreshold: number): void
请求参数	说明
inputDBThreshold	多帧入库阈值

4.8.2.6 多帧检测人员入库监听

方法名	setInputDBListener
说明	对识别过程中识别图像满足多帧条件后，识别图片入库的监听
方法	setInputDBListener(inputDBListener: InputDBListener): void
请求参数	说明
inputDBListener	onInputDB(int id1, int id2)多帧检测监听，返回多帧入库后的人员id

4.8.3 1:1比对

方法名	compare
说明	两张feature人脸特征进行比对，返回float得
方法	compare(featureType: FeatureType, feature1: Uint8Array, feature2: Uint8Array, isPercent: boolean): number
请求参数	说明
featureType	BDFACE_FEATURE_TYPE_LIVE_PHOTO // 生活照特征 BDFACE_FEATURE_TYPE_ID_PHOTO, // 证件照特征 BDFACE_FEATURE_TYPE_NIR
feature1	特征1
feature2	特征2
isPercent	是否进行阈值映射

4.8.4 1:N比对

方法名	search
说明	当前feature和预加载Feature集合比对，返回预加载Feature集合中命中的id，feature字段和比对分值score；用户可以通过id在数据库中查找全量信息。
方法	search(featureType: FeatureType, threshold: number, topNum: number, feature: Uint8Array): ArrayList | undefined
请求参数	说明
featureType	BDFACE_FEATURE_TYPE_LIVE_PHOTO// 生活照特征 BDFACE_FEATURE_TYPE_ID_PHOTO, // 证件照特征 BDFACE_FEATURE_TYPE_NIR
threshold	比对阈值
topNum	获取前num个feature+id映射数组
feature	当前检查人脸特征值

5 SDK实体类说明

5.1 BDFaceSDKConfig配置实体类

变量	类型	默认值	说明
scaleRatio	number	-1	输入图像的缩放系数
maxDetectNum	number	10	需要检测的最大人脸数目
minFaceSize	number	0	需要检测的最小人脸大小
notRGBFaceThreshold	number	0.3	人脸置信度阈值（检测分值大于该阈值认为是人脸）
notNIRFaceThreshold	number	0.5	人脸置信度阈值（检测分值大于该阈值认为是人脸）
detectInterval	number	0	未跟踪到人脸前的检测时间间隔
trackInterval	number	500	已跟踪到人脸后的检测时间间隔
isCheckBlur	boolean	false	质量检测模糊，默认不做质量检测
isOcclusion	boolean	false	质量检测遮挡，默认不做质量检测
isIllumination	boolean	false	质量检测光照，默认不做质量检测
isHeadPose	boolean	false	姿态角检测，获取yaw（左右偏转角），roll（人脸平行平面内的头部旋转角），pitch（上下偏转角），默认不检测
isAttribute	boolean	false	属性检查，获取年龄，种族，是否戴眼镜等信息，默认不检测
isEmotion	boolean	false	7种情绪信息获取，默认不检测
isCropFace	boolean	false	是否扣图，默认不扣图
isEyeClose	boolean	false	是否检测眼睛闭合，默认不检测
isMouthClose	boolean	false	是否检测嘴巴闭合，默认不检测
isBestImage	boolean	false	是否开启最优人脸检测，默认步开启

5.2 FaceInfo实体类

变量	类型	默认值	说明
faceID	number		人脸索引值，标记连续视频帧追踪中人脸ID
centerX	number		人脸中心点x坐标
centerY	number		人脸中心点y坐标
width	number		人脸宽度
height	number		人脸高度
angle	number		人脸角度
score	number		人脸置信度
landmarks	number[]		人脸72个关键点数据（鼻子，眼镜，嘴巴，眉毛）
yaw	number		人脸左右偏转角
roll	number		人脸平行平面内的头部旋转角
pitch	number		人脸上下偏转角
bluriness	number		人脸模糊度信息
illum	number		人脸光照信息
occlusion	BDFaceOcclusion		人脸遮挡信息
age	number		人脸年龄

6 多端特征同步说明

鸿蒙1.0版本sdk与安卓8.0、windos 8.0、Linux Arm V8.0特征值对齐，但由于系统不同相同图片不同SDK提取的特征值不会完全相同。

百度AI官网也提供了可从云端进行人脸特征值提取的接口功能（通过http调用传入图片base64，返回人脸特征值）接口调用文档可参考： https://ai.baidu.com/ai-doc/FACE/Okg7edktq ，会返回base64加密的String类型特征，可解码为Uint8Array在项目中正常使用。

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

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

错误码	描述
0	激活成功
1	license未初始化
2	license数据解密失败
3	license格式错误
4	key校验错误
5	算法id校验错误
6	MD5校验失败
7	设备id校验失败
8	包名校验错误
9	过期时间不正确
10	功能未授权
11	授权过期
12	本地文件读取失败
13	远程数据拉取失败
14	本地时间校验失败

7.2 模型初始化错误码说明

错误码	描述
0	激活成功
1	为null或者模型路径错误；
-1	非法的参数
-2	内存分配失败
-3	实例对象为空
-4	模型内容为空
-5	不支持的能力类型
-6	不支持预测类型
-7	预测库对象创建失败
-8	预测库初始化失败
-9	图像数据为空
-10	人脸能力初始化失败
-11	能力未加载
-12	人脸能力已加载
-13	未授权
-14	人脸能力运行异常
-15	不支持的图像类型
-16	图像转换失败；

8 常见问题

8.1 SDK崩溃

8.1.1 设备架构不适配

目前设备仅支持鸿蒙5.0以上64位系统的架构，请检查系统是否符合改架构。

8.1.2 CPU线程过载（通常为模型初始化崩溃）

部分鸿蒙系统仅支持单线程cpu，请将setCoreConfigure该接口调整线程数调整为1在进行测试。

8.2 摄像头无法启动

8.2.1 检查是否正常检测到摄像头

摄像头无法启动可能是由于摄像头id设置错误导致，先排查是否正常检测获取摄像头信息，且保证摄像头id设置正常。，代码如下

8.2.2 检查启动SurfaceId是否可以正常获取

部分鸿蒙系统可能启动摄像头可能获取SurfaceId时崩溃，导致摄像头启动失败，可排查SurfaceId接口获取是否正常，如失败需检测硬件链接是否正常。

8.3 考勤、人证核验或注册模块进入后崩溃

该问题通常为摄像头启动后摄像头数据格式不匹配导致，demo默认使用yuv 21格式解码，部分摄像头需要使用rgba格式，可调整为rgba格式测试是否成功。

8.4 无法检测到人脸

8.4.1 SDK检测角度不正确

可点击首页右上角按钮，在设置设置中可调整SDK检测角度。

8.4.2 检测图片格式不正确

摄像头逐帧数据和SDK解码后的图片格式不正确（未出现崩溃）会导致检测不到人脸，需保存摄像头识别图片到沙盒排查该图片是否存在花屏或角度不正确问题，截图如下

在考勤界面onTrackCallback接口中添加存图逻辑，图片会保存到沙盒路径Save-Image文件夹下。

若存在图片花屏请联系摄像头厂确认摄像头数据格式，后通过该接口调整SDK摄像头解码格式（通常为RGBA或YUV 21）。