更新记录

0.1.9（2026-06-27）

0.1.9

平台兼容性

uni-app(4.87)

uni-app x(4.87)

ainuo-face-sdk

Ainuo Face SDK uni-app 插件，提供人脸初始化、相机录入、相机识别、动作活体、图片特征提取、图片 1:1 对比、图片 1:N 搜索、人脸库管理，以及可嵌入页面的 <ainuo-face-search-view /> 相机识别组件。

本文面向 uni-app 业务开发者，只说明 JS/UTS 调用方式、参数、事件和使用注意事项。

🚀 核心优势

• 纯离线运行：SDK 所有的活体检测、特征提取、1:1 / 1:N 对比均在本地端侧完成，完全支持离线运行，无需依赖外网，保证数据的绝对安全与极高的识别响应速度。
• Web 端生态支持：除了提供 App 端的插件，我们还提供配套的 Web-SDK。支持在纯 Web 浏览器环境下提取人脸特征，方便业务侧实现多端统一的人脸信息采集与注册。
• 支持双引擎切换：默认内置极速版轻量模型（体积小、推理极快）；同时，为了满足更苛刻的场景，SDK 可免费平替/兼容更高精度的工业级模型（如海量数据训练的经典通用大库模型），业务线可按需灵活选型！

🎯 适用场景与说明

• ✅ 推荐场景：非常适合用于企业考勤打卡、门禁通行、内部人员签到、展会/活动入场核验等日常业务级的身份核实，可快速帮助您搭建高效、低成本的人脸识别功能。
• ⚠️ 不适用场景（非金融级方案）：本 SDK 属于业务级通用人脸识别方案，并非“金融级”防伪方案。不支持且强烈不建议用于支付、金融转账、高等级政务安防等对防伪级别有极其严苛要求的场景。请各位开发者合理评估业务需求后使用。

📱 体验 App (Demo)

欢迎扫码下载体验 App，直观感受人脸识别、动作活体等功能的效果：

原生体验版 (Android/iOS)	uni-app 体验版 (Android)

💡 购买权益与授权

购买本插件（普通版或源码版）后，您将获得以下权益，请联系作者（微信 z448401921 / 邮箱 448401921@qq.com）获取相关资料与授权：

• 终身离线授权：获取无时间限制、完全纯离线运行的 licenseText 授权文本，绝无定期联网验证，保证绝对离线安全。
• Web-SDK 授权：免费赠送配套的纯前端 Web-SDK，方便您在浏览器或网页管理后台实现统一的人脸采集与录入。
• 插件源码开放：提供当前 uni-app 插件层面的全部源代码，方便您在业务侧进行深度二次定制与开发。
• 底层 SDK 源码（仅限源码买断版）：如果您购买的是“源码买断版”，除上述内容外，您还将获得完整的 Android / iOS 底层原生 SDK 源代码，实现底层技术的完全自主可控。
• 高阶技术支持：提供 VIP 级别的远程技术支持，包含免费指导替换高精度工业级模型以及深度的远程模型定制训练技术支持。

支持范围

• App Android
• App iOS
• uni-app 普通 .vue 页面可调用 API 方法
• <ainuo-face-search-view /> 需要放在 app-nvue 页面或 uni-app x app-uvue 页面中
• H5、小程序端不支持本插件能力

插件包含相机、识别和人脸库能力，首次集成、升级插件版本、变更权限或变更平台依赖后，需要重新制作自定义基座或重新云打包。普通热更新适合调试页面 JS 逻辑，不适合验证新增的插件能力。

快速开始

在页面中导入插件方法：

import {
  initialize,
  isInitialized,
  getSdkInfo,
  release,
  startRegister,
  startSearch,
  startLiveness,
  extractFeatureFromImage,
  compareImages,
  searchImage,
  importPersonFeature,
  countPersons,
  listPersons,
  deletePerson,
  clearPersons,
} from '@/uni_modules/ainuo-face-sdk'

应用启动后先初始化一次：

initialize({
  licenseText: '你的授权文本',
  success: res => {
    console.log('初始化成功', res)
  },
  fail: err => {
    console.log('初始化失败', err)
  },
})

推荐流程：

1. 调用 initialize。
2. 调用 countPersons / listPersons 刷新人脸库。
3. 使用 startRegister 录入人员，或用 extractFeatureFromImage + importPersonFeature 从图片导入人员。
4. 使用 startSearch 打开识别页面，或在 app-nvue 页面中使用 <ainuo-face-search-view />。

通用返回格式

所有异步 API 都通过 success、fail、complete 回调返回对象。基础字段如下：

常见状态码：

常见业务字段：

API 方法

initialize(options)

初始化插件。建议在 App 启动或首页进入时调用一次。

说明：

• 已初始化时再次调用会直接返回当前状态，不会重复初始化。
• 授权文本通常与应用包名绑定，换包名后需要使用匹配的授权。

isInitialized()

同步返回是否已初始化。

