万少 · 万绍业 技术 · 创造 · 价值

鸿蒙开发技巧 鸿蒙7文搜图做旅行照片检索

鸿蒙7文搜图做旅行照片检索

找一张"去年在洱海边上拍的落日",在相册里是这么回事:

找一张"去年在洱海边上拍的落日",在相册里是这么回事:

  • 按日期翻,四月十二号那几张挨个点开看;
  • 搜文字,能命中的只有文件名里真写了"落日"的图,而相机给的文件名是 IMG_20260412_184705.jpg;
  • 搜地点,前提是当时打过标签,而绝大多数人从来不打。

图片内容本身没被看过一眼。想在自己的应用里补上这块能力,自己接一个图文多模态模型,权重几百兆、首字几秒,端侧根本落不了地。

HarmonyOS 7(API 26)开始,华为把这件事做进了 Core Vision Kit,命名空间 textSearchImage,六个方法,模型由系统持有:应用不打包权重、不联网、不申请存储权限。官方对它的描述只有一句,我把文档页截下来了,注意"基于文本语意"这五个字,它不是关键词匹配:

官方文档「通过文本搜索图片」页面的适用场景段落,写明该服务提供基于文本语意的图片检索能力,适用于图片检索、相册管理、内容推荐等场景

我照着相册应用的样子写了个 demo:一条按日期分组的旅行时间轴,顶上一个小搜索框,输一句中文把符合的图挑出来。下面是它在真机上的样子、全部实测数字,以及六处文档口径和真机行为不一致的地方。


先确认你的设备能不能跑

这个能力的门槛不在代码,在设备。先对完这张表再往下读。

条件 要求 来源
系统版本 HarmonyOS 7 / API 26,接口起始版本 26.0.0 官方 API 参考
设备类型 Phone、Tablet、PC/2in1 官方约束与限制
地区 仅中国境内(香港特别行政区、澳门特别行政区、中国台湾除外) 官方约束与限制
模拟器 不支持,官方原文"本Kit暂不支持模拟器" 官方约束与限制
模型下载 不需要,端侧系统 AI 直接提供 官方接口说明
权限 不需要声明存储、媒体权限;从相册挑图走 Picker,属于免权限路径 实测
并发 不支持同一用户并发调用同一特性 官方约束与限制

模拟器这一条单独说。Core Vision Kit 的约束页在"通过文本搜索图片"这一行下面,紧跟着两段说明,一段是输入图像的成像质量要求,一段是并发限制,再往下就是"模拟器支持情况:本Kit暂不支持模拟器"。我把这一段截全了:

官方约束与限制表格中「通过文本搜索图片」的输入图像要求,以及下方关于多用户接入不支持同一用户并发调用的说明和「本Kit暂不支持模拟器」

原因是特征提取和图文匹配都在 NPU 上跑,模拟器没有 NPU。所以本文所有数字都来自一台真机:HUAWEI MatePad Pro,序列号 59HYD25A17202258,HarmonyOS 7.0.0.109,分辨率 2800 x 1840,USB 连接。


先看效果

首页是一条按日期分组的时间轴

刚打开时相册是空的。这一屏没有任何技术字段,就一句话加两个入口:

相册首页空状态:标题「相册」、右上角「管理」、搜索入口提示「搜索照片内容」,中间是「相册还是空的」和两个按钮,导入示例相册(12 张)与从本机相册挑选

点"导入示例相册"之后,照片按日期一组一组冒出来,还没建好索引的那几张压着暗、上面转着圈,建好一张亮一张:

建库进行中的首页:状态行「正在建立搜索索引 1/3」配一条进度条,4月12日 周日 大理 · 洱海 分组下第一张已经点亮,后两张蒙着灰色遮罩并显示转圈

十二张全跑完,大约五秒:

建库完成后的相册首页:状态行「12 张照片已可以按内容搜索」,下面是按日期分组的时间轴,4月12日 周日 大理 · 洱海 三张,4月13日 周一 两张,7月18日 周六 市区 · 江边 一张

往下翻是十月国庆那次:

时间轴下半段:9月30日的雪山湖泊一张,10月1日 周四 三张(日照金山、草原上的牦牛、盘山公路),10月2日 周五 川西 · 营地 一张夜晚篝火

注意 4月13日 和 10月1日 这两组只有日期没有地点,因为那两天的照片不在同一个地方拍的。这个细节后面代码里会讲。

搜索页先给说法,再给结果

点首页那个搜索条进来。没搜之前它不空着,而是把相册里真实存在的画面写成说法摆在下面:

搜索页初始状态:返回、输入框(占位「说说你想找哪张照片」)、搜索按钮,下方「相册里有这些画面」一排 chips:落日、雪山、橙色的小猫、草原上的牦牛、夜晚的篝火、城市天际线

点"落日",五张:

落日检索结果页:标题「和「落日」相近的照片 5 张」,按日期分成三组,4月12日 大理 · 洱海 三张分别标角标最匹配、较匹配、可能相关,10月1日 川西 · 折多山 一张标较匹配,4月13日 大理 · 客栈阳台 一张标可能相关

角标是"最匹配 / 较匹配 / 可能相关",不是 0.333 这种数字。排第一的是有椰子树剪影那张洱海落日,第三张是折多山的日照金山,第五张是客栈阳台下午四点的天光。库里跟"落日"沾边的图全找出来了,猫、牦牛、篝火一张没混进来。

点任意一张进详情:

照片详情页:整屏洱海落日图,顶部居中「大理 · 洱海」,底部「2026年4月12日 18:47」和「按「落日」找到 · 最匹配」,最下一排上一张、1 / 3、下一张,右上角「技术信息」

这一屏也没有相似度。想看得点右上角"技术信息"。

技术数据都在开发者信息页

详情页右上角进去,第一屏是服务和调用的原始数值:

开发者信息页上半:phase 2、isReady() true、init() 耗时 753 ms、建库总耗时 5216 ms、search() 耗时 17 ms、scope trip2026、topKey 100、query 落日、命中条数 5

往下是逐张 insertImage 的耗时和沙箱路径长度,再往下是这一次 search() 返回的完整 ImageObject:

