【HarmonyOS 7新能力｜053】Core Vision Kit异常排查：定位配置、权限与运行期失败

Core Vision Kit 为 HarmonyOS 应用提供端侧视觉 AI 基础能力，典型方向包括文字识别、人脸检测或比对、主体分割等。视觉功能的故障往往不表现为明确异常：接口可能成功返回，但框的位置偏移、竖图被横向解释、低光场景结果骤降，或者连续预览几分钟后出现卡顿。本文从输入契约到坐标系统、并发、性能与隐私建立一条排障链。代码是用于讲解的工程抽象，不代表具体 SDK 签名；能力范围、支持设备和正式 API 请以当前官方文档为准。

一、先把“识别不准”拆成四类问题

视觉链路至少包含输入质量、模型执行、结果后处理和界面呈现。模型结果为空，不一定是模型失败；也可能是图像解码错误、方向信息丢失、阈值过高或坐标被错误缩放。

type VisionStage = 'decode' | 'normalize' | 'infer' | 'postprocess' | 'render'

interface VisionFailure {
  stage: VisionStage
  code: string
  frameId: string
  elapsedMs: number
}

先记录最后一个成功阶段和输入摘要，再决定复现方式。

二、为输入建立不可绕过的契约

图片来源可能是相机帧、图库文件、屏幕截图或网络缓存，它们在尺寸、像素格式、颜色空间、方向和生命周期上都不同。进入视觉服务前统一成一种内部模型。

interface VisionFrame {
  id: string
  width: number
  height: number
  rotation: 0 | 90 | 180 | 270
  format: 'rgba' | 'nv21' | 'jpeg'
  timestampMs: number
}

function validFrame(f: VisionFrame): boolean {
  return f.width > 0 && f.height > 0 && f.timestampMs > 0
}

无效帧应在入口拒绝，而不是交给模型后再猜测空结果原因。

三、方向与镜像是高频根因

图库照片可能依赖元数据表达旋转，相机前置预览又可能带镜像。若模型使用原始像素、界面使用校正后的画面，检测框就会错位。应明确推理坐标属于原图、旋转后图还是预览图。

interface Point { x: number; y: number }

function rotate90(p: Point, sourceHeight: number): Point {
  return { x: sourceHeight - p.y, y: p.x }
}

function mirrorX(p: Point, width: number): Point {
  return { x: width - p.x, y: p.y }
}

使用带明显方向标记的测试图分别验证四种旋转与前后摄像头。

四、坐标映射要考虑裁剪而非只做缩放

预览常用 cover 填充，会裁掉部分图像；结果层若按完整原图等比缩放，框会整体平移。映射器应同时计算缩放比例和水平、垂直裁剪偏移。

interface Rect { left: number; top: number; right: number; bottom: number }

function mapCover(r: Rect, sw: number, sh: number, vw: number, vh: number): Rect {
  const scale = Math.max(vw / sw, vh / sh)
  const dx = (sw * scale - vw) / 2
  const dy = (sh * scale - vh) / 2
  return {
    left: r.left * scale - dx, top: r.top * scale - dy,
    right: r.right * scale - dx, bottom: r.bottom * scale - dy
  }
}

结果渲染测试应使用可计算的矩形样例，而不是只靠肉眼判断。

五、模型初始化失败要与单帧失败分开

模型或能力实例通常具有初始化成本。不要每帧创建，也不要在初始化尚未完成时并发提交。页面可显示 initializing、ready、failed 三态，并提供一次受控重试。

type EngineState = 'idle' | 'initializing' | 'ready' | 'failed' | 'released'

class EngineGuard {
  state: EngineState = 'idle'
  canInfer(): boolean { return this.state === 'ready' }
  canInitialize(): boolean { return this.state === 'idle' || this.state === 'failed' }
}

初始化日志记录设备信息、能力版本、耗时和错误码，但不要记录用户图像。

六、实时预览必须主动背压

相机可能以每秒数十帧生产图像，而端侧推理速度更慢。若每帧排队，延迟会不断累积，最终显示“几秒前”的结果。实时交互通常应保留最新帧而丢弃过期帧。

