更新记录
1.0.0(2026-11-16)
- 首次发布。
- 支持百度人脸离线识别 SDK 9.0:在线 / 离线(License.zip)/ 批量激活,设备指纹与授权信息查询。
- 支持 SDK 初始化参数:CPU 核数、运行模式、活体 / 质量 / 属性 / 口罩 / 安全帽 / 视线 / 暗光增强。
- 支持人脸注册:单图(路径 / base64)、目录批量、相机实时注册(活体 + 质量 + 特征采集)。
- 支持 1:N 底库检索与 1:1 人证核检,阈值可配,命中冷却去重。
- 支持两张图片 1:1 比对。
- 支持人脸库增删查、按 id 查询、模糊搜索、分页、总数、清空,SQLite 持久化 + 内存底库自动同步。
- 支持自定义数据目录(人脸库 / 注册图 / 授权文件)。
- 提供
<zy-baidu-face-register>与<zy-baidu-face-recognition>两个 nvue 原生组件: 设备相机(CameraX)与 UVC/USB 外接摄像头(CameraHelper)双路取流、人脸框叠加、事件回传。
平台兼容性
uni-app(4.72)
| Vue2 | Vue3 | Vue3插件版本 | Chrome | Safari | app-vue | app-vue插件版本 | app-nvue | app-nvue插件版本 | Android | Android插件版本 | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| √ | √ | 1.0.0 | × | × | √ | 1.0.0 | √ | 1.0.0 | 5.0 | 1.0.0 | × | × |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| × | × | × | × | × | × | × | × | × | - | × | × |
uni-app x(4.72)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| - | - | 5.0 | - | - | - |
zy-baidu-face 百度离线人脸识别(支持 UVC / USB 外接摄像头)
Android 平台 UTS 插件(uni-app / uni-app x),基于 百度人脸离线识别 SDK 9.0(FaceSDK + datalibrary), 识别全程离线(仅在线激活需要联网),支持设备相机与 UVC/USB 外接摄像头两种取流方式。
| 能力 | 说明 |
|---|---|
| 激活授权 | 在线激活、离线激活(License.zip)、批量激活、设备指纹、授权信息(到期时间)、激活状态查询 |
| SDK 初始化 | CPU 核数 / 运行模式、底层日志开关、活体 / 质量 / 属性 / 口罩 / 安全帽 / 视线 / 暗光增强模型按需初始化 |
| 人脸注册 | 单图注册(路径 / base64)、批量注册(目录)、相机实时注册(活体 + 质量 + 特征自动采集) |
| 人脸识别 | 1:N 底库检索(可多目标)、1:1 人证核检(底图比对)、相似度阈值可配 |
| 人脸比对 | 两张图片(路径 / base64)1:1 比对,返回分值与是否通过 |
| 人脸库 | 增删查、按 id 查、模糊搜索、分页、总数、清空;SQLite 持久化 + 内存底库同步 |
| 数据目录 | 自定义数据目录(人脸库 / 注册图 / 授权文件),支持迁移 |
- 支持平台:App-Android(uni-app Vue2/Vue3、uni-app x)
- 最低系统:Android 5.0(API 21),实测建议 Android 7.0+
- ABI:
armeabi-v7a、arm64-v8a
示例页面
| 示例 | 文件 | 内容 |
|---|---|---|
| 百度离线人脸识别(API) | pages/baidu-face/baidu-face.vue |
权限、激活(在线/离线/批量)、初始化、单图/批量注册、人脸库、1:1 比对、日志 |
| 人脸注册(nvue 组件) | pages/baidu-face/baidu-face-camera.nvue |
<zy-baidu-face-register> 预览、人脸框、活体/质量开关、手动与自动注册 |
| 人脸识别(nvue 组件) | pages/baidu-face/baidu-face-recognition.nvue |
<zy-baidu-face-recognition> 1:N 识别、识别开关热切换、人证核检 |
组件用法要点:uts 组件不要 import、也不要写 components 注册,直接用组件名作为标签 (
<zy-baidu-face-register>/<zy-baidu-face-recognition>),由编译器自动解析到uni_modules/zy-baidu-face/utssdk/app-android/index.vue与recognition.vue。 组件依赖NVLoad / NVLoaded生命周期,只能用在 nvue 页面,且必须给原生组件设置宽高。
一、依赖说明
utssdk/app-android/config.json 已声明全部依赖(来自私有 maven 仓库,凭据已内置):
| 依赖 | 用途 |
|---|---|
com.zy.sdk:faceSDK-9.0-core-20261015 |
百度人脸 SDK 核心(datalibrary + FaceSDK + 授权库) |
com.zy.sdk:faceSDK-9.0-core-20261015-models |
检测/对齐/活体/特征/属性模型(assets 内置) |
com.zy.sdk:libuvccamera |
UVC/USB 摄像头预览与取帧(CameraHelper) |
androidx.camera:camera-*:1.4.2 |
设备相机预览与帧分析(CameraX) |
模型随 aar 的 assets 打进 App,无需手动拷贝模型文件。
模型路径要求:FaceSDK 按常量路径
assets/face-sdk-models/detect|align|feature|...读取模型, 因此 models 依赖内的模型必须位于 aar 的assets/face-sdk-models/目录下(本插件配套的faceSDK-9.0-core-20261015-models已按该结构打包)。另外:插件依赖 maven 三方 SDK,标准基座无法生效,必须使用自定义基座/云打包。
二、激活(重要)
首次使用必须先激活,否则 initSdk 会失败。
1. 离线激活(推荐)
- 调用
getDeviceId拿到设备指纹; - 在百度控制台用设备指纹申请
License.zip; - 把
License.zip放到设备存储根目录/storage/emulated/0/(这是 SDK 的默认查找目录,需要「所有文件访问权限」, 可先调toAllFilesPermissionPage引导授权); - 调用
activeOffline()(不传path即走默认目录)。
也可以把 License.zip 放在任意应用可读目录,用显式路径激活:
activeOffline({ path: '/storage/emulated/0/Android/data/<包名>/files/License.zip' }),
path 既可以是 zip 文件,也可以是所在目录。
传空
path时 SDK 报「未找到授权文件,请将文件放到 /storage/emulated/0 目录」, 即说明默认目录下没有License.zip(或未获得所有文件访问权限)。
2. 在线激活
activeOnline({
code: 'AAAA-BBBB-CCCC-DDDD',
success: (res) => console.log('激活成功', res.data),
fail: (err) => console.error('激活失败', err.errCode, err.errMsg)
})
3. 批量激活
activeBatch({ licenseId })。
三、快速开始
import {
requestPermissions, isActive, initSdk, imageRegister, getAllFaces, imageCompare
} from '@/uni_modules/zy-baidu-face'
// 1) 权限(相机 + 存储 + 电话状态,SDK 生成稳定设备指纹用)
requestPermissions({ success: () => {} })
// 2) 初始化(激活后调用,耗时 1~3 秒,建议在页面 onLoad 之后)
initSdk({
live: true, // 活体模型
quality: true, // 质量模型(模糊/遮挡/光照/姿态)
attribute: true, // 年龄/性别/眼镜/表情
rgbLiveScore: 0.8, // 活体阈值
minFaceSize: 80, // 最小人脸像素
success: (res) => console.log('SDK 就绪,底库人数', res.data.faceCount),
fail: (err) => console.error('初始化失败', err.errCode, err.errMsg)
})
// 3) 单图注册
imageRegister({
userName: '张三',
imagePath: '/storage/emulated/0/DCIM/zhangsan.jpg',
success: (res) => console.log('注册成功 id=', res.data.id),
fail: (err) => console.error(err.errCode, err.errMsg)
})
// 4) 查询
getAllFaces({ page: 1, pageSize: 20, success: (res) => console.log(res.data.total, res.data.list) })
// 5) 1:1 比对
imageCompare({
imagePath1: '/storage/emulated/0/DCIM/a.jpg',
imagePath2: '/storage/emulated/0/DCIM/b.jpg',
threshold: 0.8,
success: (res) => console.log('分值', res.data.score, '通过', res.data.matched)
})
四、API
所有方法均支持 success / fail / complete;success 收到 { code, message, data },
fail 收到 UniError(errCode 为 93xxxxx,见文末错误码)。
1. 权限
| 方法 | 参数 | 说明 |
|---|---|---|
requestPermissions |
permissions?: string[] |
申请相机/存储/电话状态权限,已授予自动跳过,最长等待 10 秒;data 返回 granted、denied、camera |
checkAllFilesPermission |
- | Android 11+ 是否拥有「所有文件访问权限」,data.granted |
toAllFilesPermissionPage |
- | 跳转「所有文件访问权限」设置页(批量导入外部目录时需要) |
2. 配置
| 方法 | 参数 | 说明 |
|---|---|---|
setActiveLog |
enable?: boolean |
打开底层日志(调试) |
setCoreConfigure |
cpuNum?: number(1~8)、runMode?: string(high/low/full/noBind/randHigh/randLow) |
需重新 initSdk 生效 |
setCustomSaveDir |
dir?: string |
自定义数据目录(人脸库 / 注册图 / 授权文件),传空串恢复默认;切换后自动重建底库 |
3. 授权
| 方法 | 参数 | 说明 |
|---|---|---|
getDeviceId |
- | data.deviceId:设备指纹(申请离线授权用) |
getLicenseData |
- | data:licenseKey、deviceId、expireTime、functionList、active 等 |
isActive |
- | 已激活走 success(data.active),未激活/过期走 fail(9300004) |
activeOnline |
code: string |
在线激活 |
activeOffline |
path?: string |
离线激活(License.zip 所在文件或目录) |
activeBatch |
licenseId: string |
批量激活 |
4. 初始化
| 方法 | 参数 | 说明 |
|---|---|---|
initSdk |
见下表 | 初始化模型,重复调用直接返回成功 |
| 字段 | 默认 | 说明 |
|---|---|---|
maxDetectNum |
1 |
最大检测人脸数(multiIdentify 为 true 时默认 5) |
minFaceSize |
80 |
最小人脸像素 |
faceThreshold |
0.5 |
检测阈值 |
multiIdentify |
false |
多人脸识别 |
attribute |
false |
年龄/性别/眼镜/表情 |
quality |
false |
模糊/遮挡/光照/姿态检查 |
bestImage |
true |
最优图。必须开启:SDK 活体前会校验 bestImageScore > 0.5,关闭时该分恒为 0,活体不会执行(rgbLiveScore 恒为 0);传 false 也会被强制为 true |
darkEnhance |
false |
暗光增强 |
live |
true |
活体模型 |
rgbLiveScore / nirLiveScore / depthLiveScore |
0.8 |
活体阈值 |
mouthMask / safetyHat / gaze |
false |
口罩 / 安全帽 / 视线模型 |
5. 注册
| 方法 | 参数 | 说明 |
|---|---|---|
imageRegister |
userName(必填)、userId?、userInfo?、imagePath? / imageBase64?、quality?、saveImage?(默认 true) |
单图注册;data 返回 id、userId、userName、imagePath、score |
batchRegister |
dir(必填)、continueOnError?、saveImage? |
目录批量注册,文件名(去扩展名)即用户名;data 返回 total、success、fail、list[] |
注册成功后特征会立即推入内存底库,识别组件无需重新初始化即可命中。
6. 人脸库
| 方法 | 参数 | 说明 |
|---|---|---|
deleteFace |
id |
删除单条(同步删除内存底库与注册图) |
deleteFaces |
ids: number[] |
批量删除 |
getAllFaces |
page?、pageSize?、keyword? |
列表,data.list[] + data.total |
getFaceById |
id |
单条详情(含 feature base64) |
getFaceCount |
- | data.count(库内数量)、data.cacheCount(内存底库数量) |
clearFace |
- | 清空人脸库(含底库与注册图) |
7. 比对
| 方法 | 参数 | 说明 |
|---|---|---|
imageCompare |
imagePath1? / imageBase64_1?、imagePath2? / imageBase64_2?、threshold?(默认 0.8) |
data.score、data.matched |
五、组件
1. 人脸注册 <zy-baidu-face-register>
<zy-baidu-face-register
class="camera"
:config="config"
:auto-start="true"
@onEvent="onEvent"
ref="camera" />
data() {
return {
config: {
cameraType: 'device', // device | uvc
front: true, // 设备相机前后
live: true, liveThreshold: 0.8,
quality: true,
attribute: true,
showOverlay: true, overlayColor: '#0D9EFF',
displayMode: 'fill', // fill | fit
detectInterval: 180,
autoCapture: false, captureStableCount: 3, userName: ''
}
}
}
方法:
| 方法 | 说明 |
|---|---|
start() / stop() |
开始 / 停止预览与检测 |
switchCamera() |
切换前后摄(UVC 不支持) |
register({ userName, userId, userInfo, saveImage }) |
用当前帧特征注册(等下一帧合格人脸执行) |
cancelRegister() |
取消等待 |
事件 onEvent:e.detail = { type, code, msg, dataJson }(nvue 里需先 unwrapUTS,参考示例页)。
| type | 说明 |
|---|---|
ready |
相机就绪(data.width/height/cameraType) |
detect |
每帧检测结果(data.faces[],含人脸框、活体分、质量、属性、识别结果) |
tip |
检测提示(未检测到人脸等) |
check |
校验未通过(质量/活体/多人脸,msg 为可展示文案) |
feature |
特征就绪(data.stableCount / needStableCount),可注册 |
register |
注册结果(code=0 成功,data 同 imageRegister) |
error |
相机/SDK 错误(code 见错误码) |
2. 人脸识别 <zy-baidu-face-recognition>
配置字段同上,另有:
| 字段 | 默认 | 说明 |
|---|---|---|
identifyThreshold |
0.8 |
1:N 判定阈值 |
multiIdentify |
false |
是否同时识别多张人脸 |
方法:
| 方法 | 说明 |
|---|---|
start() / stop() |
开始 / 停止 |
switchCamera() |
前后摄切换 |
openRecognition() / closeRecognition() |
1:N 识别开关热切换(关闭后仍做人脸检测与活体) |
checkRecognition() |
查询是否可识别:data.ready / faceCount / recognitionEnabled |
startIdentify({ imagePath, imageBase64, threshold }) |
开始人证核检(1:1) |
endIdentify() |
结束人证核检 |
事件额外包含:
| type | 说明 |
|---|---|
recognize |
1:N 命中:data.id / userName / score / centerX / centerY |
identify |
人证核检通过:data.score / threshold / matched |
checkRecognition |
识别状态查询结果 |
openRecognition / closeRecognition |
开关回执 |
同一人 2 秒内只派发一次
recognize;阈值不足会派发check(msg可展示)。
六、UVC / USB 摄像头
config.cameraType = 'uvc'
config.uvcVendorId = 0 // 0 = 不限制,可按设备过滤
config.uvcProductId = 0
config.uvcWidth = 640 // 0 = 自动挑最接近 640x480 的分辨率
config.uvcHeight = 480
config.direction = 0 // 0/90/180/270,摄像头倒装时用
config.mirror = 0 // 1 = 镜像
首次插入 USB 摄像头时系统会弹「允许访问 USB 设备」,同意后即可预览;
拔插设备会通过 attach / detach / deviceOpen / cameraOpen 等事件回传。
提示:
direction != 0时 SDK 内部会旋转后检测,人脸框叠加可能与人脸错位, 建议优先通过摄像头安装方向解决,而不是用direction。 人脸框对齐依赖displayMode,UVC 建议fill,画面有黑边时改fit。
七、错误码
| 错误码 | 说明 |
|---|---|
| 9300001 | 参数错误 |
| 9300002 | SDK 未初始化(先 initSdk) |
| 9300003 | SDK 初始化失败(模型缺失 / 授权无效 / 设备不支持) |
| 9300004 | 未激活或授权已过期 |
| 9300005 | 激活失败 |
| 9300006 | 未检测到人脸 |
| 9300007 | 检测到多张人脸 |
| 9300008 | 人脸质量不合格 |
| 9300009 | 活体检测未通过 |
| 9300010 | 特征提取失败 |
| 9300011 | 人脸已存在(用户名重复) |
| 9300012 | 人脸不存在 |
| 9300013 | 人脸库为空 |
| 9300014 | 图片读取失败 |
| 9300015 | 图片保存失败 |
| 9300016 | 未获得相机权限 |
| 9300017 | 相机不可用 |
| 9300018 | 未检测到 USB 摄像头 |
| 9300019 | 存储目录不可用 |
| 9300020 | 操作进行中 |
| 9300021 | 文件不存在 |
| 9300022 | 未获得存储权限 |
| 9300023 | 操作失败 |
八、注意事项
- 必须先激活再 initSdk;授权与设备指纹绑定,换设备需重新申请 License。
initSdk与激活回调都在异步线程执行,不要阻塞主线程等待。- 人脸特征(512 字节)与注册图保存在本机(默认
Android/data/<包名>/files/zyBaiduFace/), 卸载应用即丢失;需要长期保存请用setCustomSaveDir指定外部目录。 - 相机组件为原生 View,必须给宽高,且只能用于 nvue 页面。
setCoreConfigure会重建 SDK 实例,调用后需重新initSdk;修改后底库会自动重新载入。- 多人脸识别需
initSdk({ multiIdentify: true }),否则只返回一张人脸。

收藏人数:
购买源码授权版(
试用
使用 HBuilderX 导入示例项目
赞赏(0)
下载 73
赞赏 0
下载 12768266
赞赏 1959
赞赏
京公网安备:11010802035340号