从零到一搭建企业级智能问答系统：Ch11 ·大模型调参与效果评测

改一行配置，怎么知道它变好了：检索评测的黄金集、指标与门禁

一、同一个"没命中"，是两种完全相反的故障

你把 top-k 从 5 调到 10，看了一圈，说"好像好点了"。

但如果答案根本没被召回到，调 top-k 一点用都没有；如果答案排在第 12 位，调 top-k 才有用。这两种情况在"感觉"的层面长得一模一样。

没有度量的时候，代价不只是不准，而是会把两种方向相反的故障报成同一个结果。

环节	当时在调什么
混合检索	融合策略（dense + BM25 + RRF）
问答主链路	检索 → 父块回填 → 出处
向量化	批量编码 / 维度一致 / 增量
精排与去冗余	Reranker + MMR
权限下推	过滤必须下推

五个环节全在调检索，而尺子是最后才补上的，等于先盲调五轮，才把量尺递过来。

把这件事拆开，只需要一个自定义指标：bury。

# evalkit/schema.py:256-260
#   bury = 第一个相关文档的排名（1-based），-1 表示压根没召回
#          这是自定义的诊断指标，专门区分两类完全不同的故障：
#            bury = -1    → 召回阶段就丢了（该查 embedding / 切片 / 权限过滤）
#            bury > top_k → 召回到了但排太后被截断（该查 rerank / 融合权重）
#          只看 Recall 会把这两种混为一谈，修错方向。

摊开成一张表：

bury	现象	真正的故障在哪	该动哪一环
-1	那个文档根本不在结果里	召回侧	embedding 模型 / 切片策略 / 权限 expr / 索引是否最新
2	在，排第 2	没问题	不用动
7	在，但被 top_k=5 截掉了	排序侧	reranker / RRF 融合权重 / 候选池 candidate_k

回到开头的场景，你改了一行 top_k：bury = -1 时文档压根没进来，你把 top_k 改成 100 也没用，因为你扩大的是"看的范围"，不是"找到的能力"，要改的是 embedding 和切片；bury = 7 时它在，只是排太后，把 top_k 从 5 提到 10 它立刻就进来了，改对了。

这两种情况的 Recall@5 都是 0，都没进前 5。如果没有 bury，你会把两者报成同一个结果，然后有一半的概率去改错的地方。

元命题在这里：一个好的指标，不只是"能比较大小"，更要"能分开故障"。Recall 是前者的代表，一个数字越大越好；bury 是后者的代表，它的取值本身就在指路。

二、评测只有三件套，但其中一件可能从来没通电

传统软件能用单元测试证明对错：assert f(2) == 4。LLM 应用不行，输出是非确定性、自然语言、统计生成的，你写不出那个 assert。替代品是三件套：

件	是什么	对应实现
黄金集	一批"问题 + 该命中的文档"，代表核心场景	evalkit/golden/retrieval.jsonl（15 条）
评分器	把"好不好"变成可比较的数字	compute_retrieval_metrics（Recall / MRR / nDCG / bury）
门禁	掉分就拦住，不让它合进主干	runner.py:201 退出码 2

RAG 的评测可以分三层，这里只碰最下面那一层：

层	问什么	成本
检索层	该找的段落找到没、排第几	零 LLM 成本，秒级
答案层	答案是否忠于上下文	要裁判模型，分钟级
端到端	用户的问题被回答了吗	要裁判模型，分钟级

为什么先做检索层，模块头把理由写死了：

# evalkit/harness_retrieval.py:5-9
# 为什么先做检索层：
# RAG 系统答错，绝大多数不是"模型笨"，而是"根本没把正确的段落喂给它"。
# 拿一个答错的问题去调 prompt、换更大的模型，往往是在错误的方向上使劲。
# 检索层评测能在零 LLM 成本、秒级的前提下告诉你：正确段落到底进没进上下文。

现在说三件套里最容易出问题的那一件。理论上"faithfulness 是幻觉的可观测化"讲得很漂亮，代码里的接线状态却是这样：

# evolution.py:471-475
fs = state.get("faithfulness_score")
answer_ok = None
if FAITHFULNESS_GRADE_ENABLED and fs is not None:
    try:
        answer_ok = float(fs) >= ANSWER_FAITH_THRESHOLD

要生效需要同时满足两个条件：开关 FAITHFULNESS_GRADE_ENABLED 打开，且 faithfulness_score 非 None。而这个字段在整个工程里没有一处写入。grep -rn "faithfulness_score" --include=*.py 只命中"读"和"注释"，没有任何赋值，于是 state.get(...) 恒为 None，这一层从来没有生效过。

这个结论不是推的，项目自己的课程脚本里已经写明了：L2 因 faithfulness_score 未写入恒为 None，L3 因 evaluate_success 未收到 rating，均未接线。

第一条纪律就在这里：指标定义了不等于指标生效了。信号没流进来，它在报表上就是一个永远的横杠，比没有还危险，因为你会以为它在看着你。

三、为什么"感觉"不算数

假设你刚做完精排优化，做了三件事：换了 rerank 的阈值、把候选池从 20 加到 40、关掉了去冗余。然后你问一句："好点了吗？"没有评测，你能给出的答案只有三种：

你的回答	它其实等价于
"感觉好点了"	你看了 2 到 3 个问题，确认偏误在起作用
"好像差不多"	你连一条能复现的基准都没有
"应该是好了，因为理论上应该更好"	把推理当成了证据

三种都不是度量。一个可以复用的判据：当你发现自己的优化循环是"改 → 随手试两个例子 → 觉得好 → 提交"时，你缺的不是更好的模型，是一份能重复跑的题。

评测分了两层，成本差一个数量级：

	检索层	答案层
问什么	该找的文档进没进、排第几	最终答案对不对
判据	文档标识匹配，确定性	LLM-as-Judge + 字符串硬判据
要不要调 LLM	不要	要
单次耗时	秒级	分钟级（实测 843.9s / 9 条）
跑的频率	每次改动都跑	发版前跑
样本量	15 条	9 条，约检索集的一半

