SuperBizAgent-java/mvp/engineering/harness/Harness RAG 检索体系学习笔记-从 query 到可验证证据.md

# Harness RAG 检索体系学习笔记：从 query 到可验证证据

> **现状说明（2026-09-29）**：RAG 模块抽离后，本文「检索前 L0 导航」与
> `MilvusHybridKnowledgeStore` / `KnowledgeQueryTransformer` 相关章节描述的类已删除
> （L0 与向量检索下沉 py-rag 服务端）；检索后处理/打包/投影/审计部分仍然现行。
> 当前架构见 [../../architecture/RAG知识检索架构.md](../../architecture/RAG知识检索架构.md)。

**更新日期**：2026-08-03
**主题**：lookup_knowledge 完整后端链路——检索前/检索/检索后/打包/组装/降级/契约/验证
**设计文档**：`mvp/engineering/rag/`（RAG 排序、Hybrid 质量分、relevance_level 等）
**代码视角**：[Harness tool 域代码学习笔记](Harness%20tool%20域代码学习笔记-工具的注册调用与执行链路.md)（工具链衔接）

## 1. 定位与骨架

一次 `lookup_knowledge` 从 query 到证据的旅程（模块化三段 + 收尾）：

```mermaid
flowchart LR
    Q["query"] --> A["检索前<br/>KnowledgeQueryTransformer<br/>L0 导航（分类/域/关键词）"]
    A --> B["检索<br/>KnowledgeDocumentRetriever<br/>dense + BM25 → RRF 融合"]
    B --> C["检索后<br/>KnowledgeEvidencePostProcessor<br/>qualityScore/去重/判级/闸门"]
    C -->|"低质"| B2["降级重试<br/>UNFILTERED_VECTOR_RETRY<br/>（去过滤 + 原始 query）"]
    C --> D["打包<br/>KnowledgeContextPacker"]
    D --> E["组装<br/>LookupResultAssembler<br/>→ LookupResult"]
    E --> F["投影<br/>RagResultProjector<br/>→ RagToolResult（Agent 契约）"]
```

**关键特征**：模块化三段各自独立 Service、降级是阶段间控制流、双轨可观测（RetrievalTrace + RerankTrace）、LookupResult 是内部契约（Agent 看到的是投影后的 RagToolResult）。

## 2. 检索前：L0 导航（缩短边界，不决定边界）

- **产出**：categoryFilter / domainHints / matchedKeywords / entities / l0Titles（从 query 语义推导）
- **只缩短边界**：categoryFilter 限定「搜哪些分类」（FILTERED_VECTOR）
- **不决定边界**：低质 → 降级去掉过滤重查（L0 边界可被推翻）
- **只解释不打分**：L0 命中只写 hitReasons（l0_domain_overlap），不改 qualityScore 和排序——防关键词碰瓷
- **语义差异应对**：降级用原始 query（非 rewritten）——抹掉 L0 推导误差

## 3. 检索：多路召回 + RRF

**为什么混合检索**：旧方案（dense 语义 + L0 关键词加权重排）有词频碰瓷误差——词频高但相关性不高的排前面。

```mermaid
flowchart LR
    subgraph 召回
        D["dense ANN（L2）<br/>抓语义相似"]
        S["sparse BM25<br/>抓精确匹配"]
    end
    D --> R["RRF 融合<br/>score = Σ w/(k + rank)"]
    S --> R
    R --> F["融合排序（originalRank）"]
```

**关键决策**：
- **RRF 用排名不用分数**——屏蔽跨路分数尺度不可比（dense 的 L2 vs BM25 的稀疏分）
- **k=60**（`retrieval.hybrid.rrf-k`）——平滑参数，排名差异对分数的影响平缓
- **加权是预留能力**：RrfFusion 支持 `w/(k+rank)`，但当前 Milvus 服务端走等权 RRFRanker（只传 k）——想让某路更可信时再调旋钮
- **召回优先**（RAG 排序文档观点）：候选池只有 3 条时，精排只能换座位，召不回的内容永远排不上来

## 4. 检索后：qualityScore 统一 + 质量闸门

### 4.1 为什么需要统一分数

三路返回三种分数（L2 距离 / BM25 稀疏分 / RRF 融合分）——不可比，必须统一成 qualityScore ∈ [0,1]。

### 4.2 打分（RetrievalScoreNormalizer）

```text
DENSE:  l2ToQuality(score) = 1 - clamp(L2)/maxL2      （maxL2 默认 2.0）
HYBRID: denseDistance != null ? l2ToQuality(denseDistance)   ← 恢复绝对质量
        : rankToQuality(rank, batchSize)                     ← BM25-only 保守回退
```

