# 先测好 RAG 检索器，别等客户来报错

> 用小型黄金集和纯 Python 算出命中率与 MRR，再交给 LlamaIndex 复核，分清错在检索还是生成。

原文: https://fdetimes.net/zh/guides/measure-rag-retrieval-hit-rate-mrr/

LlamaIndex 示例文档里有一行输出可能让读者吃惊：同一个查询，命中率和 MRR 都达到 1.0，精确率却只有 0.5。这并不矛盾，每个指标回答的是不同的问题。

这对前线部署工程师（FDE）很重要。客户现场的检索增强生成（RAG）系统往往以一种熟悉的方式出问题：答案错了，却没人知道问题出在查找文档，还是出在 LLM 生成答案。Pinecone 给自己的 RAG 评测指南起的标题就是“别让客户先告诉你”。

要做到这一点，就得单独测量检索器，并给出非技术人员也能看懂的数字。

本指南在一台笔记本电脑上完成整个过程：先建一个小型黄金集，用纯 Python 计算命中率和 MRR，弄清它们测的是什么，再用 LlamaIndex 的 `RetrieverEvaluator` 做同样的测量。

## 需要准备什么？

需要一个能运行的 RAG 系统，原型也可以；还需要一个检索器，输入查询，返回带 ID 的段落排序列表。另外需要 Python，第 3 步还要用到 LlamaIndex。

下面的代码都做了精简，只用于说明思路。正式使用前，请对照已安装版本的文档核对函数名。

LlamaIndex 把检索评测和答案生成分开：`RetrieverEvaluator` 可以给库中定义的任何 Retriever 模块打分。要保持这种思路：先把搜索层测清楚、做扎实，再去动提示词。

## 第 1 步：黄金集决定数字有多可信

黄金集是一组查询，每个查询都配有确定相关的段落。Kunal Ganglani 在关于生产环境检索评测的手册中建议，先从几十个查询起步，再逐步扩充到 50-200 个。

他还建议按段落 ID 标注，而不是按文本内容标注，这样分块方式改变后标注依然有效。

```python
golden = [
    {"query": "退款上限是多少？",
     "relevant_ids": {"policy_v3#12"}, "group": "easy"},
    {"query": "企业客户在计费周期中途更换套餐时，费用如何计算？",
     "relevant_ids": {"billing#4", "billing#7"}, "group": "hard"},
    # ……继续添加，直到几十个查询
]
```

本步检查：打开文件，数一数有多少是简单的常见问题，有多少是困难查询，例如需要组合两个段落，或者措辞和文档不同的查询。Ganglani 提醒，如果黄金集大部分是简单的常见问题，数字会比系统的真实表现好看。

如果手工标注太费力，LlamaIndex 文档建议用 LLM 生成合成数据，即问题和上下文的配对。这样能快速起步。不过生成的数据不保证简单和困难查询的平衡，所以要通读一遍，按分组计数，缺少困难查询的地方自己补写。

## 第 2 步：亲手计算，看清指标测的是什么

命中率@k 对每个查询做是或否的判断：前 k 个结果里是否至少有一个相关段落？按 Weaviate 的定义，MRR 衡量系统把相关结果排在前面的能力。每个查询的得分是 1 除以第一个相关段落的排名。

```python
def hit_rate_and_mrr(golden, retrieve, k=5):
    hits, rr_sum = 0, 0.0
    for item in golden:
        ids = retrieve(item["query"], k)  # 段落 ID 列表，已排序
        for rank, pid in enumerate(ids, start=1):
            if pid in item["relevant_ids"]:
                hits += 1
                rr_sum += 1 / rank
                break  # 只计第一个相关段落
    n = len(golden)
    return hits / n, rr_sum / n
```

用四个查询算一个例子。第一个相关段落分别排在第 1 位、第 3 位、不在前 k 个结果中、第 2 位。命中率为 3/4 = 0.75。MRR 为 (1 + 1/3 + 0 + 1/2) / 4，约等于 0.458。

本步检查：先手算这个例子，再把这四种情况原样输入函数，看结果是否一致。如果不一致，常见原因是 `rank` 从 0 而不是从 1 开始计数。

由于两个指标都只看第一个相关段落，再加一个简单的召回率@k 函数：对每个查询，用前 k 个结果中找到的相关段落数除以相关段落总数，然后取平均。`group` 参数可以按查询分组分别打分。

```python
def recall_at_k(golden, retrieve, k=5, group=None):
    items = [i for i in golden if group is None or i["group"] == group]
    total = 0.0
    for item in items:
        found = set(retrieve(item["query"], k)) & item["relevant_ids"]
        total += len(found) / len(item["relevant_ids"])
    return total / len(items)
```

