鸿蒙Core Vision Kit端侧图像超分与文本搜图实践

鸿蒙专家

在弱网环境下打开电商应用，商品图加载缓慢，画质像马赛克；本地相册积累了上万张照片，想找一张“去年在海边穿红裙子的”却只能手动翻时间轴；医疗影像或老旧监控画面分辨率不足，关键细节看不清。这些场景依赖云端AI就有明显短板：高清图上传下载带宽成本高，个人相册数据出域也伴随隐私合规风险。HarmonyOS 7.0 引入的 Core Vision Kit 把大模型推理能力下沉到设备 NPU，让图像超分重建和自然语言搜图能在端侧离线完成。下面结合我们在电商图片流和千万级相册管理场景中的实践，聊聊 Core Vision Kit 的接入方法、架构设计与防翻车经验。

一、整体架构与模块划分

应用里有两个共享 NPU 资源的模块：智能超分查看器（SuperRes Viewer）和自然语言搜图引擎（Semantic Search Engine）。前者在列表页使用低分辨率缩略图保证滚动流畅，点击进入详情页后再调用超分模型补全高频纹理，呈现出清晰大图；后者在本地图库上方提供搜索框，输入自然语言后可在 100 毫秒内从本地库中检索出匹配照片。

核心代码结构大致如下，使用 TaskPool 分发任务，避免阻塞 UI 主线程：

2. entry/src/main/ets/
3. ├── entryability
4. │   └── EntryAbility.ets // 宿主能力生命周期管理与上下文初始化
5. ├── pages
6. │   ├── Index.ets // 首页入口与权限校验申请
7. │   ├── SuperResPage.ets // 超分效果实时对比展示页
8. │   └── TextSearchPage.ets // 文本搜图主功能视图
9. ├── core
10. │   ├── vision
11. │   │   ├── SuperResEngine.ets // 超分引擎单例封装
12. │   │   └── SearchEngine.ets // 图文双模态特征提取封装
13. │   ├── db
14. │   │   └── VectorDatabase.ets // 向量检索与余弦相似度计算
15. │   └── pool
16. │       ├── VisionTaskPool.ets // 全局任务分发中心
17. │       └── FeatureExtractWorker.ets // 后台全量图库特征扫描 Worker
18. └── utils
19.     ├── PixelMapUtil.ets // 图像格式转换与内存释放工具
20.     └── HardwareMonitor.ets // NPU 温度及内存压力监控

复制代码

二、Core Vision Kit 核心能力与 API

图像超分辨率重建与传统图像放大完全不同。传统 Bicubic 插值只是做像素间的平滑过渡，无法产生真实细节，放大后边缘会模糊甚至出现锯齿。深度学习超分模型通过大量高低清图片对预训练，学习从低频信息恢复高频纹理的非线性映射。HarmonyOS 7.0 提供的 `vision.ImageSuperResolutionAnalyzer` 接受 `PixelMap` 输入，内部将 RGB 数据转成张量送 NPU 计算，再重构为新的 `PixelMap`。该分析器内置分块预测与无缝拼合机制，能在内存受限设备上稳定运行。

跨模态搜图引擎的基础是 CLIP（Contrastive Language-Image Pre-training）架构的变体模型。原理上，模型把图像和文本映射到同一个高维特征空间，“蓝天白云”这段文本的向量坐标，与一张蓝天白云照片提取出的向量坐标距离很近。图像侧 Encoder 输入一张 PixelMap，输出 512 维 `Float32Array`；文本侧 Encoder 输入自然语言字符串，也输出 512 维 `Float32Array`。`vision.TextToImageSearchAnalyzer` 封装了 `extractImageFeature` 和 `extractTextFeature` 两个 API，检索阶段就从语义理解退化为向量余弦相似度计算。

三、超分引擎封装与资源管控

NPU 推理是耗时操作，必须把初始化、处理和销毁的生命周期管理好。下面是我们对超分引擎的封装，重点在于异常捕获和显式释放底层资源：

2. import { vision } from '@kit.CoreVisionKit';
3. import { image } from '@kit.ImageKit';
4. import { hilog } from '@kit.PerformanceAnalysisKit';
6. export class SuperResEngine {
7.     private analyzer: vision.ImageSuperResolutionAnalyzer | null = null;
8.     private readonly TAG = 'SuperResEngine';
10.     // 初始化分析器，提前加载模型权重到 NPU 缓存
11.     public async init(): Promise<void> {
12.         try {
13.             const options: vision.SuperResolutionOptions = {
14.                 quality: vision.QualityLevel.HIGH
15.             };
16.             this.analyzer = await vision.createImageSuperResolutionAnalyzer(options);
17.             hilog.info(0x0000, this.TAG, '超分分析器初始化成功');
18.         } catch (error) {
19.             hilog.error(0x0000, this.TAG, `硬件推理能力初始化失败: ${error.message}`);
20.         }
21.     }
23.     // 执行超分处理
24.     public async process(source: image.PixelMap): Promise<image.PixelMap | null> {
25.         if (!this.analyzer) {
26.             hilog.warn(0x0000, this.TAG, '分析器未就绪，终止推理请求');
27.             return null;
28.         }
29.         try {
30.             const startTime = Date.now();
31.             const resultPixelMap = await this.analyzer.process(source);
32.             hilog.info(0x0000, this.TAG, `单帧超分推理完成，耗时 ${Date.now() - startTime}ms`);
33.             return resultPixelMap;
34.         } catch (error) {
35.             hilog.error(0x0000, this.TAG, `推理管线抛出异常: ${error.message}`);
36.             return null;
37.         }
38.     }
40.     // 析构时必须回收底层 NPU 显存
41.     public async release(): Promise<void> {
42.         if (this.analyzer) {
43.             await this.analyzer.destroy();
44.             this.analyzer = null;
45.         }
46.     }
47. }

