osiman/SuperBizAgent-java

Fork 0

Files

T

zhuyongxin 841437fa06 docs(mvp): organize mvp documentation

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

10 KiB

Raw Blame History

RAG 检索重构计划

状态：待规划
严重程度：高
发现时间：2026-07-05
范围：RAG、检索、知识库、Agent Tool、AIOps 诊断证据链

目标

将当前自研 RAG MVP 重构为“成熟框架能力 + 业务可观测编排”的架构：

Agent
  -> lookup_knowledge Tool
      -> L0 domain/entity hint
      -> query augmentation / transformer
      -> Spring AI Retriever / VectorStore
      -> metadata filter
      -> document postprocess
      -> neighbor / section expansion
      -> evidence packing
      -> tool_invocation record

核心原则：

通用 RAG 基础设施尽量交给 Spring AI / Spring AI Alibaba。
Agent 工具入口、AIOps 业务语义、证据追踪继续保留在项目内。
不把系统改成隐式 Chat RAG，仍然保留显式 lookup_knowledge 工具调用。
分阶段迁移，避免一次性推倒当前可运行链路。

当前问题汇总

当前 RAG 已经打通上传、切片、向量化、L0/L1 召回和工具调用记录，但主要问题集中在：

检索基础设施偏自研
- Milvus 写入和查询直接使用 SDK。
- topK、threshold、metadata filter、结果结构由业务代码维护。
- 后续接入 Spring AI RAG 能力会有重复适配成本。
L0 职责过重
- 当前 L0 可能被当成最终召回决策。
- 关键词质量不稳定时容易误召回。
- 更适合作为 domain/entity hint，而不是最终答案来源。
query 构造不稳定
- 主要依赖 Agent 传入原始 query。
- AIOps payload 中的 alertName、service、metric、symptom 没有稳定进入检索 query。
上下文重建不足
- 同章节被切成多个 chunk 后，命中片段不会自动扩展前后文。
- breadcrumb 存在 metadata 中，但没有充分参与 embedding、filter 或 context packing。
缺少检索后处理
- 缺少统一 evidence block。
- 缺少去重、token budget、hitReason、source 结构化输出。
缺少量化评测
- 目前主要靠接口回放、日志和 tool_invocation 人工判断。
- 还没有 golden query set、Recall@K、MRR、NDCG 等检索评测。

保留设计

这些设计值得保留，并作为重构后的项目亮点：

1. `lookup_knowledge` 显式 Agent Tool

保留显式工具调用，不直接用隐式 Advisor 取代。

原因：

面试项目重点是 Agent 工程，不是普通 Chat RAG。
显式工具调用能展示 Agent 何时检索、检索了什么、证据如何支撑诊断。
tool_invocation、evidence score、diagnosis session 都依赖这条链路。

2. L0

保留 L0，但降级为：

domain detector
entity extractor
metadata filter generator
explainability signal

不再默认执行：

L0 unique hit -> 直接返回

目标职责：

query / payload
  -> L0 matched keywords/entities/domain
  -> metadata filter + query augmentation
  -> retriever

3. metadata

保留并加强 metadata：

docId
chunkIndex
totalChunks
title
breadcrumb
category
source

后续可扩展：

sectionId
parentSection
documentType
domain
tags
version

metadata 是 filter、上下文扩展、证据追踪、可解释性的基础。

4. Markdown-aware chunking

保留当前 Markdown 结构化切片思路：

识别标题层级
生成 title
生成 breadcrumb
保留 chunkIndex
尽量不打断列表和代码块

可以替换或复用框架能力的是底层 token 长度控制和 overlap 策略，而不是完全抛弃结构化切片。

5. `tool_invocation` 证据追踪

保留并增强：

sessionId
query
rewrittenQuery
matchedKeywords
domain/entities
retrievedDocs
scores
hitReasons
evidence
duration
relevanceLevel

这是后续检索评测、诊断质量评估、面试讲解的基础。

6. AIOps payload 到 query 的业务映射

保留 AIOps 场景逻辑：

alertName
service
metric
symptom
category/domain

这些是业务语义，不能完全交给通用框架隐式处理。

替换设计

这些能力适合逐步交给 Spring AI / Spring AI Alibaba：

当前能力	目标能力	说明
Milvus SDK 直接写入/查询	Spring AI `VectorStore`	减少基础设施代码
自研 `VectorSearchService` 检索细节	`VectorStoreDocumentRetriever`	标准化 topK、threshold、filter
手写 query 拼接	Query Transformer / 模板化 query augmentation	先规则化，后框架化
手写结果拼接	DocumentPostProcessor / evidence postprocess	做去重、压缩、证据块
L0 最终召回判断	L0 domain/entity hint	降低误召回风险