const ready = isInitialized()

getSdkInfo()

同步返回当前初始化状态、版本、模型信息和授权信息。

const info = getSdkInfo()
console.log(info.initialized, info.version)

release()

释放当前插件资源。一般只在退出登录、切换授权、应用不再需要人脸能力时调用。普通页面返回不需要调用全局 release()。

const res = release()

startRegister(options)

打开内置相机录入页面。录入成功后自动返回当前 uni-app 页面。

示例：

startRegister({
  personId: 'person-' + Date.now(),
  name: '张三',
  extraJson: JSON.stringify({ source: 'uniapp' }),
  groupId: 'default',
  title: '录入人脸',
  success: res => {
    console.log('录入成功', res.personId, res.name)
  },
})

startSearch(options)

打开内置相机识别页面。

也可以把 threshold、topK、livenessRequired 等识别配置字段直接写在 options 顶层。顶层字段会覆盖 searchConfig 中同名字段。

startSearch({
  title: '人脸识别',
  finishOnMatched: true,
  searchConfig: {
    threshold: 0.55,
    topK: 3,
    livenessRequired: false,
    groupId: 'default',
  },
  success: res => {
    if (res.matched) {
      console.log('命中人员', res.personId, res.name, res.similarity)
    }
  },
})

startLiveness(options)

打开内置动作活体页面。

startLiveness({
  title: '活体检测',
  enableSound: true,
  success: res => {
    console.log('活体结果', res.code)
  },
})

extractFeatureFromImage(options)

从图片路径中提取人脸特征。图片路径可使用 uni.chooseImage 返回的 tempFilePaths[0]。

成功返回的主要字段：

uni.chooseImage({
  count: 1,
  success: ({ tempFilePaths }) => {
    extractFeatureFromImage({
      imagePath: tempFilePaths[0],
      success: res => {
        console.log('特征', res.featureBase64)
      },
    })
  },
})

compareImages(options)

图片 1:1 对比，返回两张图片是否为同一人。

compareImages({
  firstImagePath: imageA,
  secondImagePath: imageB,
  success: res => {
    console.log(res.matched, res.similarity, res.threshold)
  },
})

searchImage(options)

图片 1:N 搜索，在本地人脸库中查找最相似的人员。

成功返回最佳结果字段，并在 matches 中返回 TopK 候选列表。

searchImage({
  imagePath,
  topK: 5,
  groupId: 'default',
  success: res => {
    console.log('最佳结果', res.personId, res.similarity)
    console.log('TopK', res.matches)
  },
})

importPersonFeature(options)

把已提取的人脸特征导入人脸库。适合做 JSON 导入、后台下发人员数据、跨端迁移等场景。

importPersonFeature({
  personId: 'person-001',
  name: '张三',
  featureBase64: record.featureBase64,
  featureFormat: record.featureFormat || 'float32-le-base64',
  modelVersion: record.modelVersion,
  groupId: 'default',
  extraJson: JSON.stringify({ source: 'manual' }),
  success: res => {
    console.log('导入成功', res.person)
  },
})

推荐手工导入 JSON 结构：

{
  "persons": [
    {
      "personId": "person-001",
      "name": "张三",
      "featureBase64": "完整特征base64",
      "featureFormat": "float32-le-base64",
      "modelVersion": "face-model",
      "groupId": "default",
      "extraJson": "{\"source\":\"manual\"}"
    }
  ]
}

countPersons(options)

查询人脸库人数。

listPersons(options)

分页查询人脸库。

deletePerson(options)

删除指定人员。

clearPersons(options)

清空人脸库。

识别配置 searchConfig

searchConfig 可用于 startSearch，也对应 <ainuo-face-search-view /> 的主要 props。

调参建议：

• 想更容易命中：适当降低 threshold 或 confirmHitCount。
• 想更严格：提高 threshold，开启 livenessRequired，或提高 confirmMinAverageScore。
• 页面需要实时候选展示：关注 mostSimilar 事件和 matches。
• 业务最终确认：优先以 matched 事件或 success 回调中的 matched === true 为准。

人脸搜索组件

<ainuo-face-search-view /> 是可嵌入页面的相机识别组件。它必须运行在 app-nvue 或 app-uvue 页面中；普通 .vue 页面请使用 API 方法，不要直接承载该组件。

组件不会自动初始化插件。请先在应用入口调用 initialize，初始化成功后再进入组件页面。

基础用法

<template>
  <view class="page">
    <ainuo-face-search-view
      ref="faceSearchView"
      class="face-search-view"
      :autoStart="true"
      :threshold="0.55"
      :topK="3"
      :livenessRequired="false"
      :enableRealtimeFaceBox="true"
      lensFacing="front"
      previewScaleType="fitCenter"
      @ready="onViewEvent('ready', $event)"
      @faceDetected="onViewEvent('faceDetected', $event)"
      @mostSimilar="onViewEvent('mostSimilar', $event)"
      @matched="onViewEvent('matched', $event)"
      @failed="onViewEvent('failed', $event)"
      @tips="onViewEvent('tips', $event)"
      @log="onViewEvent('log', $event)"
    />
  </view>
