387 lines
11 KiB
Markdown
387 lines
11 KiB
Markdown
# RAG 检索重构计划
|
||
|
||
**状态**：已归档（设计过时）
|
||
**严重程度**：高
|
||
**发现时间**：2026-07-05
|
||
**范围**：RAG、检索、知识库、Agent Tool、AIOps 诊断证据链
|
||
**归档时间**：2026-07-23
|
||
|
||
---
|
||
|
||
## 归档说明
|
||
|
||
本计划基于旧的 Milvus SDK、L0/L1 分层和 `VectorSearchService` 架构，包含 Spring AI VectorStore 旁路迁移、Query Transformer 和多阶段检索替换路线；当前实现已经收敛到 ISS-014 定义的单体 Diagnosis Agent、Harness 和显式 `lookup_knowledge` Tool Contract，原计划中的内部边界、验收口径和阶段拆分均已过时。
|
||
|
||
本文仅保留作为历史设计背景和 RAG 子问题来源，不再作为当前实现依据。后续若需要改造检索基础设施，应基于当前代码和 ISS-014 的 ACI/证据投影约束新建独立 Issue，不直接沿用本文的阶段计划。
|
||
|
||
---
|
||
|
||
## 目标
|
||
|
||
将当前自研 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`
|