osiman/SuperBizAgent-java

Fork 0

Files

T

zhuyongxin 841437fa06 docs(mvp): organize mvp documentation

2026-07-09 13:40:08 +08:00

12 KiB

Raw Blame History

RAG 新架构

更新日期：2026-07-06 状态：当前主架构 + 后续演进边界
关联计划：mvp/issues/active/rag-refactor-plan.md

1. 架构目标

RAG 重构的目标不是把所有能力交给框架，也不是继续维护一套完全自研检索框架，而是形成：

成熟框架能力 + 业务可观测编排

具体原则：

通用向量检索能力交给 Spring AI VectorStore。
项目保留 Agent Tool 入口、AIOps 业务 query 映射、证据打包、trace 记录。
lookup_knowledge 继续是显式工具，不替换成隐式 Advisor。
Spring AI 读取路径作为主路径，Milvus SDK 作为 fallback。
所有检索行为必须可评测、可回放、可解释。

2. 当前主链路

flowchart TD
    Agent["Agent Executor"] --> Tool["lookup_knowledge(query)"]

    Tool --> L0["KnowledgeIndexService.analyzeQuery"]
    L0 --> Hint["L0 hint: domain / entities / matchedKeywords"]
    Hint --> Filter["category filter candidate"]

    Tool --> Search["VectorSearchService.searchSimilarDocuments"]
    Filter --> Search

    Search --> Mode{"retrieval.vector-store.mode"}
    Mode -->|auto| SpringTry["try Spring AI VectorStore"]
    SpringTry -->|success| Results["SearchResult list"]
    SpringTry -->|failure| SdkFallback["Milvus SDK fallback"]
    Mode -->|spring / spring-ai| SpringOnly["Spring AI VectorStore only"]
    Mode -->|sdk| SdkOnly["Milvus SDK only"]

    SpringOnly --> Results
    SdkFallback --> Results
    SdkOnly --> Results

    Results --> Retry{"filtered result usable?"}
    Retry -->|no| RetryL1["raw query unfiltered L1 retry"]
    Retry -->|yes| Post["post-retrieval processing"]
    RetryL1 --> Post
    Post --> Pack["context packing"]
    Pack --> Dedup["session dedup: RetrievedDocTracker"]
    Dedup --> Output["LookupResult: evidenceBlocks / contextPack / traces"]
    Output --> Record["tool_invocation record"]
    Output --> Agent

Agent Executor
  -> lookup_knowledge(query)
      -> KnowledgeIndexService.analyzeQuery
          -> L0 domain/entity hint
          -> matchedKeywords
          -> category filter candidate
      -> VectorSearchService.searchSimilarDocuments
          -> mode=auto
              -> Spring AI VectorStore
              -> fallback: Milvus SDK
          -> mode=spring / spring-ai
              -> Spring AI VectorStore only
          -> mode=sdk
              -> Milvus SDK only
      -> post-retrieval processing
          -> relevanceLevel
          -> completenessHint
          -> evidenceBlocks
          -> rerankTrace
      -> context packing
          -> contextPack
      -> session dedup
          -> RetrievedDocTracker
      -> tool_invocation record

运行配置：

retrieval.vector-store.mode=auto
retrieval.normalization.max-l2-distance=2.0
retrieval.normalization.highly-relevant-threshold=0.75
retrieval.normalization.reference-threshold=0.5

3. 稳定边界

flowchart LR
    subgraph AgentBoundary["Agent boundary"]
        Executor["Executor Agent"]
        Tool["LookupKnowledgeTool"]
    end

    subgraph RetrievalBoundary["Retrieval boundary"]
        Search["VectorSearchService"]
        Spring["Spring AI VectorStore"]
        SDK["Milvus SDK"]
    end

    subgraph ObservabilityBoundary["Observability boundary"]
        Invocation["tool_invocation"]
        Eval["RAG baseline / trace inspection"]
    end

    Executor --> Tool
    Tool --> Search
    Search --> Spring
    Search --> SDK
    Tool --> Invocation
    Invocation --> Eval

3.1 Agent 边界

Agent 只知道自己可以调用 lookup_knowledge，不直接关心底层是 Spring AI VectorStore 还是 Milvus SDK。

