HelloFace 提供在设备端运行的人脸检测、采集、活体检测、1:1 比对以及 1:N/M:N 搜索能力。本文以 0.8.11 Beta 为例，介绍如何在原生鸿蒙应用中通过 ArkTS 接入 SDK，并完成两张图片的人脸特征提取和比对。

鸿蒙版本使用字节码 HAR 与 ARM64 Native 运行库，模型随 SDK 提供。推理和人脸库查询在本机完成，无需调用远程人脸识别服务。

• 官方网站：helloface.dev
• Demo 与接入文档：FaceSDKPro/HelloFace

一、能力与运行环境

能力	典型入口
人脸检测	processFrame()、processRgba()
静态图片采集与特征提取	capture()
动作与静默活体	liveness()
1:1 人脸比对	verification()
1:N/M:N 人脸搜索	search()
本地 SQLite 人脸库	HiFaceSdk.openSearchDatabase()

本文示例的运行环境为 HarmonyOS API 20+、arm64-v8a 手机、DevEco Studio 26。接入方需要配置自己的应用包名、签名证书与设备 Profile。

SDK 的公开入口为 HiFaceSdk。Demo UI 用于展示 SDK 能力，页面布局、交互和业务流程都可以按项目需求定制。

配图来自项目公开 README，为产品能力与应用场景示意；图中匹配数值是示例，不代表识别准确率或设备实测结论。

二、获取 Demo 与本地 HAR

仓库使用 Git LFS 管理 SDK 二进制等大文件。安装 Git LFS 后，可浅克隆当前默认分支：

git lfs install
git clone --depth 1 --single-branch https://github.com/FaceSDKPro/HelloFace.git
cd HelloFace
git lfs pull

用 DevEco Studio 打开 platforms/Harmony，同步工程依赖，然后为 demo 配置自己的签名信息。

如果向已有应用接入，可将 hiface-0.8.11.har 放在应用工程的 libs/ 下，并在消费模块的 oh-package.json5 中声明本地依赖。路径相对于该模块的配置文件；例如 HAR 位于模块上一级的 libs/ 时：

{
  "dependencies": {
    "hiface": "file:../libs/hiface-0.8.11.har"
  }
}

本文采用本地 HAR 接入。仓库后续版本可能更新，实际文件名与依赖版本请保持一致；不要把 Git LFS 指针文本当作 HAR 导入。

三、创建 SDK，等待初始化完成

模型准备是异步过程。创建实例后，应先等待 whenReady()，再开始检测、采集或比对。

import { common } from '@kit.AbilityKit';
import { HiFaceResult, HiFaceSdk, RgbaImage } from 'hiface';

async function createSdk(
  context: common.UIAbilityContext
): Promise<HiFaceSdk> {
  const sdk: HiFaceSdk = HiFaceSdk.create(context);
  try {
    const ready: HiFaceResult<boolean> = await sdk.whenReady();
    if (ready.isFailure()) {
      throw new Error(ready.requireError().message);
    }
    return sdk;
  } catch (error) {
    sdk.close();
    throw error;
  }
}

这里的 context 由宿主 Ability 或页面取得。建议在 Ability 或业务容器中持有并复用 SDK 实例；页面退出或初始化被替换时，应防止旧异步结果重新更新当前页面。

ArkUI 子组件通过普通字段接收 SDK 引用，必要时使用 @Require。不要使用 @Prop 传递 HiFaceSdk，以免深拷贝破坏内部异步状态。

四、提取两张图片的特征，进行 1:1 比对

以下函数延续上一节的导入，输入为两张已经解码、归正方向的 RgbaImage。JPEG/PNG 文件字节需要由宿主解码成 RGBA 像素，不能直接作为 RgbaImage 的像素数据。