分阶段计划

Phase 0：重构前基线

目标：先固定当前行为，避免重构后不知道是否变好。

任务：

固化 10-20 条 golden queries。
覆盖 Chat 和 AIOps 场景。
每条 query 标注 expected doc、breadcrumb、关键 chunk 或 evidence。
用当前链路跑一遍，记录 baseline。
初始离线基线落在 eval/rag-retrieval/，用于后续 change 对比。

验收：

有可重复运行的检索回放清单。
能记录当前 Recall@K、first hit rank 或人工 hit level。

Phase 1：L0 降级为 domain/entity hint

目标：保留 L0 价值，降低 L0 误决策风险。

任务：

KnowledgeIndexService 输出 matched keywords、domain、entities。
LookupKnowledgeTool 不再把 L0 unique hit 作为默认最终结果。
将 L0 结果用于 query augmentation 和 metadata filter。
tool_invocation 记录 L0 hit reason。

验收：

L0 命中不会绕过向量检索直接返回。
检索记录能看到 domain/entities/matchedKeywords。
AIOps payload 能生成稳定领域 hint。

Phase 2：Evidence Postprocess 和上下文打包

目标：先提升 Agent 实际拿到的证据质量。

任务：

定义 evidence block：

source
docId
chunkIndex
title
breadcrumb
score
hitReason
content
expandedFrom

对检索结果做去重。
支持命中 chunk 的相邻 chunk / 同章节扩展。
加 token 或字符预算控制。
返回给 Agent 的内容按 evidence block 组织。

验收：

同一 docId/chunkIndex 不重复进入上下文。
命中 chunk 可以补充前后文。
tool_invocation 记录 postprocess 前后候选数量和最终 evidence 数量。

Phase 3：Spring AI VectorStore 旁路验证

目标：验证框架能力，不直接替换主链路。

任务：

引入 Spring AI Milvus VectorStore。
建立旁路 SpringAiVectorSearchService 或适配层。
同一批 golden queries 同时跑旧链路和新链路。
对比 topK、metadata、score、filter 行为。

验收：

旁路检索可跑通。
metadata 不丢失。
查询结果与当前链路差异可解释。
不影响现有 Chat / AIOps 主链路。

Phase 4：替换底层 VectorSearchService

目标：对外接口不变，内部检索切到 Spring AI VectorStore / Retriever。

任务：

保持 LookupKnowledgeTool 调用方式不变。
VectorSearchService 内部迁移到 Spring AI 检索抽象。
支持 topK、similarity threshold、category metadata filter。
保留旧实现一段时间作为 fallback。

验收：

Chat / AIOps 检索链路行为兼容。
golden queries 不低于 baseline。
检索结果仍能完整记录到 tool_invocation。

Phase 5：Query Transformer 和框架化 PostProcessor

目标：在稳定的 VectorStore 基础上接入更成熟 RAG 能力。

任务：

AIOps 场景优先使用模板化 query augmentation。
需要时接入 Spring AI Query Transformer / MultiQuery。
将现有 evidence postprocess 抽象成 DocumentPostProcessor 风格。
可选接入 rerank，但不作为第一优先级。

验收：

原始 query 和 rewritten query 都可追踪。
query rewrite 失败可以 fallback。
postprocess 行为可配置、可记录、可回放。

暂不做

以下能力暂不进入近期重构：

不做完整自研 RRF 框架。
不直接把 lookup_knowledge 替换成隐式 Advisor。
不一口气迁移所有 RAG ETL。
不先引入 Elasticsearch / OpenSearch，除非评测证明 BM25 必须。
不先上 cross-encoder / LLM rerank，先做规则型 evidence postprocess。

风险

1. Milvus schema 兼容风险

当前 collection 是项目自建，Spring AI VectorStore 可能有自己的 schema 假设。需要旁路验证。

2. 检索行为变化风险

框架检索分数和当前 L2 score 可能不完全一致，需要 golden queries 对比。

3. 可观测性丢失风险

如果迁移到隐式 Advisor，可能丢失工具调用证据链。因此 Spring AI RAG 能力应优先封装在 lookup_knowledge 内部。

4. 重构范围膨胀风险

RAG、Agent、AIOps、数据库记录互相关联，必须分阶段推进，每阶段都保持可运行。

合并来源

本计划合并以下问题和改造方向：

10 KiB Raw Blame History Unescape Escape