SuperBizAgent-java/mvp/architecture/modular-rag-pipeline.md

模块化 RAG Pipeline 架构

更新日期：2026-07-06 状态：当前已实现架构 关联 OpenSpec：openspec/changes/archive/2026-07-06-modular-rag-pipeline

1. 定位

本文记录 lookup_knowledge 的当前模块化 RAG 实现。它是 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. 当前链路

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：

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 降级策略保持简单：

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 当前核心字段：

found
evidenceBlocks
contextPack
retrievalTrace
rerankTrace
relevanceLevel
completenessHint
retrievedDomainsThisSession
message

旧字段已删除：

primary
supplement

这是一项 L4 breaking interface change。项目内已同步迁移：

• LookupKnowledgeTool
• ToolInvocationRecorder
• executor prompts
• lookup / recorder tests
• RAG architecture docs
• OpenSpec 主 spec

6. Trace 结构

retrieval_details 保持 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. 验证

已执行：

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。