【HarmonyOS 7新能力028】Core Vision Kit工程封装把接入逻辑放进可维护的分层结构端侧视觉 AI 的演示通常只需要“取一张图并显示识别结果”工程实现却必须处理实时帧、方向旋转、坐标换算、页面生命周期、推理背压和隐私留存。任意一环失控都可能出现框选错位、页面退出后仍计算、内存持续增长等问题。本文构建“受控取帧—图像归一化—端侧推理—结构化校验—坐标映射—页面渲染—及时释放”的分层链路。文中的类型、接口和阈值均为应用侧教学封装不代表 HarmonyOS 7 Core Vision Kit 的官方 API 或模型指标实际能力、输入格式与支持设备必须以当前 SDK 和华为官方文档为准。封面检测数值属于视觉示意不是实测准确率。一、先定义视觉任务与失败边界“识别画面中的东西”过于宽泛。第一版应固定输入来源、任务类型、输出结构和用户动作例如“在相机预览中识别有限类别结果只用于本地叠加不保存原始图像”。验收目标包括没有相机权限时不启动只保留最新待处理帧旋转后框选位置正确低置信结果不展示页面退出后迟到结果丢弃异常路径释放图像与推理会话原始帧默认不落盘。二、业务层只接收稳定结果模型页面不应直接解析平台原始对象。视觉适配器把结果映射为归一化矩形和有限标签。interface NormalizedRect { left: number top: number right: number bottom: number } interface VisionDetection { id: string label: string confidence: number box: NormalizedRect frameId: number }归一化坐标统一限定在 0 到 1页面再按预览区域换算像素。这样推理输入尺寸变化不会渗透到 UI。三、图像帧必须拥有明确所有权相机回调提供的帧可能绑定原生缓冲区其生命周期不一定覆盖异步推理。会话层要明确是立即复制必要数据还是由平台支持的引用机制延长所有权。interface FrameLease { frameId: number width: number height: number rotation: 0 | 90 | 180 | 270 timestamp: number close(): void }无论推理成功、失败还是取消close()都要执行且可安全重复。不要把帧对象存进全局状态。四、用会话状态机管理生命周期页面出现不等于相机已就绪页面消失也不等于异步任务立即停止。显式状态机能阻止关闭后的新帧进入。type VisionSessionState | idle | requesting-permission | starting | running | stopping | stopped | failed interface VisionSession { id: string revision: number state: VisionSessionState latestFrameId: number }启动、权限返回、旋转和停止都增加 revision。异步结果提交前检查会话版本与状态。五、预处理要记录完整几何变换推理输入可能经过旋转、裁剪、缩放和补边。若只保存最终尺寸结果无法准确映射回预览。应把每一步变换参数组织成可逆链路。interface ImageTransform { sourceWidth: number sourceHeight: number rotation: 0 | 90 | 180 | 270 scale: number padX: number padY: number cropLeft: number cropTop: number }方向信息应只应用一次避免相机层和模型层重复旋转。裁剪区域也必须在源图边界内。六、通过背压保持实时链路稳定相机帧率高于推理速度时不能无限排队。实时预览通常采用“最多一个正在处理、最多一个最新待处理帧”的策略中间旧帧直接释放。class LatestFrameQueue { private pending: FrameLease | null null replace(frame: FrameLease): void { this.pending?.close() this.pending frame } take(): FrameLease | null { const frame this.pending this.pending null return frame } }这不是丢失业务数据而是用新鲜度换取实时性。离线批处理则应采用不同队列和进度策略。七、平台能力收口在视觉适配器图像格式转换、Core Vision 能力调用和原始错误解析都属于适配层。上层只依赖窄接口。interface VisionInput { frameId: number bytes: Uint8Array width: number height: number } interface VisionPort { infer(input: VisionInput, signal: AbortSignal): PromiseReadonlyArrayVisionDetection close(): Promisevoid }测试时可注入假实现稳定复现空结果、慢结果、越界结果和异常而不依赖真实模型。八、所有推理结果都按不可信数据校验即使推理运行在本地返回值也可能因模型、输入或适配错误而异常。展示前检查有限数值、置信区间、标签白名单和矩形边界。function validDetection(item: VisionDetection, allowed: ReadonlySetstring): boolean { const b item.box return allowed.has(item.label) Number.isFinite(item.confidence) item.confidence 0 item.confidence 1 [b.left, b.top, b.right, b.bottom].every((v) Number.isFinite(v) v 0 v 1) b.left b.right b.top b.bottom }阈值是产品策略不应散落在页面组件中。九、坐标映射必须覆盖裁剪模式预览常用等比填充部分图像会超出视口并被裁剪。简单地把归一化坐标乘以视图宽高会产生偏移。需要结合源宽高、旋转、缩放和裁剪量做反变换。interface Viewport { width: number height: number contentScale: number offsetX: number offsetY: number } function toViewX(normalizedX: number, viewport: Viewport): number { return normalizedX * viewport.width * viewport.contentScale viewport.offsetX }完整实现还要处理 Y 轴、旋转和镜像。使用四角测试图比肉眼拖框更可靠。十、迟到结果不能覆盖新画面实时推理可能乱序完成。页面只接受当前会话、当前 revision 且不早于已展示帧号的结果。function canCommit(session: VisionSession, resultFrameId: number, resultRevision: number): boolean { return session.state running resultRevision session.revision resultFrameId session.latestFrameId }页面停止或切换镜头后旧任务即使无法立即取消也只能完成清理不能更新 UI 或持久化。十一、隐私策略默认不留存原始帧实时识别不等于需要保存图像。默认只在内存中处理帧推理后立即释放日志仅记录帧号、耗时、结果数量和错误码不记录图像、完整识别文本或可识别个人信息。interface VisionMetric { sessionId: string frameId: number elapsedMs: number resultCount: number outcome: ok | empty | cancelled | failed }若业务确实需要保存必须单独定义用户目的、授权、保存位置、保留期限和删除入口。十二、用设备故障场景完成验收测试覆盖权限拒绝与撤回、空帧、异常方向、前后摄切换、快速进入退出、连续旋转、推理慢于帧率、低内存、结果含 NaN、矩形越界、模型返回空、取消后迟到结果以及多轮启动停止后的资源基线。还要分别检查适配填充和裁剪填充下的框选坐标并确认深浅色模式中覆盖层可读。性能结论只能来自目标设备的可复现实测不能由示意图或单次调试推断。端侧视觉 AI 的可靠性来自完整链路而不只是模型调用。把帧所有权、状态机、背压、几何变换、结果校验、迟到保护和隐私最小化放进分层结构Core Vision Kit 才能成为可持续演进的应用能力。十三、接入前检查清单Core Vision 正式接入前工程侧要过一遍检查清单SDK 版本与目标 API 版本匹配、权限在清单中声明且按需申请、能力开关在专用配置层管理、包体积增量符合预算。任何一项不过就先停带着不匹配的版本往上冲排错成本会翻倍。interface PrecheckItem { name: string; pass: boolean; note?: string } const checklist: PrecheckItem[] [ { name: SDK/API版本匹配, pass: false }, { name: 权限声明完整, pass: false }, { name: 开关集中管理, pass: false }, { name: 包体积增量预算, pass: false }, ] const allPass checklist.every(x x.pass)检查清单跑通的标志是新建工程按清单接入一次成功且不依赖任何口头经验。做不到说明文档还缺关键步骤。十四、常见坑与版本适配记录Core Vision 最常踩的坑集中在三处示例代码用的旧接口在新版本被拆分、默认配置与生产预期不一致、调试环境与真机行为有差异。每踩一个坑就记进版本适配表注明坑点、影响版本、修复方式与验证方式。interface Pitfall { issue: string; sinceApi: string; fix: string; verifiedOn: string[] } const pitfalls: Pitfall[] [] function knownPit(api: string): Pitfall[] { return pitfalls.filter(p p.sinceApi api) }适配表的价值在升级时兑现每次目标版本变更先对照表过一遍已知坑能省下一整轮盲目排查。十五、回归口径与停止线Core Vision 的任何改动合入前都要回答同一个问题怎么证明没有把好的部分改坏。回归口径必须落在纸面上一版通过的用例清单全量重跑、上一版记录的基线值全量对比、新增能力补一条专属用例。三件事缺一件回归就是走过场。interface RegressionGate { lastPassedCases: number; rerun: number; baselineCompare: PASS | FAIL; newCaseAdded: boolean } function gateOk(g: RegressionGate): boolean { return g.rerun g.lastPassedCases g.baselineCompare PASS g.newCaseAdded }停止线同样要提前写明同一问题打回三次、回归连挂两轮、或验证环境与目标环境指纹不一致满足其一就停下来复盘流程而不是继续硬修。把停止线当成流程的一部分才能避免在小问题上耗掉整块的排期。
【HarmonyOS 7新能力028】Core Vision Kit工程封装把接入逻辑放进可维护的分层结构端侧视觉 AI 的演示通常只需要“取一张图并显示识别结果”工程实现却必须处理实时帧、方向旋转、坐标换算、页面生命周期、推理背压和隐私留存。任意一环失控都可能出现框选错位、页面退出后仍计算、内存持续增长等问题。本文构建“受控取帧—图像归一化—端侧推理—结构化校验—坐标映射—页面渲染—及时释放”的分层链路。文中的类型、接口和阈值均为应用侧教学封装不代表 HarmonyOS 7 Core Vision Kit 的官方 API 或模型指标实际能力、输入格式与支持设备必须以当前 SDK 和华为官方文档为准。封面检测数值属于视觉示意不是实测准确率。一、先定义视觉任务与失败边界“识别画面中的东西”过于宽泛。第一版应固定输入来源、任务类型、输出结构和用户动作例如“在相机预览中识别有限类别结果只用于本地叠加不保存原始图像”。验收目标包括没有相机权限时不启动只保留最新待处理帧旋转后框选位置正确低置信结果不展示页面退出后迟到结果丢弃异常路径释放图像与推理会话原始帧默认不落盘。二、业务层只接收稳定结果模型页面不应直接解析平台原始对象。视觉适配器把结果映射为归一化矩形和有限标签。interface NormalizedRect { left: number top: number right: number bottom: number } interface VisionDetection { id: string label: string confidence: number box: NormalizedRect frameId: number }归一化坐标统一限定在 0 到 1页面再按预览区域换算像素。这样推理输入尺寸变化不会渗透到 UI。三、图像帧必须拥有明确所有权相机回调提供的帧可能绑定原生缓冲区其生命周期不一定覆盖异步推理。会话层要明确是立即复制必要数据还是由平台支持的引用机制延长所有权。interface FrameLease { frameId: number width: number height: number rotation: 0 | 90 | 180 | 270 timestamp: number close(): void }无论推理成功、失败还是取消close()都要执行且可安全重复。不要把帧对象存进全局状态。四、用会话状态机管理生命周期页面出现不等于相机已就绪页面消失也不等于异步任务立即停止。显式状态机能阻止关闭后的新帧进入。type VisionSessionState | idle | requesting-permission | starting | running | stopping | stopped | failed interface VisionSession { id: string revision: number state: VisionSessionState latestFrameId: number }启动、权限返回、旋转和停止都增加 revision。异步结果提交前检查会话版本与状态。五、预处理要记录完整几何变换推理输入可能经过旋转、裁剪、缩放和补边。若只保存最终尺寸结果无法准确映射回预览。应把每一步变换参数组织成可逆链路。interface ImageTransform { sourceWidth: number sourceHeight: number rotation: 0 | 90 | 180 | 270 scale: number padX: number padY: number cropLeft: number cropTop: number }方向信息应只应用一次避免相机层和模型层重复旋转。裁剪区域也必须在源图边界内。六、通过背压保持实时链路稳定相机帧率高于推理速度时不能无限排队。实时预览通常采用“最多一个正在处理、最多一个最新待处理帧”的策略中间旧帧直接释放。class LatestFrameQueue { private pending: FrameLease | null null replace(frame: FrameLease): void { this.pending?.close() this.pending frame } take(): FrameLease | null { const frame this.pending this.pending null return frame } }这不是丢失业务数据而是用新鲜度换取实时性。离线批处理则应采用不同队列和进度策略。七、平台能力收口在视觉适配器图像格式转换、Core Vision 能力调用和原始错误解析都属于适配层。上层只依赖窄接口。interface VisionInput { frameId: number bytes: Uint8Array width: number height: number } interface VisionPort { infer(input: VisionInput, signal: AbortSignal): PromiseReadonlyArrayVisionDetection close(): Promisevoid }测试时可注入假实现稳定复现空结果、慢结果、越界结果和异常而不依赖真实模型。八、所有推理结果都按不可信数据校验即使推理运行在本地返回值也可能因模型、输入或适配错误而异常。展示前检查有限数值、置信区间、标签白名单和矩形边界。function validDetection(item: VisionDetection, allowed: ReadonlySetstring): boolean { const b item.box return allowed.has(item.label) Number.isFinite(item.confidence) item.confidence 0 item.confidence 1 [b.left, b.top, b.right, b.bottom].every((v) Number.isFinite(v) v 0 v 1) b.left b.right b.top b.bottom }阈值是产品策略不应散落在页面组件中。九、坐标映射必须覆盖裁剪模式预览常用等比填充部分图像会超出视口并被裁剪。简单地把归一化坐标乘以视图宽高会产生偏移。需要结合源宽高、旋转、缩放和裁剪量做反变换。interface Viewport { width: number height: number contentScale: number offsetX: number offsetY: number } function toViewX(normalizedX: number, viewport: Viewport): number { return normalizedX * viewport.width * viewport.contentScale viewport.offsetX }完整实现还要处理 Y 轴、旋转和镜像。使用四角测试图比肉眼拖框更可靠。十、迟到结果不能覆盖新画面实时推理可能乱序完成。页面只接受当前会话、当前 revision 且不早于已展示帧号的结果。function canCommit(session: VisionSession, resultFrameId: number, resultRevision: number): boolean { return session.state running resultRevision session.revision resultFrameId session.latestFrameId }页面停止或切换镜头后旧任务即使无法立即取消也只能完成清理不能更新 UI 或持久化。十一、隐私策略默认不留存原始帧实时识别不等于需要保存图像。默认只在内存中处理帧推理后立即释放日志仅记录帧号、耗时、结果数量和错误码不记录图像、完整识别文本或可识别个人信息。interface VisionMetric { sessionId: string frameId: number elapsedMs: number resultCount: number outcome: ok | empty | cancelled | failed }若业务确实需要保存必须单独定义用户目的、授权、保存位置、保留期限和删除入口。十二、用设备故障场景完成验收测试覆盖权限拒绝与撤回、空帧、异常方向、前后摄切换、快速进入退出、连续旋转、推理慢于帧率、低内存、结果含 NaN、矩形越界、模型返回空、取消后迟到结果以及多轮启动停止后的资源基线。还要分别检查适配填充和裁剪填充下的框选坐标并确认深浅色模式中覆盖层可读。性能结论只能来自目标设备的可复现实测不能由示意图或单次调试推断。端侧视觉 AI 的可靠性来自完整链路而不只是模型调用。把帧所有权、状态机、背压、几何变换、结果校验、迟到保护和隐私最小化放进分层结构Core Vision Kit 才能成为可持续演进的应用能力。十三、接入前检查清单Core Vision 正式接入前工程侧要过一遍检查清单SDK 版本与目标 API 版本匹配、权限在清单中声明且按需申请、能力开关在专用配置层管理、包体积增量符合预算。任何一项不过就先停带着不匹配的版本往上冲排错成本会翻倍。interface PrecheckItem { name: string; pass: boolean; note?: string } const checklist: PrecheckItem[] [ { name: SDK/API版本匹配, pass: false }, { name: 权限声明完整, pass: false }, { name: 开关集中管理, pass: false }, { name: 包体积增量预算, pass: false }, ] const allPass checklist.every(x x.pass)检查清单跑通的标志是新建工程按清单接入一次成功且不依赖任何口头经验。做不到说明文档还缺关键步骤。十四、常见坑与版本适配记录Core Vision 最常踩的坑集中在三处示例代码用的旧接口在新版本被拆分、默认配置与生产预期不一致、调试环境与真机行为有差异。每踩一个坑就记进版本适配表注明坑点、影响版本、修复方式与验证方式。interface Pitfall { issue: string; sinceApi: string; fix: string; verifiedOn: string[] } const pitfalls: Pitfall[] [] function knownPit(api: string): Pitfall[] { return pitfalls.filter(p p.sinceApi api) }适配表的价值在升级时兑现每次目标版本变更先对照表过一遍已知坑能省下一整轮盲目排查。十五、回归口径与停止线Core Vision 的任何改动合入前都要回答同一个问题怎么证明没有把好的部分改坏。回归口径必须落在纸面上一版通过的用例清单全量重跑、上一版记录的基线值全量对比、新增能力补一条专属用例。三件事缺一件回归就是走过场。interface RegressionGate { lastPassedCases: number; rerun: number; baselineCompare: PASS | FAIL; newCaseAdded: boolean } function gateOk(g: RegressionGate): boolean { return g.rerun g.lastPassedCases g.baselineCompare PASS g.newCaseAdded }停止线同样要提前写明同一问题打回三次、回归连挂两轮、或验证环境与目标环境指纹不一致满足其一就停下来复盘流程而不是继续硬修。把停止线当成流程的一部分才能避免在小问题上耗掉整块的排期。