两层的关系是：检索层是下界。检索层挂了，答案层不可能好，因为你把材料喂错了，模型再怎么生成也是错的。所以修的顺序永远是先召回、后生成。

检索层凭什么不调 LLM 也能出结论？关键在判据的性质：

问题	判据是什么	性质
该找的段落找到了吗	标注里的 file / pages / keywords 与检索结果的元数据比对	统计，可完全脱离模型
答案措辞对不对	语义是否一致、有没有编	生成，需要裁判模型

零成本带来的是频率上的自由：既然秒级、不花钱，就可以每改一行都跑。而"每次改动都跑"是评测能不能活下来的前提。

第一个致命坑：Harness 自己写了一套"差不多的检索"

这个坑的病根非常反直觉，它不是"评测写错了"，是评测写得太好了。

# evalkit/harness_retrieval.py:30-37
# 为什么要复用线上代码而不是自己重写一遍检索逻辑
#
# Harness 自己实现一套"差不多的检索"，就会与线上实现慢慢漂移，
# 最后评测分数很好看，线上依然拉胯。所以 pipeline 模式直接调
# LangGraphRAGApp._do_retrieve，评的就是线上那份代码本身。

"差不多"是这里最危险的三个字。你自己写一套检索，第一天它确实差不多；一周后线上加了图页召回、改了距离归一化、加了一层权限兜底，你那套副本一项都没跟上。于是：

评测：100% 通过
线上：答错
你以为的问题：模型不行
真实的问题：评测测的不是线上

怎么做到复用又不启动整个 App？因为 _do_retrieve 只依赖三份状态：

# evalkit/harness_retrieval.py:66-101（节选）
class _LiteHost:
    """轻量宿主：检索链路只需要 vector_db / user / tenant_id 三份状态，
    因此不必构造完整的 App（省掉 MySQL / Redis / LLM 网关 / 提示词管理器的初始化）。"""

    def __init__(self, vector_db, user_id: str, tenant_id: str):
        self.vector_db = vector_db
        self.user = user_id
        self.tenant_id = tenant_id

    def __getattr__(self, name: str):
        # 凡本对象没有的属性，自动到真实 App 上取同名函数并绑定到 self。
        ...
        if callable(attr):
            return attr.__get__(self, type(self))   # 绑定为本对象的方法
        return attr

__getattr__ 那一段是整个设计的精髓，目的是一句很工程的话：线上加一个 self._xxx 调用，评测不会崩。这正是防止漂移的落地形态，不是靠"我记得去同步评测脚本"，而是靠结构上让它无法不同步。

# evalkit/harness_retrieval.py:203-205
host = _LiteHost(self.vector_db, case.user_id, case.tenant_id)
# 只传原句，不做 LLM 改写，保证本层评测零 LLM 成本
pairs = self._lg.LangGraphRAGApp._do_retrieve(host, [case.query], case.role)

一句话：评测的价值不在于"能跑"，在于"跑的是线上那一份"。复刻一份等价实现，测出来的是你的副本，不是你的系统。

四、黄金集：评测的地基

评测的质量，上限是黄金集的质量。一份标注错了的黄金集，会让你在错误的方向上使劲，而且它每次都会报红，直到你不再相信这份报告。

一条 case 长什么样

// evalkit/golden/retrieval.jsonl 的 jm-001
{"case_id": "jm-001",
 "query": "登录包的协议号是多少",
 "tenant_id": "jm",
 "role": "admin",
 "tags": ["fact-lookup", "protocol-id"],
 "relevant": [{"file": "个人定位终端通讯协议", "pages": [7, 8],
               "keywords": ["登录包0x01", "0x01"], "gain": 3,
               "note": "登录包章节，协议号 0x01"}]}

八个字段，各有各的职责：

字段	作用	不写会怎样
case_id	唯一标识，报表与根因分析靠它	报表里认不出是哪条
query	用户的问法，不是检索关键词	测的是"检索器会不会猜你要什么"
tenant_id / role / user_id	检索上下文，必须固定	结果不可复现
tags	分组标签	只能看到总分，看不到在哪类问题上弱
relevant[]	哪些文档算命中	没有它就没有题
forbidden[]	哪些文档绝不能出现，负例专用	测不出跨租户泄漏

为什么 query 必须写"用户的问法"？因为这两件事测的东西完全不同：

你写什么	你实际在测
登录包 0x01 协议号，人造关键词	检索器认不认得这个词，一定认得
登录包的协议号是多少，真实问法	检索器能不能把一句人话映射到正确的段落，这才是用户干的事

命中判据：file 子串，加上 pages 或 keywords

这是整份黄金集最容易被误解的一处设计。判定逻辑在 evalkit/schema.py:94-121，读成一张判定树：

① 文件不匹配？            → 否（直接出局）
② 没标 pages/keywords？   → 是（文件对了就算命中）
③ 页码对上了？            → 是（命中）
④ 关键词出现在正文里？    → 是（命中）
⑤ 以上都不成立            → 否

"或"是这里的关键。为什么不全用页码、不全用关键词？因为两者都会失效，而失效的原因正好相反：

判据	优点	失效场景
pages 页码	精确	依赖 PDF 排版不变，重新导出或换版本后页码全错
keywords 关键词	抗变化	可能误判，关键词出现在无关段落
两者是"或"	任一成立即命中	pages 因换版失效时，keywords 还兜得住

一种"两个都标了但依然会误判"的场景：标注 pages: [1] 加 keywords: ["优先级"]，page 1 命中是真的；但同一份文档的 page 12 上只要出现"优先级"两个字，这条也会被判成命中，而它可能讲的根本不是定位数据的上报优先级。

项目的回答是：接受这个噪声，但不假装它不存在。note 字段就是让人写清"为什么这段是答案"的，而垃圾关键词在挖掘阶段会被过滤。

抗重建：别用 chunk_index

