@@ -0,0 +1,336 @@
# RAG 证据链探索笔记：从 py-rag 响应到引用验真
**日期 ** ：
**范围 ** ：RAG 模块抽离后的完整数据链路——每个站点"数据长什么样、字段怎么来、为什么这样设计"
**读者 ** ：要理解或维护 `lookup_knowledge` 证据链的工程同学
**关联文档 ** ：
- 架构规范：[../../architecture/RAG知识检索架构.md ](../../architecture/RAG知识检索架构.md )（本次抽离后的权威口径）
- Trace / 审计：[../../architecture/RAG检索可观测性与审计.md ](../../architecture/RAG检索可观测性与审计.md )
- 契约原文：py-rag 仓库 `docs/Java接入文档.md` （
- 前置知识：`RAG-Hybrid质量分与后处理.md` （分数语义演进史）
> 本文按一次真实代码探索的顺序组织：从 py-rag 返回的 JSON 出发，沿着数据走过的每一站，
> 讲清关键字段、加工规则与设计取舍，最后到 Agent 引用验真收口。
---
## 0. 全景路线图
``` text
py-rag JSON ──► KnowledgeSearchHit 站点1-2：数据形态与防腐层映射
│
① 后处理 ──► EvidencePostprocessResult 站点3：去重/限流/判级
│
② 打包 ──► ContextPack 站点4：文本储备（非 Agent 口粮）
│
③ 组装 ──► LookupResult 站点5：内部真相全集
│
④ 投影 ──► RagToolResult ──► Agent 站点6-7：冻结契约与 Agent 视图
│
⑤ Agent 写报告引用 toolCallId
│
⑥ EvidenceGuard 对账验真 ──► 语义审查 ──► 发布 站点8：证据安全链
（旁路：每站关键字段 ──► tool_invocation 审计表，供人排障）
```
一句话定位：**py-rag 负责"把对的片段找出来"，Java 侧负责"把找到的证据管起来"**；
检索质量可以整体外换，证据治理一寸不动——这次抽离（71 文件 / 约 -8000 行）本身就是证明。
---
## 1. 站点一：py-rag 返回的数据结构
响应 JSON 按职责分四块，四块数据两条去路（①②③喂后处理，④喂审计）：
``` json
{
"query" : "网关超时怎么排查" , // ① 入参回显
"mode" : "hybrid" , // ① 查询模式（hybrid | semantic）
"hits" : [ // ② 命中数组（检索的基本单位是 chunk）
{
"evidence_key" : "e2e-gateway-b9c1fa12-md-34223174#chunk-1" , // chunk 级身份
"document_id" : "e2e-gateway-b9c1fa12-md-34223174" , // 所属文档
"source" : "e2e-gateway-b9c1fa12-md" , // 来源路径
"title" : "网关超时排查" ,
"breadcrumb" : "网关超时排查 > 处理步骤" ,
"excerpt" : "网关超时先检查 upstream 配置…" , // 正文
"quality_score" : 0.9147 , // rerank 绝对分
"relevance_level" : "PRECISE" // py-rag 自己的判级（Java 不用）
}
] ,
"relevance_level" : "PRECISE" , // ③ 顶层判级（top1）
"evidence_status" : "supported" , // ③ 业务状态
"retrieval_trace" : { // ④ 过程记录（不参与后处理，进审计）
"mode" : "hybrid" , "filters" : { "category" : "gateway" } ,
"recall_count" : 20 , "rerank_model" : "BAAI/bge-reranker-v2-m3" ,
"no_evidence_basis" : null
}
}
```
关键语义：
- **`evidence_status` 只有两类**： `supported` （正常）/ `no_evidence` （查到了但都是垃圾或无候选，
此时 `hits` 恒为空）。它是 **200 正常业务响应 ** ，Java 侧直接走"无知识可用"分支，不重试不报错。
- **`relevance_level` 是分数的档位化**： `quality_score ≥0.75 → PRECISE` ， `≥0.5 → REFERENCE` ，
`<0.5` 不输出。阈值当前未校准（契约已知边界）。**它是给模型的，分数是给系统的**——
同一信息两种表达，服务两种消费者。
- **命中没有独立 metadata map**（旧 Milvus 方案遗留概念），文档归属信息就是那几个平铺字段。
---
## 2. 站点二：防腐层映射——`KnowledgeSearchHit`
`PyRagKnowledgeSearchAdapter` 把每个 hit 映射成可移植结构。从此全 Java 侧只认这个类型，
py-rag 字段再怎么变只改 adapter 一处。后处理实际只消费其中 **7 个字段 ** ：
``` text
evidenceKey → 去重键（docId#chunk-N，原样采纳）
docId / chunkIndex → 文档分桶（单文档上限）；chunkIndex 从 "#chunk-N" 解析
content ← excerpt，最终证据正文
score + scoreLabel ← quality_score + 常量 "rerank"（
originalRank ← 数组下标 +1，排序的权威
source / title / breadcrumb → 透传展示
```
`retrieval_trace` 不进这条链——它走审计旁路。**进入后处理时，每个 hit 被浓缩成
"身份 + 分数 + 名次 + 正文"四组信息，四步加工全部围绕它们转。**
---
## 3. 站点三：后处理四步——`EvidencePostprocessResult`
``` text
① 打分 score + scoreLabel → qualityScore（ ）
② 排序 只按 originalRank —— ★ 分数不参与排序，只用于判级
③ 去重截断 evidenceKey 去重 → 单文档 chunk ≤2 → 总数 ≤5（ ）
④ 判级 顶分 ≥0.75 PRECISE / ≥0.5 REFERENCE / 否则无档
```
输出结构逐字段（7 条命中进、5 块存出的例子）：
| 字段 | 规则 | 例值 |
|---|---|---|
| `candidateCount` | 输入候选数 | 7 |
| `evidenceBlockCount` | 存活块数（差值 = 被治理掉的） | 5 |
| `topSimilarity` | 排序后第一名的 qualityScore | 0.91 |
| `relevanceLevel` | Java 按本地阈值独立判定（**不用 py-rag 返回的档位**，那个字段映射时已丢弃） | PRECISE |
| `completenessHint` | 档位绑定的天花板提示文案 | "知识库中不存在比上述结果更精准的文档" |
| `rerankTrace[]` | 每个**存活**块的最终序账本 | finalRank 1~5 |
### 3.1 去重辨析：三条规则别混淆
| 层 | 键 | 规则 | 目的 |
|---|---|---|---|
| 去重 | `evidenceKey = docId#chunk-N` | 同一块再现 → **合并 ** （
| 单文档上限 | `docId` （分桶） | 同文档**不同** chunk 可共存，最多 2 | 防单文档刷屏 |
| 总条数 | — | 最多 5 | 上下文预算 |
**合并键是 evidenceKey 而不是 docId ** ——同文档的第 0 段和第 1 段是两份不同证据，按 docId
合并会把多片段证据文档级折叠掉。单次检索正常不会返回同一个 chunk 两次（每个 chunk 是唯一
索引条目），合并分支是给"索引脏数据 / 未来多路归并"准备的**防御性兜底**，成本一次 map 查询。
### 3.2 为什么会同文档多块命中——根源在分块
入库时文档切成多个 chunk，每块独立 embedding、独立索引；检索按 chunk 算相似度。
这是刻意的颗粒度选择：整篇文档一个向量会稀释语义，且上下文也塞不下全文。
**切块是为了检索得准、取得少；同文档多块命中是切块的自然结果；
"chunk 级身份 + 单文档上限"就是为管理这个现象而生的。**
### 3.3 `rerankTrace`：最终序账本
``` java
Item { finalRank ; source ; baseScore ; finalScore ; boostReasons }
```
- 条数 = 存活块数（finalRank 连续编号）；被合并/截断的块不产生条目；
- `baseScore == finalScore` **恒相等 ** ——双字段是规则加分时代的化石（当年关键词加分，
现已废除防操纵）；`boostReasons` 同理，装的已是纯解释标签；
- 只记到**文档级**（无 evidenceKey），chunk 身份要看 `evidenceBlocks[]` ；
- Agent 看不到它，审计默认不落库——活在内存 LookupResult 与评测快照里。
### 3.4 附带闸门
`isLowQuality()` ：无可用块或顶分 <0.5 即低质。原触发 filtered→unfiltered 重试，
L0 下沉后分支休眠、闸门保留——将来 Java 侧重引过滤策略可直接接上。
---
## 4. 站点四：打包——`ContextPack`（不是 Agent 口粮）
`KnowledgeContextPacker` 把证据块压成**一段有字符预算的文本**（默认 4000 字符）：
``` text
策略 ranked_evidence_char_budget：名次即优先级，先到先得
[Evidence 1]
source: gateway-timeout.md
breadcrumb: 网关超时排查 > 处理步骤
reasons: semantic_rank:1, attempt:UNFILTERED_VECTOR ← 召回溯源标签
content:
网关超时先检查 upstream 配置…
预算见底：装得下 header → 正文截断加 "..."；连 header 都放不下 → 整条进 omittedSources
```
``` java
ContextPack { packedText ; strategy ; charBudget ; usedChars ; includedSources ; omittedSources }
```
**必须澄清的定位 ** ：主诊断链路里 **Agent 不消费 packedText ** （主代码零调用）——Agent 拿的是
站点六投影后的结构化列表。它的价值：人工回放可读、评测快照存证、以及将来任何
"证据进 prompt"路径的现成格式化出口（字符预算是与后处理"块数预算"互补的物理闸门）。
`reasons:` 行是证据的"简历"： `semantic_rank:N` （本次检索第几名）+ `attempt:X` （哪次尝试产出，
当前只剩 `UNFILTERED_VECTOR` ；历史值 `FILTERED_VECTOR` / `UNFILTERED_VECTOR_RETRY` 已随
L0 下沉绝迹）。
> 小化石：`ContextPack` 的 javadoc 仍写 "Agent-facing"，与 packer 侧注释矛盾——
> 它诞生时确实面向 Agent，投影路线成为主路径后退居内部，注释没跟上身份变化。
---
## 5. 站点五：组装——`LookupResult` 真相全集
`LookupResultAssembler` 把三样东西合体成内部契约出口：
``` text
EvidencePostprocessResult（证据集+档位+trace）┐
ContextPack（打包文本） ├─► LookupResult
RetrievalTrace（检索路径） ┘
```
只有两个字段是"算"出来的：`found = hasUsableEvidence()` （
"知识库未检索到可用证据，请结合日志、指标、告警继续排查"）；两个 count 把"进多少/出多少"
带给审计。其余字段一一搬运。
---
## 6. 站点六：投影——`RagResultProjector`（加工链最后一站）
**输入是 LookupResult 的 JSON 字符串而非对象 ** ——内部结构随便演化，冻结契约纹丝不动，
解耦的关键就是这层"字符串边界"（字段名还带防御性别名对：`evidenceBlocks` /`evidence_blocks` ）。
``` text
① query 截断（≤500 字） 动了 → truncated
② 逐块过三道闸：
条数 ≤8（超出 truncated+停止）
身份去重（evidenceKey → document_id → docId#chunk-N → 序号兜底 的回退链）
摘录 ≤1200 字（截断 → truncated）
③ evidence_status 客观判定：数组空不空（EVIDENCE_FOUND / NO_EVIDENCE）
④ relevance_level：有证据才读，解析不出 → null
⑤ fitBudget 总字节兜底：整个 JSON 超 16KB → 从尾部逐条裁
裁到空 → 诚实降级 NO_EVIDENCE；还超 → 抛异常（fail closed）
```
**三道递进预算闸 ** （条数管语义 / 片段管局部 / 字节管整体）集中在 `ToolProjectionLimits`
一个 record（ `truncated` 只要任何一处
动过就置位——Agent 永远知道"看到的可能不全"**，不会把截断结果当全量。
---
## 7. 站点七：Agent 视图——模型实际看到的 JSON
``` json
{
"evidence_status" : "EVIDENCE_FOUND" ,
"tool_call_id" : "call_x1" ,
"query" : "网关超时怎么排查" ,
"evidence" : [
{ "document_id" : "e2e-gateway-…-34223174#chunk-1" ,
"source" : "e2e-gateway-b9c1fa12-md" ,
"title" : "网关超时排查" ,
"breadcrumb" : "网关超时排查 > 处理步骤" ,
"excerpt" : "网关超时先检查 upstream 配置…" }
] ,
"returned_count" : 5 ,
"relevance_level" : "PRECISE" ,
"truncated" : false
}
```
| 字段 | 模型的正确用法 |
|---|---|
| `evidence_status` | `NO_EVIDENCE` → 老实换工具（日志/指标/MySQL），不许编 |
| `evidence[].excerpt` | 结论唯一的内容依据 |
| `evidence[].document_id` | **引用坐标 ** ——报告里逐字引用它，EvidenceGuard 只认这个 |
| `relevance_level` | PRECISE 可放心下结论；REFERENCE 结合上下文判断，必要时说清还缺什么维度 |
| `truncated` | true → 看到的可能不全，可收窄 query 重搜 |
**三个"看不到" ** ：分数（防未校准数字诱导过度自信）、过程（attempt/trace 留给人）、
其他站的内部字段。一句话：**留坐标、留内容、留诚实，剥掉一切会误导或撑爆上下文的东西。**
---
## 8. 站点八：验真——`EvidenceGuard`（证据安全链第一道闸）
Agent 写完诊断产出结构化草稿 `DiagnosisDraft` （ ，
conclusion/action_plan 带 basedOnAnalysisIds，
``` text
A 结构校验 id 唯一、正文非空、报告引用必须指向已登记分析、limitations 必填
B 引用验真 runId+toolCallId → Redis 账本可查 → READY 状态 → 同 Run（防跨 Run 挪用）
→ kind 语义匹配：NORMAL↔EVIDENCE_FOUND / NEGATIVE_OBSERVATION↔NO_EVIDENCE
C 重读重建 从账本严格反序列化投影（多一个字段都违规）→ 用账本内容重建证据快照
```
四个设计点：
1. **证据内容从账本重读，不信模型复述 ** ——模型转述的"检索结果"进不了快照；
2. **kind 匹配堵两头撒谎 ** ——"查到了装没查到"与"没查到装查到了"都过不去；
3. **runId 绑定 + READY ** ——别的 Run 的证据、失败/过期的调用不可引用；
4. **纯规则、20 个违规码全枚举 ** ——便宜、确定、可审计；"结论是否夸大"留给下一道
SemanticGuard，这里只回答"引用是否真实、结构是否合法"。
---
## 9. 附：模型怎么知道要输出那份 JSON
四层合力，没有一刻依赖模型"自觉"：
| 层 | 机制 |
|---|---|
| 格式 | `DiagnosisDraftOutputSchema` （
| 语义 | `diagnosis-agent-prompt.md` ：证据充分 → 全填并建立完整引用链；证据不足 → `conclusion=null` 是合法成功（schema 层把 conclusion 类型改成 `object\|null` ）；limitations 无条件必填 |
| 时机 | 模型自主停止（无有效查询范围即停）+ Harness 强制（连续 NO_GAIN / 预算耗尽 → STOP_REQUIRED 后必须直接交卷） |
| 兜底 | 格式错/引用违规 → evidence-repair-prompt 修复重试 → 仍败 → 固定降级 FALLBACK |
---
## 10. 设计思路总结（五条哲学）
1. **防腐层：换引擎不换证据链 ** ——`KnowledgeSearchPort` 是接缝，抽离时消费面零改动、
250 个测试原样通过，这是接口设计价值的最硬证明。
2. **分数给系统，档位给模型 ** ——未校准的连续分数会诱导过度自信；`quality_score` 在
Java 侧做闸门和审计，Agent 只见 PRECISE/REFERENCE。
3. **chunk 级身份贯穿始终 ** ——入库分块、检索按块、去重按 `docId#chunk-N` 、引用坐标到块、
验真对块。颗粒度统一，才有多片段证据共存与伪引用无处遁形。
4. **诚实标记 ** ——`truncated` 、`no_evidence` 、`unchanged` 、`no_evidence_basis` ：
系统从不假装"看到的即全部"，每个不完整/为空都有显式信号与原因。
5. **所见即所证 ** ——投影结果是"模型看到的"与"Redis 存证的"同一份；EvidenceGuard 对账
没有翻译损耗，伪引用无处遁形。
### 化石清单（读代码时的辨认指南）
| 化石 | 现状 |
|---|---|
| `RerankTrace.baseScore/finalScore` 双字段 | 恒相等（规则加分已废），保留兼容旧审计格式 |
| `boostReasons` 字段名 | 装的是纯解释标签，不再加分 |
| `ContextPack` javadoc "Agent-facing" | 身份已变（内部/储备），注释未跟上 |
| `LookupResultAssembler.deduped()` | 会话级去重回包的历史占位，主链路不再调用 |
| `FILTERED_VECTOR` / `UNFILTERED_VECTOR_RETRY` attempt | L0 下沉后不可达，仅存于旧 Run 回放 |
| `KnowledgeQuery` 的 L0 hint 字段 | 恒空结构，供后处理与 trace 兼容保留 |
---
## 11. 关键字段速查
| 字段 | 哪一站 | 一句话 |
|---|---|---|
| `evidence_key` | py-rag → 全程 | chunk 级身份 `docId#chunk-N` ，去重与验真的锚 |
| `quality_score` | py-rag → 后处理 | rerank 绝对分 [0,1]，
| `evidence_status` | py-rag / 投影 | 两类：supported / no_evidence（正常业务响应） |
| `relevance_level` | 后处理 → Agent | PRECISE/REFERENCE 档位，Java 按本地阈值独立判定 |
| `originalRank` | adapter → 后处理 | 排序唯一权威，分数不动序 |
| `candidateCount / evidenceBlockCount` | 后处理 | 进多少 / 出多少，差值即治理幅度 |
| `truncated` | 投影 | 任何截断都置位，诚实标记 |
| `tool_call_ids` | Draft → EvidenceGuard | 引用验真的入口，runId 绑定 + READY 校验 |
zhuyongxin