class LatestFrameSlot {
  private latest?: VisionFrame
  offer(frame: VisionFrame): void { this.latest = frame }
  take(): VisionFrame | undefined {
    const value = this.latest
    this.latest = undefined
    return value
  }
}

离线文档批处理则可以排队，但要限制并发和内存占用。

七、置信度阈值不能全场景共用

OCR、人脸与主体分割的结果语义不同，低光、运动模糊和远距离也会改变分数分布。阈值应按能力和产品风险配置，并保留灰区处理。

type Decision = 'accept' | 'review' | 'reject'

function decide(score: number, accept: number, reject: number): Decision {
  if (score >= accept) return 'accept'
  if (score < reject) return 'reject'
  return 'review'
}

不要把模型置信度包装成绝对正确概率，也不要用一次样例决定阈值。

八、OCR要保留块结构与阅读顺序

只拼接识别文本会丢失段落、列和位置，票据或双栏文档尤其明显。内部结果应保留文本块、行、边界框与置信度，再由业务层决定排序和展示。

interface TextBlock {
  text: string
  bounds: Rect
  confidence: number
  lineIndex: number
}

function stableReadingOrder(rows: TextBlock[]): TextBlock[] {
  return [...rows].sort((a, b) => a.bounds.top - b.bounds.top || a.bounds.left - b.bounds.left)
}

复杂版面需要独立的布局策略，不能假设所有文本从左到右逐行排列。

九、人脸能力要区分检测与身份结论

检测到人脸只说明画面存在符合特征的区域；比对分数也不应直接替代身份认证结论。涉及访问控制时，需要活体、阈值、失败锁定、人工兜底和合规评估组成完整方案。

测试集应覆盖不同光照、姿态、遮挡、年龄段与设备，但不得将真实敏感样本随意写入仓库或日志。

十、主体分割要检查边缘与透明度语义

分割结果可能是二值掩码，也可能是连续透明度。直接硬阈值会造成头发、透明物体和运动边缘锯齿。合成前明确掩码尺寸、插值方式、前景定义和颜色空间。

function alphaBlend(fg: number, bg: number, alpha: number): number {
  const a = Math.max(0, Math.min(1, alpha))
  return Math.round(fg * a + bg * (1 - a))
}

用纯色背景检查漏边，比复杂真实背景更容易定位问题。

十一、建立性能与隐私双门禁

记录初始化、解码、推理、后处理和渲染耗时，观察 P50、P95、峰值内存、温升和丢帧率。端侧处理不等于天然合规：图像是否落盘、是否进入日志、失败样本是否上传，都必须与隐私说明一致。

指标	证据	失败处理
首次初始化	分阶段耗时	预热或延迟初始化
连续推理	P95与丢帧	降频、背压
内存	峰值与释放	缩小输入、复用缓冲
原始图像	数据流审计	默认不记录

十二、用黄金样本与真机矩阵收口

准备一小组有合法来源、固定预期的黄金样本，覆盖旋转、镜像、低光、模糊、空结果、多目标和极端尺寸。对每个版本保存输入摘要、预期结构和容差；再到目标真机验证相机生命周期、前后台切换、权限拒绝和长时间运行。

Core Vision Kit 排障的核心不是不断调高模型参数，而是让输入、坐标、状态、结果与设备环境都可观察。先证明每层契约正确，再讨论模型效果，才能把“偶尔识别不准”变成可复现、可度量、可回归的问题。

上线后还应按能力类型分别监控空结果率、低置信度率、推理超时率和主动降级率，但不要采集原始人脸、证件或屏幕内容来换取可观测性。若确需用户反馈失败样本，应提供明确说明、单次选择、预览和撤回路径，并对文件做最小化处理。版本升级时使用同一黄金集回归，结果结构发生变化则先适配映射层，避免页面与业务代码直接依赖模型的临时字段。

参考资料：

• HarmonyOS 智能化特性
• HarmonyOS 7 新能力一览