先说错误做法，它非常自然，你几乎一定会先这么干：

// 错误示范：用 chunk_index 当文档标识
{"query": "登录包的协议号是多少", "relevant": [{"chunk_index": 47}]}

然后你把知识库重建了一遍，改了切片参数、补了一份文档、升级了切片器。代码一行没改，结果：

[evalkit] 检索评测开始：15 条 case
  [1/15] ✗ jm-001   未召回   登录包的协议号是多少
通过率 0.0%

测试全红，而代码没有问题。你会花掉一整天去查检索链路，最后发现是标注过期了。因为 chunk_index 是切片过程的产物，不是文档的属性：

原来（chunk_size=500）：  第 47 片 = 登录包那一节
重建后（chunk_size=800）： 第 47 片 = 心跳包那一节   ← 边界全移了

挖掘脚本的头部注释把这个设计讲得很清楚：

# scripts/mine_golden.py:17-22
# 抗重建标注（关键设计）：
#     不用 chunk_index 当标识，重新 ingest 后切片边界会变，标注立即失效。
#     改用 file_name + pages + keywords 三重定位（或关系兜底），
#     跨越多次索引重建依然有效。

正确的标识该用什么？用文档自身的、不随处理流程改变的属性：

标识	属于谁	重建后会变吗
chunk_index	切片过程的产物	会变，边界移了
file_name	文档的属性	不变
pages	文档的属性（PDF 排版不变时）	不变
keywords	内容的属性	不变

可以带走的判据：当你要给某个东西写"标识"时，先问一句，它是"事物的属性"，还是"处理流程的产物"？凡是流程的产物，自增 ID、切片序号、日志行号、缓存位置，都会在下一次流程变化时失效。这条判据跟 RAG 无关，数据仓库的增量断点、定时任务的游标，全是同一个问题。

三条来源，各有各的毛病

source	怎么来的	覆盖的是什么	毛病
manual	人工编写	我们以为用户会问的	想不全，且越写越像需求文档
mined	从历史 trace 自动挖掘	用户真正问的	带 LLM 标注噪声
feedback	用户点踩转化	真的出过问题的那几条	最珍贵，也最少

为什么"用户真正问的"更重要？挖掘脚本 scripts/mine_golden.py:1-10 的注释写得很直白：手写黄金集覆盖的是"我们以为用户会问的"，而 trace 里是"用户真正问的"，后者才是线上质量的真实分布，也是回归测试最该守住的阵地。

关键洞见是：标注不用重新做，它已经躺在你的数据库里了。系统跑问答时，评测节点会让 LLM 判定"每篇召回的文档是否相关"，这个结果存在 task_checkpoints.state_json 的 doc_grades 里。

用户提问 → 检索（召回 7 篇） → LLM 判定 5/7 相关
         → 落盘到 task_checkpoints.state_json → 挖出来就是一条带标注的 case

这是"副产品思维"的一个漂亮例子：系统为了另一个目的产出的信号，恰好就是你评测最缺的东西。值得问一句，我现在跑的流程，有没有已经顺手产出了我后来要花大力气补的数据？

还有一个更朴素的约束：数据不出内网。内网语料不能上传给第三方评测平台替你算指标，一上传边界就破了。所以黄金集只能从本地数据库挖，Harness 只能用你机器上那一份线上代码，不调 LLM 的模式才能保证 query 不出网。

从 trace 挖标注：四个门槛加一次自校验

"免费"不等于"照单全收"。挖掘脚本的第二个注释标题就是：质量门槛，宁缺毋滥，脏数据比没数据更糟。

#	门槛	挡掉什么
1	至少有 1 篇被判定相关	全不相关的记录
2	query 长度 ≥ MIN_QUERY_LEN = 4	"你好"之类的闲聊
3	同题只保留相关文档最多的那次	同题重复问，取信息最全的
4	与既有黄金集按归一化 query 去重	制造重复题目

还有两个防伪造 case 的设计，它们都属于"不这么做就会造出一条永远失败的 case"：

# scripts/mine_golden.py
# trace 是历史记录，里面会引用早已被删除或改名的文档
# （实测挖到过 Jimi_IoT__V1.21.pdf，当前库里根本不存在）。
# 把这种标注写进黄金集，等于制造了一条永远失败的 case。

# 切片器留下的结构标记不是文档内容，用它们当关键词等于标了个永远匹配不上的锚点：
# 实测挖到过 keywords=["[Page 4]"]，同样会伪造出一条永远失败的 case。
_JUNK_KW = re.compile(r"^(\[?page\s*\d+\]?|第?\s*\d+\s*页|图\s*\d+|表\s*\d+|...)$", re.IGNORECASE)

最后一道、也是最有教益的一道是自校验。挖掘用的是 LLM 的判定，而 LLM 会判错。做法是用当前检索器把挖出来的 case 全跑一遍，分成"可信"与"存疑"两组：

# scripts/mine_golden.py: verify()
"""
用当前检索器把挖出来的 case 跑一遍，分成可信与存疑两组。

为什么必须做：标注来自 LLM 的 doc_grades，本身带噪声。实测挖到过
"输出一下通信流程图"被标到"设备信息结构""白名单获取"这种明显无关的章节上。
这类标注进了黄金集，评测就会长期报红，而问题其实出在标注、不在系统。

注意：验证不通过 ≠ 系统有 bug，只是"这条标注不够可信"，
因此不丢弃，而是单独存到 *_review.jsonl 供人工裁决。
"""

这段注释里最值钱的是最后那句判据：验证不通过不等于系统有 bug，只是"这条标注不够可信"。两种处理方式的差别很大：

处理	后果
把未命中的直接丢弃	你丢掉的可能正是"检索真的错了"的那些样本
放进 *_review.jsonl 等人工裁决	既不失真，也不污染主集

落地的产物就是三个文件：

