语义代码检索 · 第 9 章 评测检索质量

语义代码检索 · 第 9 章 评测检索质量

章节摘要：全书最后一章，给检索装仪表盘——7.4 的肉眼扫描到此升级为指标化闭环。9.1 三个指标的纯 Python 实现：MRR（平均倒数排名，第一个相关结果排得越前越好——Agent 单步导航的主指标）；Recall@K（前 K 结果覆盖了多少金标——上下文组装场景的主指标）；nDCG（折损累计增益归一化，让三级相关度金标——精确命中 3 分、同文件 2 分、相关模块 1 分——全部参与排序评价）。指标公式与通用 IR 评测的系统性讲解详见 《利用 Zvec 实现完整的 RAG 技术》第 7 章，本节聚焦代码检索场景的用法与分级金标。9.2 评测集构造：查询从三处来（6.3 的工具调用日志、开发者访谈、git 历史弱标注），金标双人标注加仲裁、指向 4.2 稳定 chunk ID；方法论详见《Evals 实战》第 3 章。9.3 迭代优化循环：evaluate.py 跑评测集出三指标、记 history；纪律是一次一变量、全量评测、结果留档；坏例归因流程把 7.4 的排查表指标化；回归护栏守住每一次改动。全章立场：没有评测集，调参是玄学；有了评测集，调参是实验。

学习目标

阅读完本章，你应当能够：

1. 手算并编程计算 MRR、Recall@K、nDCG，说清各自适配的场景；
2. 设计三级相关度金标，并解释"金标指向 chunk ID 而非行号"的原因；
3. 从查询日志、访谈、git 历史三个来源构造评测集；
4. 运行 evaluate.py 完成基线、单变量改动、对比归因、保留或回滚的完整循环；
5. 设置回归护栏，把评测变成 CI 的一道门。

核心概念速览

（文字流程图）
E ──▶ "9.1 三指标·MRR · Recall@K · nDCG"
"9.1 三指标·MRR · Recall@K · nDCG" ──▶ "9.3 迭代循环·基线→单变量→全量评测→归因→保留/回滚"
"9.3 迭代循环·基线→单变量→全量评测→归因→保留/回滚" ──回归护栏──▶ history.jsonl 趋势
​

一句话金句：没有评测集，调参是玄学；有了评测集，调参是实验。

子章节导航

9.1 检索指标：MRR、nDCG 与 Recall

三个指标的定义、手算示例与纯 Python 实现；三级相关度金标；场景—指标选择表。

9.2 构造评测集：查询与金标对

查询三来源（日志/访谈/git 弱标注）；三级金标与标注纪律；评测集的规模、配比与版本化。

9.3 迭代优化循环

evaluate.py 完整实现；一次一变量的纪律；坏例归因流程；回归护栏与调参 playbook。

本章你将动手完成（跟做清单）：

• 手算并运行 metrics.py 的三指标，核对手算值；
• 造 30~50 条带三级金标的评测集（9.2）；
• 完成一次"单变量改动→全量评测→对比"的循环（9.3）。

子章节之间的逻辑关系

9.1 指标（尺子：什么算"好"——三个指标各盯一种使用场景）
   │
   ▼
9.2 评测集（被测物：拿真实分布的查询与可信金标去量）
   │    尺子和被测物互为前提：指标定义金标分级，金标决定指标可算
   ▼
9.3 循环（用法：基线→单变量→全量评测→归因→保留/回滚，护栏防退化）
   │
   └──► 全书管线闭环：切分→嵌入→索引→混合→重排→改写→评测
        评测反哺每一环的参数——这就是"检索系统不是调出来而是测出来的"
​

前置知识与后续延伸

前置知识：7.3 的 Retriever（被测对象）；7.2 的 metas.jsonl 与稳定 chunk ID（金标对齐键）；2.3 节（本书第一次接触 Recall@K 与 MRR 的地方——本节把公式补全）；7.4 的扫描表（肉眼版，本章是其指标化）。与姊妹教程的分工：通用 IR 指标与混合检索评测详见 《利用 Zvec 实现完整的 RAG 技术》第 7 章；评测集构造的通用方法论详见《Evals 实战》第 3 章——本章只讲代码检索特有：分级金标、chunk 级对齐、Agent 日志挖查询。

为后续奠定基础：本章是全书的收口——评测循环转起来之后，第 2~7 章的每个部件都进入了持续可优化的状态；附录 C 的练习题里有两题（弱标注、消融）是本章循环的实战延伸。