摘要：本文围绕 HarmonyOS Core Vision Kit 的文搜图（Text-to-Image Search）能力，讲透端侧索引从建库、检索到释放的完整生命周期。核心结论是四句话——scope 先分库、启动做增量、插入放后台、检索加阈值。文中给出可直接复用的建库/检索骨架、基于 Preferences 的增量清单、taskpool 后台插入与进度回调，并配生命周期全景图、检索时序图、scope 隔离示意图，帮你避开启动卡顿、scope 串扰、低置信误召回等常见坑。

目录

• 一、背景与痛点
• 二、能力与规格边界
• 三、核心代码（建库 + 检索骨架）
  • 3.0 骨架代码逐段拆解
  • 3.1 增量建库：维护"已索引清单"
  • 3.2 后台插入 + 进度回调
• 四、索引生命周期的 5 个实战要点
  • 4.1 索引生命周期全景图
  • 4.2 检索链路时序图
  • 4.3 scope 分库与检索隔离示意
• 五、小结与适用边界

一、背景与痛点

上一篇我们聊了图像超分的接入坑，这一篇把镜头转到"找图"——Core Vision Kit 的文搜图（Text-to-Image Search）。它的爽点很直观：用户说一句"海边日落"“猫趴窗台”，端侧模型就把本地相册里语义匹配的照片捞出来，全程数据不出设备。

但我第一次把它做成相册搜索功能时，翻车不在"搜不准"，而在索引怎么管：启动就卡 3 秒、换 scope 搜出串扰结果、release 之后索引全没、低相似度的图也混进来……这些都不是算法问题，而是索引生命周期没设计好。本文把端侧文搜图从建库、检索到释放的完整链路讲透，帮你少走弯路。

二、能力与规格边界

文搜图是跨模态检索：端侧模型把每张图编码成向量，把一句话也编码进同一语义空间，按相似度降序返回。先记牢约束：

维度	规格
归属	@kit.CoreVisionKit 下的 textSearchImage
起始版本	26.0.0，仅 Stage 模型；支持 Phone / Tablet / PC·2in1
区域	仅中国境内（港、澳、中国台湾除外）
输入	imagePath 沙箱绝对路径（不带 file://，1–128 字符）
scope	作用域仅字母/数字，长度 1–32，用于分组过滤
query	查询词 1–100 字符，不支持纯数字/纯字母，支持中文
topKey	返回上限 0–100，默认 100
返回	ImageObject[]：imagePath / scope / similarity（范围 [-1, 1]）

两个高频坑先标红：query 不能纯数字/纯字母，以及索引按 scope 隔离——这两点直接决定你后文的架构。

三、核心代码（建库 + 检索骨架）

最关键的认知：init() 之后索引服务才就绪，索引是否跨会话持久化要看实测——稳妥做法是每次启动重新 insert 一次（增量判断见坑 2），退出时 release()。

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

// 1. 初始化（返回 true 才可用，失败多为设备/版本/区域不支持）
async function ready(): Promise<boolean> {
  return await textSearchImage.init();
}

// 2. 建库：按 scope 分组插入沙箱图片，而非一锅炖
async function buildIndex(paths: string[], scope: string): Promise<void> {
  for (const p of paths) {
    await textSearchImage.insertImage(p, scope); // scope 隔离不同图库
  }
}

// 3. 检索：中文语义查询，按 scope 收窄范围
async function search(query: string, scope: string, top: number) {
  const hits = await textSearchImage.search(query, scope, top);
  return hits
    .filter(h => h.similarity >= 0.30) // 阈值过滤低置信误召回
    .sort((a, b) => b.similarity - a.similarity);
}

// 4. 退出释放
async function teardown(): Promise<void> {
  await textSearchImage.release();
}

3.0 骨架代码逐段拆解

上面这段骨架看着简单，但每一行都对应一个生命周期决策，逐段说清楚：