evalkit/golden/retrieval.jsonl        15 条  主集（人工编写，逐条有 note）
evalkit/golden/mined_retrieval.jsonl   7 条  挖掘出的可信 case
evalkit/golden/mined_review.jsonl      1 条  挖掘出的存疑 case（待人工裁决）

条数是当时快照，会随挖掘跑动而变。要讲的不是"几个"，而是"分成两个池子"这件事本身。

隔离负例：另一种 case

权限怎么评测？答案是另一种 case，它没有正确答案，只有禁止出现的答案：

// evalkit/golden/retrieval.jsonl 的 iso-001
{"case_id": "iso-001",
 "query": "心跳包 0x36 的字段定义",
 "tenant_id": "yh",
 "role": "user",
 "tags": ["isolation", "negative"],
 "relevant": [],
 "forbidden": [{"file": "Jimi", "note": "几米协议文档不应出现在 yh 租户检索结果中"}],
 "note": "0x36 只存在于 jm 租户文档；在 yh 租户下若召回到几米协议内容即为跨租户泄漏"}

读法：0x36 只存在于 jm 租户的文档里。现在在 yh 租户下问它，正确行为是什么都召不到。一旦召回到 Jimi 的文件，就是跨租户泄漏。relevant 为空、forbidden 非空，这种 case 就是负例，代码上的判据就是 not self.relevant（evalkit/schema.py:183-186）。

判定要整体反转，第六节展开。为什么要单独讲？因为负例把评测从"质量工具"变成了"安全工具"。正例失败等于分数掉了，负例失败等于出事了。这两个数字在门禁里的地位完全不同：通过率掉了可以商量，泄漏数必须为 0。

五、一把尺子：四个指标、两种模式、一次真实 run

一共算四个数。三个是教科书指标，第四个是自定义的，而第四个才是最该带走的东西。k 的取值是固定的四个：DEFAULT_KS = [1, 3, 5, 10]。

Recall@k：该找的找到了几成

# evalkit/schema.py:409-412
for k in ks:
    # Recall@k：排名在前 k 的命中数 / 相关文档总数
    hit_k = sum(1 for r in hit_ranks if 0 < r <= k)
    out["recall_at_k"][str(k)] = hit_k / total

它回答的是"找到了几成"，最直观，也最常用。一条 case 可以标多个 relevant，所以召回率是按条数算的：

标注了	找到了	Recall@5
1 篇	1 篇，排第 3	1/1 = 1.0
2 篇	1 篇，另一篇没进来	1/2 = 0.5
2 篇	2 篇	2/2 = 1.0

它最大的问题也在"直观"上：Recall 只回答"在不在前 k"，完全不看排第几。而"排第 3"和"排第 12"在用户眼里是天差地别的两件事。

MRR：用户要往下翻多久

# evalkit/schema.py:403-404
# ---- MRR ----
out["mrr"] = 1.0 / min(valid) if valid else 0.0

MRR 是第一个相关文档排名的倒数，惩罚很陡：

第一个相关文档排第	MRR
1	1.000
2	0.500
3	0.333
5	0.200
10	0.100
没召回	0

为什么"排第 5 只有 0.2"这件事重要？因为它和线上 top_k = 5 正好卡在同一个位置：

排第 5：MRR = 0.2，但刚好还在上下文里，用户看得到
排第 6：MRR = 0.167，但已经被截掉了，用户看不到

0.2 与 0.167 在指标上只差 0.033，在用户体验上是"看到"与"没看到"的区别。这就是为什么单靠 MRR 还不够。

nDCG@k：考虑相关度分级的排序质量

前两个指标把"相关"当成有或无，但真实标注是有分级的，用 gain 表达：

gain	含义
3	直接写着答案
2	需推理
1	背景相关

DCG@k  = Σ  gain_i / log2(rank_i + 1)    只累加排名 ≤ k 的命中
IDCG@k = Σ  gain_j / log2(j + 1)         把所有 gain 按降序排列后的理想值
nDCG@k = DCG@k / IDCG@k                  归一化到 0~1，可跨 case 平均

这里有一个很容易写错的地方：

# evalkit/schema.py:384-391（节选）
# 注意 IDCG 要用"按 gain 降序"的理想排列，而不是原始顺序，
# 否则当高 gain 文档在标注里排后面时，nDCG 会算出大于 1 的值。

为什么"降序"这么关键？因为 IDCG 是理想排序的上界。如果标注里恰好把 gain=2 写在前面、gain=3 写在后面，而 IDCG 按原始顺序算，理想值就被人为压低了，实际的 DCG 就可能超过它，于是你得到一个 nDCG > 1 的数。

可以带走的经验：凡是"归一化指标"，都要问一句"分母是理论最优吗"。分母算错不会报错，它只会让指标在特定标注顺序下悄悄越界，而你通常只会在看到大于 1 的那天才发现。

bury 成立的前提：检索深度必须比线上深

# evalkit/harness_retrieval.py:55-59
DEFAULT_KS = [1, 3, 5, 10]
# 检索深度：比线上实际使用的 top_k 深，这样才能区分
#   "压根没召回（bury=-1）"  vs  "召回了但排在第 12 位（bury=12）"
# 如果只取 top 5，两者都表现为"没命中"，会把人引向错误的修复方向。
DEFAULT_FETCH_K = 20

线上 top_k = 5，评测 fetch_k = 20，差别是这样的：

评测取 5（错）：bury = -1 与 bury = 12 都输出"未命中"  →  两类故障又混在一起
评测取 20（对）：bury = -1 输出"未召回"，bury = 12 输出"rank 12"  →  一眼分清

注意这两个字的区别：线上取 5 是为了给模型省上下文，评测取 20 是为了看清故障在哪。同一个参数，两个目的，取值就该不同。pipeline 模式还会临时把线上参数顶到 fetch_k，用完再还原，否则同进程里跑第二个 suite 就被污染了。

一个判据：凡是"为了诊断而临时改配置"，离开前必须还原。这类 bug 的表现是"第二次跑结果不一样"，而你上一次跑得很正常，所以你会怀疑模型、怀疑数据，就是不怀疑那个没被还原的全局变量。

