【共创稿事节】「不想上班」实战系列:一句话找到那张图——文本搜图的零标注检索实践
一句话找到那张图——文本搜图的零标注检索实践
「不想上班鸿蒙实战系列 | 前作:「不想上班」鸿蒙实战系列 :两份配置零代码,平行视界把工位搬上大屏
「不想上班」的随手记攒了几百条之后,一个问题开始折磨人:“之前那张停发票,到底记在哪条日志里?” 文字内容可以 SQL 模糊搜,但图片内容一直是检索盲区——除非用户勤快到手打标签,而打工人显然不勤快。
HarmonyOS 7.0(API 26)CoreVisionKit 的文本搜索图片能力(textSearchImage)恰好补上了这块短板:不标注、不打 tag,输入"发票"两个字,直接把图捞出来。本文基于「不想上班」的落地代码,讲清这套能力怎么接、怎么管好。API 细节以华为官方文档为准,工程代码全部来自项目实战。
一、它搜的是"画了什么",不是"写了什么"
1.1 官方定义
文本搜索图片提供基于文本描述的图片检索能力。通过输入文本关键词,从已插入的图片库中搜索匹配的图像结果,返回图片沙箱路径、作用域和相似度信息。API 26.0.0 起提供(phone / 2in1 / tablet 均支持)。
1.2 三个反直觉的点
接入前先把心智模型掰正,这套 API 和"以图搜图""OCR 搜文字"都不是一回事:
- 它管的是特征库,不是文件。
insertImage只提取图片特征进系统数据库,不做任何像素处理;图片文件的增删仍是业务自己的事。API 面就是一套特征库的增删查:init / insertImage / search / deleteImage / clearData / release。 - 它按语义匹配,不按文字匹配。搜"咖啡"能命中一杯拿铁的照片,哪怕这张图里既没有"咖啡"两个字的 OCR 文本,文件名里也没有。这既是威力所在,也是边界所在——别指望它搜票据上的具体号码。
- 结果自带相似度。每条命中返回
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 链路,图片命中与正文命中混排分组展示。
五、这些坑我们替你先踩了
- 纯数字关键词会扑空。系统不支持纯数字/纯字母查询,我们在调用前用正则保守过滤(必须含至少一个非字母数字字符),否则用户搜"2024"会得到一个莫名其妙的空列表。
- 插入失败别当大事。图片刚落盘时特征提取可能未就绪,插入会瞬时失败——我们做了延迟重试一次,仍失败就留给启动对账兜底。索引是异步锦上添花,不该阻塞保存流程。
- topKey 默认 100 但别乱给大。我们固定 50:语义检索的长尾结果相似度衰减很快,50 名开外基本是噪声。
- 删图路径要全覆盖。单图删除、删日志、清空数据三条路径都要挂删除钩子,漏一条就是特征库里的幽灵数据。
- 模拟器上永远等不到结果。Core Vision Kit 不支持模拟器,联调请直接上真机,别怀疑自己。
六、总结:检索质量交给系统,一致性交给工程
文本搜图的接入代码量不大,真正的工程量在"管好这个黑盒":
- 心智上,它是特征库的增删查,不是文件管理,更不是 OCR;
- 架构上,归档目录设计成可反解 logId 的结构,检索结果一步到家;
- 稳定性上,双门控降级、串行队列、记账 + 对账 + 灾后重建,让"系统库与业务数据的差集"永远在收敛。
超分管"看得清",搜图管"找得到"。「不想上班」的随手记图片链路——压缩存、超分看、搜得到——正式闭环。
参考文档
- 通过文本搜索图片(开发指南):https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/core-vision-text-search-image
- textSearchImage(通过文本搜索图片)API 参考:https://developer.huawei.com/consumer/cn/doc/harmonyos-references/core-vision-text-search-image-api
- Core Vision Kit 介绍(约束与限制):https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/core-vision-introduction
- 「不想上班鸿蒙实战系列 | 前作:「不想上班」鸿蒙实战系列 :两份配置零代码,平行视界把工位搬上大屏
- 不想上班下载链接
更多推荐





所有评论(0)