复制代码

四、文本搜图引擎接入

文本搜图要严格区分“后台建库”和“前台检索”两个阶段。建库时逐张调用 `extractImageFeature` 提取图片特征，存入本地向量数据库；检索时用户输入文本，调用 `extractTextFeature` 得到查询向量，再与库中全部特征做余弦相似度排序。核心代码结构如下：

2. import { vision } from '@kit.CoreVisionKit';
3. import { image } from '@kit.ImageKit';
5. export class SearchEngine {
6.     private searchAnalyzer: vision.TextToImageSearchAnalyzer | null = null;
8.     public async init(): Promise<void> {
9.         try {
10.             this.searchAnalyzer = await vision.createTextToImageSearchAnalyzer();
11.         } catch (error) {
12.             console.error(`搜图引擎装载失败: ${error.message}`);
13.         }
14.     }
16.     public async extractImageFeature(imgMap: image.PixelMap): Promise<Float32Array | null> {
17.         if (!this.searchAnalyzer) return null;
18.         try {
19.             return await this.searchAnalyzer.extractImageFeature(imgMap);
20.         } catch (error) {
21.             console.error(`图像语义提取失败: ${error.message}`);
22.             return null;
23.         }
24.     }
26.     public async extractTextFeature(query: string): Promise<Float32Array | null> {
27.         if (!this.searchAnalyzer || !query || query.trim() === '') return null;
28.         try {
29.             return await this.searchAnalyzer.extractTextFeature(query);
30.         } catch (error) {
31.             console.error(`文本特征映射失败: ${error.message}`);
32.             return null;
33.         }
34.     }
36.     public async release(): Promise<void> {
37.         if (this.searchAnalyzer) {
38.             await this.searchAnalyzer.destroy();
39.             this.searchAnalyzer = null;
40.         }
41.     }
42. }

复制代码

得到特征向量后，检索就是数学问题。Cosine 相似度越高，表示语义越接近。代码层面需要做向量维度校验，防止不同版本的模型特征长度不一致导致计算错乱：

2. export class VectorDatabase {
3.     public static calculateCosineSimilarity(vecA: Float32Array, vecB: Float32Array): number {
4.         if (vecA.length !== vecB.length) {
5.             throw new Error('模型特征维度不匹配');
6.         }
7.         let dotProduct = 0.0;
8.         for (let i = 0; i < vecA.length; i++) {
9.             dotProduct += vecA[i] * vecB[i];
10.         }
11.         return dotProduct;
12.     }
14.     public static searchTopK(
15.         queryFeature: Float32Array,
16.         dbRecords: Array<{ uri: string, feature: Float32Array }>,
17.         k: number = 20
18.     ): Array<{ uri: string, score: number }> {
19.         const results = dbRecords.map(record => ({
20.             uri: record.uri,
21.             score: this.calculateCosineSimilarity(queryFeature, record.feature)
22.         }));
23.         return results.sort((a, b) => b.score - a.score).slice(0, k);
24.     }
25. }

复制代码

五、避坑指南：真实生产环境的四个大坑

第一，PixelMap 显存泄漏。调用超分处理后会得到一个新的 PixelMap，原 `source PixelMap` 如果不再需要渲染，必须立刻显式调用 `source.release()`。ArkTS 的 GC 对 Native 层堆外内存感知有延迟，连续滑动触发密集超分时，若依赖 GC 自动回收，可能两秒内吃光系统物理内存，导致整机强杀或 OOM。

第二，跨线程传递分析器实例会崩溃。Core Vision Kit 的底层句柄绑定创建时的线程上下文。如果在 TaskPool 的 Worker A 中初始化了 Analyzer，再把它通过消息传到 Worker B 调用 process()，会直接抛出非法访问。正确做法是：在同一个子线程生命周期内完成初始化、处理、销毁的闭环。

第三，后台建库一定要节流。处理全量相册建库时，不能用大 for 循环并发提交上千张图片的特征提取。端侧模型推理是密集计算，NPU 任务队列堆积会迅速升温，触发系统降频、掉帧甚至应用强杀。建议通过 WorkScheduler 在设备息屏且充电时调度低优先级批处理，并用并发锁控制每次只处理 3～5 张图片。

第四，注意输入分辨率上限。超分 API 底层对输入张量大小有严格限制。传入 4K 或 8K 原图并请求 3 倍以上缩放，可能直接撑爆 NPU 固定显存配额。调用前必须读取图片原始尺寸元数据做安全校验，超过预设安全线的直接降级返回原图。

六、总结

HarmonyOS 7.0 的 Core Vision Kit 把复杂 AI 推理从云端迁移到端侧，通过抽象接口拉平了开发者接触 NPU 的门槛。无论是弱网环境下的超分重建，还是打破时间轴限制的语义搜图，都能在数据不出域的前提下获得低延迟体验。但封装简单的 API 背后，内存管理、线程调度、硬件极限负载都是必须处理的工程问题。只有用防御性编码和精细的资源控制搭建起稳定管线，端侧 AI 才能真正在企业级场景中长期可靠运行。