两种模式，定位故障在哪一层

模式	做了什么	评的是
raw	只做向量库检索（dense + BM25 混合），不做融合、不做精排	embedding 质量 / 切片策略 / 权限过滤是否误杀
pipeline	raw + RRF 融合 + cross-encoder 精排，复用线上真实代码	排序质量

对照着跑，结论直接出来：raw 差是召回侧问题，该换 embedding、调切片、查权限 expr；raw 好但 pipeline 差是排序侧问题，rerank 把对的压下去了，或者融合权重不对。

raw 模式有两处必须与线上保持一致，其中一处很容易漏：向量检索之后还有一层应用层权限过滤，评测必须把它也带上（pairs = self._acl.filter_results(pairs, case.role)，evalkit/harness_retrieval.py:194-205），否则会漏掉"被权限误杀"这类故障。

filter_results 在权限那一轮里被讲成"第二道防线"，主力是下推的 expr。评测里必须把它也带上，否则会漏掉一整类故障：权限把该看的文档挡在了门外。

顺便说一处真实的漂移：这段注释里原本写的是"被权限误杀（根因 R5）"，但按根因表定稿，权限过滤误杀是 R4，R5 是生成幻觉。这是注释漂移，R1 到 R8 的编号在演化过程中调整过，这条注释没跟上。代码注释也是会过期的文档，引用一个编号之前先 grep 一遍它现在的定义。

一次真实 run：15 条长什么样

跑一次是 python -m evalkit.runner --suite retrieval --mode pipeline，--mode raw 只看召回侧，--compare last 和上次比。

模块头描述了三种模式，但 full 只存在于那段 docstring 里。

$ grep -n "full" evalkit/harness_retrieval.py
19:    full      pipeline + LLM query 改写（要调 LLM，有成本，默认不跑）
26:    pipeline 好但 full 差    → 改写侧问题：LLM 把问题改跑偏了

只有这两行，没有实现。retrieve() 里只有 raw 与 else 两枝，CLI 的 --mode 也只允许 raw 和 pipeline。"改写侧归因"是一个设计意图，还不是一个功能。

这就是第二条校正：文档比代码乐观，是文档类项目最常见的腐化方式。看到文档里的"三种模式""四个指标"，先 grep 一遍再引用，判据永远是"是否存在"，而不是"是否合理"。

下面是本项目一次完整输出（出处：evalkit/runs/full_20260810.log）：

[evalkit] 检索评测开始：15 条 case，mode=pipeline，fetch_k=20
[evalkit] 配置：hybrid=True rerank=True top_k=20
  [1/15] ✓ jm-001 rank 1   ...   [13/15] ✓ yh-005 rank 1
 [14/15] ✓ iso-001 已隔离 泄漏=0   [15/15] ✓ iso-002 已隔离 泄漏=0

[evalkit] 完成：15 条 | 通过率 100.0% | MRR 0.853 | Recall@5 1.000 | nDCG@5 0.897
[evalkit] 诊断：完全未召回 0 条（召回侧问题）| 召回但排在 5 名外 0 条（排序侧问题）
[evalkit] 隔离负例：2 条，泄漏 0 条

先看最有价值的三行，注意它们全都是计数，不是比率：

输出行	含义	该做什么
完全未召回 0 条	没有 bury = -1 的 case	召回侧没事，不用动 embedding / 切片
召回但排在 5 名外 0 条	没有 bury > 5 的 case	排序侧没事，不用动 reranker
隔离负例：2 条，泄漏 0 条	负例全过	没有跨租户泄漏，这一条必须为 0

这三行就是 bury 的价值：报表不给你一个笼统的分数，而是直接把问题分到两个抽屉里，然后告诉你两个抽屉都是空的。

再看那条率：

指标	数值	样本量	能不能手算复核
MRR	0.853	13 正例	能，见下
Recall@5	1.000	13 正例	能，13 条全在 top_k=5 内
nDCG@5	0.897	13 正例	需要 gain 分布，较长
avg_bury	1.46	13 正例	能

MRR = 0.853 的手算复核，这是全文唯一一个"能把数字算回去"的范例：

逐条 rank（13 条正例的 bury）：jm-001..008 为 1,2,1,1,1,1,1,1；yh-001..005 为 4,1,3,1,1

逐条 1/rank：
  jm-001..008:  1 + 0.5 + 1 + 1 + 1 + 1 + 1 + 1 = 7.5
  yh-001..005:  0.25 + 1 + 0.3333 + 1 + 1 = 3.5833
                                     合计 = 11.0833

11.0833 ÷ 13 = 0.8526  →  四舍五入 = 0.853，与日志一致

为什么要费这个劲？因为后面要立的纪律是"数字必须能指回行"。连自己项目的汇总行都算不回去，它就只是一个不能复现的数字。

最后，关于样本量必须说清楚：这 15 条的构成是 13 条正例加 2 条负例。Recall@5 = 1.000 意味着这 13 条里答案全在前 5 名。它不能推出"系统的召回率是 100%"，只说明"这套集子当前没抓到问题"。13 条够做回归，不够做能力断言，两者的区别是下一节的核心。

六、从数字到动作：R1--R8

指标回答"差多少"，分类回答"往哪改"

假设你看到一条失败 case，已知它 bury = -1。然后呢？bury = -1 只是把范围缩到了"召回侧"，而召回侧至少有三个可能：embedding 不合适、切片把答案劈开了、权限 expr 把它挡了。你要挨个试吗？

evalkit/triage.py 干的就是这件事：把"差多少"翻译成"是哪一个根因、该动哪一环"，再给出具体动作。

R1--R8 全表

