RankGuard 最近换了一版文搜图索引,人工体验看起来更“聪明”:搜“雨天红伞”,第一张确实是红伞;搜“窗边的猫”,相似度也比旧版高。可灰度当天,测试同学发来一句很难回答的话:“有些词结果更准,有些词只是第一张换了,我们怎么证明整体没有退步?”

只盯相似度不够。模型升级后,分数分布可能整体漂移,0.82 和旧版的 0.82 甚至不再等价;只看第一张也不够,用户经常会翻到前十张。最后我没有继续截图对比,而是整理了 48 条 Golden Query,把相关图片分成 0、1、2、3 四级,固定数据集版本,再用 Recall@10 和 NDCG@10 做发布门禁。

一、一次“结果看着不错”的升级,差点混过发布

旧索引基线记为 vision-text-7.1,候选版本为 vision-text-7.2。最初的抽查只有六个词,五个词的首图更符合直觉,于是大家倾向于直接上线。问题出在“雨夜公交站”:候选版本把一张白天公交站排到第二位,而真正的雨夜照片掉到了第八位。

如果只算 Top1,这条查询会被判失败;如果只看“前十是否找到”,它又算成功。两种判断都不完整。Recall@10 回答的是相关图片有没有被召回,NDCG@10 还会考虑相关程度和排序位置:高相关照片越靠前,得分越高。

本轮批次固定为 RG-1002-0512,数据集版本 gallery-golden-2026.10.02-r3,共 48 个查询,每条最多返回 10 张。发布阈值不是“候选必须每项都更高”,而是 Recall@10 不能下降超过 0.010,NDCG@10 不能下降超过 0.015,且不能出现未解释的结果抖动。

二、Golden Query 不是一份关键词列表

最开始我把查询和“期望文件名”写在 JSON 里,很快就发现这会把测试做死。一张海边日落同时适合“橙色天空”“海边散步”“落日背影”,相关程度也不一样。Golden 集最终改为查询、scope、相关性分级、场景标签和审阅版本五部分。

下面的结构解决的是“同一张图对不同查询的相关性不相同”。grade 取 0~3:3 是核心命中,2 是明显相关,1 是弱相关,0 是负样本。数据只引用稳定的 assetId,不把沙箱路径当主键。

export interface GoldenJudgement {
  assetId: string
  grade: 0 | 1 | 2 | 3
}

export interface GoldenQuery {
  queryId: string
  text: string
  scope: string
  tags: string[]
  reviewedAt: string
  judgements: GoldenJudgement[]
}

export const GOLDEN_SET_VERSION = 'gallery-golden-2026.10.02-r3'
export const TOP_K = 10
export const RECALL_DROP_LIMIT = 0.010
export const NDCG_DROP_LIMIT = 0.015

审阅人看到的是缩略图和查询,不看到模型版本,避免“新模型应该更好”的心理暗示。新增照片不会直接进入 Golden 集;先进入候选池,完成双人标注后才提升数据集版本。否则同一批次的基线与候选实际上在跑不同题目,指标差异就失去解释力。

删除资源也有规则。如果产品库里删掉一张 Golden 图片,门禁不悄悄忽略,而是把查询标记为 DATASET_INVALID。数据缺口要先修复,再比较模型,不能把坏题目当成模型退步。

三、搜索适配层只负责得到稳定的 TopK

Core Vision Kit 的 textSearchImage.search(query, scope, topKey) 会返回图片路径、scope 和相似度。回归工具不直接依赖页面状态,而是通过一个适配层完成初始化、查询、路径到 assetId 的映射和资源释放。

这段代码解决的是“页面切走或批次取消后,迟到结果仍写入当前报告”。每次运行生成 generation,只有同代结果才能进入指标计算;aboutToDisappear() 里递增代际并释放服务。

import { textSearchImage } from '@kit.CoreVisionKit'

export class SearchProbe {
  private generation: number = 0
  private ready: boolean = false

  async open(): Promise<void> {
    this.generation++
    this.ready = await textSearchImage.init()
    if (!this.ready) throw new Error('TEXT_SEARCH_INIT_FAILED')
  }

  async search(query: GoldenQuery): Promise<string[]> {
    if (!this.ready) throw new Error('PROBE_NOT_READY')
    const runGeneration = this.generation
    const rows = await textSearchImage.search(query.text, query.scope, TOP_K)
    if (runGeneration !== this.generation) return []
    return rows.map((row) => assetCatalog.idOf(row.imagePath))
  }

  async close(): Promise<void> {
    this.generation++
    this.ready = false
    await textSearchImage.release()
  }
}

这里故意不把 similarity 放进质量指标。它仍会写入诊断快照,帮助判断分数分布是否变化,但 Golden 判定依赖人工相关性等级。候选模型可以把所有分数都抬高,却不代表排序更好。

资源释放也不能省。48 条查询会连续调用服务,页面退后台时停止当前批次,已完成的查询保存为临时报告,未完成部分下次从查询 ID 续跑。重复调用 init() 前必须确认上一次已经 release(),否则测试工具本身会制造错误状态。

四、NDCG 的价值在于它知道“相关也分轻重”

Recall@10 的分子是前十中命中的相关资源数,分母是 Golden 集里所有 grade 大于 0 的资源数。NDCG 则先计算 DCG:位置越靠后折扣越大,grade 越高收益越高;再除以理想排序的 DCG,得到 0~1 的归一化值。

下面的实现解决的是指标口径不透明的问题。每条查询都输出 recallAt10、ndcgAt10 和前十 assetId,报告能够追溯到具体排序,而不是只剩一个总分。

