# 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`