一句话找到那张图——文本搜图的零标注检索实践

「不想上班鸿蒙实战系列 | 前作:「不想上班」鸿蒙实战系列 :两份配置零代码,平行视界把工位搬上大屏

「不想上班」的随手记攒了几百条之后,一个问题开始折磨人:“之前那张停发票,到底记在哪条日志里?” 文字内容可以 SQL 模糊搜,但图片内容一直是检索盲区——除非用户勤快到手打标签,而打工人显然不勤快。

HarmonyOS 7.0(API 26)CoreVisionKit 的文本搜索图片能力(textSearchImage)恰好补上了这块短板:不标注、不打 tag,输入"发票"两个字,直接把图捞出来。本文基于「不想上班」的落地代码,讲清这套能力怎么接、怎么管好。API 细节以华为官方文档为准,工程代码全部来自项目实战。

一、它搜的是"画了什么",不是"写了什么"

1.1 官方定义

文本搜索图片提供基于文本描述的图片检索能力。通过输入文本关键词,从已插入的图片库中搜索匹配的图像结果,返回图片沙箱路径、作用域和相似度信息。API 26.0.0 起提供(phone / 2in1 / tablet 均支持)。

1.2 三个反直觉的点

接入前先把心智模型掰正,这套 API 和"以图搜图""OCR 搜文字"都不是一回事:

  1. 它管的是特征库,不是文件。insertImage 只提取图片特征进系统数据库,不做任何像素处理;图片文件的增删仍是业务自己的事。API 面就是一套特征库的增删查:init / insertImage / search / deleteImage / clearData / release。
  2. 它按语义匹配,不按文字匹配。搜"咖啡"能命中一杯拿铁的照片,哪怕这张图里既没有"咖啡"两个字的 OCR 文本,文件名里也没有。这既是威力所在,也是边界所在——别指望它搜票据上的具体号码。
  3. 结果自带相似度。每条命中返回 similarity([-1, 1],越大越相似),排序和阈值过滤的空间都留给了业务。

1.3 和传统方案对比

维度手打标签 / 文件名检索OCR 文本识别文本搜图(语义检索)
维护成本高,靠用户自觉零零
能搜什么标签写了什么图里印了什么图里画了什么
典型漏检没打标签的图没有文字的图抽象语义弱的图

三者不是替代关系。「不想上班」的组合是:正文走 SQL 模糊搜,图片语义走 textSearchImage,各司其职。

二、随手记的找图痛点与三段链路

随手记的图片归档本身就有规矩:每条日志一个目录,filesDir/worklog_images/{logId}/。这个看似普通的目录约定,后面会成为整条检索链路的命门。

围绕文本搜图,落地拆成三段:

① 索引侧:图片落盘即入特征库(零标注的源头)

在这里插入图片描述

工作日志保存/新建/删图时在图片文件增删的同一事务点调用TextSearchImageUtil 的 indexWorkLogImage / removeWorkLogImageIndex——打标成本为零,语义特征由系统模型自动提取。

② 搜索侧:自然语言命中图片,反解日志直达
在这里插入图片描述在这里插入图片描述
搜索框输入"猫",searchLogImages 命中图片后按路径反解出所属日志,聚合展示"日志标题 + 命中缩略图",点击直达详情如上图。

③ 一致性侧:删图即删索引,错位自动对账

日志删除、图片移除、备份恢复、模型能力更新,每一条会破坏"文件 ↔ 特征库"一致性的路径都有对应清理或重建动作。

三段配合的结果:检索质量由系统语义模型保证,数据一致性由业务工程保证——这是本项目用文本搜图的核心思路。

三、六个方法与三条硬约束

3.1 API 全览

全部能力挂在 @kit.CoreVisionKit 的 textSearchImage 命名空间下:

方法职责
init(): Promise<boolean>初始化分析器服务
insertImage(imagePath, scope): Promise<boolean>插入图片特征
search(query, scope, topKey?): Promise<ImageObject[]>语义检索
deleteImage(imagePath, scope): Promise<boolean>删除指定图片特征
clearData(): Promise<boolean>清空整个数据库(模型能力更新后须执行)
release(): Promise<boolean>释放服务

返回的 ImageObject 三件套:imagePath(沙箱路径)、scope(作用域)、similarity([-1,1] 相似度)。

3.2 三条硬约束