Executor -> LookupKnowledgeTool -> VectorSearchService

这个边界让 RAG 底层迁移不影响 Agent prompt、工具声明和 trace 数据结构。

3.2 检索边界

VectorSearchService 是当前检索门面：

auto：优先 Spring AI VectorStore，失败后 fallback 到 SDK。
spring / spring-ai：只走 Spring AI VectorStore。
sdk：只走原 Milvus SDK。

这样可以在不改 Agent 工具的情况下切换检索实现，并支持线上验证和回退。

3.3 可观测边界

无论底层检索路径如何变化，都必须写入 tool_invocation：

sessionId
toolName
inputParams
outputPreview
retrievalLayer
l0MatchCount
l1MatchCount
retrievalDetails
relevanceLevel
dedupReason
duration
success

4. L0 的新职责

旧版 L0 容易承担过重职责，例如唯一匹配后直接跳过 L1。当前架构中 L0 被降级为 hint 层。

flowchart TD
    Input["query / AIOps payload"] --> L0["L0 hint analysis"]
    L0 --> Domain["domain detector"]
    L0 --> Entity["entity extractor"]
    L0 --> Keyword["matched keyword explanation"]
    L0 --> Filter["metadata/category filter candidate"]

    Domain --> Retrieval["L1 semantic retrieval"]
    Entity --> Retrieval
    Keyword --> Trace["hit reason in tool_invocation"]
    Filter --> Retrieval

    Retrieval --> Normalize["relevance normalization"]
    Normalize --> Evidence["evidence returned to Agent"]

L0 负责：

domain detector
entity extractor
matched keyword explanation
metadata/category filter candidate
trace 中的 hit reason

L0 不再负责：

L0 unique hit -> 直接作为最终检索结果
L1 no result -> 返回 L0 文档作为事实证据

当前职责是：

query / AIOps payload
  -> L0 matched keywords / domains / entities
  -> category filter candidate
  -> filtered L1 semantic retrieval
  -> low-quality? raw query unfiltered L1 retry
  -> post-retrieval processing
  -> context packing

这样既保留精确关键词和领域 hint 的价值，也避免 L0 误召回直接污染最终证据。

5. L1 向量检索

L1 语义检索通过 VectorSearchService 调度。

flowchart TD
    Search["VectorSearchService"] --> Request["SearchRequest: query / topK / threshold / filter"]
    Request --> VectorStore["Spring AI VectorStore"]
    VectorStore --> Docs["Document results"]
    Docs --> Map["map to SearchResult"]
    Map --> Score["score compatibility mapping"]

    Search --> SDK["Milvus SDK fallback"]
    SDK --> SdkRows["id / content / metadata / L2 distance"]
    SdkRows --> Map

    Score --> Output["id / content / metadata / score / rawScore / scoreLabel"]

Spring AI VectorStore 路径

SearchRequest
  -> query
  -> topK
  -> similarityThresholdAll
  -> optional filterExpression: category == '...'
  -> VectorStore.similaritySearch

返回结果会映射为项目兼容结构：

id
content
metadata
score
rawScore
scoreLabel

Milvus SDK fallback

SDK 路径仍保留：

用于 auto 模式兜底。
用于与旧链路对比。
用于 VectorStore 配置或 collection schema 异常时保证 MVP 可运行。

6. 分数语义

旧 SDK 使用 L2 distance，Spring AI 返回 similarity。两者不能混用为同一个含义。

当前统一输出：

字段	含义
`score`	兼容旧逻辑的距离型分数，越小越近
`rawScore`	底层实现的原始分数
`scoreLabel`	`l2_distance` 或 `similarity`

SDK 路径：

score = L2 distance
rawScore = L2 distance
scoreLabel = l2_distance

VectorStore 路径：

rawScore = Spring AI similarity
scoreLabel = similarity
score = metadata.distance if available else compatible distance

7. 文档切片和 embedding 输入

当前保留 Markdown-aware chunking：

识别 Markdown 标题层级。
生成 title。
生成 breadcrumb。
保留 chunkIndex。
使用 token 估算和软/硬上限控制 chunk 大小。
尽量不打断列表和代码块。