**denseDistance 的来源**（隐藏机制）：hybrid 融合后**再单独跑一次 searchDense**，按 id 把 L2 补到融合结果上——因为服务端 RRF 只输出融合分，原始 L2 信息丢了。`attachDenseDistances` 只填充不改 score/label/order（排序评估分离的又一体现）。

### 4.3 排序与评估分离（核心设计）

```text
originalRank（RRF 融合序）→ 排序：谁在前面（相对序）
qualityScore（L2/rank）   → 评估：够不够格、要不要降级（绝对度）
→ 排序不用 quality 重排（防 boost 操纵）
→ quality 只被判级和闸门消费
```

**为什么排名不能证明质量**：排名是「序」（A 在 B 前），质量是「度」（0.75 就是 0.75）——排第 1 只代表「这批里最好」，不代表「够好」（候选池全是低质时排第 1 的也低质）；RRF 分本身不含距离信息；跨批次的两个「第 1 名」绝对质量天差地别。

### 4.4 五步流程（process）

```
① 打分（toQualityScore）→ ② 排序（originalRank，不用 quality 重排）
③ 去重/截断：evidenceKey 合并 + maxChunksPerDocument=2 + returnN=5
④ 判级：top qualityScore ≥0.75→PRECISE / ≥0.5→REFERENCE
⑤ 闸门：topSimilarity <0.5 → 低质 → 降级重查
```

**两级去重**（粒度不同）：
```
evidenceKey 去重（chunk 级）：同 chunk（docId#chunkIndex）被两路召回 → mergeEvidence 合并
  —— mergeEvidence 只合并 hitReasons + 补 breadcrumb，不处理 content（同 chunk 内容相同）
maxChunksPerDocument（文档级）：同文档不同 chunk 最多 2 个 → 防单文档垄断证据槽位
```

**判级用 ranked（全量）不是 deduped**——判级评估「整体质量」（全量 top），去重决定「输出内容」（合并片段），两件事平行。

**BM25-only 的弱点**：无 dense 邻居 → rankToQuality 回退（排第 1 恒为 1.0）——整批 BM25-only 时闸门永不降级（topSimilarity=1.0 ≥ 0.5）。改善方向：文本相似度兜底（绝对信号）+ 批次一致性检查（整体水平），而非返回 BM25 分（统计度量无绝对语义）。

## 5. 契约语义：relevance_level 是什么、不是什么

- **是什么**：一次 lookup_knowledge 调用整体有多相关的**粗档标签**（判级产出：PRECISE/REFERENCE/null）
- **不是什么**：不是单条 evidence 的分数、不是相似度数值、不是「结论可发布」判据
- **Agent 正确用法**：evidence_status 管有没有证据，relevance_level 管这批评据多硬/要不要再查，实际写诊断引用的是 evidence[].excerpt
- **REFERENCE ≠ NO_GAIN**：一般相关可能仍排除一个假设——语义价值由模型判断（progress 原则）

## 6. 打包与组装

### ContextPacker（打包）

```
输入顺序即优先级 → 逐条塞进 4000 字符预算
  单条放不下 → content 截断（+"..."）
  连 header 都放不下 → 整条省略（记 omittedSources）
输出：packedText + strategy + charBudget/usedChars + included/omittedSources
```

**当前定位**：Agent 主要看结构化 evidence 列表，packedText 更多用于内部/调试/审计（Harness 用结构化列表因为可验真——evidence_ref 引用 document_id）。

### LookupResultAssembler（组装）

- **内部契约出口**：found / evidenceBlocks / 双数量 / 双 trace / relevanceLevel / completenessHint / message
- **found 在这里综合判定**：evidence.hasUsableEvidence()
- **message 语义**：found=false 时「知识库未检索到可用证据，请结合日志、指标、告警继续排查」——证据不足不是失败，是换方向引导
- **与投影的关系**：LookupResult 是后端完整出口，RagResultProjector 再裁剪成 Agent 契约（两层契约）

## 7. 降级：突破 L0 边界的兜底

```
触发：categoryFilter != null && isLowQuality（无证据 或 topSimilarity < 0.5）
动作：原始 query（非 rewritten）+ 去掉分类过滤 + 覆盖选择（不合并两轮）
原因分类：FALLBACK_LOW_QUALITY（查到了但低质）/ FALLBACK_NO_EVIDENCE（完全没查到）
有限降级：只一次（防重查风暴）；retry 低质也接受（降级失败直接返回）
trace：attempts 记录全部尝试（FILTERED/UNFILTERED/UNFILTERED_RETRY）
     + selectedAttempt + fallbackReason → 可对比「过滤 vs 全域」判断 L0 过滤是否过度
```