代码段	做了什么	为什么这么写
textSearchImage.init()	拉起端侧索引服务	返回 false 说明设备/版本/区域不支持，必须走降级分支，不能硬用
insertImage(p, scope)	把单张图编码成向量并写入指定作用域	串行 await 保证顺序，避免并发写索引导致状态错乱
search(query, scope, top)	在 scope 内做语义检索	top 先给足（如 100），再在本地过滤，避免服务端截断丢掉真实命中
.filter(similarity >= 0.30)	挡掉低置信误召回	阈值是召回质量的分水岭，见要点 4
.sort(降序)	保证最相关的排最前	服务端虽按相似度返回，但过滤后仍需重排，避免顺序错乱
release()	释放索引服务	退出时调用，避免内存常驻；下次启动重新 init

一句话记忆：init 决定能不能用，insert 决定有什么，search 决定找得准不准，release 决定放不放得干净。

3.1 增量建库：维护"已索引清单"

要点 2 的落地代码——用 Preferences 存一份 路径 -> 修改时间 的映射，启动时只插新文件：

import { preferences } from '@kit.ArkData';
import { fileIo } from '@kit.FileKit';

const STORE = 'index_manifest';

// 读取已索引清单
async function loadManifest(ctx: Context): Promise<Record<string, number>> {
  const store = await preferences.getPreferences(ctx, STORE);
  const raw = store.getSync('manifest', '{}') as string;
  return JSON.parse(raw);
}

// 增量插入：只处理新文件或修改时间变化的文件
async function incrementalBuild(
  ctx: Context,
  paths: string[],
  scope: string,
  onProgress?: (done: number, total: number) => void
): Promise<void> {
  const manifest = await loadManifest(ctx);
  const todo = paths.filter(p => {
    const stat = fileIo.statSync(p);
    return manifest[p] !== stat.mtime; // 新文件或已改动
  });

  let done = 0;
  for (const p of todo) {
    await textSearchImage.insertImage(p, scope);
    manifest[p] = fileIo.statSync(p).mtime;
    onProgress?.(++done, todo.length);
  }

  const store = await preferences.getPreferences(ctx, STORE);
  await store.put('manifest', JSON.stringify(manifest));
  await store.flush();
}

这段增量代码的三个关键点：

1. manifest[p] !== stat.mtime 是增量判断的核心——用文件修改时间而非文件大小，能同时覆盖"新增"和"编辑过"两种情况；mtime 相同即视为已索引，直接跳过。
2. todo 先算完再循环插入——把过滤和插入分离，todo.length 就是进度条的总数，进度回调才有准确分母。
3. flush() 不能省——put 只写内存，flush 才落盘；漏掉它，下次启动清单还是旧的，增量就退化成全量重建。

3.2 后台插入 + 进度回调

把建库丢进 taskpool，主线程只负责刷新进度条：

import { taskpool } from '@kit.ArkTS';

@Concurrent
async function buildInWorker(paths: string[], scope: string): Promise<number> {
  let ok = 0;
  for (const p of paths) {
    try {
      await textSearchImage.insertImage(p, scope);
      ok++;
    } catch (e) {
      // 单张失败不中断整批
    }
  }
  return ok;
}

async function buildAsync(paths: string[], scope: string): Promise<number> {
  const task = new taskpool.Task(buildInWorker, paths, scope);
  return await taskpool.execute(task) as number;
}

为什么用 taskpool 而不是 Promise.all 并发？

• insertImage 内部是端侧模型推理，属于 CPU 密集任务，Promise.all 仍在主线程事件循环里排队，照样卡 UI；
• taskpool 把任务丢到独立工作线程，主线程只等结果，帧率不受影响；
• 但 @Concurrent 函数有隔离限制：不能捕获外部闭包、不能引用 Context/UI 对象，所以 paths、scope 必须作为参数显式传入。

进度回调的正确接法（主线程侧）：

// 主线程：分批投递，边插边刷新进度
async function buildWithProgress(paths: string[], scope: string, onTick: (p: number) => void) {
  const BATCH = 50;
  let done = 0;
  for (let i = 0; i < paths.length; i += BATCH) {
    const chunk = paths.slice(i, i + BATCH);
    done += await buildAsync(chunk, scope); // 每批返回成功数
    onTick(Math.round((done / paths.length) * 100)); // 0~100
  }
}

分批投递的好处：单批失败不影响整体、进度更新更平滑、内存占用可控。

注意：@Concurrent 函数内不能直接引用 UI 或 Context，路径数组需提前在主线程算好再传入。