function dcg(grades: number[]): number {
  return grades.reduce((sum, grade, index) => {
    const gain = Math.pow(2, grade) - 1
    return sum + gain / Math.log2(index + 2)
  }, 0)
}

export function scoreQuery(query: GoldenQuery, rankedIds: string[]): QueryScore {
  const gradeMap = new Map(query.judgements.map((item) => [item.assetId, item.grade]))
  const topGrades = rankedIds.slice(0, TOP_K).map((id) => gradeMap.get(id) ?? 0)
  const relevantTotal = query.judgements.filter((item) => item.grade > 0).length
  const hitCount = topGrades.filter((grade) => grade > 0).length
  const idealGrades = query.judgements.map((item) => item.grade)
    .sort((a, b) => b - a).slice(0, TOP_K)
  const ideal = dcg(idealGrades)

  return {
    queryId: query.queryId,
    recallAt10: relevantTotal === 0 ? 1 : hitCount / relevantTotal,
    ndcgAt10: ideal === 0 ? 1 : dcg(topGrades) / ideal,
    rankedIds: rankedIds.slice(0, TOP_K)
  }
}

零相关查询单独放在负样本组,不参与这里的平均分,避免用大量“什么都搜不到”的查询把总分冲高。负样本关注的是误召回数量和最高相似度,属于另一条门禁。

指标计算必须固定排序。相似度相同的结果用 assetId 做二级排序,避免底层返回顺序不稳定导致快照反复变化。这个细节不影响用户体验,却会直接决定 CI 报告能否重复。

五、门禁不只看平均值,还要找局部坍塌

候选版最后的汇总看起来不错:Recall@10 从 0.938 升到 0.944,变化 +0.006;NDCG@10 从 0.912 降到 0.908,变化 -0.004,仍在 0.015 阈值内。如果只看平均值,已经可以放行。

我又加了单查询规则:任何 query 的 NDCG 下降超过 0.12 都算 LOCAL_COLLAPSE。因为平均值会把一条严重退步藏在几十条轻微提升里。第一次跑时,“雨夜公交站”下降 0.19,因此状态从 EVALUATING 进入 DRIFT_BLOCKED。

排查后发现新索引少插入两张夜景图,问题不在模型,而在构建候选 scope 时发生了资源遗漏。修复索引清单后再次运行,局部坍塌为 0,未解释抖动为 0,48 条全部完成。

六、Hvigor 只消费报告,不重跑模型

文搜图依赖设备能力,构建机不一定能执行。我的处理是让真机/模拟器测试页生成签名报告,Hvigor 在 release 前验证报告版本、数据集哈希、模型标识、完成时间和阈值结论。报告过期、批次未完成或存在局部坍塌,都直接阻断。

这段任务解决的是“拿上一次绿灯给这一次构建背书”。候选版本必须与报告里的 candidateModel 完全一致,报告时间不能早于当前索引产物。

node.registerTask({
  name: 'rankQualityGate',
  run: () => {
    const report = readReport('build/reports/rank-RG-1002-0512.json')
    assertEqual(report.datasetVersion, 'gallery-golden-2026.10.02-r3')
    assertEqual(report.candidateModel, 'vision-text-7.2')
    assertEqual(report.completedQueries, 48)
    assertLessOrEqual(report.recallDrop, 0.010)
    assertLessOrEqual(report.ndcgDrop, 0.015)
    assertEqual(report.localCollapseCount, 0)
    assertEqual(report.unexplainedChanges, 0)
    console.info('RELEASE_READY batch=RG-1002-0512 recall=0.944 ndcg=0.908 queries=48/48')
  }
})

门禁中的 recallDrop 和 ndcgDrop 取下降幅度,提升时按 0 处理,避免正负号判断写反。报告原始 delta 仍保留 +0.006 与 -0.004,页面展示更直观。

如果 Core Vision Kit 返回能力更新错误,测试页不会自动清库后继续,因为那会改变本轮数据集。它把批次标记为 CAPABILITY_UPDATED,由操作者清理、重建索引并生成新报告。发布门禁最怕“失败后偷偷换环境再跑”。

七、最终页面不是排行榜,而是一张发布证据

最终运行页固定显示批次 RG-1002-0512、数据集 gallery-golden-2026.10.02-r3、模型 vision-text-7.2、查询 48 / 48、TopK 10。Recall@10 为 0.944,NDCG@10 为 0.908,变化分别为 +0.006 和 -0.004,局部坍塌与未解释变化都为 0。

状态机走完 BASELINE → EVALUATING → RELEASE_READY,构建退出码为 0。截图时间统一为 05:12;HiLog 同时记录数据集哈希和报告文件名,避免只凭 UI 上的一枚绿色标签做判断。

八、这套方法真正约束的是发布判断

Golden Query 不是越多越好。48 条能覆盖雨天、夜景、人物、宠物、票据、食物和旅行等主场景,先把标注质量做扎实,比堆 500 条含糊查询更可靠。每次产品新增一类真实搜索失败,再把它沉淀为回归样本。

Recall 与 NDCG 也不是通用真理。若产品只展示一张图,应提高 Top1 指标权重;若用户会浏览长列表,前十排序更有意义。阈值要结合业务损失设定,不能从别的项目抄一个数字。

这次改造最大的变化,是把“结果看起来还行”变成了可追溯的发布结论。模型可以升级,索引可以重建,分数分布也可以变化,但数据集版本、相关性判断、局部退步和生命周期证据都必须留下。文搜图真正进入产品后,稳定发布比一次漂亮 Demo 更难,也更值得工程化。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