找一张"去年在洱海边上拍的落日",在相册里是这么回事:
- 按日期翻,四月十二号那几张挨个点开看;
- 搜文字,能命中的只有文件名里真写了"落日"的图,而相机给的文件名是
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暂不支持模拟器"。我把这一段截全了:

原因是特征提取和图文匹配都在 NPU 上跑,模拟器没有 NPU。所以本文所有数字都来自一台真机:HUAWEI MatePad Pro,序列号 59HYD25A17202258,HarmonyOS 7.0.0.109,分辨率 2800 x 1840,USB 连接。
先看效果
首页是一条按日期分组的时间轴
刚打开时相册是空的。这一屏没有任何技术字段,就一句话加两个入口:

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

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

往下翻是十月国庆那次:

注意 4月13日 和 10月1日 这两组只有日期没有地点,因为那两天的照片不在同一个地方拍的。这个细节后面代码里会讲。
搜索页先给说法,再给结果
点首页那个搜索条进来。没搜之前它不空着,而是把相册里真实存在的画面写成说法摆在下面:

点"落日",五张:

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

这一屏也没有相似度。想看得点右上角"技术信息"。
技术数据都在开发者信息页
详情页右上角进去,第一屏是服务和调用的原始数值:

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

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

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

整个应用里没有一处 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):

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

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

也就是说它确实读到了"雪山"这个要素,并且给了它最高权重,同时把"落日"里的一张挤了出去。这跟"整句一个向量、多要素会落空"是两种行为。同样,"猫"命中 1 张,"橙色的小猫"也命中 1 张(0.330617),加了定语没落空。
能用的结论是:多要素查询会同时改变命中集合和排序,且结果条数可能变少。它不是 AND 交集,也不是简单的整句向量。查询词仍然建议短、单一主题,但理由不是"多了就搜不到",而是"多了你没法预测它怎么权衡"。
纯字母和纯数字不报错,但固定 0 命中,而且明显更快。 官方对 query 的描述是"不支持纯数字和纯字母,支持中文,拼接数字、字母或者符号"。"不支持"没说是抛错还是返回空。实测:2026 用 2 ms、sunset 用 1 ms 返回空数组,而正常中文查询要 8 到 15 ms。快到像是服务侧在参数校验阶段直接短路,没走模型。
有个反例值得记:a cat 也是纯字母(中间一个空格),返回 0 命中但花了 8 ms,跟正常中文查询一个量级。所以"快"不是"纯字母"的可靠信号,别拿耗时去反推服务侧走没走模型。
工程上该做的是前置判断:查询串里一个汉字都没有,就直接提示"试试用中文描述画面",省一次没意义的调用。demo 里那个空结果页也给了出口:

四条失败路径
一、作用域里带下划线,十二张全部 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 字,全塞进标题里会变成一大坨把整屏占满的代码级文本,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 的表格。


留言讨论
正在加载评论…