## 8. 投影衔接（RagResultProjector）

- **契约转换**：LookupResult JSON → RagToolResult（evidence[] + relevance_level + evidence_status + truncated）
- **四重有界**：query 500 字 / excerpt 1200 字 / 条数 8（maxEvidence）/ 总字节 16KB（fitBudget）
- **优先级链去重**：evidenceKey → document_id → docId#chunk-idx → legacy 序号（chunk 级身份）
- **诚实标记**：一切有损（截断/去重丢弃/query 截断）都置 truncated；fitBudget 裁空诚实降级 NO_EVIDENCE + relevance 置 null（没有证据就没有相关度，自洽）
- **两级数量限制**：后端 returnN=5（业务目标值）vs maxEvidence=8（Harness 护栏）——5<8 时护栏休眠，后端配置失控时兜底

## 9. 验证：审计 + 离线评测

### 9.1 审计 vs Trace（两套记录系统）

| | DiagnosisTrace（事件流） | ToolInvocationAudit（调用档案） |
|---|---|---|
| 粒度 | 事件（一次调用多个事件） | 记录（一次调用一行） |
| 覆盖 | Run 全生命周期 | 仅工具调用 |
| 内容 | metadata-only（不存 raw） | 完整（raw + agentResult + enrichments） |
| 用途 | 时序回放 / Token 对账 | 单次调用深查 |

```
RAG 后端双 trace（Retrieval/Rerank）→ 进 LookupResult → Harness
  → 安全字段提取 → tool_invocation 审计（enrichments）
  → 轻量事件 → DiagnosisTrace
审计在投影之后、给模型之前（ToolBoundary.execute 内先落库）
```

### 9.2 离线评测设计（eval/rag-retrieval）

```
三层：offline（fixtures × golden-cases，无真实栈）/ snapshot 生成（真实跑一次冻结）/ live smoke
断言：行为契约（expectedDocIds/Breadcrumbs/Keywords/SelectedAttempt/FallbackReason/EvidenceStatus）
     + 不断言 raw scores / chunkId / 全序（脆或内部实现）
基线：baseline.json + diff（区分有意改进 vs 无意回归）
隔离：seed-docs + kb_scope=rag-eval
```

**断言设计原则**：
- 断言「用户可感知的结果 + 管道行为」，不断言「实现细节」（chunk/分数/全序）
- 双信号：fail 抓行为回归 + diff 抓「绿了但漂了」（通过但退化可见）
- **期望来自设计意图，不从当前输出反推**（否则固化 bug）
- golden set 是演进的：初期种子（设计意图）→ 中期真实数据（**必须人工验证**——成功案例只是观测，不是契约）→ 持续事故固化

### 9.3 指标（缺的下一步）

```
检索质量：recall@k / Hit@k / MRR（复用 expectedDocIds + rank，低成本）
管道行为：降级触发正确率 / 降级有效率 / 过滤误伤率（复用 trace 字段）
质量闸门：低质识别准确率 / 降级误杀率（BM25-only 弱信号代价可测）
需要新标注：precision@k（负例）/ nDCG（相关度分级）
```

## 10. 易错点

| 易错 | 正确 |
|---|---|
| RRF 排序了就不用打分 | 排序（RRF）与评估（qualityScore）分离——RRF 管谁在前，L2 管够不够格 |
| 排第 1 = 质量好 | 排第 1 只代表「这批里最好」——候选池全低质时排第 1 也低质 |
| 返回 BM25 分能解决 BM25-only | BM25 是统计度量（无界/依赖集合），无绝对语义——用文本相似度/一致性检查 |
| denseDistance 是融合分 | 是融合后再跑一次 dense 探测的 L2（RRF 丢了原始 L2） |
| 去重和判级有先后 | 平行：去重管输出（deduped），判级管评估（ranked 全量 top） |
| 后端 returnN=5，maxEvidence=8 多余 | returnN 是业务目标值，maxEvidence 是 Harness 护栏（防配置失控） |
| 线上成功案例可直接当 golden | 成功只是「当前实现没出错」的观测——必须人工确认设计意图 |
| 审计在给模型之后 | 审计在投影后、给模型前（ToolBoundary 内先落库） |