编号	名称	严重度	判据	该动哪一环
R1	召回侧完全丢失	high	bury <= 0 / Recall@5 = 0	换/微调 embedding、调 chunk_size 与重叠、重新 ingest
R2	排序侧埋没	medium	召回但排在 5 名之后，或 nDCG@5 偏低	调 rerank 阈值/模型、调 RRF 权重、加大 candidate_k
R3	改写/精排负优化	medium	raw 明显好于 pipeline，同一条 query	关掉/弱化 query rewrite、单独验证 rerank 模型、A/B 对比
R4	权限过滤误杀	high	raw 命中但 pipeline 未命中，或 admin 命中、user 未命中	查租户/角色过滤 expr、验证 AccessControlFilter 逻辑、补单测
R5	生成幻觉	high	检索正常（bury > 0）但答案出现禁词 / faithfulness < 0.6	强化 generate prompt 约束、补充相关文档、降温/加 cite 要求
R6	答非所问	medium	检索正常但 relevancy < 0.6	修 classify 路由、强化 multi-hop 拆解、校验对齐
R7	拒答错误	medium	should_refuse 却编了答案（漏拒），或不该拒却拒了（误拒）	调整拒答判定阈值、补充安全策略样例、校准标注
R8	跨租户泄漏	critical	本租户 query 召回了其他租户文档	立即检查租户过滤 expr、确认索引是否混库、加隔离回归测试

注意严重度分布：R5 是 high，R6 和 R7 是 medium，而 R8 是唯一的 critical。这一列不是装饰，它决定了你先看哪一行。R1 到 R7 全是质量问题，只有 R8 是安全事件。质量差一点，用户多问一次；泄漏一次，就是一次数据事故，而且不可撤回。

分类器的实际输出长这样：

[evalkit] Bad Case 根因分布（3 条失败）
  R5 生成幻觉 [high] ×2
  R7 拒答错误 [medium] ×1
   - ans-jm-003: R5 生成幻觉 --- faithfulness=0.00 低于阈值0.6，答案不忠于上下文。
   - ans-yh-001: R7 拒答错误 --- 不该拒答的问题被拒了（误拒）。

那个"×2"的计数比任何分数都有用，它告诉你这一轮的主要矛盾是幻觉，不是路由。

优先级：安全 → 召回 → 拒答 → 生成

八个编号不是并列的，文档字符串给出了一条排序：

# evalkit/triage.py:32-34
安全类（R8）→ 召回类（R1/R4/R2/R3）→ 拒答类（R7）→ 生成类（R5/R6）。
即：先确认"有没有把错的文档放出来 / 有没有把对的挡住"，再看"生成质量"。
因为召回错了，后面生成再好也是建立在错误材料上，先修召回。

画成阶梯：

① 安全类   R8                     ← 有泄漏，其他一切免谈
② 召回类   R1 / R4 / R2 / R3      ← 材料都没拿对，后面全部无效
③ 拒答类   R7                     ← 该说"不知道"的时候说了
④ 生成类   R5 / R6                ← 材料对了，是模型没用好

为什么"先修召回"这句这么重要？因为它对应一个非常常见的错误动作：

报表：Recall@5 = 0.62，faithfulness = 0.55（一堆 R5）

错误的第一反应：调 generate 的 prompt，让它"更严格地只依据上下文"。
   材料本身就是错的，你把生成约束得再死，也只是忠实地复述错误材料。

正确的第一反应：先看 R1/R2，那 38% 没召回的，是因为答案压根没进来，
   还是因为排太后被截了？把材料修对，faithfulness 会自己上来。

可以带走的判据：当"上游"和"下游"同时有失败时，永远先修上游。数据管道要先修抽取再修清洗，前端要先修接口再修渲染，都是同一个道理：下游的一切努力，都可能只是在忠实地放大上游的错误。

一个反直觉的判定顺序：R4 必须先于 R1

召回类内部，R4 排在 R1 前面。这不是随便排的，它是一个代码实现上的顺序：

# evalkit/triage.py:155-158 与 :163-166
# R4：raw 命中但 pipeline 未命中 → 权限误杀（比 R1 更具体，优先判定）
# 必须放在 R1 之前：pipeline 未召回时 bury<=0，若不先判 R4 会被 R1 抢走，
# 而"权限误杀"比"泛化的召回丢失"更能直接指导修复。
if raw_bury is not None and raw_bury > 0 and bury <= 0:
    return _make("R4",
                 f"raw 模式能召回（bury={raw_bury}）但 pipeline 未召回，"
                 f"疑似权限/角色过滤误杀。")

# R1：完全没召回（无 raw 对比信号，或 raw 也未召回）
if bury <= 0 or recall5 == 0.0:
    return _make("R1",
                 f"正确文档未进入召回（bury={bury}, Recall@5={recall5:.2f}）。")

问题的本质是"条件重叠"：

一条 case：raw_bury = 2（raw 能召回到），bury = -1（pipeline 没召回到）

它同时满足两个条件：
  · R4 的判据：raw 命中 且 pipeline 未命中   命中
  · R1 的判据：bury <= 0                     命中

如果 R1 写在前面，这条 case 会被判成 R1，而 R1 的行动建议是"去换 embedding、调切片"，方向完全错了。真正的问题是权限 expr 把该看的文档挡在了门外。

R4 之所以必须赢，是因为它更具体：

	判据的信息量	行动的可执行性
R1 召回侧完全丢失	只知道"没召回到"	宽：embedding / 切片 / 索引 / 权限，四个方向都要试
R4 权限过滤误杀	知道"raw 能、pipeline 不能"	窄：差异只在 pipeline 多出来的那一层，也就是权限过滤

一个通用到可以写进代码规范的判据：把"更具体的判据"排在"更泛化的判据"前面。因为分类器是首个命中即返回的结构，泛化的条件会吃掉所有本该落到更具体分支的样本，具体异常要先于 Exception 捕获就是这个道理。反过来说，如果你发现某个分支"永远不进"，先检查它前面是不是站着一个判定条件更宽的分支。

隔离负例：判定要整体反转

	正例	负例