开发者信息页下半:search() 返回的 ImageObject 五条,rank 0 到 rank 4,相似度 0.333215 / 0.330086 / 0.324715 / 0.323298 / 0.321341,每条带 scope "trip2026" 和完整沙箱路径 /data/storage/el2/base/haps/entry/files/IMG_xxx.jpg,最后「最近一次错误(无)」

管理页(首页右上角"管理")负责索引本身:状态、重建、单张移除。

管理页:已索引 12 / 12 张,索引操作卡片里一句说明加左对齐的「重建全部索引」按钮,关于这个能力三行(开发者信息、使用须知、版本 1.0.0),下方已入库照片列表每行缩略图加日期加地点加已索引加移除

使用须知页把十三条约束直接列在应用里:

使用须知页:调用前需要知道的约束,十三条编号清单,覆盖起始版本、模拟器、输入图像尺寸、imagePath 与 scope 与 query 的长度和字符集、topKey 只是上限、多要素查询改写排序、错误码归属

整个应用里没有一处 emoji,没有一处把 similarity、scope 这种字段名印在用户会看到的地方。


实测数据

建库:慢的是它

同一份十二张的库、同一台设备,冷启动重复跑:

操作 实测值 说明
init() 753 / 769 / 772 / 780 / 781 ms 五次冷启动,区间 753 到 781 ms
单张 insertImage 374 ~ 524 ms 十二张各自计时,绝大多数落在 400 到 440 ms
十二张建库总耗时 4959 / 5049 / 5082 / 5095 / 5124 / 5144 / 5216 / 5252 ms 单张之和约 5000 ms,循环自身只多花几十毫秒
沙箱路径长度 63 字符 每张都一样:/data/storage/el2/base/haps/entry/files/ 前缀 43 字符 + 19 字符文件名

结论:这个能力的交互成本全在建库侧。单张提特征 400 多毫秒,一百张就是四十多秒。所以建库必须做成增量、放在用户不忙的时候跑(首次进入、充电、空闲),不能等到用户搜的时候现建。demo 里那个"一张一张亮起来"的效果不是为了好看,是把 5 秒的等待拆成十二次可看见的进度。

检索:稳态二十毫秒上下

查询 命中 耗时 测法
落日 5 张 17 / 21 / 27 / 39 ms 界面上单次点查,每次间隔几秒
海边的落日 4 张 21 ms 同上
海边的落日和雪山 3 张 22 ms 同上
2026 0 张 8 / 10 ms 同上
草原上的牦牛 1 张 133 ms 设备休眠后唤醒的第一次查询
上面十四组查询连跑一遍 — 8 ~ 15 ms 探针里背靠背循环

两件事:

第一,首查有一次性预热开销。同一句查询,唤醒后第一次 133 ms,紧跟着再查就掉到 20 ms 上下。做体验埋点时别把这一次 133 ms 当常态,也别拿热态的 15 ms 去承诺首屏体验。

第二,界面上单次点查比循环里慢。17 到 39 ms 对 8 到 15 ms。差的是服务侧空闲后要重新拾起模型的那点开销,量级不大,但如果你要做"输入即查",得把这个抖动算进防抖窗口里。

命中数量与相似度全表

十二张库(大理三日 5 张 + 城市夜景 + 家猫 + 川西国庆 4 张)上,一次探针连跑十四组查询的完整结果:

查询词 命中 相似度(按 rank 顺序) 耗时
落日 5 0.333215 / 0.330086 / 0.324715 / 0.323486 / 0.321341 15 ms
海边 4 0.323433 / 0.318549 / 0.316681 / 0.312577 10 ms
雪山 1 0.328454 11 ms
猫 1 0.327737 11 ms
橙色的小猫 1 0.330617 9 ms
城市夜景 1 0.339005 12 ms
城市天际线 1 0.328450 15 ms
草原上的牦牛 1 0.354855 11 ms
海边的落日 4 0.348895 / 0.340479 / 0.326392 / 0.324538 13 ms
海边的落日和雪山 3 0.341485 / 0.340717 / 0.329696 14 ms
营地篝火 1 0.381055 8 ms
2026(纯数字) 0 — 2 ms
sunset(纯字母) 0 — 1 ms
a cat(字母加空格) 0 — 8 ms

顺带一个观察:similarity 的末位在不同次运行之间会抖。同一句"落日",rank 3 那次是 0.323486,这次是 0.323298,差了 0.0002。次序没变过。所以别拿它做等值判断,也别指望缓存命中。

三条值得单独讲的结论

相似度不是百分比,别拿它当置信度。 官方给 similarity 的取值范围是 [-1, 1]。这台设备上一次探针跑完十一组有命中的查询、共二十三次返回,值全部落在 0.312577 到 0.381055 之间,一条负数没有,一条 0.9 也没有。最高分是"营地篝火"对上那张夜景篝火(0.381055),最低分是"海边"对上客栈阳台(0.312577)。

所以它的正确用法是在同一批返回结果里排序,不是设一个"大于 0.8 才算命中"的绝对阈值。真机上试过就知道,那样写一条都过滤不出来。demo 里把 rank 翻译成"最匹配 / 较匹配 / 可能相关",就是把一个不能横比的数值降级成序数。

多要素查询不是落空,是改写排序。 这条推翻了我上一版的判断。

"海边的落日"命中 4 张,第一名是洱海那张椰子树落日(0.348895):

「海边的落日」结果页:和「海边的落日」相近的照片 4 张,4月12日 大理 · 洱海 三张(最匹配、较匹配、可能相关),4月13日 大理 · 客栈阳台 一张(可能相关)

在后面加三个字,"海边的落日和雪山"命中 3 张:

「海边的落日和雪山」结果页:3 张,4月12日 大理 · 洱海 两张,10月1日 川西 · 折多山 一张带最匹配角标排在第二组

洱海三张掉到两张,折多山那张日照金山挤进来了,而且它的相似度 0.341485 是这一批里最高的:

折多山日照金山详情页:顶部「川西 · 折多山」,底部「2026年10月1日 07:55」和「按「海边的落日和雪山」找到 · 最匹配」

也就是说它确实读到了"雪山"这个要素,并且给了它最高权重,同时把"落日"里的一张挤了出去。这跟"整句一个向量、多要素会落空"是两种行为。同样,"猫"命中 1 张,"橙色的小猫"也命中 1 张(0.330617),加了定语没落空。