embedding 输入中已经加强：

title + breadcrumb + content

这样可以降低单个 chunk 脱离章节上下文后的召回损失。

8. AIOps query 增强

AIOps payload 中的业务字段不能完全交给通用检索框架隐式理解。

payload 模式会把以下字段拼成推荐知识库 query：

alertName
service
severity
description
timeRange
userRequest

Prompt 会明确要求 Agent 在需要知识库证据时，优先使用推荐 query 或保留 alertName/service 的更窄 query。

AIOps payload
  -> buildKnowledgeRetrievalQuery
  -> Recommended lookup_knowledge query
  -> lookup_knowledge
  -> tool_invocation

9. Evidence 与去重

当前 evidence 输出已从旧 primary/supplement 迁移为 evidence-first contract，核心字段包括：

evidenceBlocks
contextPack
retrievalTrace
rerankTrace
relevanceLevel
completenessHint
retrievedDomainsThisSession
tool_invocation.retrieval_details

evidence block 结构：

source / title / breadcrumb / retrievalLayer / content / score / hitReasons

context pack 会按重排后的证据顺序生成 Agent 可消费的紧凑上下文，并保留 included/omitted sources 供 trace 检查。

10. 评测与验收

RAG 架构变更必须先过评测，再认为可合入主链路。

当前评测资产：

eval/rag-retrieval/cases/golden-cases.json
eval/rag-retrieval/fixtures/
eval/rag-retrieval/reports/baseline.json
eval/rag-retrieval/reports/baseline.md
scripts/eval_rag_retrieval.py
scripts/eval_rag_live_acceptance.py

评测层次：

层次	作用
Offline baseline	不依赖 MySQL、Redis、Milvus、LLM，用固定 fixtures 检查召回行为
Live acceptance	应用运行并重建索引后，调用 `/api/search/similar` 验证真实检索
Trace inspection	通过 `tool_invocation` 检查 Agent 是否真的使用了证据

11. 当前已完成

lookup_knowledge 保持显式 Agent Tool。
L0 降级为 domain/entity hint。
L1 默认执行语义检索。
VectorSearchService 支持 auto、spring/spring-ai、sdk 三种模式。
Spring AI VectorStore 成为读取主路径。
Milvus SDK fallback 保留。
分数语义拆成 score、rawScore、scoreLabel。
Markdown chunk 保留 title 和 breadcrumb。
embedding 输入包含 title、breadcrumb 和 content。
AIOps payload 生成推荐知识库 query。
tool_invocation 记录 relevance level、dedup reason、evidence summaries、retrieval trace、rerank trace 和 context pack summary。
lookup_knowledge 输出使用 evidence-first contract，不再暴露旧 primary/supplement 字段。
RAG offline baseline 和 live acceptance 脚本已补齐。

12. 后续演进

近期优先：

命中 chunk 的相邻 chunk / 同章节上下文扩展。
metadata taxonomy 清理，例如 database 与 infrastructure 的分类边界。
Query Transformer / MultiQuery 的可回退接入。
VectorStore 写入路径评估。

暂不优先：

把 lookup_knowledge 替换成隐式 Advisor。
完整自研 RRF 框架。
立即引入 Elasticsearch / OpenSearch。
立即引入 cross-encoder 或 LLM rerank。

13. 关键代码索引

能力	代码
Agent 工具入口	`src/main/java/com/superbiz/agent/tool/LookupKnowledgeTool.java`
L0 hint	`src/main/java/com/superbiz/agent/service/KnowledgeIndexService.java`
向量检索门面	`src/main/java/com/superbiz/agent/service/VectorSearchService.java`
文档切片	`src/main/java/com/superbiz/agent/service/DocumentChunkService.java`
文档管理	`src/main/java/com/superbiz/agent/service/DocumentManagementService.java`
向量写入	`src/main/java/com/superbiz/agent/service/VectorIndexService.java`
AIOps query 增强	`src/main/java/com/superbiz/agent/service/AiOpsService.java`
工具调用记录	`src/main/java/com/superbiz/agent/service/ToolInvocationRecorder.java`

12 KiB Raw Blame History Unescape Escape