用户说“找那张下雨天的红伞照片”，检索框里可能同时包含物体、场景和天气。把所有词连成一句话交给模型，是合理的起点，但还会遇到另一种情况：照片确实有红色雨伞，石板街道却只占画面很小的一部分，一次查询的排序没有把它排在前面。此时追加一个阈值，可能让用户以为“图库里不存在”。本文讨论的是已经建立检索索引之后，怎样合并两条描述的候选顺序。业务侧并不训练图像模型，也不把 RRF 分数说成模型置信度。工程重点是一条可追溯的排序协议：同一个 scope、独立查询、保留名次、去重融合，再向用户解释结果来自哪些描述。## 一、先把“两个描述”与“两个过滤条件”分开示例项目叫 QueryWeave，页面为 QueryMergePage，使用相册业务范围 street2026，两条描述分别是“红色雨伞”和“石板街道”。每条查询限制请求返回 topKey = 4 个候选；这里的 4 是单次检索上限，不是合并结果的精确数量。最后呈现多少条，要看两个列表有多少重复图。一个容易混淆的地方是“同时命中”并不是“两个条件绝对为真”。Core Vision Kit 的 textSearchImage.search(query, scope, topKey) 返回图像路径、所属范围以及相似度。它能帮助寻找相近内容，但不会证明某个对象、场景或者事实一定存在。将两条结果取交集，只能说明它们分别进入了两次召回列表；如果其中一条查询漏检，交集甚至比原始检索更差。所以 Demo 先给用户显示融合排序，再把“双描述命中”当成辅助标志。不使用两个相似度的平均值，因为不同查询的分数缺乏天然可比的业务校准。最终的解释可以写成“这张图同时出现在两条描述的候选中”，不能写“模型判定完全匹配”。官方文档显示，该能力属于 @kit.CoreVisionKit 的 textSearchImage，相关接口标注从 26.0.0 起支持，且限定 Stage 模型。文章题目中使用 HarmonyOS 7 技术主题，不代表所有名为 HarmonyOS 7 的设备都自动满足该接口的设备、SDK 与能力条件。接入前仍需以目标设备和 SDK 的能力声明检查。## 二、用排名而不是相似度做融合先假设演示用例返回两组人工构造的候选名单。第一组按顺序为 IMG-014、IMG-009、IMG-032、IMG-037，第二组依次为 IMG-014、IMG-032、IMG-009。第二组返回了 3 张图，没有填满单次 topKey 上限。两组来自同一 scope。IMG-014 排名都是第一，因此融合分数较高；IMG-009 与 IMG-032 一前一后，按当前规则可能出现同分，需要确定性的次级排序。倒数排名融合（Reciprocal Rank Fusion）可以用于这种需求。这里选用 k = 60 作为应用侧演示参数，其公式是把每条查询中的 1 / (k + rank) 加起来。这个常数不来自华为的模型接口，也不是系统推荐的阈值。它只决定不同名次被平滑后的相对权重，换设备、换图库不应把它当作固定准确率指标。下面的纯 ArkTS 函数只接受官方返回对象所需的三个字段。先用 scope + imagePath 做去重身份，再累计查询贡献并记录每条查询的名次。这里刻意保留原图路径，不用数组索引充当身份，避免排序变化后把另一张图认成同一张。arktsinterface RankedImage { imagePath: string; scope: string; similarity: number;}interface FusedHit { imagePath: string; scope: string; score: number; matched: number; ranks: number[];}function fuseRankings(groups: Array<Array<RankedImage>>, k: number = 60): FusedHit[] { const seen: Map<string, FusedHit> = new Map(); groups.forEach((group: RankedImage[]) => { group.forEach((hit: RankedImage, index: number) => { const key = `${hit.scope}|${hit.imagePath}`; let row: FusedHit | undefined = seen.get(key); if (!row) { row = { imagePath: hit.imagePath, scope: hit.scope, score: 0, matched: 0, ranks: [] }; seen.set(key, row); } row.score += 1 / (k + index + 1); row.matched += 1; row.ranks.push(index + 1); }); }); return Array.from(seen.values()).sort((x: FusedHit, y: FusedHit) => y.score - x.score || y.matched - x.matched || x.imagePath.localeCompare(y.imagePath));}对演示名单进行手工计算：IMG-014 为 2/61 ≈ 0.0328，IMG-009 和 IMG-032 都是 1/62 + 1/63 ≈ 0.0320。同分时以路径字典序兜底，保证测试录像和问题复现的顺序可比较。IMG-037 只在第一组出现，最终分数较低。0.0328 不是 3.28% 的匹配概率，也不能按这个数字来发放业务权益。## 三、服务层只负责取候选，解释层才决定展示项目结构可以保持简单：pages/QueryMergePage.ets 负责入口和状态，service/SearchService.ets 负责调用能力，model/RankFusion.ets 承担纯排序逻辑。另存一份图片业务映射，用来把沙箱路径转换为 UI 的资源名称和可访问展示路径。系统接口并不会帮应用保存“IMG-014”这样的产品编号。下面的服务代码展示对两条查询逐次检索。使用逐次 await 的目的不是性能最优，而是让错误属于哪条描述更容易诊断，并避免在示例中引入并行初始化、释放的额外复杂度。对查询文本先做输入检查；文档规定长度 1～100，不能只有字母或数字，scope 长度为 1～32 且由字母数字构成。实际产品还应对复杂输入、超长文本以及业务字典做更细的提示。arktsimport { textSearchImage } from '@kit.CoreVisionKit';class SearchService { async run(queries: string[], scope: string): Promise<FusedHit[]> { if (queries.length < 1 || queries.length > 5 || !/^[A-Za-z0-9]{1,32}$/.test(scope)) { throw new Error('搜索描述或范围不符合业务限制'); } for (const q of queries) { if (q.trim().length < 1 || q.length > 100 || /^[A-Za-z0-9]+$/.test(q.trim())) { throw new Error('搜索描述不满足接口输入条件'); } } const ready = await textSearchImage.init(); if (!ready) { throw new Error('文搜图分析器初始化失败'); } try { const groups: Array<Array<RankedImage>> = []; for (const query of queries) { groups.push(await textSearchImage.search(query.trim(), scope, 4)); } return fuseRankings(groups, 60); } finally { await textSearchImage.release(); } }}这段代码刻意把 init() 和 release() 放在同一个所有权边界：仅适用于服务由当前动作独占的最小 Demo。如果应用中搜索页和相册页共享同一分析器，就不能在任意一次查询完成时直接释放；那要另做共享租约和在途调用排空。官方 clearData() 是清除全部索引数据的维护接口，也不应拿来当某次检索失败的普通重试按钮。日志最好只记录查询数量、scope、耗时区间、返回数量和错误码。原始关键词与本地图片路径都可能包含个人信息，不应无条件上报生产日志。演示图里即使出现 IMG-014，也只是业务层替代 ID，并非 SDK 自动生成的真实任务 ID。## 四、把用户能理解的证据放在卡片里页面可以显示两枚描述标签、一行“融合分数仅用于排序”的提示，以及每张图自己的名次信息。第一条显示 IMG-014、rank (1,1)、RRF 0.0328 和“双描述命中”；第二条为 IMG-009、rank (2,3)、RRF 0.0320；第三条为 IMG-032、rank (3,2)。这是人工样例数据，目的是约束页面设计和测试断言，不是设备上实测的相似度。为了不让异步操作覆盖最新页面，结果提交还需要一个业务代际值。新的搜索动作增量更新 requestSeq，旧动作完成时如果版本对不上，就不把结果写进当前 @State。这只是应用层状态保护；它并不取消模型内部已开始的计算，也不应被误解成接口自带取消能力。arkts@Entry@Componentstruct QueryMergePage { @State status: string = '就绪'; @State results: FusedHit[] = []; private requestSeq: number = 0; private service: SearchService = new SearchService(); private async search(): Promise<void> { const seq = ++this.requestSeq; this.status = '搜索中'; try { const rows = await this.service.run(['红色雨伞', '石板街道'], 'street2026'); if (seq !== this.requestSeq) { return; } this.results = rows; this.status = `已融合 ${rows.length} 条候选`; } catch (_error) { if (seq === this.requestSeq) { this.status = '搜索失败，请检查输入与能力状态'; } } } aboutToDisappear(): void { this.requestSeq++; } build() { Column({ space: 12 }) { Text('QueryWeave · 多描述搜图').fontSize(22) Button('开始搜索').onClick(() => { void this.search(); }) Text(this.status) List() { ForEach(this.results, (item: FusedHit) => { ListItem() { Text(`${item.matched} 条描述命中 · RRF ${item.score.toFixed(4)}`) } }, (item: FusedHit) => `${item.scope}|${item.imagePath}`) }.height('70%') }.padding(16) }}这种写法要注意一件事：requestSeq 能拦住迟到的 UI 写入，却无法保证同一个共享底层引擎的释放安全。生产环境应该让分析器生命周期独立于页面生命周期，另给查询增加可观测的业务请求号。示例页为说明状态策略而简化了搜索控制器，不代表已经处理了全部多页面并发路径。## 五、验收不看“命中漂亮”，先看错误能否解释一个可执行的最小测试表至少包含四类输入。第一类是两条查询完全不重合，页面可以列出各自候选，但不能打上“双描述命中”；第二类是同一张图在两条列表中位置相反，需要验证 RRF 加分与去重数量；第三类是两条结果分数相同，用路径作为稳定兜底，不要让同分结果每次乱跳；第四类是用户连续输入或离开页面，检查旧结果是否能够被阻断。还要测失败：init() 返回 false、搜索抛异常、scope 非法、服务在运行过程中异常，以及业务记录指向的图片已经不可读。对不可读图片，UI 应当改为占位卡并提供“重新建立索引”的指引；不能仅凭模型返回过路径就说文件现在仍存在。对于能力更新类异常，按官方文档和业务数据重建方案专门处理，而不是吞掉错误继续显示过期列表。结果判断：当前只完成了可审计的设计、代码片段和人工数据推演，并未宣称在 DevEco Studio 编译通过，也未声称在真实设备产生截图或具体召回率。需要进入产品前，应增加分描述命中率、首屏等待时间、错误分布和人工误命中复核记录，再决定是否将“多描述融合”设为默认模式。## 六、适用范围与最后的取舍这套融合适合描述由几个独立线索构成、且用户更在意找全候选的场景，如素材管理、私人相册检索和编辑选图。它也可能把两组各自相关、但整体不相关的照片一起推上来，因此不能替代复杂自然语言一次性查询。更稳妥的产品方案是把“整体描述”和“分描述融合”作为两个可比较的检索策略，通过真实样本来做选择。如果只能留一个工程原则，我会留给解释性：索引负责产生候选，RRF 负责合并候选，业务负责说明“为何出现”，用户仍然拥有最终判断权。把这三层混成一个看似精确的百分比，比搜不到一张图更容易产生误导。> 资料核对：华为官方 textSearchImage API，检索时页面显示更新时间 2026-09-04。本文使用已确认存在的 init/search/release，RRF、FusedHit 与 requestSeq 属于应用层实现。所有界面及 HiLog 为合成演示，不是实测证据。