智能体工程 · 11c
指标变好了,怎样确认是这一个改动带来的?
读完能做的判断:固定题集和基线,以单变量消融、失败样本与落盘记录解释变化。
📑 本页目录(点开跳转)
11c · 检索调优:保留失败样本的实验台
⏱ 阅读约 23 分钟 · 动手实践另计
🎯 一句话
调优要回答“哪类问题改善了、代价是什么、有没有退化”,而不是宣布加了新组件。 本页能实际比较 BM25、中文向量、融合与重排,并导出逐题结果。
🔗 先完成入库与数据治理,任务设计见共同项目。以下用 lab.py 与 models.py 说明评测入口和模型适配的分工;命令用于讲解实验组织,完整工程不随教程分发。
🔬 一、让实验产生文件
实验先设计不需要下载模型的基线,调用形式如下:
python examples/knowledge-assistant/lab.py evaluate --report output/rag-bm25.json
为实验实现神经检索并安装相应依赖后,可用下面的调用形式比较结果。首次加载公开 ONNX 模型需要联网和额外磁盘空间;这一方案不调用付费 API:
python examples/knowledge-assistant/lab.py evaluate --neural --rerank --report output/rag-neural.json
每次评测使用临时数据库,不覆盖日常练习的文档。默认 embedding 为 BAAI/bge-small-zh-v1.5,带中文查询前缀;默认重排器 Xenova/ms-marco-MiniLM-L-6-v2 面向英文,在这里故意测中文迁移是否成立。模型不匹配是可检验的假设,不能因为接口成功就忽略它。
报告包含配置、包版本、模型文件哈希、语料与代码哈希、每道题的候选和最终文档,以及各阶段组合的延迟与质量。模型缓存目录可以用 --cache 指定;离线运行应提前准备权重并记录来源与许可。
本轮看到的反例
2026-09-06 的这套小型开发语料有 20 题,其中 16 题有授权范围内的答案。最终代码复测中,BM25、向量和融合在 K=3 的文档级 Recall 都为 1,而英文重排器为 0.90625(Hit 为 0.9375)。表头与说明一起保留的解析修复也改变了重排结果,体现了上游处理与下游排序之间的关联。这只是小语料结果,绝不是业务准确率 100%。
在型号题中,XR-300 文档反复提到与 XR-200 的差异,可能先于正确的 XR-200 文档被召回;重排修好这一题,却可能弄坏别的中文问题。查报告中的逐题排序,比只看平均数有用。复测时同时记录配置、逐题结果与测量边界。
二、先定义题集和指标
| 题型 | 构造方法 | 必须检查 |
|---|---|---|
| 精确实体 | 相近型号、版本、错误码 | XR-200 与 XR-300 不能混答 |
| 语义改写 | 同一需求不同措辞 | 同义词变化后证据仍命中 |
| 多文档条件 | 报销政策 + 额度表 | 多个 gold 文档是否同时进入上下文 |
| 无答案 | 语料没有相应政策 | 能否拒答/澄清,不能硬造 gold |
| 权限负例 | 普通用户问 HR、租户 A 问 B | 候选、引用、生成、缓存均不泄漏 |
| 时间变化 | 旧版与新版、撤权后重问 | 当前版本优先,旧引用不再被认可 |
Hit@K 只看是否至少命中一个相关文档;Recall@K 是命中的不同相关文档数除以全部相关文档数。两者只有每题一个 gold 时才会一致。MRR 看第一个正确文档排得多靠前;本项目的 NDCG 用二元相关标签衡量顺序,不冒充细粒度人工相关性评分。
同文档的多个块不能刷高文档召回率。无答案题没有 Recall 的有效分母,本项目返回空指标,另报候选;还需在生成阶段计算应拒答时回答的比例。空测试集应失败,不能显示完美成绩。
这 20 题属于公开开发集。求职项目需要另建保留集:按文档来源、时间或用户会话切分,避免同一问法的改写跨集合;加入难负例,保留双人标注分歧与裁决。先定验收线,再查看保留集结果。反复用保留集调参数,它就变成了开发集。
也可按语雀 RAG 评测材料的合成题流程(PDF 第 1–3 页),让 LLM 从文档块生成问题与参考答案:问题脱离该片段仍应有意义,又能据原文回答。合成结果先当候选。 本项目采用的质量要求是:由独立人工回查原文,确认问题可答、答案正确后再入题集;生成模型自评不能替代独立验证。
三、消融只改一个变量
| 实验 | 命令中的变化 | 对照与诊断 |
|---|---|---|
| 候选量 | --candidate-k 6 与 12 |
目标不在候选中时,重排无从补救 |
| 最终 K | --k 1 与 3 |
Recall 增益是否抵得过噪声与上下文 |
| 切块长度 | --chunk-chars 250 与 450 |
表格保留时可能超目标;实际 token 另测 |
| 上下文预算 | --context-chars 800 与 2400 |
候选正确却没进 prompt,属于拼装损失 |
| 检索路线 | 基线与 --neural |
BM25、dense、RRF 在同题集独立比较 |
| 重排 | --neural --rerank |
候选固定,比较入选文档、顺序和延迟 |
例如只缩小候选量,输出到另一个文件:
python examples/knowledge-assistant/lab.py evaluate --neural --rerank --candidate-k 6 --report output/rag-candidates6.json
本项目融合用 RRF:每路按名次贡献分数,常数为 60;每路先去重,避免重复项多次加分。它不要求 BM25 与余弦分数同量纲。若改线性加权,先校准分数分布,再用开发集调权重。原始相似度没有通用的“0.8 以上可信”含义。
不要把逐个单因素最佳值直接拼成最终配置。 切块、K、上下文预算有交互;最终组合要再跑全套和保留集,记录退化题。报告失败样本、每题差值和按题型的表现,小样本置信区间应宽,不能多报几位小数制造确定感。
这组可复跑的检索结果可用于对照近似检索或 embedding 的数据与训练方案。
四、向量数据库慢与召回差,要分开测
当前代码对授权候选做精确向量打分,没有实现 ANN。迁移 Qdrant、pgvector 或其他引擎时,先用相同向量、距离与过滤条件的精确搜索建立参照。
| 参数或机制 | 影响 | 实验必须同时记录 |
|---|---|---|
| HNSW 的 M、构建 ef | 图连边、构建开销与内存 | 构建时间、内存、ANN recall |
| 查询 ef | 探索范围 | p50/p95/p99 与相对精确搜索的召回 |
| IVF 的 nlist / nprobe | 分区与探测范围 | 不同过滤选择率、冷热点分布 |
| 量化 / 磁盘索引 | 内存与 IO,可能引入近似误差 | 重评分开关、量化前后误差 |
| filter 前置 / 后置 / 迭代扫描 | ACL 与有效候选量 | 严格过滤下是否不足 K、是否越权 |
| 批量写入 / 刷新 / 删除整理 | 吞吐与新鲜度 | 写入到可见延迟、查询尾延迟 |
ANN recall 是“是否找回精确近邻”,业务 Recall 是“是否找回有用证据”。精确近邻本来就不相关时,把 ANN recall 调到 1 也不能让答案变正确。参照 Qdrant 的 ANN recall 测量与AI 全栈的落库章节。
五、性能与模型选型记录什么
分开冷启动与热请求;记录 CPU/GPU、内存、并发、文本 token 长度、模型权重与线程数。对请求做分层抽样,观察检索、重排、首 token、生成和总耗时。16 题的 p95 只是开发观察,不能用来承诺生产 SLO。
先修漏索引、权限错误、分词和型号丢失,再判断是否换模型。语种、领域、query 前缀、截断率和归一化不对时,应优先修配置。领域训练需要正例、难负例、去重与保留集;点击不是天然相关标签,曝光位置会造成偏差。调温度、负例数量或训练轮数都要看未见文档上的效果。
第一批实践:从阅读到验收
检索之后继续评测答案层。开发集与公开冻结集各 20 题,按文档/问题簇区分;冻结题是公开材料,不能宣称未知盲测。独立保留集由未参与调参的人在本地私有路径另作。
| 层 | 看什么 | 分母 |
|---|---|---|
| 检索 | 有答案题的 Hit / Recall 等 | 有答案题;受限与无答案单列 |
| 运行 | 成功、异常、超时、非法工具 | 全部题次,失败不删除 |
| 事实与引用 | 关键命题正确、引用语义支持 | 标明可评题次与已复核题次;未知不算成功 |
| 拒答与权限 | 无资料、撤权、注入是否守住边界 | 各自题类;不能合并成总体准确率 |
扩大题集前,先检查一道失败题的原始记录和它所属的分母。检索 Recall 与生成质量分别评估。
索引更新和预算是两项独立检查
11g · 缓存与索引一致性 检查版本、ACL、TTL与失败发布;教学哈希向量只验收系统契约。11h · 重排与上下文预算 固定候选比较排序和片段取舍,记录目标已召回却未进入上下文的情况。两项都不能替代真实模型质量或生产ANN容量验收。
先检查输入,再比较检索
11i · 扫描件 OCR 与人工复核 从原图识别出待复核候选,置信度不能替代人工核对。11j · 表格分块与证据保真 用人工结构化表格验证标题、单位、条件与行来源是否一起保留;不把自动 OCR 等同于表格还原。
✅ 检查点
- 为什么 Hit@3=1 不能说明所有证据都找齐?
- 加了重排,一道题改善、总体下降,怎么处理?
- ANN recall 很高但回答很差,下一步看哪层?
展开答案
- 一题可能需要多个文档,Hit 只要求命中一个;应看文档级 Recall 和证据完整性。
- 保留逐题结果,查语种、截断和训练域;在同候选上复测,达不到预定质量/延迟线就不采用。
- 先看精确检索的业务相关性,再定位证据是否被拼入、是否被正确使用;不能只继续调 ANN 参数。
先定义题型和 gold;一次改一个变量;平均数旁边保留退化题;速度、权限和答案质量都要验收。
🔗 接下来去哪
➡️ 下一站:11d · 生成引用与查询诊断。