检索与质量调优

命中测试（检索实验室）在不改动生产配置的前提下运行真实检索，并展示召回、融合、重排序、最终排名各阶段的中间结果。用它验证分块改动、模式切换或权重调整是否真的改善了召回。入口：知识库详情 → 命中测试（需要 kb:test 权限）。

检索模式

注意默认值有两层：检索请求不传 search_mode 时按 hybrid 执行；而知识库设置里的 search_mode 默认是空的（null），只有你显式设置后才会成为该知识库 Agent/工作流检索的默认模式。字段定义见知识库设置参考。

参数参考

命中测试面板可覆盖以下参数（全部可选）：

混合检索如何融合

两路召回后按加权倒数排名融合（RRF）合并，公式为：

score = Σ 权重 × 1 / (rrf_k + 排名)

• 权重只影响对应通道：dense_weight 作用于向量通道，lexical_weight 作用于全文通道，设为 0 等于关闭该通道。
• 混合模式下，两个权重不能同时为 0，否则请求被拒绝（界面也会禁用搜索按钮）。
• rrf_k 越小，头部排名的优势越明显；越大，排名差异被抹平。

A/B 对比

打开 A/B 对比 可以并排运行同一查询的两套配置：

1. 分别配置 A、B 两侧（各自独立的模式、top_k、阈值、权重、重排序参数）。
2. 提交后返回每个配置独立的结果：一侧失败不会隐藏另一侧的成功结果，失败侧会单独提示原因。
3. 结果面板显示两侧的名次、重合结果数（重合结果：N/总数）与各阶段分数。

批量检索接口 POST /api/v1/knowledge-bases/{kb_id}/search/batch 一次最多接受 10 个配置，且每个配置的 id 必须唯一。

读取结果与诊断

每条结果会标注各阶段取值，可用 final_score_stage 判断最终排序由哪个阶段决定：

阶段耗时 timings 拆分为 recall、rerank、context、total，可直接定位是召回慢还是重排序慢。

诊断 diagnostics 可能返回以下代码：

请求失败时响应带 retrieval_error_category 与 stage，用于区分处理方向：

应用到生产

命中测试面板的配置可以保存为本地预设（保存在浏览器本地，不跨设备同步），然后选择应用到生产把 A 侧配置写回知识库设置：

{
  "search_mode": "hybrid",
  "top_k": 5,
  "score_threshold": 0.0,
  "dense_weight": 1.0,
  "lexical_weight": 1.0,
  "rrf_k": 60,
  "rerank_enabled": true,
  "rerank_candidate_k": 10,
  "rerank_score_threshold": null
}

应用前请确认：

• 嵌入模型与索引维度未变化（否则先重建索引）。
• 混合模式下至少一个权重大于 0。
• 该知识库确实被 Agent/工作流引用——写回的是知识库级默认，Agent 关联上的 retrieval_top_k、score_threshold、search_mode 仍会覆盖它。

故障排查

常见故障和恢复步骤另见知识库设置参考；调参取舍见知识库优化。