引言：不接大模型，也能让 App “看懂” 图像

V哥在 HarmonyOS 7 视觉 AI 实战讲过 HarmonyOS 的视觉 AI 能力全景——Core Vision Kit、Vision Kit 一大家子。那篇是"地图"，这篇是"按图索骥"：挑两个最高频、最落地、也最容易让新手出活儿的场景——人脸检测和通用文字识别（OCR），把接入链路给你走通。

很多人一听"视觉 AI"就觉得要训模型、接云端、烧显卡。在 HarmonyOS 7 上完全不用：系统把人脸检测、OCR 这些能力做成了端侧、开箱即用的 Kit，你 import 一个模块、init 一下、调一个异步接口，结果就回来了。更狠的是 Vision Kit 还提供了场景化控件——人脸活体检测、卡证识别、文档扫描，连 UI 都给你画好了，拉起来就能用。

口径说明：本文 API 名称、@kit 模块路径、约束条件均来自华为官方文档与开发者社区公开材料，具体接口参数与版本边界以官方最新文档为准；运行表现以真机实测为准。

一、为什么先讲这两个场景

人脸检测和 OCR 是视觉能力里"复用面最广"的两个：

• 人脸检测：返回人脸矩形框、五官坐标、朝向、置信度。美颜定位五官、相册按人聚类、门禁考勤、互动贴纸，全靠它打底。
• OCR（通用文字识别）：把票据、卡证、表格、报刊、书籍的印刷体文字转成可编辑字符，还带屏幕坐标和外框。发票报销、名片录入、文档摘录，刚需中的刚需。

两者都不依赖大模型、不上传图片、在设备端跑完，隐私和响应速度天然占优。先把这两个吃透，再去看主体分割、人脸比对、骨骼点检测，一路平推。

二、人脸检测实战（faceDetector）

人脸检测来自 Core Vision Kit，模块路径 @kit.CoreVisionKit，核心类 faceDetector。三步走：init 初始化 → detect 检测 → release 释放。

import { faceDetector } from '@kit.CoreVisionKit';
import { image } from '@kit.ImageKit';

// 1. 初始化（建议在页面加载时）
await faceDetector.init();

// 2. 准备输入：detect 只认 PixelMap
let visionInfo: faceDetector.VisionInfo = { pixelMap: this.chooseImage };

// 3. 检测，返回 Face[]（每个含矩形框、五官、朝向、置信度）
const faces: faceDetector.Face[] = await faceDetector.detect(visionInfo);
if (faces.length > 0) {
  const f = faces[0];
  // 矩形框：左上角坐标 + 宽高
  console.info(`人脸位置: left=${f.faceRectangle.left}, top=${f.faceRectangle.top}, w=${f.faceRectangle.width}, h=${f.faceRectangle.height}`);
  // 置信度 0~1，越接近 1 越准
  console.info(`置信度: ${f.confidence}`);
  // 五官坐标（左眼/右眼/鼻子/嘴巴）
  console.info(`左眼: ${f.faceFeatures.leftEye.x}, ${f.faceFeatures.leftEye.y}`);
}

// 4. 用完释放，别占 Native 内存
await faceDetector.release();

Face 里能掏出来的信息很全：faceRectangle（矩形框，left/top/width/height）、confidence（置信度）、orientation（基于世界坐标系的朝向）、faceFeatures（左眼、右眼、鼻子、嘴巴的坐标）。你拿到矩形框和五官，就能在 Canvas 上画框、做美颜磨皮、贴纸定位，全在本地完成。

三个避坑点 V哥必须提醒你：

1. 不支持模拟器，必须真机实测。Core Vision Kit 深度依赖底层硬件加速，模拟器跑不起来，别在模拟器上纠结为什么调不动。
2. 接口调用耗时较久，不适合实时预览帧。它不是为"视频流每帧识别"设计的，适合拍照后的静态图处理。想做自研美颜/贴纸，在拍照后的图上搞，别在相机预览流里逐帧 detect。
3. 同一进程内不支持对同一特性的并发调用。用户连点两次识别，要用状态位拦截或排队，别让它同时跑两个 detect。

三、通用文字识别实战（textRecognition）

OCR 同样来自 Core Vision Kit，模块路径 @kit.CoreVisionKit，核心类 textRecognition。流程一样：init → recognizeText → release，而且 recognizeText 也只吃 PixelMap。

import { textRecognition } from '@kit.CoreVisionKit';

// 1. 初始化
const initResult = await textRecognition.init();

// 2. 构造入参（仅支持 PixelMap）
let visionInfo: textRecognition.VisionInfo = { pixelMap: this.chooseImage };

