osiman/SuperBizAgent-java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(mvp): organize mvp documentation

Browse Source
This commit is contained in:
zhuyongxin
2026-07-09 13:40:08 +08:00
parent 9c9a0024d4
commit 841437fa06
57 changed files with 452 additions and 675 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mvp/issues/active/rag-refactor-plan.md
+377
View File
@@ -0,0 +1,377 @@
# RAG 检索重构计划
**状态**：待规划
**严重程度**：高
**发现时间**：2026-07-05
**范围**：RAG、检索、知识库、Agent Tool、AIOps 诊断证据链
---
## 目标
将当前自研 RAG MVP 重构为“成熟框架能力 + 业务可观测编排”的架构：
```text
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
```
核心原则：
1. 通用 RAG 基础设施尽量交给 Spring AI / Spring AI Alibaba。
2. Agent 工具入口、AIOps 业务语义、证据追踪继续保留在项目内。
3. 不把系统改成隐式 Chat RAG，仍然保留显式 `lookup_knowledge` 工具调用。
4. 分阶段迁移，避免一次性推倒当前可运行链路。
---
## 当前问题汇总
当前 RAG 已经打通上传、切片、向量化、L0/L1 召回和工具调用记录，但主要问题集中在：
1. **检索基础设施偏自研**
- Milvus 写入和查询直接使用 SDK。
- topK、threshold、metadata filter、结果结构由业务代码维护。
- 后续接入 Spring AI RAG 能力会有重复适配成本。
2. **L0 职责过重**
- 当前 L0 可能被当成最终召回决策。
- 关键词质量不稳定时容易误召回。
- 更适合作为 domain/entity hint，而不是最终答案来源。
3. **query 构造不稳定**
- 主要依赖 Agent 传入原始 query。
- AIOps payload 中的 alertName、service、metric、symptom 没有稳定进入检索 query。
4. **上下文重建不足**
- 同章节被切成多个 chunk 后，命中片段不会自动扩展前后文。
- `breadcrumb` 存在 metadata 中，但没有充分参与 embedding、filter 或 context packing。
5. **缺少检索后处理**
- 缺少统一 evidence block。
- 缺少去重、token budget、hitReason、source 结构化输出。
6. **缺少量化评测**
- 目前主要靠接口回放、日志和 `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
不再默认执行：
```text
L0 unique hit -> 直接返回
```
目标职责：
```text
query / payload
-> L0 matched keywords/entities/domain
-> metadata filter + query augmentation
-> retriever
```
### 3. metadata
保留并加强 metadata：
```text
docId
chunkIndex
totalChunks
title
breadcrumb
category
source
```
后续可扩展：
```text
sectionId
parentSection
documentType
domain
tags
version
```
metadata 是 filter、上下文扩展、证据追踪、可解释性的基础。
### 4. Markdown-aware chunking
保留当前 Markdown 结构化切片思路：
- 识别标题层级
- 生成 `title`
- 生成 `breadcrumb`
- 保留 `chunkIndex`
- 尽量不打断列表和代码块
可以替换或复用框架能力的是底层 token 长度控制和 overlap 策略，而不是完全抛弃结构化切片。
### 5. `tool_invocation` 证据追踪
保留并增强：
```text
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：
```text
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 行为可配置、可记录、可回放。
---
## 暂不做
以下能力暂不进入近期重构：
1. 不做完整自研 RRF 框架。
2. 不直接把 `lookup_knowledge` 替换成隐式 Advisor。
3. 不一口气迁移所有 RAG ETL。
4. 不先引入 Elasticsearch / OpenSearch，除非评测证明 BM25 必须。
5. 不先上 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、数据库记录互相关联，必须分阶段推进，每阶段都保持可运行。
---
## 合并来源
本计划合并以下问题和改造方向：
- [rag-chunk-context-reconstruction.md](../rag/rag-chunk-context-reconstruction.md)
- [rag-breadcrumb-embedding-gap.md](../rag/rag-breadcrumb-embedding-gap.md)
- [rag-l0-l1-fusion-ranking.md](../rag/rag-l0-l1-fusion-ranking.md)
- [rag-l0-keyword-matching-quality.md](../rag/rag-l0-keyword-matching-quality.md)
- [rag-l1-score-calibration.md](../rag/rag-l1-score-calibration.md)
- [rag-context-packing-and-reranking.md](../rag/rag-context-packing-and-reranking.md)
- [rag-upload-chunk-parameter-drift.md](../rag/rag-upload-chunk-parameter-drift.md)
- [rag-query-rewrite-gap.md](../rag/rag-query-rewrite-gap.md)
- [rag-spring-ai-vectorstore-migration.md](../rag/rag-spring-ai-vectorstore-migration.md)
- [rag-spring-ai-query-transformer.md](../rag/rag-spring-ai-query-transformer.md)
- [rag-spring-ai-document-postprocessor.md](../rag/rag-spring-ai-document-postprocessor.md)
- [rag-l0-domain-entity-hint.md](../rag/rag-l0-domain-entity-hint.md)
- [rag-spring-ai-advisor-boundary.md](../rag/rag-spring-ai-advisor-boundary.md)
---
## 相关文件
- `src/main/java/com/superbiz/agent/tool/LookupKnowledgeTool.java`
- `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/VectorIndexService.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/AiOpsService.java`
- `src/main/java/com/superbiz/agent/service/ToolInvocationRecorder.java`
- `src/main/resources/application.yml`
- `pom.xml`