参数表里有几条红线,越过就是错误或空结果:

  • 路径与 scope 长度:imagePath 长度 [1,128],scope 长度 [1,32]、仅字母或数字——归档目录必须浅而短;
  • 查询词:长度 [1,100],不支持纯数字和纯字母(含纯字母数字组合),中文、中文混排数字字母符号都可以;
  • topKey:返回数量上限,取值 [0,100],默认 100。

图像本身的要求(Core Vision Kit 全局约束):高宽均在 100px~10000px 之间,高宽比建议 10:1 以内。

3.3 错误码

错误码含义应对
1013100001图片路径非法检查沙箱路径与长度
1013100002服务异常记录日志,静默降级
1013100003模型能力已更新,旧特征全部失效clearData 清库后重建,详见 4.2

第三个最特殊:它不是"失败",是"通知你换了个脑子"——旧特征在新模型下全部作废,必须清库重建。我们的处理贯穿了索引与搜索两侧,下文展开。

3.4 调用骨架

心智模型一句话:先 init,之后所有操作(增/删/搜/清)都是特征库操作,且必须串行(Core Vision Kit 不支持同特性并发,并发会返回系统繁忙)。核心调用长这样:

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

await textSearchImage.init();
await textSearchImage.insertImage(absPath, 'worklog');
const results = await textSearchImage.search('咖啡', 'worklog', 50);
// results[i] = { imagePath, scope, similarity }

四、工程化:把黑盒管成白盒

系统特征库对业务完全不可见——查不了、导不出。把这样的黑盒接入生产环境,我们的原则是:能降级、可串行、有账本。

4.1 进门之前:双门控 + 懒初始化

能力探测沿用实战系列文章图像超分的同款姿势(API 版本 + canIUse 双门控),不支持就静默消失:

/** 设备是否支持文本搜索图片(API 版本 + 系统能力双门控,与超分同款) */
export function isTsiSupported(): boolean {
  return getSdkApiVersion() >= 26 && canIUse('SystemCapability.AI.Vision.VisionBase');
}

初始化做成幂等懒加载:首个操作触发 init(),全局共享同一个 promise;失败置空允许下次重试;成功后整个进程存续期不 release(随用随在,避免反复初始化开销):

/** 懒初始化(幂等;失败返回 false 且允许后续重试) */
function ensureInit(): Promise<boolean> {
  if (!initPromise) {
    initPromise = textSearchImage.init()
      .then((ok: boolean): boolean => {
        if (!ok) {
          initPromise = null; // 允许下次重试
        }
        return ok;
      })
      .catch((e: object): boolean => {
        initPromise = null;
        return false;
      });
  }
  return initPromise;
}

降级策略一句话:索引侧直接 return,搜索侧返回空数组——老设备上功能不存在,但没有任何报错弹窗去打扰用户。

4.2 并发与一致性:队列、账本与对账

串行队列。所有特征库操作(插入/删除/搜索/清库)都经同一个 FIFO 队列 enqueue() 串行执行,前序失败不阻断后续任务。这一层直接消化了"同特性并发返回系统繁忙"的 Kit 级约束。

本地记账。系统库不可查,那"哪些图已经索引过"就得自己记:用 preferences 持久化一个已索引绝对路径的 Set(内存缓存 + 全量 JSON 写盘)。插入成功才入账,删除执行就销账。

错误码 1013100003 的专门通道。插入时撞见"模型能力更新",处理是清库 + 清记账 + 重试本次插入(目录与记账的差集机制会自动补回其余图片):

// 1013100003 模型能力更新:旧特征全部失效 → 清库 + 清记账(目录与记账差集会自动重插其余图片)后重试本次插入
try {
  await textSearchImage.clearData();
} catch (ce) { /* ... */ return; }
set.clear();
if (await textSearchImage.insertImage(abs, SCOPE)) {
  set.add(abs);
}

搜索侧撞见同款错误,则清库清记账后触发后台全量重建,本次搜索返回空——宁可本次无结果,不留一个全是死特征的旧库。

启动对账。应用冷启动延迟 5 秒(避开启动高峰)跑一次增量对账:扫 worklog_images 目录与记账求双向差集——目录有、记账无的补索引;记账有、目录无的清索引。幂等、防重入(进行中再调用直接返回):

// EntryAbility.onCreate 中:
if (isTsiSupported()) {
  setTimeout((): void => {
    void syncIndexInBackground(this.context);
  }, 5000);
}

对账主体的核心就是两个差集循环:

