feat(rag): modularize knowledge retrieval pipeline

2026-07-06 17:06:05 +08:00
parent a375daead7
commit cf3333d607
38 changed files with 2981 additions and 1033 deletions
@@ -0,0 +1,201 @@
+# 模块化 RAG Pipeline 架构
+
+**更新日期**：2026-07-06
+**状态**：当前已实现架构
+**关联 OpenSpec**：`openspec/changes/archive/2026-07-06-modular-rag-pipeline`
+
+## 1. 定位
+
+本文记录 `lookup_knowledge` 的当前模块化 RAG 实现。它是 [rag-architecture.md](rag-architecture.md) 的落地版，重点说明代码模块、数据契约、降级策略和可观测性边界。
+
+核心目标：
+
+- 保留显式 Agent Tool：`lookup_knowledge(query)`。
+- L0 只作为 query understanding / filter / rerank / trace hint。
+- L1 向量检索作为事实证据来源。
+- filtered L1 低质量时，降级为 raw query unfiltered L1 retry。
+- 输出 evidence-first contract，替代旧 `primary/supplement`。
+
+## 2. 当前链路
+
+```mermaid
+flowchart TD
+    Agent["Executor Agent"] --> Tool["LookupKnowledgeTool.lookupKnowledge(query)"]
+
+    Tool --> Transform["KnowledgeQueryTransformer"]
+    Transform --> KQ["KnowledgeQuery"]
+
+    KQ --> Retriever["KnowledgeDocumentRetriever"]
+    Retriever --> Attempt1["FILTERED_VECTOR or UNFILTERED_VECTOR"]
+    Attempt1 --> Post1["KnowledgeEvidencePostProcessor"]
+    Post1 --> Quality{"usable evidence?"}
+    Quality -->|yes| Pack
+    Quality -->|no and categoryFilter exists| Retry["UNFILTERED_VECTOR_RETRY"]
+    Retry --> Post2["KnowledgeEvidencePostProcessor"]
+    Post2 --> Pack["KnowledgeContextPacker"]
+
+    Pack --> Assemble["LookupResultAssembler"]
+    Assemble --> Result["LookupResult"]
+    Result --> Dedup["RetrievedDocTracker session dedup"]
+    Dedup --> Recorder["ToolInvocationRecorder"]
+    Recorder --> Trace["tool_invocation.retrieval_details"]
+    Result --> Agent
+```
+
+对应代码：
+
+| 阶段 | 类 | 职责 |
+|---|---|---|
+| Tool Boundary | `LookupKnowledgeTool` | 接收 Agent 工具调用，编排 pipeline，处理 session dedup 和 recorder |
+| Query Transformation | `KnowledgeQueryTransformer` | 复用 L0，输出 query hints 和可选 category filter |
+| Retrieval | `KnowledgeDocumentRetriever` | 调用 `VectorSearchService`，统一 filtered / unfiltered attempt |
+| Post-Retrieval | `KnowledgeEvidencePostProcessor` | L2 归一化、证据块构建、source dedup、规则 rerank |
+| Context Packing | `KnowledgeContextPacker` | 按字符预算打包 Agent 可消费 context |
+| Result Assembly | `LookupResultAssembler` | 统一 evidence result、no-evidence result、dedup result |
+| Observability | `ToolInvocationRecorder` | 写入 query transform、retrieval trace、rerank trace、context pack summary |
+
+## 3. L0 与 L1 边界
+
+L0 来源于 `KnowledgeIndexService.analyzeQuery`，输出进入 `KnowledgeQuery`：
+
+```text
+originalQuery
+rewrittenQuery
+domainHints
+matchedKeywords
+entities
+categoryFilter
+l0Titles
+l0MatchCount
+```
+
+L0 可以做：
+
+- 给 L1 提供单一 category filter。
+- 给 rerank 提供 domain / keyword / entity boost 信号。
+- 给 trace 提供解释信息。
+
+L0 不再做：
+
+- 不因唯一命中直接返回文档正文。
+- 不在 L1 无结果时作为事实证据兜底。
+- 不进入 `evidenceBlocks`，除非未来明确引入新的 evidence source 规则。
+
+L1 通过 `VectorSearchService.searchSimilarDocuments(query, topK, category)` 执行，内部仍保留 Spring AI VectorStore 优先和 Milvus SDK fallback。
+
+## 4. 降级策略
+
+MVP 降级策略保持简单：
+
+```text
+if categoryFilter exists:
+    run FILTERED_VECTOR
+    if empty / no evidence / top similarity < referenceThreshold:
+        run UNFILTERED_VECTOR_RETRY with original query
+else:
+    run UNFILTERED_VECTOR
+```
+
+fallback reason：
+
+| reason | 含义 |
+|---|---|
+| `filtered_vector_no_evidence` | filtered L1 无候选或 post-processing 后无 evidence |
+| `filtered_vector_low_quality` | filtered L1 有候选，但 top normalized similarity 低于 `retrieval.normalization.reference-threshold` |
+
+当 retry 后仍无证据：
+
+- `found=false`
+- `evidenceStatus=no_evidence`
+- 保留 `retrievalTrace`
+- 不返回 L0 文档作为事实证据
+
+## 5. Evidence-First Contract
+
+`LookupResult` 当前核心字段：
+
+```text
+found
+evidenceBlocks
+contextPack
+retrievalTrace
+rerankTrace
+relevanceLevel
+completenessHint
+retrievedDomainsThisSession
+message
+```
+
+旧字段已删除：
+
+```text
+primary
+supplement
+```
+
+这是一项 L4 breaking interface change。项目内已同步迁移：
+
+- `LookupKnowledgeTool`
+- `ToolInvocationRecorder`
+- executor prompts
+- lookup / recorder tests
+- RAG architecture docs
+- OpenSpec 主 spec
+
+## 6. Trace 结构
+
+`retrieval_details` 保持 JSON 扩展，不改表结构。关键内容：
+
+```json
+{
+  "query_transform": {},
+  "retrieval_trace": {
+    "selected_attempt": "UNFILTERED_VECTOR_RETRY",
+    "fallback_reason": "filtered_vector_no_evidence",
+    "attempts": []
+  },
+  "context_pack_summary": {},
+  "rerank_trace": {},
+  "evidence_blocks": []
+}
+```
+
+这样 Trace API、Verifier、Eval 可以继续从 `tool_invocation` 读取证据链。
+
+## 7. Review 修正
+
+归档前 review 发现：session dedup 命中时返回 `found=false`，但仍携带 `evidenceBlocks/contextPack`，可能导致 Agent 重复消费证据。
+
+当前行为已修正：
+
+- dedup result 不再返回可消费 evidence/context。
+- 保留 message、retrieval trace、relevance hint 和 retrieved domains。
+- 测试覆盖：`LookupKnowledgeToolTest.sessionDedupDoesNotReturnConsumableEvidenceAgain`。
+
+## 8. 验证
+
+已执行：
+
+```powershell
+mvn -q -DskipTests compile
+mvn -q "-Dtest=LookupKnowledgeToolTest,ToolInvocationRecorderTest" test
+$env:MILVUS_TOKEN = <application.yml 中的 milvus.token>; mvn -q test
+openspec validate --all --strict
+git diff --check
+```
+
+结果：全部通过。
+
+注意：
+
+- `MilvusConnectionTest` 直接读 `MILVUS_TOKEN` 环境变量，不读 Spring 配置。
+- 完整测试需要在 Maven 进程里注入该环境变量。
+
+## 9. 后续演进
+
+建议后续按评测结果推进，而不是先堆复杂能力：
+
+- 增加 RAG eval cases：固定 query、期望 source、期望 fallback path。
+- 引入更严格的 evidence grounding 检查。
+- 当规则 rerank 不足时，再考虑 model-based rerank。
+- 当召回覆盖率不足时，再考虑 BM25/RRF/hybrid retrieval。