更新记录

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. 离线激活(推荐)

  1. 调用 getDeviceId 拿到设备指纹;
  2. 在百度控制台用设备指纹申请 License.zip;
  3. 把 License.zip 放到设备存储根目录 /storage/emulated/0/(这是 SDK 的默认查找目录,需要「所有文件访问权限」, 可先调 toAllFilesPermissionPage 引导授权);
  4. 调用 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 操作失败

八、注意事项

  1. 必须先激活再 initSdk;授权与设备指纹绑定,换设备需重新申请 License。
  2. initSdk 与激活回调都在异步线程执行,不要阻塞主线程等待。
  3. 人脸特征(512 字节)与注册图保存在本机(默认 Android/data/<包名>/files/zyBaiduFace/), 卸载应用即丢失;需要长期保存请用 setCustomSaveDir 指定外部目录。
  4. 相机组件为原生 View,必须给宽高,且只能用于 nvue 页面。
  5. setCoreConfigure 会重建 SDK 实例,调用后需重新 initSdk;修改后底库会自动重新载入。
  6. 多人脸识别需 initSdk({ multiIdentify: true }),否则只返回一张人脸。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

android.permission.CAMERA(相机)、android.permission.INTERNET(在线激活)、android.permission.READ_PHONE_STATE / WRITE_SETTINGS(SDK 获取稳定设备指纹)、android.permission.READ_EXTERNAL_STORAGE / WRITE_EXTERNAL_STORAGE(批量导入、自定义目录)

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件使用百度离线人脸识别 SDK,人脸特征与注册图仅保存在本机应用目录;激活时会把设备指纹提交到百度授权服务

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。