以周期中途换套餐的查询为例，如果前 k 个结果只有 `billing#4`，该查询的召回率就是 0.5，而它的 MRR 仍可能是 1.0。

## 第 3 步：用 LlamaIndex 做同样的测量

原理清楚之后，剩下的可以交给库。根据 LlamaIndex 文档，评估器由指标名称和检索器构建，然后在整个数据集上异步运行。下面的代码只是示意，请核对所用版本的导入路径。

```python
from llama_index.core.evaluation import RetrieverEvaluator

retriever = index.as_retriever(similarity_top_k=5)
retriever_evaluator = RetrieverEvaluator.from_metric_names(
    ["hit_rate", "mrr"], retriever=retriever
)
eval_results = await retriever_evaluator.aevaluate_dataset(qa_dataset)
```

除命中率和 MRR 外，评估器还支持精确率、召回率、AP 和 NDCG，都按名称选择。本步检查：拿一个在第 2 步已知答案的黄金集查询来运行，两种方法的结果必须相同。如果不同，检查你的 ID 是否与索引生成的节点 ID 一致。

## 两个好看的数字还可能掩盖什么？

回到开头那行输出：命中率 1.0，MRR 1.0，召回率 1.0，精确率却只有 0.5，NDCG 约 0.61。相关段落已经排在第一位，但返回列表有一半是噪声，而这些噪声会进入 LLM 的上下文。

Ganglani 和 Weaviate 都指出了 MRR 的一个局限：它只考虑第一个相关段落。第 1 步中周期中途换套餐的查询同时需要 `billing#4` 和 `billing#7`，系统可能拿到满分 MRR，却仍漏掉一半信息。

因此，如果黄金集里有很多需要多个段落的查询，还要用第 2 步的函数报告召回率@k。

**要点:** 命中率告诉你检索器有没有找到东西，MRR 告诉你找得多早，但两者都不能告诉你找得够不够。

## 常见错误

第一个错误是按文本内容标注。分块大小改一次，整个黄金集就失去价值，无法对比改动前后。第二个错误是只报告一个 k 值。

k=10 时的命中率几乎总是高于 k=3，所以只有在旁边注明 k，这个数字才有意义。

第三个错误更难发现：黄金集全是简单查询。演示时一切正常，上线第一周真实用户就问出测试集里从没有过的问题。解决办法是按查询分组拆分结果，让困难组始终有自己的分数。

## 这项技能在客户现场如何体现？

在客户现场，最常听到的抱怨是“机器人答错了”。设想一位 FDE 带着 60 个查询的黄金集去见运营团队，用假设的数字说：“常见问题组的命中率@5 是 0.92。

需要组合两个段落的查询组，命中率@5 仍有 0.80，但召回率@5 只有 0.45，所以机器人通常只找到所需信息的一半。”

下一句才是客户真正需要的：“所以这周团队会修正计费文档的分块方式，在同样这 60 个查询上重新测量，暂时不换模型。”双方不再争论机器人“看起来”好还是不好，而是就要做什么、怎么验证结果达成一致。

转向 FDE 岗位的开发者，简历也该这样写。不要只写“搭建了 RAG 聊天机器人”，而要写明黄金集有多少个查询、分成了几组、更换分块策略后困难组的某个指标如何变化。

阅读岗位描述时，留意“evaluation”“retrieval quality”或“offline eval”这类说法，它们说明雇主需要的正是这项技能。

第一个黄金集通常只有几十个查询，也有不少粗糙之处。但它提供了一个固定基准，每次改动系统后都能重新测量，让你在客户打电话报错之前发现问题。

**本周动手试试:**

- 针对手头的文档集写 30 个查询，为每个查询标注段落 ID，并明确分成简单和困难两组。
- 在 k=3 和 k=10 下运行 hit_rate_and_mrr 和 recall_at_k，把两个 k 值之间的差异记录在 README 文件里。
- 修改检索器的一个参数（分块大小或 top_k），重新测量，用两句话解释数字为什么变化。

## 信源

- [Retrieval Evaluation (LlamaIndex docs)](https://developers.llamaindex.ai/python/examples/evaluation/retrieval/retriever_eval/)

- [Retrieval Evaluation (LlamaIndex docs, markdown)](https://developers.llamaindex.ai/python/examples/evaluation/retrieval/retriever_eval/index.md)

- [RAG Evaluation Metrics for Retrieval Quality: My Production Playbook](https://www.kunalganglani.com/blog/rag-evaluation-metrics-retrieval-quality.md)

- [Evaluation Metrics for Search and Recommendation Systems (Weaviate)](https://weaviate.io/blog/retrieval-evaluation-metrics)

- [RAG Evaluation: Don't let customers tell you first (Pinecone)](https://www.pinecone.io/learn/series/rag/rag-evaluation/md/)