// 3. 配置识别选项（是否开启朝向检测，自动纠正旋转文字）
let config: textRecognition.TextRecognitionConfiguration = {
  isDirectionDetectionSupported: true
};

// 4. 调用，data.value 是识别出的全文文本，还带坐标外框
textRecognition.recognizeText(visionInfo, config).then((data) => {
  this.resultText = data.value; // 全文
});

// 5. 释放
await textRecognition.release();

OCR 的价值不只是"全文文本"——它还返回每个文字的屏幕坐标和外框，这让你可以做"点哪段字高亮哪段"“按区块提取表格单元格”。语种上支持简体中文、英文、日文、韩文、繁体中文，覆盖绝大多数报销、录入场景。

两个工程注意点：

• 图像质量决定识别率：官方建议分辨率 720p 以上，拍摄角度与文本平面夹角小于 30°，高宽比最好别超过 10:1。识别率不如预期时，先用 ImageKit 做对比度/亮度增强再识别。
• 不识别手写体：业务设计上要明确告诉用户，OCR 面向票据、名片等印刷品，手写先不接。

四、不想自己画 UI？直接用场景化控件（Vision Kit）

人脸检测和 OCR 是"能力"，你得自己写选择图片、画框、展示结果的 UI。如果连 UI 都不想写，HarmonyOS 7 的 Vision Kit（场景化视觉服务） 把更高层的玩法包成了控件：

• 人脸活体检测 interactiveLiveness：用户互动完成活体验证，防照片/视频伪造冒用，适合登录、支付前二次确认；注意它暂不支持横屏、分屏，且不允许被其他组件遮挡。
• 卡证识别 CardRecognition：识别身份证、行驶证、驾驶证、护照、银行卡 5 种卡证，直接返回结构化数据；同样不允许被遮挡。
• 文档扫描 DocumentScanner：拍摄或从图库选文档，转高清扫描件，还能识别表格生成表格文档；仅支持 phone、tablet。
• AI 识图控件：场景化的文本识别、主体分割、识图搜索，图片最小 100×100，仅支持 RGBA_8888 的 PixelMap。

这些控件"拉起来就有界面"，V哥建议：做考勤门禁、发票录入这类标准化业务，直接用控件省时间；要做差异化体验（比如自定义美颜、自定义扫描交互），再回到底层的 faceDetector / textRecognition 自己搭。

五、三条工程纪律（新手最容易翻车的地方）

1. init / release 必须配对。所有视觉子能力都遵循 init() 和 release() 的配对原则，务必在 aboutToDisappear 里 release。不释放，长期 Native 内存占用会让应用被系统回收——这是 3 年以上开发者都容易忘的坑。
2. 端侧处理，但隐私协议要写清楚。Core Vision Kit 声明图片数据不留存、不上传，但你在调用图库或相机获取图片时，仍要在应用隐私协议里明确告知用户视觉分析的用途。合规不是系统替你做的，是你自己写的。
3. 传参前先缩放图片。PixelMap 跨进程传输开销大，调用视觉接口前先按算法要求的尺寸（OCR 建议 720p）适度缩放，既能保精度，又大幅缩短 Native 层序列化耗时。

六、和 19 篇的关系，以及下一步

19 篇是 HarmonyOS 视觉 AI 的"总览地图"，这篇是"按地图走通两条最常走的路"。把人脸检测和 OCR 跑顺了，下一步可以接着看 19 篇里提到的人脸比对（1v1 相似度，做应用内二次身份确认）、主体分割（一键抠图）、骨骼点检测（17 关键点，健身/康复场景）。能力体系是通的，调通一个，其余只是参数和返回结构的差别。

---

参考与出处

以下为本文涉及的官方文档与开发者社区公开材料，API 名称、模块路径与约束条件均以此为据；具体接口参数与版本边界以官方最新文档为准。

• 华为开发者联盟 · Core Vision Kit（基础视觉服务）Codelab：https://developer.huawei.com/consumer/cn/codelabsPortal/carddetails/tutorials_Next-CoreVisionKit
• 华为开发者联盟 · Vision Kit（场景化视觉服务）Codelab：https://developer.huawei.com/consumer/cn/codelabsPortal/carddetails/tutorials_Next-VisionKit
• 华为开发者联盟 · HarmonyOS 新能力一览：https://developer.huawei.com/consumer/cn/features/

---

最后一句：视觉 AI 最怕"一上来就想训模型"——HarmonyOS 7 把人脸检测和 OCR 做成了端侧开箱即用的 Kit，先 import、再 init、调一个异步接口就拿结果，把这两步跑通，你离"让 App 看懂世界"就只差把返回的坐标画上去了。