四、索引生命周期的 5 个实战要点

要点 1：用 scope 做"图库分库"，别把所有图塞一个作用域。
我最初把所有相册照片插进同一个 scope，结果"宠物"的 query 把工作截图也带了出来。正确姿势：相册用 album、宠物用 pet、素材用 work，同一句话在不同 scope 里分别检索，互不串扰，也大幅缩小单 scope 检索范围、提速。

要点 2：启动别全量重建，做增量插入。
首次建库几千张图，insertImage 串行跑能卡 3 秒以上。我的做法是维护一份"已索引文件清单"（路径 + 修改时间），启动只对新文件/改动文件 insertImage，老图跳过。即便索引不跨会话持久化，增量也能把启动耗时压到几百毫秒。

要点 3：insert 放后台，带进度，别阻塞 UI。
大量插入建议在 taskpool 或异步任务里跑，并回调进度条；主线程直接插会掉帧、触发 ANR 风险。用户感知是"相册正在建立语义索引"，比黑屏卡死友好得多。

要点 4：设相似度阈值，挡掉低置信误召回。
similarity 范围是 [-1, 1]，但很多弱相关图分数在 0.1~0.2 之间。直接全量返回会让结果"看起来很准其实很杂"。我线上固定 >= 0.30 才展示，召回质量肉眼可见变干净。阈值不是越大越好——太严苛会漏掉真实命中，建议 0.25~0.35 之间按业务调。

要点 5：release 时机与跨会话持久化要实测确认。
init 后索引在内存里可用，release 会释放服务。索引是否落盘跨启动保留，官方文档未明说，必须以真机实测为准：我测的机型重启后需重新 init，但已 insert 的图是否还在要打印验证。最稳策略是不依赖持久化，按要点 2 做增量重建，行为可预期。

4.1 索引生命周期全景图

把上面 5 个要点串成一条时间线，看清每个阶段该做什么：

图解读： 这张图把生命周期切成三段——启动段（init → 读清单 → 扫描 → 增量插入）、运行段（query → search → 过滤 → 渲染，可循环）、退出段（release）。注意 init 失败直接走降级分支，这是很多 demo 漏掉的健壮性设计；而"有新文件?"的判断让无变化启动可以秒开，直接进入可检索状态。

4.2 检索链路时序图

一次查询从输入到出图，端侧各环节的调用顺序：

图解读： 时序图强调了两处"本地加工"——SearchService 在调 textSearchImage 前先做 query 合法性校验（挡掉纯数字/纯字母），拿到结果后再做阈值过滤和降序排序。也就是说，端侧模型只负责算相似度，业务层的清洗和排序要自己做，这是保证结果"看起来准"的关键。最后按 imagePath 异步加载缩略图，避免一次性解码大图卡顿。

4.3 scope 分库与检索隔离示意

五、小结与适用边界

文搜图最适合本地语义相册、私密图库检索、素材库按内容分组这类"数据不能出设备"的场景——这也是它相对云端方案的核心卖点。但它有边界：仅中国境内、query 必须带语义（中文最佳）、scope 隔离需要你主动设计、相似度阈值要调。

落地记住四句话：scope 先分库、启动做增量、插入放后台、检索加阈值。把索引生命周期管顺了，一句话找图的体验才真正丝滑。

5.1 全文总结

把整篇的脉络收拢成一张表，方便回查：

阶段	关键动作	对应要点	落地代码
初始化	init() 判可用，失败走降级	健壮性前提	ready()
建库	按 scope 分组，增量插入	要点 1、2	buildIndex() / incrementalBuild()
后台化	taskpool 分批插入 + 进度回调	要点 3	buildAsync() / buildWithProgress()
检索	query 校验 + 阈值过滤 + 降序	要点 4	search()
释放	退出 release()，不依赖持久化	要点 5	teardown()

一句话概括：把索引当成有生命周期的资源来管，而不是一次性调用的接口——启动时增量补齐、运行时按 scope 精准检索、退出时干净释放，端侧文搜图才能既快又准。

---

本文为原创首发实战笔记，基于 HarmonyOS 7.0.0（API 26）Core Vision Kit 文搜图能力，代码示例为可复用骨架，实际接口以华为官方文档为准。