及格判据	至少召回一个相关文档	一条禁止规格都没命中
"什么都没召回"	失败，该找的没找到	正确行为，不该漏的没漏
失败意味着什么	分数掉了	出事了

如果沿用正例口径去判负例，会把"隔离成功"误报成"失败"，直接污染通过率与未召回计数，把人引向一个根本不存在的召回问题。另外，负例的扫描是独立的一轮：一条 case 可以同时有正例要求和禁止要求，所以"禁止规格扫描"与"相关文档扫描"要分开做，对 forbidden 里的每条规格扫一遍召回结果，命中即为泄漏。

这条在工程上还剩很多细节，规格怎么写、命中怎么定位到 rank、泄漏计数怎么汇总，那些属于实现。要记住的是：判据的方向变了，而且必须变。

七、诚实口径与门禁

负例不进均值，只进泄漏计数

直觉做法是把负例当成普通 case，一起算平均分。为什么不行？聚合函数的注释写得非常清楚：

# evalkit/schema.py:438-443
# 负例（隔离类）没有正确答案，Recall/nDCG/MRR 对它恒为 0。
# 若混进均值会凭空拉低分数，且让指标随负例条数漂移、跨 run 不可比，
# 所以质量类指标只在正例上计算；负例单独用 leak_count 体现。

两个后果，第二个更严重：

后果	说明
凭空拉低分数	负例的 recall/mrr/ndcg 恒为 0，混进去会让 MRR 从 0.853 掉到 0.739，而系统一行没变
指标随条数漂移	这是真正致命的：今天 2 条负例、明天加 5 条，指标自己就变了。于是你再也无法跨 run 比较，而"跨 run 比较"正是评测存在的唯一理由

所以负例走自己的一条通道，而通过率覆盖全部 case，因为它的口径由统一的判定函数给出，正负例各自反转：

# evalkit/schema.py:458-462
# 泄漏数：负例中命中了禁止规格的条数，安全类指标，必须为 0
summary["leak_count"] = sum(1 for r in neg if r.get("forbidden_hits"))
# 通过率覆盖全部 case（正例看召回、负例看隔离），口径由 _passed 统一给出
summary["pass_rate"] = round(sum(1 for r in results if r.get("_passed")) / n, 4)

一张表看清谁进哪个池：

指标	池子	为什么
recall@k / ndcg@k / mrr	只算正例	负例没有正确答案，这些指标对它无意义
miss_count / buried_count / avg_bury	只算正例	同理
leak_count	只算负例	负例唯一的产出，也是安全指标
pass_rate	全部	正负例判定方向相反，但"通过"含义一致

一个可以直接拿去自查的动作：把负例条数从 2 条改成 10 条，看正例的 Recall 会不会变。变了说明口径脏了，指标正在随"你测了多少条负例"而漂移。

n 小就别报百分比

这是最需要纪律的一段，因为它的诱惑最大。你手上有三个漂亮的数字：Recall@5 = 1.000、MRR = 0.853、nDCG@5 = 0.897。拿它去汇报，太顺了。

但在按下发送之前，先看另一个场景。项目里还有一次不同性质的度量，它只有三条 query：

# scripts/eval_retrieval_bury.py:160-164
CASE1_Q = "基站信息格式是什么"
EXTRA = ["基站信息格式", "VI 基站信息格式"]

三条 query。如果它输出"救回率 66.7%"，你会信吗？所以这个脚本给了一条口径声明：不给"召回率 62%/78%/91%"这类具体百分比。原因有两个，一是真实数字随评估集变化，样本量不足以支撑百分比；二是给出没有复现步骤的数字，等于让读者以为"跑一遍就能得到这个数"。能负责任地讲的结论只有一条：三种合并策略在"gold 排名"上会给出不同的排序结果，而这个脚本让差异可量化、可对比。

这条声明里有两条判据，都很硬：

判据	意思
样本量不足以支撑百分比	n = 3 时，"2/3 命中"和"3/3 命中"的差别没有统计意义
给出没有复现步骤的数字，等于让读者以为跑一遍就能得到这个数	数字不是形容词，它是一个承诺：别人照你的步骤能跑出同一个数

那 15 条黄金集呢，它是"能报"还是"不能报"？看三个维度：

维度	3 条 query 的埋点	15 条的黄金集 run
样本量	3	15，13 正例加 2 负例
是否可复现	否，脚本没固定黄金集	是，有固定黄金集、run 日志、配置快照（hybrid / rerank / top_k / fetch_k）
数字能否手算复核	否，只输出排名	能，11.0833 ÷ 13 = 0.8526

所以落点是：

	怎么处理
可以报	15 条 run 的 MRR 0.853 / Recall@5 1.000 / nDCG@5 0.897，但每次必须紧跟 n = 13 正例
不许报	3 条 query 埋点的任何百分比，连"救回 2/3"都别写成 66.7%
最该报的	三个计数：未召回 0 / 埋没 0 / 泄漏 0。它们是形态，不是比率，不受样本量影响
必须跟一句	"单次满分只说明这套集子当前没抓到问题"

那句"必须跟的话"为什么不能省？因为 Recall@5 = 1.000 读起来像能力断言，而它其实是回归结论：

回归结论（成立）：这 13 条里答案全在前 5 名，本次改动没有让它们退化。
能力断言（不成立）：系统的召回率是 100%。这需要远大于 13 的样本、
                    且样本要覆盖真实的 query 分布（这正是 mined 用例存在的理由）。

一句话：样本量小的时候，"看起来很好"本身就是一种风险，因为它会让你停止找问题。能负责任地说的只有一句："这套集子目前没抓到问题"，后面紧跟"所以下一步是把它变大"。

门禁：让评测真的拦得住

评测最大的敌人不是"测不准"，是"没人跑"。而"没人跑"的根本原因通常是，跑不跑结果都一样。所以最后一环是门禁，落地形态是一个退出码：

