Onyx(Danswer)搜索质量回归评测指南:基于 Ground Truth 的检索与回答自动评估

原创2026-09-09 23:49:421,434 阅读
文章标签:人工智能AI 应用RAGAI Agent深度研究MCP 服务知识库搜索引擎企业应用后端前端数据集成

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 的要求,运行前需满足以下条件:

  1. 依赖已安装、Onyx 已在运行:脚本通过 HTTP 请求调用 Onyx API,因此需要一个可访问的 API 服务(本地开发可用 docker compose 或 python -m onyx 启动)。
  2. 设置 OPENAI_API_KEY:答案评估默认启用(除非加 -s 参数),而答案评估由 RAGAS 驱动,RAGAS 需要调用 OpenAI 的 LLM 打分,因此必须配置该密钥。
  3. 生成并配置 ONYX_API_KEY:在 Onyx 管理后台的 API Keys 页面生成一个 basic API token(形如 on_...),写入环境文件:
    ONYX_API_KEY=on_...
    
  4. 准备 .env 文件:从源码看,脚本在启动时会强制加载仓库根目录 .vscode/.env(见 run_search_eval.py),若该文件不存在会直接抛错:
    RuntimeError: Could not find .env file. Please create one in the root .vscode directory.
    
    同时脚本在真正发起评测前会做三重校验(run_search_eval.py):
    • 若开启答案评估但未设置 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,避免触发外部系统限流。

七、最佳实践小结

  1. 先做纯检索评测:改动 Embedding、混合检索 hybrid_alpha、Reranking 等参数后,用 -s 快速跑一遍,关注 percent_found、avg_rank、top_1/top_3_accuracy 与 search_score 是否回退。
  2. 再补答案质量评测:需要调优 Prompt 或评估 RAG 答案质量时,开启完整评测并配置 OPENAI_API_KEY,为每条测试问题补写 ground_truth_response 以获得 factual_correctness。
  3. 善用 categories:将测试问题按来源(如 keyword/broad/easy)或业务域打标签,CSV 报告会按类别分别汇总,便于定位是整体回退还是特定领域回退。
  4. 复用上次数据集:用上次生成的 test_queries.json(已含 ground_truth_docids)作为 -d 输入,可跳过 ground truth 解析、加快加载。
  5. 控制并发与限速:本地压测用 -w 提升吞吐;对接真实数据源或联邦搜索时调低 -w、设 -r,防止把服务或第三方 API 打挂。

参考资料

登录后查看全文
danswer