</template>

.page {
  flex: 1;
  background-color: #000000;
}

.face-search-view {
  width: 750rpx;
  height: 1334rpx;
}

全屏页面建议用 uni.getSystemInfoSync() 读取 windowWidth/windowHeight，把组件 style 设置为真实窗口宽高，避免相机画面被错误拉伸。

Props

previewScaleType 可选：

• fitCenter
• fitStart
• fitEnd
• fillCenter
• fillStart
• fillEnd

enableRealtimeFaceBox=false 时，组件不绘制内置跟随框。业务可以监听 faceDetected.faces，根据 left/top/right/bottom 自行画框或自绘 UI。

Events

faces 单项字段：

matches 单项字段：

mostSimilar.matches 适合展示实时 TopK 候选；matched 事件适合作为业务确认依据。

Android 和 iOS 组件都声明相同事件。由于不同平台的事件对象包装方式不同，建议在页面中统一解析：

function parseAinuoEvent(event) {
  const detail = event && event.detail ? event.detail : event

  const payloadJson =
    detail && detail.payloadJson
      ? detail.payloadJson
      : detail && detail.dynamicJSONFields
        ? detail.dynamicJSONFields.payloadJson
        : ''

  if (payloadJson) {
    try {
      return JSON.parse(payloadJson)
    } catch (error) {
      return {}
    }
  }

  if (detail && detail.dynamicJSONFields) {
    return detail.dynamicJSONFields
  }

  return detail || {}
}

日志里看到 dynamicJSONFields 是 uni-app 对事件对象的包装，不代表字段丢失。

Methods

通过 ref 调用组件方法：

this.$refs.faceSearchView.start()
this.$refs.faceSearchView.stop()

页面生命周期建议：

export default {
  onHide() {
    this.$refs.faceSearchView && this.$refs.faceSearchView.stop()
  },
  onUnload() {
    this.$refs.faceSearchView && this.$refs.faceSearchView.stop()
  },
}

人脸库与分组

groupId 用于把人员划分到不同业务分组。以下 API 支持 groupId：

• startRegister
• startSearch
• searchImage
• importPersonFeature
• countPersons
• listPersons
• clearPersons
• <ainuo-face-search-view />

注意：

• deletePerson 按 personId 删除，不需要 groupId。
• 同一个 personId 不建议跨分组重复使用。
• 识别时传入 groupId 后，只会在该分组内搜索。

图片特征与 JSON 导入

featureBase64 是人脸特征，不是图片。它适合保存到你的业务数据库中，用于后续导入：

1. 通过 extractFeatureFromImage 提取图片特征。
2. 保存 personId、name、featureBase64、featureFormat、modelVersion、groupId 等字段。
3. 在新设备或新安装包中调用 importPersonFeature 导入。

手工导入建议支持两种结构：

[
  {
    "personId": "person-001",
    "name": "张三",
    "featureBase64": "完整特征base64",
    "featureFormat": "float32-le-base64"
  }
]

{
  "persons": [
    {
      "personId": "person-001",
      "name": "张三",
      "featureBase64": "完整特征base64",
      "featureFormat": "float32-le-base64"
    }
  ]
}

Demo 页面

您可以在插件市场点击“导入示例项目”，或者在下载的 ZIP 包中找到完整的 Demo 工程。Demo 包含两个核心页面：

• pages/index/index.vue：普通 .vue 页面，演示初始化、内置相机录入、内置相机识别、动作活体、图片特征、图片 1:1、图片 1:N、手工导入、人脸库管理。
• pages/face-search-view/face-search-view.nvue：app-nvue 页面，演示 <ainuo-face-search-view /> 全屏识别组件。

普通 .vue 页面适合验证 API 方法；app-nvue / app-uvue 页面适合验证相机识别组件。

使用注意事项

• 必须先调用 initialize，再使用录入、识别、图片和人脸库 API。
• 授权文本要与当前 App 匹配；更换包名或应用标识后，请使用新的授权。
• 第一次安装、升级插件、变更相机权限或变更平台能力后，需要重新制作自定义基座或云打包。
• 使用相机能力前，用户需要同意相机权限。
• 内置相机识别和图片 1:N 搜索前，请先确认人脸库不为空，否则会返回 FACE_LIBRARY_EMPTY。
• 图片路径建议使用 uni.chooseImage 返回的本地路径；网络图片请先下载到本地再传入。
• <ainuo-face-search-view /> 必须设置明确宽高；看不到画面时先检查页面是否为 app-nvue / app-uvue，再检查组件尺寸。
• 页面离开时建议调用组件 stop()，避免相机继续工作。
• release() 是全局释放，不是普通页面返回的必需步骤；调用后如需继续使用，需要重新 initialize。