async function compareImages(
  sdk: HiFaceSdk,
  leftImage: RgbaImage,
  rightImage: RgbaImage
): Promise<number> {
  const left: HiFaceResult<string> =
    await sdk.capture().extractFeature(leftImage);
  if (left.isFailure()) {
    throw new Error(left.requireError().message);
  }

  const right: HiFaceResult<string> =
    await sdk.capture().extractFeature(rightImage);
  if (right.isFailure()) {
    throw new Error(right.requireError().message);
  }

  const score: HiFaceResult<number> = sdk.verification().compare(
    left.requireValue(),
    right.requireValue()
  );
  if (score.isFailure()) {
    throw new Error(score.requireError().message);
  }
  return score.requireValue();
}

HiFaceResult<T> 用于表达可预期的业务失败。先检查成功或失败，再读取值或错误，可避免把“无脸”“模型尚未就绪”等状态当成正常识别结果。

静态图片入口选择最大人脸。若需要图片中的多人处理，可查看 facesFromRgba()；若要获取对齐预览和特征，可查看 fromRgba()。

比对分数需要结合目标设备、图像质量和业务样本设置阈值，不能把一次演示分数当作整体准确率。图片特征提取与静态比对也不等于已经执行活体检测，存在活体要求时需接入对应流程。

五、从静态比对扩展到实时相机与人脸库

实时相机流程可以按下面的顺序接入：

1. 由宿主处理用户告知、相机权限、相机启动与图像方向。
2. 创建 FaceRealtimeProcessor，将相机帧交给 tryProcessFrame()。
3. 忙时返回 undefined，及时释放新帧，避免排成无界队列。
4. 根据业务调用采集、活体、验证或搜索流程，并处理回调和错误。
5. 离开页面时先取消流程，再停止送帧与相机，最后关闭资源。

人脸库通过 HiFaceSdk.openSearchDatabase(context) 管理，支持本地记录的录入、查询、修改、删除及特征搜索。显式打开的数据库句柄需要独立关闭，关闭 SDK 不会代替关闭这个句柄。

采集、活体、验证和搜索共享相机处理槽，同一时刻启动一种流程。完整相机帧参数、监听器与搜索配置可参考仓库 Demo，避免只复制界面而遗漏生命周期处理。

六、离线处理与数据保护边界

SDK 不声明网络权限或网络 capability，不将图像或人脸特征上传给 SDK 开发者。相机帧、照片、特征和本地图库仍属于实际的数据处理，接入方需要对自己的 App 或服务负责。

尤其需要注意：

• SDK 创建的 SQLite 人脸库当前不提供包内加密，应用应落实访问控制与存储保护。
• HF1 特征是 Q7/Base64URL 表示，不是加密后的数据；避免写入普通日志或公开调试输出。
• 用户告知与同意、数据保留期限、删除机制，以及 App 自行增加的云端同步，都由接入方按实际场景管理。
• SDK 的离线架构可以减少向外部服务暴露人脸数据的环节，不能代替整个应用的数据保护措施。

详细说明见：数据处理与隐私合规说明。

七、版本与使用限制

• 当前 SDK 处于 Beta 迭代公测，请及时升级；现有 SDK 与模型许可为测试用途，使用范围以包内许可说明为准。
• 当前模型不支持 12 周岁以下儿童人脸识别，不能用于金融相关场景。
• 人脸搜索要求摄像头成像清晰；室外环境下，摄像头宽动态范围须大于 100 dB。
• 移动端运行需配置自己的应用签名；跨平台接入时，Windows/Linux 桌面与摄像头待真机摄像头验证。

实际部署前，应使用目标设备和业务图像完成验证。本文的代码展示公开 API 的接入方式，不提供固定耗时或准确率承诺。

八、文档与反馈

• HelloFace 官方网站
• Demo 与集成代码
• HarmonyOS SDK 中文接入指南
• HarmonyOS Demo 运行说明
• 问题反馈

SDK 集成支持与安全问题反馈：FaceAISDK.Service@gmail.com。