// 新增:目录有、记账无 → 补索引
for (const p of present) {
  if (!set.has(p)) { await insertIndex(p, set); }
}
// 清理:记账有、目录无 → 删索引
for (const p of Array.from(set)) {
  if (!present.has(p)) { await deleteIndex(p, set); }
}
await saveRegistry(context);

灾后重建。备份恢复后,本机系统库与恢复回来的记账必然错位,选择最干脆的策略:清库清记账,延迟 3 秒全量重建。日志全量重置(resetAll)走同一条清库路径:

// BackupManager:图片搜索索引重建(registry 不参与备份,恢复后与本机系统库必然错位,
// 清空后延迟触发后台补索引,扫恢复后的 worklog_images 全量重建)
clearTsiIndex(context).then((): void => {
  setTimeout((): void => {
    void syncIndexInBackground(context);
  }, 3000);
});

clearTsiIndex 有一个容易漏掉的细节:先等待进行中的对账完成再清库——否则对账尾部的 saveRegistry 会把旧记账写回,或对账中的插入落在 clearData 之后,造成"记账有、系统库无"的永久漏检。

4.3 让结果回得了家:路径反解与搜索侧体验

系统返回的是图片沙箱路径,但用户要的是"这条日志"。好在归档目录是 worklog_images/{logId}/,一个正则把 logId 反解出来:

/** 从图片路径反解日志 id:worklog_images/{logId}/xxx;解析失败返回空串 */
export function tsiLogIdFromPath(path: string): string {
  const abs = tsiAbsPath(path);
  const m = abs.match(/worklog_images\/([^/]+)\//);
  return m ? m[1] : '';
}

归档结构即索引结构——这是整套方案里性价比最高的一步棋。

搜索侧(随手记页内搜索为例)三个小动作,都是体验细节:

/** 图片语义搜索(关键词非空时并行执行;seq 防过期结果覆盖;按 logId 去重取最高相似度) */
private async runImageSearch(): Promise<void> {
  const seq = ++this.imageSearchSeq;
  // ...
  const hits: LogImageHit[] = await searchLogImages(getContext(this), kw, 50);
  if (seq !== this.imageSearchSeq) {
    return; // 慢结果晚到直接丢弃,不覆盖新关键词的结果
  }
  // hits 已按 similarity 降序:首次出现的 logId 即该日志最高相似度命中
}
  • 防抖:输入停顿 300ms 才发起检索,不打字就搜;
  • 序号防过期:慢查询结果回来时若关键词已变,直接丢弃;
  • 按 logId 去重:一条日志可能命中多张图,只保留最高相似度那张做代表。

点击命中项后,通过 editRequest 中转直达日志详情页(只读模式),与日志列表的点击行为完全一致。全局搜索入口(GlobalSearchModel)复用同一条 searchLogImages 链路,图片命中与正文命中混排分组展示。

五、这些坑我们替你先踩了

  1. 纯数字关键词会扑空。系统不支持纯数字/纯字母查询,我们在调用前用正则保守过滤(必须含至少一个非字母数字字符),否则用户搜"2024"会得到一个莫名其妙的空列表。
  2. 插入失败别当大事。图片刚落盘时特征提取可能未就绪,插入会瞬时失败——我们做了延迟重试一次,仍失败就留给启动对账兜底。索引是异步锦上添花,不该阻塞保存流程。
  3. topKey 默认 100 但别乱给大。我们固定 50:语义检索的长尾结果相似度衰减很快,50 名开外基本是噪声。
  4. 删图路径要全覆盖。单图删除、删日志、清空数据三条路径都要挂删除钩子,漏一条就是特征库里的幽灵数据。
  5. 模拟器上永远等不到结果。Core Vision Kit 不支持模拟器,联调请直接上真机,别怀疑自己。

六、总结:检索质量交给系统,一致性交给工程

文本搜图的接入代码量不大,真正的工程量在"管好这个黑盒":

  • 心智上,它是特征库的增删查,不是文件管理,更不是 OCR;
  • 架构上,归档目录设计成可反解 logId 的结构,检索结果一步到家;
  • 稳定性上,双门控降级、串行队列、记账 + 对账 + 灾后重建,让"系统库与业务数据的差集"永远在收敛。

超分管"看得清",搜图管"找得到"。「不想上班」的随手记图片链路——压缩存、超分看、搜得到——正式闭环。


参考文档

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