## 11. 讨论沉淀：值得记住的问题与洞见

本节收录学习过程中的关键问答——按价值分层，面试准备直接翻这里。

### 11.1 触及设计本质（第一梯队）

**① 「RRF 已经排序了，为什么还要打分」——排序与评估分离**

```text
RRF 管「谁在前面」（融合排序，相对序）
qualityScore 管「够不够格」（质量评估，绝对度）

为什么排名不能证明质量：
  排名是「序」（A 在 B 前），质量是「度」（0.75 就是 0.75）
  排第 1 只代表「这批里最好」，不代表「够好」——候选池全是低质时排第 1 也低质
  RRF 分不含距离信息；跨批次的两个「第 1 名」绝对质量天差地别
```

**② 「最终落地到 dense 决定，RRF 白用了吗」——谁被评估 vs 评估够不够**

```text
RRF/BM25 管：召回 + 排序（BM25 路召回 dense 召不回的候选，RRF 让两路共识靠前）
dense L2 管：质量评估的绝对标尺（唯一有绝对语义的）
→ 分工：RRF 决定「谁能被评估」，dense 决定「评估结果够不够」
→ 「排第一但 dense 低质 → 降级」不是矛盾，是排序与评估分离的价值（发现域选错）
```

**③ 「能不能返回 BM25 分当质量」——度量类型决定能否设阈值**

```text
几何度量（L2）：embedding 空间稳定 → 能设 0.75/0.5 绝对阈值
统计度量（BM25）：无界、依赖集合 IDF、随集合演进漂移 → 设不了稳定阈值
→ 质量评估需要绝对标尺，只能来自几何度量或可解释相似度（字符重叠）
→ 改善 BM25-only：文本相似度兜底 / 批次一致性检查 / fail-closed，而非返回 BM25 分
```

**④ 「BM25-only 质量有问题」（自己发现的设计弱项）**

```text
rank 回退：排第 1 恒为 1.0 → 整批 BM25-only 时闸门永不降级（topSimilarity=1.0 ≥ 0.5）
根因：rank 是相对序（第 1 名不代表够 0.5），顶位给满分是「排序最好 = 质量满分」的错误等价
改进：rank 顶位保守化 / 文本相似度兜底 / 批次一致性检查
```

### 11.2 隐藏机制（第二梯队）

**⑤ 「denseDistance 是融合分还是 dense 分」**

```text
是 dense 那一路的 L2——RRF 服务端融合只输出融合分，原始 L2 信息丢了
→ attachDenseDistances 融合后再单独跑一次 searchDense，按 id 把 L2 补到融合结果
→ 只填充不改 score/label/order（排序评估分离的又一体现）
```

**⑥ 「为什么降级只一次」——有限降级**

```text
降级 = 突破 L0 边界重查（原始 query + 去过滤 + 覆盖选择）
只降级一次：预算约束（retrieveK × 2 检索成本）防重查风暴
fallbackReason 区分：FALLBACK_LOW_QUALITY（查到了但低质）/ FALLBACK_NO_EVIDENCE（没查到）
```

**⑦ 「returnN=5 为什么 maxEvidence=8」——目标值 vs 护栏**

```text
returnN=5：RAG 业务目标值（rag.return-n）——打算给 5 条
maxEvidence=8：Harness 安全上限（ToolProjectionLimits）——最多允许多少
两级解耦：业务层和安全层各自配置；5<8 时护栏休眠，后端配置失控时兜底
```

### 11.3 方法论沉淀（第三梯队，可迁移）

**⑧ 从 0 设计离线评测的八步**

```text
目标（回归保护）→ 粒度（工具级）→ 输入（冻结快照）→ 断言（行为契约）
→ 用例（行为维度覆盖）→ 隔离（种子数据）→ 基线（区分有意/无意变化）→ 成本（分层运行）
```

**⑨ golden set 怎么设计**

```text
行为清单 → 每个行为一个 case → query 拟真（能触发目标行为）
→ 期望来自设计意图（不从当前输出反推——否则固化 bug）→ 补负例/边界
→ 演进：初期种子打底 → 中期真实数据（人工验证后转契约）→ 持续事故固化
```

**⑩ 「线上成功案例能不能直接用」——观测 ≠ 契约**

```text
线上成功只是「当前实现没出错」的观测：可能恰好没触发 bug 路径、结果碰巧对
→ 必须人工确认「结果确实符合设计意图」后才从观测升级为契约
→ 失败案例则明确「期望应该怎样」作回归保护
```