# evalkit/runner.py:192-201
# ---- 门禁 ----
# 两个 suite 都以 harness 落盘的 _passed 为准：检索层的正例（看召回）
# 与隔离负例（看有没有泄漏）判定方向相反，不能再用 bury 一刀切。
failed = sum(1 for r in run.results if not r.get("_passed"))
if failed:
    any_failure = True
    print(f"[evalkit] ⚠ {suite} 有 {failed} 条失败 case")
    _print_triage(run)

return 0 if (args.no_fail or not any_failure) else 2

四件事值得逐个说。

第一，退出码是 2，不是 1。

退出码	含义
0	全部通过
2	有失败 case
1 被 argparse 占用	参数错误，不冲突

CI 里靠的就是这个非零码，这是门禁唯一真正生效的机制。

第二，--no-fail 是一个逃生舱，但它必须显式使用。它存在是对的，有时候你就是要跑一遍看看，不想被拦，但它必须是"我知道我在跳过门禁"，而不是默认行为。判据：如果你的 CI 里天天带着 --no-fail，那你其实没有门禁。

第三，门禁的判据是 _passed，不是 bury。因为 bury 只对正例有意义：

case 类型	用 bury 判会怎样
正例	bury > 0 就是通过
负例	负例的 bury 恒为 -1，它本来就不该召回，用 bury 判会把每一条隔离成功的负例都判成失败

这就是"判定反转"在门禁层的体现。同一个坑，在三个地方各出现一次：判定、聚合时正负例分池、门禁里用 _passed 而不是 bury。

第四，失败时顺手把根因打出来。这一步把"拦住"和"下一步"接上了：门禁不只告诉你没过，还告诉你哪一类没过。

为什么必须进 CI？因为人的注意力是稀缺资源。

靠自觉："每次改完记得跑一下评测" → 第 1 周认真跑 → 第 3 周改的是文档就不跑了 → 第 6 周没人记得它还存在
靠门禁：不跑过不了 CI → 它会一直跑下去

一个判据：一项检查如果"失败也不影响任何事"，它就会在几周内停止运行。要让一件事长期做下去，最可靠的办法不是反复强调它的重要性，而是"让它成为流程的必经之路"。

八条已知边界

#	边界	说明
1	样本量小	15 条，13 正例加 2 负例。Recall@5 = 1.000 是回归结论，不是能力断言
2	正例偏向 admin 视角	13 条正例全是 role: "admin"，两条负例才用 role: "user"。user 角色下的召回质量没有正例覆盖
3	知识库强绑定	黄金集绑定两个租户的具体文档。换一套知识库，manual 部分基本要重写
4	第三种模式未实现	模块头描述的 LLM 改写模式只有 docstring，改写侧归因只能靠 R3 的间接信号
5	没有精确率指标	评分器只算 recall_at_k / ndcg_at_k / mrr / bury，检索的准确率没有实现
6	标注带 LLM 噪声	mined 用例的标注来自 LLM 判定，已用自校验分组，存疑组仍需人工裁决
7	命中判定用 rank 不用 score	score 只做展示。判定走 rank，因为 score 的语义有失真可能
8	注释会过期	实测两处：一条注释把权限误杀写成 R5，模块头写了三种模式而代码只有两种

第二条值得单独看一眼，它藏着一个很容易被忽略的盲区：

13 条正例，role 全都是 admin
2 条负例，role 才是 user

也就是说，普通用户角色下的检索质量，这份黄金集目前测不到。而 role 直接决定权限表达式，admin 看本租户全部，其他角色还要叠加 public or 本人。一个只测 admin 的黄金集，恰好绕过了整个权限维度。

八、九个坑，成因只有两个字

#	坑	现象	根因	严重度
1	只报 Recall，不用 bury	报告里只有"命中率"，两类故障混在一起	Recall 不看排名；bury = -1 与 bury = 12 都表现为"没在前 k 里"	高危，修错方向
2	黄金集拿 chunk_index 当标识	重新 ingest 一遍，测试全红，代码一行没错	chunk_index 是切片流程的产物，边界一变就失效	高危，标注失效
3	Harness 自建一套"差不多的检索"	评测 100% 通过，线上照样答错	副本与线上慢慢漂移；"等价"是个不成立的假设	高危，评测绿线上红
4	不筛标注噪声	评测长期报红，最后没人再打开报告	LLM 判定本身带噪声，照单全收等于自己骗自己	高危，摧毁信任
5	n 小却给百分比	报了个漂亮数字，没人能复现	3 条 query 不支撑百分比；没有复现步骤的数字是一个承诺	高危，虚假精确
6	负例混进均值	加了几条负例，正例的 Recall 自己变了	负例的 recall/mrr/ndcg 恒为 0，导致跨 run 不可比	中等，口径污染
7	检索深度设成线上 top_k	分不清"压根没召回"和"排在 12 位"	fetch_k 必须比线上深，否则 bury 失去分辨力	中等，丢失分辨力
8	评测不进 CI	三周后再没人跑	失败不影响任何事，注意力被别的事拿走	中等，一定会腐烂
9	只看绝对指标，不看基线	每周掉 1%，十周后才发现	没有基线对比，缓慢退化不会跳出来	次要，缓慢退化

第 1 到第 5 条是一组，它们全都是致命的，而且没有一条会报错。复查顺序建议从上往下：先用 bury 把报表拆成"未召回 / 埋没"两列（坑 1），再确认黄金集的标识用文档属性而不是切片序号（坑 2），最后给评测加一个退出码（坑 8）。

这九个坑跟前几轮遇到的坑性质不同。权限那一轮的坑是"想不到"，维度漏掉比边界写错危险；而这一轮的坑全是"想省事"：自建一套检索省事、用 chunk_index 省事、不建门禁省事。

所以药方不是"更细心"，是把标准写下来。因为省事的冲动是持续的，而标准是唯一能对抗它的东西，不依赖你每次都记得。

只能带走一句的话：

度量必须先于优化。没有尺子，你的每一次改动都只是一次猜测。

再加一句：

最危险的降级，是那个让指标"看起来还行"的降级。