Onyx(Danswer)搜索质量回归评测指南:基于 Ground Truth 的检索与回答自动评估
Onyx(Danswer)搜索质量回归评测指南:基于 Ground Truth 的检索与回答自动评估
导读
本文围绕 Onyx 开源仓库(即原 Danswer 项目,目录 backend/tests/regression/search_quality)中的搜索质量回归测试脚本展开,完整讲解如何构建"问题—期望检索文档"评测数据集、调用真实 Onyx API 对搜索与答案生成质量做自动化评估,并解读其底层打分机制与并发实现。读完本文,你将掌握:如何准备评测数据集、如何通过命令行参数控制评测流程、如何理解 eval-* 输出目录中的各项指标(排名、Top-K 准确率、RAGAS 答案质量分),以及如何在多租户与联邦搜索场景下正确运行回归评测。
一、Search Quality 测试脚本是什么
search_quality 是一个面向 搜索(检索)与答案(生成)质量 的回归评测脚本,位于 backend/tests/regression/search_quality。它的核心思想是:
- 用户提供一组测试问题(query)与对应的 Ground Truth(期望检索到的文档链接);
- 脚本调用正在运行中的 Onyx 实例(默认
http://127.0.0.1:8080)的搜索 API,对每个问题做真实检索; - 将检索结果与 Ground Truth 比对,计算命中与否、命中排名、Top-K 准确率等指标;
- 可选地(默认开启)再对生成答案做质量评估(基于 RAGAS 的 answer relevancy / faithfulness / factual correctness);
- 最终输出 CSV 指标报告与排名柱状图。
注意:该脚本不修改索引,也不注入数据——它直接使用当前已索引的文档进行搜索、答案生成与 Ground Truth 比对,因此它是一把"回归测试尺",用于在代码改动、配置调整(如 Embedding 模型、混合检索参数、Reranking 开关)后量化检索效果是否回退。
目录结构
backend/tests/regression/search_quality/
├── README.md # 使用说明(本文所依据的官方文档)
├── models.py # Pydantic 数据模型(TestQuery、EvalConfig、指标模型等)
├── run_search_eval.py # 评测主入口(参数解析、并发调度、报告与图表生成)
├── test_queries.json.template # 测试集模板
└── utils.py # 工具函数(文档定位、RAGAS 评估、整体打分、LazyJsonWriter 等)
二、环境准备与运行前置条件
按官方 README 的要求,运行前需满足以下条件:
- 依赖已安装、Onyx 已在运行:脚本通过 HTTP 请求调用 Onyx API,因此需要一个可访问的 API 服务(本地开发可用 docker compose 或
python -m onyx启动)。 - 设置
OPENAI_API_KEY:答案评估默认启用(除非加-s参数),而答案评估由 RAGAS 驱动,RAGAS 需要调用 OpenAI 的 LLM 打分,因此必须配置该密钥。 - 生成并配置
ONYX_API_KEY:在 Onyx 管理后台的 API Keys 页面生成一个 basic API token(形如on_...),写入环境文件:ONYX_API_KEY=on_... - 准备
.env文件:从源码看,脚本在启动时会强制加载仓库根目录.vscode/.env(见 run_search_eval.py),若该文件不存在会直接抛错:
同时脚本在真正发起评测前会做三重校验(run_search_eval.py):RuntimeError: Could not find .env file. Please create one in the root .vscode directory.- 若开启答案评估但未设置
OPENAI_API_KEY,报错; - 若未设置
ONYX_API_KEY,报错(认证始终必需); - 对
{api_url}/health做健康检查,连接失败则报错。
- 若开启答案评估但未设置
从源码结构看,脚本为了以独立脚本方式运行,会自行将
backend目录加入sys.path并加载.vscode/.env,再导入ee.onyx.server.query_and_chat.models、onyx.context.search.models等模块(见 run_search_eval.py),因此必须在仓库环境下运行。
三、构建测试数据集
3.1 从模板复制
将模板复制为正式测试集文件:
cd path/to/onyx/backend/tests/regression/search_quality
cp test_queries.json.template test_queries.json
3.2 字段说明
模板位于 test_queries.json.template,每一条测试查询的完整字段定义在 models.py 中:
| 字段 | 类型 | 说明 |
|---|---|---|
question |
str |
测试问题原文 |
ground_truth |
list[GroundTruth] |
期望检索结果的无序列表,每项含两个字段 |
ground_truth.doc_source |
str |
文档来源,如 web、google_drive、linear,用于某些场景下归一化链接 |
ground_truth.doc_link |
str |
文档链接,用于在本地索引中定位对应文档 |
ground_truth_response |
Optional[str] |
理想答案应包含的要点/参考回答(用于答案质量评估) |
categories |
Optional[list[str]] |
分类标签列表,用于按类别聚合统计评测结果 |
模板示例:
[
{
"question": "What is Onyx?",
"ground_truth": [
{
"doc_source": "web",
"doc_link": "https://docs.onyx.app/welcome"
}
],
"categories": [
"keyword",
"broad",
"easy"
]
}
]
添加/删除测试问题时,只需按上述字段结构编辑该 JSON 数组即可。建议覆盖不同难度与检索意图(如关键词型、泛化型、需要跨文档推理型),并利用 categories 对不同维度分别汇总。
3.3 Ground Truth 的定位逻辑(源码级)
models.py 中定义了 TestQuery.ground_truth_docids(自动生成,不需手写):脚本加载数据集时,会通过 utils.find_document_id 将 doc_link 解析为本地索引中的真实 document_id,若解析失败则跳过该查询并告警(见 utils.py 与 run_search_eval.py)。定位时的关键细节:
- 联邦来源处理:若
doc_source属于数据库中FederatedConnector的联邦来源集合(见get_federated_sources),当前对 Slack 有特例——从链接archives/{CHANNEL_ID}/p{TS}中解析出channel_id__message_id形式的文档 ID。 - 链接预处理:Google Drive 链接会去掉
/edit或/view后缀;Fireflies 链接会去掉?之后的查询参数,以提高匹配成功率。 - 模糊匹配:使用
Document.link.ilike(f"{doc_link}%")前缀模糊匹配;命中多个文档时取第一个并告警,0 个时返回None。
因此,ground_truth.doc_link 必须与索引中文档的实际链接一致(至少前缀一致),否则该测试用例会被跳过。
四、运行评测与命令行参数
4.1 基本用法
所有参数均为可选、有合理默认值:
python run_search_eval.py
完整参数表(来自 run_search_eval.py):
| 短参 | 长参 | 默认值 | 说明 |
|---|---|---|---|
-d |
--dataset |
./test_queries.json |
测试集 JSON 路径 |
-n |
--num_search |
50 |
每次搜索最多检索的文档数 |
-a |
--num_answer |
25 |
答案评估最多使用的文档上下文数 |
-w |
--max_workers |
10 |
并发搜索请求数上限(0 = 不限) |
-r |
--max_req_rate |
0 |
每分钟搜索请求数上限(0 = 不限) |
-q |
--timeout |
120 |
请求超时(秒) |
-e |
--api_endpoint |
http://127.0.0.1:8080 |
Onyx API 服务基地址 |
-s |
--search_only |
False |
仅做检索评估,跳过答案评估 |
-t |
--tenant_id |
None |
多租户模式下使用的租户 ID |
官方 README 特别给出了两条实用建议:
- 只关心检索质量时务必加
-s:跳过 RAGAS 答案打分能显著加快评测速度; - 开启联邦搜索(federated search)时建议设
-r 1:避免触发各数据源接口的速率限制。
4.2 脚本背后的请求流程
脚本通过 HTTP 调用 Onyx 的搜索 API(对应后端 search_backend.py 中 /api/search/send-search-message 接口,需要 READ_SEARCH 权限与向量数据库可用)。核心请求构造见 _perform_search(run_search_eval.py):
- 构造
SendSearchQueryRequest:search_query为问题文本,filters为空(BaseFilters(),即不做任何来源/标签过滤),num_docs_fed_to_llm_selection=max_search_results,run_query_expansion=False,stream=False; - 若设置了
ONYX_API_KEY,则在请求头附加Authorization: Bearer ...; - 请求体为
POST {api_url}/search/send-search-message; - 响应按
SearchFullResponse反序列化后,截取前max_search_results个SearchDoc转换为SavedSearchDoc(其定义见 models.py); - 对失败请求带
retry_builder(tries=3, delay=1, backoff=2)自动重试(指数退避)。
其中 num_docs_fed_to_llm_selection 对应后端 SendSearchQueryRequest 中的字段,该字段决定进入后续 LLM 文档选择阶段的候选数量。
4.3 并发与限速实现
评测采用线程池 + 信号量 + 令牌间隔的三重控制(run_search_eval.py):
Semaphore(max_workers)限制同时运行的请求数(0 表示不限,此时线程池max_workers=None);- 若
max_req_rate > 0,按60/max_req_rate秒的间隔逐条提交请求,实现每分钟限速; - 任一查询分析抛错会通过
stop_event终止后续提交,并在as_completed阶段向上抛出异常。
这种设计让你可以用 -w 10 -r 0 做快速全量评测,或用 -w 1 -r 1 做温和的慢速评测以保护第三方数据源。
五、理解输出与指标
运行结束后,会在 search_quality 目录下生成一个以时间戳命名的文件夹 eval-YYYY-MM-DD-HH-MM-SS,包含四个产物(README 中明确列出):
| 文件 | 内容 |
|---|---|
test_queries.json |
本次使用的数据集(含解析出的有效查询与对应的索引内 ground truth) |
search_results.json |
逐查询的搜索与答案详情 |
results_by_category.csv |
按分类聚合的指标(含 all 汇总) |
search_position_chart.png |
Ground Truth 命中排名的柱状图 |
小技巧:官方 README 建议,下次运行时可以把上次生成的
test_queries.json替换为-d的输入——它已经包含ground_truth_docids,加载时会直接复用、跳过重新解析,从而显著加快加载速度(见 run_search_eval.py)。
5.1 检索质量指标
逐查询分析(_run_and_analyze_one,run_search_eval.py)会计算 Ground Truth 文档在结果列表中的 rank(从 1 开始;未命中记为 None)。聚合指标定义于 models.py 的 SearchMetrics:
total_queries:查询总数;found_count:至少命中一条 Ground Truth 的查询数;best_rank/worst_rank/average_rank:命中结果的最高/最低/平均排名;top_k_accuracy:对k ∈ {1, 3, 5, 10}(源码常量TOP_K_LIST)计算 Top-K 准确率(命中的查询占比,聚合时换算为百分比)。
5.2 答案质量指标(RAGAS)
非 -s 模式下,脚本会用 ragas_evaluate(utils.py)对每个查询的答案打分,指标来自 RAGAS 框架:
response_relevancy:答案对问题的相关性;faithfulness:答案是否忠实于检索上下文(不凭空编造);factual_correctness(mode=recall):仅当提供了ground_truth_response时计算,衡量答案与参考回答的事实一致程度。
这三个指标分别对应 utils.py 中导入的 ResponseRelevancy、Faithfulness、FactualCorrectness。评测时会把检索到的文档内容(经 build_doc_context_str 拼装为带元数据的上下文,见 search_docs_to_doc_contexts)作为 RAGAS 的 retrieved_contexts 传入。
前提说明:RAGAS 依赖 OpenAI 作为评测 LLM,因此答案评估必须配置
OPENAI_API_KEY;且答案评估只在前max_answer_context(默认 25)条检索上下文上执行。
5.3 综合得分
compute_overall_scores(utils.py)输出两个 0–100 的综合分(源码注释明确说明"分数带有主观性,可能需要根据自身场景调参"):
- search_score:40% 权重来自命中率(found ratio),60% 来自按排名衰减加权的 Top-K 准确率(
TOP_IMPORTANCE=0.7控制"排第一"相对其他排名的权重); - answer_score:可用指标(relevancy / faithfulness / factual_correctness)的简单平均。
5.4 CSV 与图表
results_by_category.csv:按分类输出total_queries、found、percent_found、best/worst/avg_rank、各 Top-K 准确率、答案三指标均值(非-s模式)、search_score、answer_score、avg_time_taken;控制台同时会打印各分类的汇总(见generate_detailed_report,run_search_eval.py)。search_position_chart.png:300 DPI 柱状图,横轴为"搜索结果中的排名位置",纵轴为"Ground Truth 文档数量";未命中的文档统一归入最右侧红色柱(标签not found (>{max_search_results})),命中柱为蓝色,顶部标注计数(见generate_chart,run_search_eval.py)。
六、多租户与联邦搜索场景
- 多租户:当后端以多租户模式运行(源码中
MULTI_TENANT配置项为真)时,必须通过-t指定tenant_id,否则脚本直接抛ValueError("Tenant ID is required for multi-tenant");单租户模式下则自动使用默认 schema 值(见 run_search_eval.py)。 - 联邦搜索:若存在联邦连接器(
FederatedConnector,见get_federated_sources),脚本会按联邦来源的特殊规则解析 Ground Truth 链接(目前特例为 Slack);同时 README 建议此类场景下将-r设为 1,避免触发外部系统限流。
七、最佳实践小结
- 先做纯检索评测:改动 Embedding、混合检索
hybrid_alpha、Reranking 等参数后,用-s快速跑一遍,关注percent_found、avg_rank、top_1/top_3_accuracy与search_score是否回退。 - 再补答案质量评测:需要调优 Prompt 或评估 RAG 答案质量时,开启完整评测并配置
OPENAI_API_KEY,为每条测试问题补写ground_truth_response以获得factual_correctness。 - 善用
categories:将测试问题按来源(如keyword/broad/easy)或业务域打标签,CSV 报告会按类别分别汇总,便于定位是整体回退还是特定领域回退。 - 复用上次数据集:用上次生成的
test_queries.json(已含ground_truth_docids)作为-d输入,可跳过 ground truth 解析、加快加载。 - 控制并发与限速:本地压测用
-w提升吞吐;对接真实数据源或联邦搜索时调低-w、设-r,防止把服务或第三方 API 打挂。
参考资料
- 官方使用文档:backend/tests/regression/search_quality/README.md
- 评测主入口与参数解析:backend/tests/regression/search_quality/run_search_eval.py
- 数据模型与指标定义:backend/tests/regression/search_quality/models.py
- 工具函数(Ground Truth 定位、RAGAS 评估、综合打分):backend/tests/regression/search_quality/utils.py
- 测试集模板:backend/tests/regression/search_quality/test_queries.json.template
- 被调用的搜索 API 后端实现:backend/ee/onyx/server/query_and_chat/search_backend.py