Spring AI RAG Pipeline 深度分析
# Spring AI RAG Pipeline 深度分析## 1. 概述Spring AI 的 RAG（Retrieval Augmented Generation，检索增强生成）模块位于 `spring-ai-rag/` 目录，采用**模块化 RAG 架构**，将整个 RAG 流程分解为预检索（Pre-Retrieval）、检索（Retrieval）和后检索（Post-Retrieval）三个独立阶段。### 目录结构```
spring-ai-rag/
├── pom.xml
└── src/main/java/org/springframework/ai/rag/├── Query.java # RAG 查询数据结构├── advisor/│ └── RetrievalAugmentationAdvisor.java # 核心编排器├── preretrieval/│ └── query/│ ├── expansion/ # Query 扩写│ │ ├── QueryExpander.java # 接口│ │ └── MultiQueryExpander.java # 实现│ └── transformation/ # Query 转换│ ├── QueryTransformer.java # 接口│ ├── RewriteQueryTransformer.java # 重写│ ├── CompressionQueryTransformer.java # 压缩│ └── TranslationQueryTransformer.java # 翻译├── retrieval/│ ├── search/ # 文档检索│ │ ├── DocumentRetriever.java # 接口│ │ └── VectorStoreDocumentRetriever.java # 实现│ └── join/ # 文档合并│ ├── DocumentJoiner.java # 接口│ └── ConcatenationDocumentJoiner.java # 实现├── postretrieval/│ └── document/│ └── DocumentPostProcessor.java # 接口├── generation/│ └── augmentation/ # Query 增强│ ├── QueryAugmenter.java # 接口│ └── ContextualQueryAugmenter.java # 实现└── util/└── PromptAssert.java # 工具类
```---## 2. RAG Pipeline 三阶段流程### 2.1 流程总览```
┌──────────────────────────────────────────────────────────────────────────────┐
│ RAG Pipeline (7 步流程) │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Step 0: 创建 Query │
│ Query(text, history, context) │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Step 1: Query 转换 (Pre-Retrieval - Query Transformation) │ │
│ │ List 链式调用 │ │
│ │ Query -> QueryTransformer1 -> QueryTransformer2 -> ... -> Query │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Step 2: Query 扩写 (Pre-Retrieval - Query Expansion) │ │
│ │ QueryExpander (可选) │ │
│ │ Query -> List │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Step 3: 文档检索 (Retrieval) │ │
│ │ DocumentRetriever 并行检索 │ │
│ │ List -> Map>> │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Step 4: 文档合并 (Retrieval - Document Joining) │ │
│ │ DocumentJoiner │ │
│ │ Map>> -> List │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Step 5: 文档后处理 (Post-Retrieval) │ │
│ │ List 链式调用 │ │
│ │ List -> DocumentPostProcessor1 -> ... -> List │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Step 6: Query 增强 (Generation - Query Augmentation) │ │
│ │ QueryAugmenter │ │
│ │ Query + List -> Augmented Query │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Step 7: 返回增强后的 ChatClientRequest │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
```### 2.2 核心类：RetrievalAugmentationAdvisor`RetrievalAugmentationAdvisor` 是整个 RAG Pipeline 的**编排引擎**，实现 `BaseAdvisor` 接口。其 `before()` 方法实现了完整的 7 步 RAG 流程：```java
@Override
public ChatClientRequest before(ChatClientRequest chatClientRequest, @Nullable AdvisorChain advisorChain) {Map context = new HashMap<>(chatClientRequest.context());// 0. Create a query from the user text, parameters, and conversation history.String text = chatClientRequest.prompt().getUserMessage().getText();Query originalQuery = Query.builder().text(Objects.requireNonNullElse(text, "")).history(chatClientRequest.prompt().getInstructions()).context(context).build();// 1. Transform original user query based on a chain of query transformers.Query transformedQuery = originalQuery;for (var queryTransformer : this.queryTransformers) {transformedQuery = queryTransformer.apply(transformedQuery);}// 2. Expand query into one or multiple queries.List expandedQueries = this.queryExpander != null? this.queryExpander.expand(transformedQuery): List.of(transformedQuery);// 3. Get similar documents for each query.Map>> documentsForQuery = expandedQueries.stream().map(query -> CompletableFuture.supplyAsync(() -> getDocumentsForQuery(query), this.taskExecutor)).toList().stream().map(CompletableFuture::join).collect(Collectors.toMap(Map.Entry::getKey, entry -> List.of(entry.getValue())));// 4. Combine documents retrieved based on multiple queries and from multiple data sources.List documents = this.documentJoiner.join(documentsForQuery);// 5. Post-process the documents.for (var documentPostProcessor : this.documentPostProcessors) {documents = documentPostProcessor.process(originalQuery, documents);}context.put(DOCUMENT_CONTEXT, documents);// 6. Augment user query with the document contextual data.Query augmentedQuery = this.queryAugmenter.augment(originalQuery, documents);// 7. Update ChatClientRequest with augmented prompt.return chatClientRequest.mutate().prompt(chatClientRequest.prompt().augmentUserMessage(augmentedQuery.text())).context(context).build();
}
```---## 3. Query 数据结构Query 是一个 **Java Record** 类型，包含三个组件：
- `text`: 查询的文本内容
- `history`: 对话历史（用于压缩等转换）
- `context`: 键值对形式的附加上下文---## 4. 预检索阶段（Pre-Retrieval）### 4.1 Query 转换（Query Transformation）#### 接口定义```java
@FunctionalInterface
public interface QueryTransformer extends Function {Query transform(Query query);default Query apply(Query query) { return transform(query); }
}
```#### 实现类| 实现类 | 功能 | 用途 |
|--------|------|------|
| `RewriteQueryTransformer` | Query 重写 | 将冗长、模糊或包含无关信息的查询优化为更适合检索的形式 |
| `CompressionQueryTransformer` | Query 压缩 | 将长对话历史+跟进问题压缩为独立的简洁查询 |
| `TranslationQueryTransformer` | Query 翻译 | 将查询翻译为目标语言（与 embedding 模型训练语言一致） |### 4.2 Query 扩写（Query Expansion）使用 LLM 将单个查询扩展为多个语义不同的变体，以捕获不同视角，增加检索到相关结果的机会。#### MultiQueryExpander 默认 Prompt 模板```
You are an expert at information retrieval and search optimization.
Your task is to generate {number} different versions of the given query.Each variant must cover different perspectives or aspects of the topic,
while maintaining the core intent of the original query. The goal is to
expand the search space and improve the chances of finding relevant information.Do not explain your choices or add any other text.
Provide the query variants separated by newlines.Original query: {query}Query variants:
```**关键属性**:
- `numberOfQueries`: 默认 3 个变体
- `includeOriginal`: 默认 true，包含原始查询---## 5. 检索阶段（Retrieval）### 5.1 文档检索（Document Retrieval）```java
public interface DocumentRetriever extends Function> {List retrieve(Query query);default List apply(Query query) { return retrieve(query); }
}
```#### VectorStoreDocumentRetriever从 VectorStore 检索语义相似文档。**特性**:
- `similarityThreshold`: 相似度阈值（默认接受所有）
- `topK`: 返回的最大文档数
- `filterExpression`: 元数据过滤表达式（支持动态计算）### 5.2 文档合并（Document Joining）将多查询多数据源的文档合并：
1. 拼接所有文档
2. 按文档 ID 去重（保留首次出现）
3. 按相似度分数降序排序---## 6. 后检索阶段（Post-Retrieval）### 6.1 文档后处理器（Document Post-Processor）**作用**:
- 解决 "lost-in-the-middle" 问题（重要信息在大量文档中间被忽略）
- 处理模型上下文长度限制
- 减少噪声和冗余**可能的实现方向**：
- **重排序（Re-ranking）**: 根据与查询的相关性对文档排序
- **去重（Deduplication）**: 移除重复或高度相似的文档
- **压缩（Compression）**: 压缩文档内容以减少噪声
- **选择（Selection）**: 选择最重要的文档---## 7. 生成增强阶段（Generation Augmentation）### ContextualQueryAugmenter将文档内容作为上下文增强用户查询。**默认 Prompt 模板**:```
Context information is below.---------------------
{context}
---------------------Given the context information and no prior knowledge, answer the query.Follow these rules:1. If the answer is not in the context, just say that you don't know.
2. Avoid statements like "Based on the context..." or "The provided information...".Query: {query}Answer:
```---## 8. 核心接口层次```
java.lang.Function│├── QueryTransformer│ ├── RewriteQueryTransformer│ ├── CompressionQueryTransformer│ └── TranslationQueryTransformer│├── QueryExpander│ └── MultiQueryExpander│├── DocumentRetriever│ └── VectorStoreDocumentRetriever│└── DocumentJoiner└── ConcatenationDocumentJoinerjava.util.function.BiFunction│├── DocumentPostProcessor│└── QueryAugmenter└── ContextualQueryAugmenter
```---## 9. 完整流程时序图```
┌─────────────┐ ┌──────────────────┐ ┌───────────────────────┐ ┌──────────────────┐
│ User │ │ RetrievalAug │ │ Other Components │ │ VectorStore │
│ Request │ │ mentationAdvisor │ │ │ │ │
└──────┬──────┘ └────────┬─────────┘ └───────────────────────┘ └──────────────────┘│ │ ││ 1. prompt │ ││───────────────────>│ ││ │ ││ │ 2. Query(text, history, context) ││ │──────┐ ││ │ │ 创建 Query 对象 ││ │<─────┘ ││ │ ││ │ 3. QueryTransformer.transform() ││ │──────┐ (链式调用，每个 transformer 处理) ││ │ │ ││ │<─────┘ ││ │ ││ │ 4. QueryExpander.expand() ││ │──────┐ (可选，将1个Query扩展为多个) ││ │ │ ││ │<─────┘ ││ │ ││ │ 5. DocumentRetriever.retrieve() ││ │──────────────────────────────────────────────────────>││ │ │ (并行执行多个 Query 的检索) ││ │<──────────────────────────────────────────────────────││ │ ││ │ 6. DocumentJoiner.join() ││ │──────┐ (合并去重，按分数排序) ││ │ │ ││ │<─────┘ ││ │ ││ │ 7. DocumentPostProcessor.process() ││ │──────┐ (链式调用，后处理文档) ││ │ │ ││ │<─────┘ ││ │ ││ │ 8. QueryAugmenter.augment() ││ │──────┐ (将文档内容注入 Query) ││ │ │ ││ │<─────┘ ││ │ ││ 9. augmented │ ││ prompt │ ││<───────────────────│ ││ │ │
```---## 10. 使用示例### 完整 RAG 配置示例```java
// 1. 构建 DocumentRetriever
DocumentRetriever retriever = VectorStoreDocumentRetriever.builder().vectorStore(vectorStore).topK(10).similarityThreshold(0.75).build();// 2. 构建 QueryTransformers 链
List queryTransformers = List.of(CompressionQueryTransformer.builder().chatClientBuilder(chatClientBuilder).build(),RewriteQueryTransformer.builder().chatClientBuilder(chatClientBuilder).targetSearchSystem("vector store").build()
);// 3. 构建 QueryExpander (可选)
QueryExpander queryExpander = MultiQueryExpander.builder().chatClientBuilder(chatClientBuilder).numberOfQueries(3).build();// 4. 构建 DocumentPostProcessors 链 (可选)
List postProcessors = List.of(/* 自定义后处理器 */);// 5. 构建 QueryAugmenter
QueryAugmenter queryAugmenter = ContextualQueryAugmenter.builder().allowEmptyContext(false).build();// 6. 构建 Advisor
RetrievalAugmentationAdvisor advisor = RetrievalAugmentationAdvisor.builder().queryTransformers(queryTransformers).queryExpander(queryExpander).documentRetriever(retriever).documentPostProcessors(postProcessors).queryAugmenter(queryAugmenter).build();// 7. 将 Advisor 添加到 ChatClient
ChatClient chatClient = ChatClient.builder(chatModel).defaultAdvisors(advisor).build();// 8. 使用 RAG 进行对话
ChatResponse response = chatClient.prompt().user("What is Spring AI?").call().chatResponse();
```---## 11. 关键设计模式| 模式 | 应用场景 |
|------|----------|
| **策略模式 (Strategy)** | 各阶段组件都定义为接口，具体实现可替换（如 QueryTransformer、DocumentRetriever） |
| **责任链模式 (Chain of Responsibility)** | QueryTransformer 和 DocumentPostProcessor 支持链式组合 |
| **模板方法模式 (Template Method)** | `Function` 和 `BiFunction` 接口的 `apply` 默认实现 |
| **建造者模式 (Builder)** | 所有实现类都提供 Builder 用于配置 |---## 12. 依赖关系spring-ai-rag 依赖：
- `spring-ai-client-chat`: ChatClient 和 Prompt 相关
- `spring-ai-vector-store`: VectorStore 和 DocumentRetriever 实现