更新记录

1.3.1（2026-10-06）

统一插件 ID、目录与导入路径为 whd-inspireface，配套使用说明和完整 Vue3 示例。
支持离线人脸检测、RGB 静默活体、512 维特征提取与 SQLite 本地 1:N 人脸库。
提供实时相机预览、人脸框和三色识别状态，显示验证进度、失败原因及业务资料。
支持摄像头枚举与 cameraId 选择，完善无摄像头、权限不足及驱动异常的退出处理。
支持实时采集、多人候选选择及用户确认登记，提供特征更新和删除。
完善系统屏幕旋转与等比预览，画面和人脸框共用映射。
提供人脸图片抓取、私有保存、再次识别与删除，并限制处理频率和缓存容量。

平台兼容性

uni-app(4.25)

Vue2	Vue3	Chrome	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
-	-	-	-	-	-	7.0	-	-

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
-	-	-	-	-	-	-	-	-	-	-	-

安卓人脸识别对比-可离线

whd-inspireface · 版本 1.3.1

为 uni-app Android 应用提供离线人脸检测、实时相机预览、RGB 静默活体和本地 1:N 人脸库。支持采集注册、特征更新与删除、姓名等业务资料展示，以及人脸图片保存。随附示例为普通 uni-app Vue3。

要求 HBuilderX 4.25.0+、Android 7.0（API 24）+，支持 armeabi-v7a / arm64-v8a。当前未提供 iOS、Web、小程序实现或 uni-app x 示例验证。

安装

从插件市场导入，或解压 whd-inspireface.zip，将其中的 uni_modules 合并到项目根目录。插件目录为 uni_modules/whd-inspireface/，内含 package.json 和 utssdk/。
在 Android 应用配置中开启 Camera 模块，声明 android.permission.CAMERA；开启实时预览前取得用户授权。相册选图使用宿主的 Gallery/系统选图能力。
制作并安装包含本插件的 Android 自定义基座，运行时选择该基座。修改 UTS、Kotlin 或 AAR 后需重新制作；标准基座不包含本插件。
下载 whd-inspireface-demo.zip，解压后用 HBuilderX 打开工程，配置自己的 AppID，再制作基座。示例包含首页自检、实时识别、人脸库和本地图片四个页面。

图片登记与识别

以下代码用于普通 uni-app Android App。将图片路径传入函数，路径应为应用可访问的本地绝对路径；仅在完成相应的用户授权后调用。

// #ifdef APP-PLUS
import * as face from '@/uni_modules/whd-inspireface'
// #endif

function registerAndRecognize(registerImagePath, queryImagePath) {
  // #ifdef APP-PLUS
  if (uni.getSystemInfoSync().platform !== 'android') return

  const initialized = face.init()
  if (!initialized.success) throw new Error(initialized.errMsg)

  const hub = face.featureHubEnable()
  if (!hub.success) throw new Error(hub.errMsg)

  const registered = face.registerFace(registerImagePath, 1001)
  if (!registered.success) throw new Error(registered.errMsg)

  const result = face.recognizeFace(queryImagePath, {
    livenessThreshold: 0.9,
    recognitionThreshold: 0.6
  })
  if (!result.success) throw new Error(result.errMsg)
  console.log(result.matched, result.id, result.confidence,
    result.recognitionMessage)
  return result
  // #endif
}

初始化和启用人脸库通常只需在业务开始时执行。ID 使用非负整数，由业务分配；未匹配时 ID 为 -1。操作成功不等于识别匹配成功，须同时检查 success 和 matched。默认启用 RGB 活体，普通照片也可能无法通过活体验证；登记用于录入特征，不等同于身份认证。

常用接口

接口	用途
`init()` / `release()`	初始化 / 释放引擎
`getCameraDevices()`	枚举摄像头，取得实际 `cameraId`
`startCameraPreview(options)`	开启实时预览，传入屏幕 CSS 像素边界 `left/top/width/height`
`getCameraPreviewState()`	查询预览状态与当前人脸结果
`updateCameraPreviewBounds(options)` / `stopCameraPreview()`	更新布局 / 停止预览
`requestCameraCapture()` / `getCameraCaptureResult(id)`	请求并读取一次人脸抓取
`featureHubEnable()` / `featureHubCount()`	启用 SQLite 人脸库 / 查询数量
`registerFace(path, id)` / `recognizeFace(path, options?)`	图片登记 / 本地 1:N 识别
`featureHubInsert(id, feature)` / `featureHubUpdate(id, feature)`	使用已取得的特征登记 / 更新
`featureHubRemove(id)` / `featureHubClear()`	删除单人 / 清空人脸库
`updateCameraFaceData(options)`	更新姓名、备注、工号等业务资料及显示字段
`saveFaceImage(options)` / `listSavedFaceImages()` / `deleteSavedFaceImage(path)`	保存、列出和删除私有人脸图片

摄像头、抓取、业务资料更新及图片保存管理接口返回 JSON 字符串，先使用 JSON.parse()。上例中的初始化、人脸库启用、登记与识别返回对象。

实时接入参考示例 pages/detect/index.vue：授权后枚举摄像头，优先前置；读取预览区域位置后启动并轮询状态。离开页面或进入后台时停止预览并清理轮询。state: 'starting' 仅表示启动请求已接受，后续仍须处理运行状态和错误。

配置与注意

默认活体阈值 0.9、1:N 相似度阈值 0.6，分数必须严格高于阈值。实时活体默认要求同一人脸连续通过 3 次，可设 1–5 次；黄色框为验证中、红色为失败、绿色为成功。
previewScaleType: 'fit' 完整等比显示并允许留边；'fill' 等比铺满并裁剪。原生处理系统旋转，页面布局变化后仍需更新预览边界。
实时登记使用 mode: 'capture'。取得候选图片与同帧特征后停止预览，让用户选择并确认，再调用登记或更新接口；不要重新检测小尺寸缩略图来提取登记特征。
临时人脸图片会受时效和容量限制，需保留时调用 saveFaceImage()。持久图片和人脸库在应用私有目录，卸载或清除应用数据会删除。
RGB 活体效果受设备、光照与距离影响，需在目标设备评估；连续通过次数不代表独立的屏幕翻拍检测能力。
遇到 method not found 或旧模块入口，重新制作并安装包含 whd-inspireface 的基座，核对设备上加载的调试资源。插件 ID 与旧版不同，直接沿用旧基座会出现入口不一致。

隐私、权限与模型授权

必需相机权限为 android.permission.CAMERA，仅处理已有图片时无需开启相机。插件私有图片和数据库无需共享存储读写权限；示例相册权限由宿主选图模块及 Android 版本决定。

当前封装及示例在设备本地处理人脸图片、特征、活体分数和业务资料，没有自动上传、广告或统计埋点实现，未配置接收人脸数据的服务器。登记资料保存在应用本地，持久图片与人脸特征可通过接口删除。

随附 AAR 使用 InspireFace 1.2.3.post4 与精简的 Pikachu 模型。上游明确规定这些开源模型仅限非商业学术用途，禁止商业应用；商业使用须另行取得适用授权。插件免费配置不改变模型限制，详见上游许可说明和包内 THIRD_PARTY_NOTICES.md。