能用的结论是:多要素查询会同时改变命中集合和排序,且结果条数可能变少。它不是 AND 交集,也不是简单的整句向量。查询词仍然建议短、单一主题,但理由不是"多了就搜不到",而是"多了你没法预测它怎么权衡"。

纯字母和纯数字不报错,但固定 0 命中,而且明显更快。 官方对 query 的描述是"不支持纯数字和纯字母,支持中文,拼接数字、字母或者符号"。"不支持"没说是抛错还是返回空。实测:2026 用 2 ms、sunset 用 1 ms 返回空数组,而正常中文查询要 8 到 15 ms。快到像是服务侧在参数校验阶段直接短路,没走模型。

有个反例值得记:a cat 也是纯字母(中间一个空格),返回 0 命中但花了 8 ms,跟正常中文查询一个量级。所以"快"不是"纯字母"的可靠信号,别拿耗时去反推服务侧走没走模型。

工程上该做的是前置判断:查询串里一个汉字都没有,就直接提示"试试用中文描述画面",省一次没意义的调用。demo 里那个空结果页也给了出口:

空结果页:和「2026」相近的照片 0 张,提示「没找到和「2026」相近的照片」,副文案说明这个能力认的是画面内容不是文件名和拍摄日期,下面一排可点的示例说法

四条失败路径

一、作用域里带下划线,十二张全部 401。 这个坑是官方文档自己埋的。开发指南的示例代码里写的是:

const scope: string = 'default_scope';

我照抄了。十二张图全部入库失败,首页搜索条下面多出一行红字,建库"总耗时"只有约 0 ms —— 因为根本没进模型,参数校验阶段就被拒了。日志里十二条一模一样的 401:

insertImage(IMG_20261002_201533.jpg) failed, code=401, msg=The parameter check failed.

对照 API 参考里 scope 的说明:长度 [1, 32],支持字母或数字。下划线不在里面。也就是说官方开发指南的示例值和官方 API 参考的参数约束互相矛盾,而真机站在 API 参考这一边。

换成 trip2026 之后同样的十二张全部成功,就是上面那组 5000 ms 的数据。

二、相册 URI 直接传,抛 1013100001。 这条也推翻了我上一版写的"相册 URI 传进去直接 401"。实测:

insertImage(file://media/Photo/1/IMG_20260101_000000/IMG_20260101.jpg)
  failed, code=1013100001, msg=Invalid image path or size
insertImage(/data/local/tmp/not_exist.jpg)
  failed, code=1013100001, msg=Invalid image path or size

1013100001 这个文档里写着"无效图片路径"的错误码是能稳定复现的,路径类问题走它。参数格式类问题(scope 字符集、query 长度)才走通用 401。上一版把两者混成一条了。

三、查询词超过 100 字,抛 401。 构造一个 101 字的查询串,search() 抛 401 The parameter check failed.,耗时 0 到 1 ms,同样不进模型。这条在界面上长什么样,见后面「错误码」一节那两张对照截图。

四、topKey 传 0 不是"返回空"。 文档写 topKey 取值 [0, 100]、默认 100,字面看像"返回前 N 条"。实测同一句"落日":传 0、传 5、传 100 都返回同样的 5 条。它是上限不是配额,0 也没有被当成"零条"。真正决定返回几条的是服务内部那个没暴露出来的相似度阈值。想在前端做"只要前三条",得自己截数组。

这四条最后都写进了应用内的使用须知页(见前面截图),现场排障时对着看比翻文档快。


接口只有六个方法

textSearchImage 这个命名空间对外就六个方法,没有回调注册、没有配置对象、没有事件监听。

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

// 1. 初始化:整个应用生命周期内一次
const ready: boolean = await textSearchImage.init();

// 2. 入库:把一张沙箱里的图提特征,归到某个作用域下
const ok: boolean = await textSearchImage.insertImage('/data/.../IMG_20260412_184705.jpg', 'trip2026');

// 3. 检索:一句话,返回按相似度排好序的图片列表
const list: textSearchImage.ImageObject[] =
  await textSearchImage.search('落日', 'trip2026', 100);

// 4. 删单张
await textSearchImage.deleteImage('/data/.../IMG_20260412_184705.jpg', 'trip2026');

// 5. 清空整个作用域的数据
await textSearchImage.clearData();

// 6. 释放
await textSearchImage.release();

返回结构 ImageObject 只有三个字段:

class ImageObject {
  imagePath: string;   // 入库时传进去的那个沙箱路径,原样返回
  scope: string;       // 入库时传进去的那个作用域
  similarity: number;  // 语意相似度,取值 [-1, 1]
}

心智模型一句话:insertImage 建索引,search 查索引,scope 是索引的分区键。 三个字段里最容易被低估的是 scope —— 它不是备注信息,入库和检索必须传同一个值,否则查不到。这跟数据库的分区、向量库的 namespace 是一回事。

官方文档的开发步骤到这儿就结束了,剩下的全是工程问题。下面按这个 demo 的真实代码顺序讲。


工程结构

entry/src/main/ets/
├── model/PhotoCatalog.ets           样张元数据表:文件名、日期、时间、地点
├── model/SearchStore.ets            状态容器(@ObservedV2 + @Trace)与日期分组逻辑
├── service/TextSearchService.ets    六个方法的封装:计时、错误归集、hilog
├── service/LibraryLoader.ets        取图与校验:rawfile / 相册 URI / 沙箱拷贝 / 尺寸检查
├── components/PhotoTile.ets         单张方砖:图片 + 压暗 + 转圈 + 角标
├── components/PhotoWall.ets         方砖墙:按列数切行
├── components/InfoRow.ets           一行「标签 + 值」,为了绕开 V2 的刷新问题
├── util/GridLayout.ets              按屏宽算列数和方砖边长
├── util/PhotoSrc.ets                缩略图地址:相册 URI 或沙箱路径
└── pages/
    ├── Index.ets                    Navigation 根容器 + @Provider
    ├── HomePage.ets                 相册时间轴首页与建库
    ├── SearchPage.ets               搜索页:说法 chips、输入、结果分组
    ├── DetailPage.ets               单张大图 + 日期地点 + 左右翻页
    ├── AlbumPage.ets                管理页:索引状态、重建、单张移除
    ├── DevInfoPage.ets              开发者信息页:全部原始数值
    └── NoticePage.ets               使用须知页:十三条约束

probe/ProbeRunner.ets                边界探针(不在工程里):参数校验、topKey 扫描
probe/MeasureProbe.ets               数据探针(不在工程里):一次跑完十四组查询并逐条打日志

probe/ 那两个文件不参与构建。所有边界数据和上面那张十四行全表都是它们跑出来的,跑完从 src/ 里移出来,免得跟着发布包走。

技术选型上有两条是固定的:状态管理用 V2,页面跳转用 Navigation。这个工程没有一处 @State / @Link,也没有 router.pushUrl。

特征库在系统侧,应用只留一份本地台账

这是这个能力和普通"本地向量库"最大的区别。insertImage 之后,特征向量存在系统侧,应用拿不到、也序列化不了。应用重启索引还在;但应用自己那份元数据(沙箱路径、入库耗时、日期地点)没了。

所以做了一张本地台账,LibraryItem 就是台账的一行:

// model/SearchStore.ets
@ObservedV2
export class LibraryItem {
  @Trace sandboxPath: string = '';
  @Trace uri: string = '';
  @Trace ok: boolean = false;
  @Trace loading: boolean = false;
  @Trace insertMs: number = 0;
  // meta 在入列前一次性写好,之后不再变,所以不需要 @Trace
  meta: PhotoMeta = PhotoCatalog.unknown();
}

search() 返回的 imagePath 只是字符串,要显示图片还得反查回本地记录:

// service/TextSearchService.ets
const hits: SearchHit[] = [];
list.forEach((o: textSearchImage.ImageObject, index: number) => {
  const hit: SearchHit = new SearchHit();
  hit.sandboxPath = o.imagePath;
  hit.scope = o.scope;
  hit.similarity = o.similarity;
  hit.rank = index;
  hit.item = this.store.findItem(o.imagePath);   // 用路径反查本地台账
  hits.push(hit);
  const label: string = hit.item === undefined ? 'OUT_OF_LIBRARY' : hit.item.meta.rawName;
  hilog.info(DOMAIN, TAG, 'hit %{public}d %{public}s %{public}s',
    index, label, o.similarity.toFixed(6));
});

最后那行 hilog 是这张表全部命中数据的来源。前面那张十四行全表不是从界面上一条条抄的,是 probe/MeasureProbe.ets 连跑一遍、把这段日志整段拉下来对齐的。

findItem 找不到时(系统侧残留着上一次安装前入库的路径),结果卡显示"库外",图片退回用 fileUri.getUriFromPath() 按沙箱路径直接渲染。换句话说:clearData() 才是让两边对齐的手段,release() 不清数据。 这一点文档没写,是实测行为。管理页那个"重建全部索引"按钮做的第一件事就是 clearData()。

init 只做一次,insert 必须串行

init() 返回 Promise<boolean>,不是 void。这个布尔要判,false 就别往下走:

// service/TextSearchService.ets
async init(): Promise<boolean> {
  this.store.phase = AppPhase.INITIALIZING;
  this.store.clearErrors();
  const t0: number = Date.now();
  try {
    const ok: boolean = await textSearchImage.init();
    this.store.initMs = Date.now() - t0;
    this.ready = ok;
    this.store.phase = ok ? AppPhase.READY : AppPhase.FAILURE;
    if (!ok) {
      this.store.lastError = '文搜图服务没连上,换台真机再试';
      this.store.lastErrorRaw = 'textSearchImage.init() 返回 false';
    }
    hilog.info(DOMAIN, TAG, 'init result=%{public}s, ms=%{public}d', `${ok}`, this.store.initMs);
    return ok;
  } catch (error) {
    const err = error as BusinessError;
    this.store.initMs = Date.now() - t0;
    this.fail('textSearchImage.init', '文搜图服务没连上,换台真机再试', err, this.store.initMs);
    return false;
  }
}

建库循环用的是 await 串行的 for,不是 Promise.all:

// pages/HomePage.ets
private async importSamples(): Promise<void> {
  if (!await this.ensureReady()) {
    return;
  }
  this.store.phase = AppPhase.BUILDING;
  const t0: number = Date.now();
  const ctx: common.Context = this.uiContext();
  const photos: PhotoMeta[] = PhotoCatalog.PHOTOS;
  for (let i = 0; i < photos.length; i++) {
    const item: LibraryItem = new LibraryItem();
    item.meta = photos[i];
    item.sandboxPath = await LibraryLoader.ensureRawFileInSandbox(ctx, photos[i].rawName);
    this.store.appendItem(item);
    await this.ingest(item);
  }
  this.finishBuild(t0, photos.length);
}

必须串行不是风格问题。官方约束原文:"Core Vision Kit 的特性支持多用户同时接入,但是不支持同一用户并发调用同一个特性,如同一个特性被同一进程同一时间多次调用,则返回系统繁忙错误。" 用 Promise.all 提十二张,就是同一进程同一时间十二次调用,等着收系统繁忙。

串行还有个副产品:ok 一张一张翻真、loading 一张一张翻假,照片墙就自动有了"逐张点亮"的进度反馈,不用额外写任何进度组件。

相册 URI 必须先拷进沙箱

insertImage 的第一个参数官方叫 imagePath,长度范围 [1, 128]。真机上它只认应用沙箱里的绝对路径,file://media/... 传进去抛 1013100001 Invalid image path or size。

所以从相册挑图要先落盘:

// service/LibraryLoader.ets
static async copyUriToSandbox(context: common.Context, uri: string, index: number): Promise<string> {
  const name: string = `gallery_${Date.now()}_${index}.jpg`;
  const dest: string = `${context.filesDir}/${name}`;
  const src = await fileIo.open(uri, fileIo.OpenMode.READ_ONLY);
  const stat = await fileIo.stat(src.fd);
  const buffer = new ArrayBuffer(stat.size);
  await fileIo.read(src.fd, buffer);
  await fileIo.close(src);
  const out = await fileIo.open(dest,
    fileIo.OpenMode.CREATE | fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.TRUNC);
  await fileIo.write(out.fd, buffer);
  await fileIo.close(out);
  return dest;
}

用 PhotoViewPicker 挑图不需要申请 ohos.permission.READ_IMAGEVIDEO,Picker 返回的 URI 本身带临时读授权,所以这段拷贝是免权限的。整个 demo 的 module.json5 里 requestPermissions 一个都没写。

代价是沙箱里多一份图片副本,[1, 128] 的路径长度也要算着点。真机上 filesDir 是 43 个字符,加一个 19 字符的文件名正好 63。看着宽裕,但如果你的应用把图放在很深的子目录里、或者用原始文件名(用户能起出很长的名字),这个上限是会撞上的。

调用前把越界的图挡掉

官方对输入图像的约束是 100px < 高度 < 10000px、100px < 宽度 < 10000px、高宽比建议 10:1 以下(官方原文括号里补了一句"高度小于宽度的10倍")。这些条件不满足时,insertImage 不会给你"尺寸不合法"这种清晰原因,只会给通用 401 或者 1013100002 服务异常。

所以入库前用 imageSource 只读元信息,不解码像素:

// service/LibraryLoader.ets
// 调用前挡越界:返回空串表示可以入库,否则返回拒绝原因
static async validate(path: string): Promise<string> {
  if (path.length === 0 || path.length > MAX_PATH_LEN) {
    return '照片路径过长';
  }
  const source = image.createImageSource(path);
  try {
    const info = await source.getImageInfo();
    const w: number = info.size.width;
    const h: number = info.size.height;
    if (w <= MIN_EDGE || w >= MAX_EDGE || h <= MIN_EDGE || h >= MAX_EDGE) {
      return `照片尺寸 ${w}x${h} 超出支持范围`;
    }
    if (h > w * MAX_RATIO) {
      return `照片尺寸 ${w}x${h} 长宽比过大`;
    }
    return '';
  } finally {
    await source.release();
  }
}

getImageInfo() 拿的是文件头里的尺寸,成本极低。十二张的 validate() 全加起来,被算在那 5000 ms 里也只占几十毫秒。

注意这里返回的文案是"照片尺寸 40x30 超出支持范围"这种用户能看懂的话,不是"违反 [100,10000] 约束"。约束数字留在使用须知页里给开发者和高级用户看。

日期分组只在整组同地时才标地点

时间轴每组标题是"4月12日 周日 大理 · 洱海 3 张"。但 4月13日 那组只有"4月13日 周一 2 张"——因为那天上午在古城、下午在客栈阳台,硬贴一个地点是假信息。

// model/SearchStore.ets
private static bucket(items: LibraryItem[], sortByDay: boolean): DayGroup[] {
  const out: DayGroup[] = [];
  items.forEach((x: LibraryItem) => {
    const key: string = x.meta.day === '' ? ' ' : x.meta.day;
    let group: DayGroup | undefined = out.find((g: DayGroup) => g.day === key);
    if (group === undefined) {
      group = new DayGroup();
      group.day = key;
      group.place = x.meta.place;
      out.push(group);
    }
    group.items.push(x);
  });
  out.forEach((g: DayGroup) => {
    const first: string = g.items.length > 0 ? g.items[0].meta.place : '';
    const same: boolean = g.items.every((x: LibraryItem) => x.meta.place === first);
    g.place = same ? first : '';
  });
  if (sortByDay) {
    out.sort((a: DayGroup, b: DayGroup) => a.day.localeCompare(b.day));
  }
  return out;
}

这个 every 判断是后加的。最初版本直接取 group.items[0].meta.place,结果 4月13日 那组挂着"大理 · 古城",下面第二张却是客栈阳台拍的,看着就是 bug。UI 上"少说一个字段"比"说错一个字段"便宜得多。

同一套分组逻辑首页和结果页共用,只差一个 sortByDay:首页要按日期正排,结果页保持相似度次序、分组只用来标日期,不重排。

相似度降级成序数,只在结果页露一次

SearchStore 里两个静态方法负责这件事:

// 命中排名换成用户能读懂的措辞,原始 similarity 只进开发者信息页
static levelOf(rank: number): string {
  if (rank === 0) {
    return '最匹配';
  }
  if (rank < 3) {
    return '较匹配';
  }
  return '可能相关';
}

// 结果墙上的角标文案:按命中次序给措辞,不暴露原始相似度数值
captionOfPath(path: string): string {
  const hit: SearchHit | undefined = this.hits.find((h: SearchHit) => h.sandboxPath === path);
  return hit === undefined ? '' : SearchStore.levelOf(hit.rank);
}

前三张给"最匹配 / 较匹配",往后统一"可能相关"。这样切是因为上面测出来的 0.312 到 0.381 这个区间里,任何绝对阈值都是没有依据的,但"服务把它排在第一"这件事是确定的。

原始数值不是不给看,是挪到开发者信息页整屏列出来(前面那张截图)。同一份数据,两种呈现,各给各的读者。

照片墙为什么不用 Grid

结果九宫格最初一片空白。devecocli ui layout 看布局,Grid 节点在、子项也在,但 Grid 高度是 1px。

Grid 是可滚动容器,放进 Scroll 时父容器给不出确定高度,它就退化成"能滚就行",不按内容撑开。常规解法是显式算高度:

private gridHeight(): number {
  const rows: number = Math.ceil(this.store.hits.length / 3);
  return rows * 120 + (rows - 1) * 10;
}

这版我换了个思路:不写 Grid,直接按列数切成"行的数组",每行一个 Row。

// components/PhotoWall.ets
private rows(): LibraryItem[][] {
  const out: LibraryItem[][] = [];
  const size: number = this.cols > 0 ? this.cols : 1;
  for (let i = 0; i < this.items.length; i += size) {
    out.push(this.items.slice(i, i + size));
  }
  return out;
}

build() {
  Column({ space: this.gap }) {
    ForEach(this.rows(), (row: LibraryItem[], rowIndex: number) => {
      Row({ space: this.gap }) {
        ForEach(row, (item: LibraryItem) => {
          PhotoTile({
            item: item,
            side: this.side,
            caption: this.captionOf(item),
            onTap: (picked: LibraryItem) => {
              this.onTap(picked, this.items.indexOf(picked));
            }
          })
        }, (item: LibraryItem) => `${item.sandboxPath}_${item.ok ? 1 : 0}_${item.loading ? 1 : 0}`)
      }
      .width('100%')
      .justifyContent(FlexAlign.Start)
    }, (row: LibraryItem[], rowIndex: number) => `${rowIndex}_${row.length}`)
  }
  .alignItems(HorizontalAlign.Start)
  .width('100%')
}

好处是不用手算容器高度,也不会跟外层 Scroll 抢手势(用 Grid 还得配 enableScrollInteraction(false))。代价是它不是虚拟化列表,几千张图会一次性建出所有节点——那是另一个话题,demo 的十二张不受影响。

两个 keyGenerator 值得单独看一眼:行 key 是 ${rowIndex}_${row.length},砖 key 里塞了 ok 和 loading。因为 @Builder / 子组件的参数只在建立时求值一次,建库过程中某张图从 loading=true 变 false,如果 key 不变,ForEach 认为这一项没变,遮罩和转圈就不会撤。把参与渲染的状态编码进 key,是让这面墙逐张亮起来的关键。

列数按屏宽算:

// util/GridLayout.ets
// 平板横屏不把照片墙拉满整屏,手机竖屏也不会只剩两列
export function computeWall(uiContext: UIContext): WallMetrics {
  const widthPx: number = display.getDefaultDisplaySync().width;
  const vp: number = uiContext.px2vp(widthPx);
  const content: number = Math.min(vp - 32, CONTENT_CAP);
  const cols: number = Math.max(2, Math.min(6, Math.floor(content / TILE_TARGET)));
  const m = new WallMetrics();
  m.cols = cols;
  m.side = Math.floor((content - (cols - 1) * GAP) / cols);
  m.content = content;
  return m;
}

CONTENT_CAP 是 1000 vp。这台平板物理宽 2800 像素,不封顶的话照片墙会拉成一条横贯全屏的窄带,每行五张六张,看着像后台表格不像相册。封顶之后实际是四列。

状态文案必须走 @Trace,读普通字段的那一行永远不刷新

这是 V2 状态管理最阴的一个坑,我在首页踩了。

首页有一行"服务状态",最初写的是 this.service.isReady() —— TextSearchService 里的 ready 是个普通 boolean 字段,不在 @ObservedV2 类里。结果初始化明明成功了(init 耗时那行都从 0 变成 753 了),服务状态这一行死活停在"未初始化"。

原因是 V2 的依赖收集只认 @Trace 字段的读取。isReady() 是个普通类的方法,读的是普通字段,UI 节点构建时求值一次,之后没有任何东西会把它标脏。同一张卡片里 init 耗时 读的是 @Trace initMs,所以它刷新、旁边那行不刷新,看起来非常像"局部坏了"。

改成从 store 出文案:

// model/SearchStore.ets
indexStatusText(): string {
  if (this.isIndexing()) {
    return `正在建立搜索索引 ${this.indexedCount()}/${this.totalCount()}`;
  }
  if (this.totalCount() === 0) {
    return '相册还没有照片';
  }
  if (this.indexedCount() === this.totalCount()) {
    return `${this.totalCount()} 张照片已可以按内容搜索`;
  }
  return `${this.indexedCount()}/${this.totalCount()} 张已建立索引`;
}
// pages/HomePage.ets
// 状态文案必须走 store 的 @Trace;service.isReady() 读普通字段,这一行会永远停在初始值
Text(this.store.indexStatusText())

注意 indexStatusText() 本身也只是个普通方法,能刷新是因为它内部读的是 @Trace 字段(phase、library)。方法不是依赖,方法里读到的那个 @Trace 才是依赖。

顺带一条同源的坑:@Builder 的参数不建立依赖,所以"标签 + 值"这种两列布局做成子组件而不是 Builder。

输入法会往输入框里追加,不会替换

这条严格说是自动化测试的教训,但它改变了我对搜索页的设计。

用 devecocli ui text "落日" 跑多组查询时,这个命令是往已有内容后面追加,不是覆盖。第一组查完不显式清空,第二组就变成了"落日埃菲尔铁塔",返回 0 命中。我有一批"0 命中"数据是这么废掉的,重跑一遍才对上。

修法有两层。应用侧:搜索页把"最近搜过"做成可点的 chips,点一下是整串替换而不是追加,用户手动改词时长按选词也能覆盖。测试侧:退格键坐标写进脚本,每组查询前先按 N 次退格再输入,并且每组跑完 dump 一次输入框内容确认它真的等于预期字符串。

// pages/SearchPage.ets
private async run(q: string): Promise<void> {
  const text: string = q.trim();
  if (text === '') {
    this.store.lastError = '先说一句你想找什么,比如落日';
    return;
  }
  this.store.lastError = '';
  this.store.query = text;
  this.store.rememberQuery(text);
  await this.service.search();
  this.searched = text;
}

rememberQuery 只留最近六条、新词插到最前:

rememberQuery(q: string): void {
  const text: string = q.trim();
  if (text === '') {
    return;
  }
  const rest: string[] = this.recentQueries.filter((x: string) => x !== text);
  this.recentQueries = [text].concat(rest).slice(0, 6);
}

空查询在调用前挡掉,因为 search('') 到底返回空数组还是抛 401,取决于服务侧,不该交给它决定。

根容器:Navigation + AppStorageV2

Index.ets 只做三件事:挂 Navigation、注册路由表、用 @Provider 把 store 和服务实例发下去。

// pages/Index.ets
@Entry
@ComponentV2
struct Index {
  @Provider('store') store: SearchStore =
    AppStorageV2.connect(SearchStore, 'searchStore', () => new SearchStore())!;
  @Provider('service') service: TextSearchService = new TextSearchService();
  @Provider('pathStack') pathStack: NavPathStack = new NavPathStack();

  @Builder
  pageMap(name: string) {
    if (name === 'search') {
      SearchPage()
    } else if (name === 'detail') {
      DetailPage()
    } else if (name === 'album') {
      AlbumPage()
    } else if (name === 'devinfo') {
      DevInfoPage()
    } else if (name === 'notice') {
      NoticePage()
    }
  }

  aboutToAppear(): void {
    this.service.attach(this.store);
  }

  aboutToDisappear(): void {
    this.service.release();
    this.store.reset();
  }

  build() {
    Navigation(this.pathStack) {
      HomePage()
    }
    .navDestination(this.pageMap)
    .mode(NavigationMode.Stack)
    .hideTitleBar(true)
    .width('100%')
    .height('100%')
    .backgroundColor($r('app.color.page_background'))
  }
}

五个页面全走 NavDestination,首页是唯一不需要名字的路由根。hideTitleBar(true) 是因为标题栏由 HomePage 自己画("相册"加右上角"管理"),系统那条空标题在平板上会多占一行。

用 AppStorageV2.connect 而不是直接 new,是为了页面被系统回收重建时,已经建好的那份本地台账还在。

aboutToDisappear 里调 release()。要说明一句:release() 释放的是服务实例,不清特征库数据。下次冷启动 init() 之后之前入库的图仍然能检索到 —— 这也是上面"库外"那个分支存在的原因。要真清干净,得显式调 clearData()。

// service/TextSearchService.ets
release(): void {
  if (!this.ready) {
    return;
  }
  this.ready = false;
  textSearchImage.release().then((ok: boolean) => {
    hilog.info(DOMAIN, TAG, 'release ok=%{public}s', `${ok}`);
  }).catch((error: BusinessError) => {
    hilog.error(DOMAIN, TAG, 'release failed, code=%{public}d', error.code);
  });
}

不 await,因为退出路径上没必要卡这一帧。


把约束写进应用里

约束这么多,用户记不住,开发者也容易忘。管理页里一个"使用须知"入口,点进去是一个 NavDestination,十三条清单直接列出来:

// pages/NoticePage.ets
const LIMITS: string[] = [
  '接口起始版本 26.0.0,仅 Stage 模型,需 HarmonyOS 7 真机',
  'Core Vision Kit 不支持模拟器:模拟器无 NPU,AI 推理无法执行',
  '输入图像约束:100px < 高度 < 10000px,100px < 宽度 < 10000px,高宽比建议 10:1 以下',
  'imagePath 是应用沙箱路径,长度范围 [1,128];相册 URI 要先拷进沙箱,直接传 file://media 开头的路径抛 1013100001',
  'scope 长度 [1,32],只允许字母或数字:带下划线时 insertImage 抛 401,官方示例里的 default_scope 在本机不可用',
  'query 长度 [1,100],超出直接抛 401;纯字母或纯数字不报错但固定 0 命中,耗时也从约 20 ms 掉到 1~2 ms',
  'topKey 只是上限:实测传 5 和传 100 都返回同样的 5 条,传 0 也不会返回空,照样给 5 条',
  '多要素查询会改写排序:「海边的落日」命中 4 条,加上「和雪山」只剩 3 条,且雪山那张排到第一',
  '文档错误码表只列了 1013100001/2/3,但 scope 与 query 参数不合法实际抛的是通用 401 The parameter check failed.',
  '特征库由系统维护,应用只能 insertImage / deleteImage / clearData 三种方式改动',
  '同一用户不支持并发调用同一特性,重复调用返回系统繁忙',
  '能力仅在中国境内可用(港澳台除外)',
  '错误码 1013100001 无效图片路径,1013100002 服务异常,1013100003 能力已更新需先 clearData'
];

这类页面在演示和排障时都省事:现场有人问"为什么我这台跑不了""为什么我搜不到",让他打开这一页对着看就行。


完整 API 描述

归属与版本

项 值
Kit Core Vision Kit(基础视觉服务)
导入模块 @kit.CoreVisionKit
命名空间 textSearchImage
系统能力 SystemCapability.AI.Vision.VisionBase
模型约束 仅 Stage 模型
接口起始版本 26.0.0(六个方法全部同版本)
支持设备 Phone / Tablet / 2in1,均自 26.0.0 起
并发 不支持同一用户并发调用同一特性,同一进程重复调用返回系统繁忙
地区 仅中国境内(港澳台除外)
模拟器 不支持,官方原文"本Kit暂不支持模拟器"
数据归属 特征库由系统维护,应用侧不可导出、不可读回

类与方法

成员 签名 说明
init init(): Promise<boolean> 初始化文搜图服务,返回是否就绪;应用生命周期内一次
insertImage insertImage(imagePath: string, scope: string): Promise<boolean> 提取图片特征并写入指定作用域的索引
search search(query: string, scope: string, topKey?: number): Promise<ImageObject[]> 按文本语意在指定作用域检索,返回按相似度降序的列表
deleteImage deleteImage(imagePath: string, scope: string): Promise<boolean> 按沙箱路径删除单张图的索引
clearData clearData(): Promise<boolean> 清空本应用写入的特征数据
release release(): Promise<boolean> 释放服务实例,不清数据
ImageObject class ImageObject 检索结果条目,含 imagePath / scope / similarity 三个字段

入参与返回结构

类型 字段 必填 说明
insertImage 参数 imagePath 是 应用沙箱绝对路径,长度 [1, 128]。相册 URI 需先拷进沙箱,否则抛 1013100001
scope 是 作用域,长度 [1, 32],官方口径"支持字母或数字"。实测下划线不通过
search 参数 query 是 查询文本,长度 [1, 100],官方口径"不支持纯数字和纯字母,支持中文,拼接数字、字母或者符号"
scope 是 必须与入库时一致,否则检索不到
topKey 否 取值 [0, 100],默认 100。实测是上限不是配额,传 0 也返回全部命中
图像本身 尺寸 — 100px < 高度 < 10000px,100px < 宽度 < 10000px,高宽比建议 10:1 以下(官方注明指高度小于宽度的 10 倍)
ImageObject 返回 imagePath — 入库时传入的路径原样返回,用于反查应用侧记录
scope — 入库时传入的作用域
similarity — 语意相似度,取值 [-1, 1]。实测样本全部落在 0.312 到 0.381,且末位在多次运行间有抖动

错误码

错误码 官方描述 实测触发场景
1013100001 Invalid image path or size 传 file://media/... 相册 URI;传沙箱里不存在的路径。可稳定复现
1013100002 Service abnormal 服务侧异常的统一归口;本次未触发
1013100003 The capability has been updated 官方要求先 clearData() 再重新建库;本次未触发
401 The parameter check failed. 实测最高频。scope 含下划线时十二张全部抛此码;query 超过 100 字符时 search() 抛此码

这一行要特别说明:文档的错误码表只列了 1013100001/2/3 三个,但参数格式不合法走的是通用 401,不在这张表里。所以 catch 里只按 1013xxxxxx 前缀判断会漏掉最常见的那类失败。

这类失败怎么呈现给用户,是我这轮改得最多的一处。最初版本只有一份 lastError,用户界面上那行红字因此长这样:

insertImage(IMG_20260412_183210.jpg) 失败:401 The parameter check failed.(耗时 407 ms)

对一个只是想找照片的人来说,这句话里没有一条信息是他能用的。现在拆成两份,一份给人,一份给机器:

// service/TextSearchService.ets
// lastError 是给用户看的一句话,接口名与错误码只进 lastErrorRaw 和日志
private fail(what: string, friendly: string, err: BusinessError, ms: number): void {
  this.store.lastError = friendly;
  this.store.lastErrorRaw = `${what} 失败:${err.code} ${err.message}(耗时 ${ms} ms)`;
  this.store.phase = AppPhase.FAILURE;
  hilog.error(DOMAIN, TAG, '%{public}s failed, code=%{public}d, msg=%{public}s',
    what, err.code, err.message);
}

五个调用点各配一句话:init 失败是「文搜图服务没连上,换台真机再试」,检索失败是「这次没查成,换一句描述再试」,入库失败是「有一张照片没能加入索引,可在管理页重建」,移除和清空各一句。同一句 401 在两个页面上是两种长相。

搜索页提交了一个超过 100 字的查询:输入框里是一长串中文,下方一行红字只有「这次没查成,换一句描述再试」,再下面的空结果标题把查询语截断成 18 个字加省略号

开发者信息页最底部的最近一次错误卡片:search("完整查询语") 失败:401 The parameter check failed.(耗时 0 ms)。接口名、错误码、耗时只在这一页出现

空结果标题那句也顺手做了截断:查询语上限 100 字,全塞进标题里会变成一大坨把整屏占满的代码级文本,brief() 只留前 18 个字加省略号,完整说法仍然在输入框里。

官方确认 vs 实测补充

结论 依据
六个方法的签名与 @since 26.0.0 官方 API 参考
输入图像 100px < 边长 < 10000px,高宽比建议 10:1 以下 官方约束与限制
imagePath 长度 [1,128]、scope 长度 [1,32]、query 长度 [1,100]、topKey [0,100] 默认 100、similarity [-1,1] 官方 API 参考参数表
不支持同一用户并发调用同一特性、不支持模拟器、仅境内可用 官方约束与限制
query 不支持纯数字和纯字母 官方 API 参考("不支持"的具体表现文档未定义)
scope 含下划线时 insertImage 抛 401,官方开发指南示例值 default_scope 在本机不可用 实测补充
纯字母 / 纯数字 query 不抛错,返回空数组,耗时 1~2 ms(正常中文查询 8~15 ms) 实测补充
含空格的纯字母(a cat)同样 0 命中,但耗时回到 8 ms,耗时不能当作"是否走了模型"的判据 实测补充
参数不合法抛通用 401;路径不合法(相册 URI、不存在的路径)抛 1013100001,可稳定复现 实测补充
topKey 传 0 / 5 / 100 返回条数相同,它是上限不是配额 实测补充
多要素查询改写命中集合与排序:「海边的落日」4 张,「海边的落日和雪山」3 张且雪山那张以 0.341485 排到第一 实测补充
实测相似度全部落在 0.312577 ~ 0.381055,未出现负数;末位在多次运行间抖动约 0.0002,次序稳定 实测补充(十二张库、十一组有命中的查询共二十三次返回)
init() 753~781 ms;单张 insertImage 374~524 ms;十二张建库 4959~5252 ms;search() 稳态 8~15 ms,界面单次点查 17~39 ms,唤醒后首查 133 ms 实测补充(同一台 MatePad Pro)
沙箱 filesDir 实测 43 字符,加 19 字符文件名共 63 字符,距 [1,128] 上限尚有空间 实测补充
release() 不清特征数据,跨启动索引仍在;要清干净必须 clearData() 工程实践补充
同一 scope 下重复 insertImage 同一沙箱路径不会产生重复索引条目 实测补充

还能往哪些场景走

旅行相册检索是最容易演示的一个。这个能力的通用价值在于:给一批没有文字标签的图,加上一层可以用自然语言访问的索引。

  • 个人相册的语义搜索。 用户拍完照不会打标签,但会记得"那天下雨的街"。接入成本就是这个 demo 的建库加检索两条链路。要注意建库是每张 400 多毫秒的重活,得做成后台增量,别在用户搜的时候现建。
  • 电商 / 内容库的素材检索。 商品图、素材图按描述召回,配合 scope 做类目隔离 —— 一个类目一个作用域,检索时只扫自己那一片。
  • OCR 之上再做一层语义。 同属 Core Vision Kit 的 textRecognition 能读出图里的文字,但读不出"这是一张海边落日"。两者互补:文字匹配走 OCR,内容匹配走文搜图,UI 上合成一个搜索框。
  • 截图与文档的召回。 聊天记录截图、票据、白板照片,按"上个月那张写着预算的白板"这类描述召回。这条路径上 query 的"不支持纯数字"是个真限制,编号类检索要另想办法。
  • 应用内图库的推荐位。 官方适用场景那段就写了"内容推荐"。用当前上下文文本作为 query,去自有图库召回配图。

三条共性提醒:scope 是字母数字的短标识,别把用户 ID 原样塞进去(可能含下划线,直接 401);同一用户不支持并发,多入口要收敛到一个串行队列;换系统版本或能力升级后可能撞上 1013100003,那时必须 clearData() 重建,所以本地台账一定要留得住原始路径,否则索引清了就没法重建。

还有一条是这次重做 demo 才想明白的:similarity 这种不能横比的数值,决定了它不能直接进 UI。凡是打算把这个能力做进产品,先想好怎么把它降级成序数(最匹配 / 较匹配 / 可能相关)、分组(同一天、同一个地方),再想界面。反过来先画界面再塞数据,就会做出满屏 0.33 的表格。


官方文档

留言讨论

正在加载评论…