**⑪ 「不用 chunk 断言也是数据原因吗」——不是**

```text
chunk 边界是切分实现细节：算法优化/文档微调都让 chunk 偏移 → 合法重构被误判回归
契约语义的证据单位是文档级（document_id 常等于 source）——chunk 模型都看不到
→ 即使数据充足也不该断言 chunk（和数据量无关）
```

### 11.4 三个核心洞见（最值得记住）

```text
① 排序与评估分离：RRF 管「序」（相对），L2 管「度」（绝对）——排名不能证明质量
② 度量类型决定能不能设阈值：几何（L2）可以，统计（BM25）不行
③ 期望来自设计意图，不从实现反推——这是评测和 golden set 的分水岭
```

## 12. 面试话术（30 秒）

### 11.1 排序与评估为什么分离

> "RRF 管『谁在前面』（融合排序），qualityScore 管『这批结果够不够格』（质量评估）——打分不是重排，是排序后的质量校验。RRF 分是排名派生的相对值，没法设绝对阈值（排第 1 不代表够 0.5，候选池全是低质时排第 1 的也低质）；qualityScore 把 dense L2 归一化成 [0,1] 的绝对质量，用于判级（0.75/0.5 阈值）和闸门（<0.5 触发降级）。排序决定看哪些，评估决定够不够好。"

### 11.2 为什么 BM25 分不能当质量

> "质量评估需要绝对标尺，绝对标尺只能来自几何度量（L2 距离——embedding 空间稳定）或可解释的相似度（字符重叠），不能来自统计度量（BM25——无界、依赖文档集合的 IDF、随集合演进漂移）。BM25-only 命中用排名回退估质量（保守），但顶位给满分是设计弱项——改进方向是文本相似度兜底或批次一致性检查，而不是返回 BM25 分。"

### 11.3 降级设计

> "降级是突破 L0 过滤边界的兜底：带分类过滤检索结果低质（无证据或 topSimilarity<0.5）时，用原始 query + 去掉分类过滤重查一次（UNFILTERED_VECTOR_RETRY），结果覆盖选择、记录进 trace。fallbackReason 区分『查到了但低质』vs『完全没查到』；只降级一次（预算约束防重查风暴），降级失败也直接以低质结果返回。attempts 列表让审计能对比过滤 vs 全域检索差异，判断 L0 过滤是否过度。"

### 11.4 golden set 怎么设计

> "golden set 是行为契约的清单：先列要保护的行为，每个行为一个 case（不耦合可定位）；query 用能触发目标行为的真实形态；期望来自设计意图（我知道这个文档属于这个场景），绝不从当前输出反推（否则固化 bug）；补负例与边界；golden set 是演进的——初期人为种子打底，中期真实数据必须人工验证后才能转契约，持续事故修复固化。核心：断言用户可感知的结果 + 管道行为，不断言实现细节。"

## 13. 代码位置索引

| 类 | 文件 |
|---|---|
| `LookupKnowledgeTool` | `src/main/java/com/superbiz/agent/tool/LookupKnowledgeTool.java` |
| `KnowledgeQueryTransformer` | `src/main/java/com/superbiz/agent/service/KnowledgeQueryTransformer.java` |
| `KnowledgeDocumentRetriever` | `src/main/java/com/superbiz/agent/service/KnowledgeDocumentRetriever.java` |
| `KnowledgeEvidencePostProcessor` | `src/main/java/com/superbiz/agent/service/KnowledgeEvidencePostProcessor.java` |
| `KnowledgeContextPacker` | `src/main/java/com/superbiz/agent/service/KnowledgeContextPacker.java` |
| `LookupResultAssembler` | `src/main/java/com/superbiz/agent/service/LookupResultAssembler.java` |
| `RetrievalScoreNormalizer` | `src/main/java/com/superbiz/agent/service/retrieval/RetrievalScoreNormalizer.java` |
| `RrfFusion` | `src/main/java/com/superbiz/agent/service/retrieval/RrfFusion.java` |
| `MilvusHybridKnowledgeStore` | `src/main/java/com/superbiz/agent/service/milvus/MilvusHybridKnowledgeStore.java` |
| `RagResultProjector` | `src/main/java/com/superbiz/agent/harness/tool/projection/RagResultProjector.java` |
| 审计链路 | `src/main/java/com/superbiz/agent/harness/audit/`（RagLookupAuditEnricher / JpaToolInvocationAuditSink） |
| 离线评测 | `eval/rag-retrieval/` + `scripts/eval_rag_retrieval.py` |