Spring AI Alibaba 1.x 系列【74】Agentic RAG 与混合 RAG

文章目录

• [1. Agentic RAG](#1. Agentic RAG)
• • [1.1 原理](#1.1 原理)
  • [1.2 与两步 RAG 的区别](#1.2 与两步 RAG 的区别)
• [2. 单工具 Agentic RAG](#2. 单工具 Agentic RAG)
• • [2.1 架构](#2.1 架构)
  • [2.2 定义检索工具](#2.2 定义检索工具)
  • [2.3 注册工具并创建 Agent](#2.3 注册工具并创建 Agent)
  • [2.4 调用示例](#2.4 调用示例)
  • [2.5 执行过程](#2.5 执行过程)
• [3. 多工具 Agentic RAG](#3. 多工具 Agentic RAG)
• • [3.1 架构](#3.1 架构)
  • [3.2 添加网络搜索工具](#3.2 添加网络搜索工具)
  • [3.3 创建多工具 Agent](#3.3 创建多工具 Agent)
  • [3.4 调用示例](#3.4 调用示例)
• [4. 混合 RAG](#4. 混合 RAG)
• • [4.1 原理](#4.1 原理)
  • [4.2 架构图](#4.2 架构图)
  • [4.3 查询增强 Hook](#4.3 查询增强 Hook)
  • [4.4 答案验证 Interceptor](#4.4 答案验证 Interceptor)
  • [4.5 创建混合 RAG Agent](#4.5 创建混合 RAG Agent)
  • [4.6 调用示例](#4.6 调用示例)
  • [4.7 执行过程](#4.7 执行过程)
• [5. 三种架构对比总结](#5. 三种架构对比总结)
• [6. 最佳实践](#6. 最佳实践)
• • [6.1 架构选择](#6.1 架构选择)
  • [6.2 检索质量优化](#6.2 检索质量优化)
  • [6.3 上下文大小控制](#6.3 上下文大小控制)
  • [6.4 性能优化](#6.4 性能优化)
  • [6.5 监控与评估](#6.5 监控与评估)
• [7. API 参考](#7. API 参考)

1. Agentic RAG

1.1 原理

Agentic RAG 将检索增强生成与基于 Agent 的推理相结合。Agent 不是在生成之前固定检索文档，而是逐步推理 并自主决定在交互过程中何时 以及如何检索信息。

用户查询 → [Think] → 需要检索？→ [Act: 调用检索工具] → [Observe: 文档内容]
                ↑                                               │
                └───────────────────────────────────────────────┘
                          ReAct 循环直到得出答案

Agent 启用 RAG 行为所需的唯一条件是访问一个或多个可以获取外部知识的工具。

1.2 与两步 RAG 的区别

维度	两步 RAG	Agentic RAG
检索时机	固定，生成前	Agent 自主决定
检索次数	固定 1 次	可变，按需多次
工具选择	单一（向量检索）	可多个（文档/网络/数据库）
灵活性	低	高
可控性	高	低

---

2. 单工具 Agentic RAG

2.1 架构

                    ┌─────────────────┐
                    │   ReactAgent     │
                    │                  │
  用户查询 ──────→ │  instruction:    │
                    │  "需要时使用     │
                    │   document_search│
                    │   工具查找信息"   │
                    │        │         │
                    │   [Think]        │
                    │     │            │
                    │     ▼            │
                    │  需要检索？       │
                    │     │            │
                    │     ▼            │
                    │ [document_search]│────→ VectorStore
                    │     │            │      similaritySearch()
                    │     ▼            │
                    │  整合结果 → 回答  │
                    └─────────────────┘

2.2 定义检索工具

将向量存储检索包装为 FunctionToolCallback：

class DocumentSearchTool {

    private final VectorStore vectorStore;
    private final int topK;

    public record Request(String query) {}
    public record Response(String content) {}

    public Response search(Request request) {
        List<Document> docs = vectorStore.similaritySearch(
                SearchRequest.builder()
                        .query(request.query())
                        .topK(topK)
                        .build());

        String content = docs.stream()
                .map(Document::getText)
                .collect(Collectors.joining("\n\n"));

        return new Response(content);
    }
}

2.3 注册工具并创建 Agent

DocumentSearchTool searchTool = new DocumentSearchTool(vectorStore, topK);

ToolCallback searchCallback = FunctionToolCallback
        .builder("document_search",
                (Function<Request, Response>) searchTool::search)
        .description("搜索文档库以查找相关信息。当需要查找特定知识或文档内容时使用此工具。")
        .inputType(DocumentSearchTool.Request.class)
        .build();

ReactAgent agent = ReactAgent.builder()
        .name("agentic-rag")
        .model(chatModel)
        .instruction("你是一个智能助手。当需要查找信息时，使用 document_search 工具。" +
                "基于检索到的信息回答用户的问题，并引用相关片段。")
        .tools(searchCallback)
        .enableLogging(true)
        .build();

2.4 调用示例

curl "http://localhost:8088/rag/agentic/single-tool?query=Spring AI Alibaba的Agent框架有哪些功能？"

2.5 执行过程

用户: "Spring AI Alibaba的Agent框架有哪些功能？"

[Think]  分析问题：需要查询文档
[Act]    document_search("Agent框架功能")
[Observe] 返回文档片段: "ReactAgent 提供 ReAct 推理循环，支持 Hook/Interceptor..."
[Think]  基于文档整合答案
[Output] "Spring AI Alibaba 的 Agent 框架提供 ReactAgent 实现，支持：
          1. ReAct 推理循环
          2. Hook 机制（AgentHook / MessagesModelHook）
          3. Interceptor 机制（ModelInterceptor）
          4. ToolCallback 工具集成
          5. MemorySaver 对话记忆管理"

---

3. 多工具 Agentic RAG

3.1 架构

Agent 同时拥有多个检索工具，根据问题类型自主选择：

                    ┌──────────────────────┐
                    │     ReactAgent         │
                    │                        │
  用户查询 ──────→ │  tools:                │
                    │  · document_search     │──→ VectorStore（文档库）
                    │  · web_search          │──→ Web API（网络搜索）
                    │                        │
                    │  "根据问题选择          │
                    │   最合适的工具"         │
                    └──────────────────────┘

3.2 添加网络搜索工具

class WebSearchTool {

    public record Request(String query) {}
    public record Response(String content) {}

    public Response search(Request request) {
        // 实际应用中调用搜索 API
        return new Response("网络搜索结果（模拟）: " + request.query());
    }
}

3.3 创建多工具 Agent

ToolCallback docSearchCallback = FunctionToolCallback
        .builder("document_search", docSearchTool::search)
        .description("搜索文档库以查找相关信息。适用于查找已存储的文档内容。")
        .inputType(DocumentSearchTool.Request.class)
        .build();

ToolCallback webSearchCallback = FunctionToolCallback
        .builder("web_search", webSearchTool::search)
        .description("从互联网搜索最新信息。适用于查找实时或最新的数据。")
        .inputType(WebSearchTool.Request.class)
        .build();

ReactAgent agent = ReactAgent.builder()
        .name("multi-source-rag")
        .model(chatModel)
        .instruction("""
                你可以访问多个信息源：
                1. document_search - 用于搜索文档库中的内部知识
                2. web_search - 用于搜索互联网上的最新信息
                根据问题选择最合适的工具。""")
        .tools(docSearchCallback, webSearchCallback)
        .enableLogging(true)
        .build();

3.4 调用示例

# 查询内部文档
curl "http://localhost:8088/rag/agentic/multi-tool?query=ReactAgent有哪些配置选项？"
# → Agent 使用 document_search

# 查询最新信息
curl "http://localhost:8088/rag/agentic/multi-tool?query=Spring AI最新版本是多少？"
# → Agent 使用 web_search

# 需要综合信息
curl "http://localhost:8088/rag/agentic/multi-tool?query=比较文档中的功能和最新的市场趋势"
# → Agent 可能先后调用两个工具

---

4. 混合 RAG

4.1 原理

混合 RAG 结合了两步 RAG 和 Agentic RAG 的特点，引入中间步骤：

         ┌── 查询增强 ──→ 检索 ──→ 生成 ──→ 答案验证 ──┐
         │                                              │
用户查询 ─┤                                              ├──→ 最终答案
         │                                              │
         └──────── 多工具自主检索（可多次） ─────────────┘

三个核心组件：

组件	类型	时机	作用
查询增强	AgentHook	Agent 开始前	检索文档，缓存上下文（只执行 1 次）
多工具检索	ToolCallback	ReAct 循环中	Agent 自主选择检索工具（可多次）
答案验证	ModelInterceptor	每次生成后	验证答案质量，必要时重新生成

4.2 架构图

                    ┌─────────────────────────────────────┐
                    │          Hybrid RAG Agent            │
                    │                                      │
  用户查询 ──────→ │  ┌──────────────────────────────┐    │
                    │  │ QueryEnhancementHook (BEFORE) │    │
                    │  │ · 检索文档                     │    │
                    │  │ · 缓存到 config.metadata       │    │
                    │  └──────────────────────────────┘    │
                    │           │                          │
                    │           ▼                          │
                    │  ┌──────────────────────────────┐    │
                    │  │       ReAct 循环               │    │
                    │  │  [Think] → [Act] → [Observe]  │    │
                    │  │           │                    │    │
                    │  │  tools:                        │    │
                    │  │  · document_search             │    │
                    │  │  · web_search                  │    │
                    │  └──────────────────────────────┘    │
                    │           │                          │
                    │           ▼                          │
                    │  ┌──────────────────────────────┐    │
                    │  │ AnswerValidationInterceptor    │    │
                    │  │ · 检查答案质量                  │    │
                    │  │ · 不合格 → 重新生成             │    │
                    │  └──────────────────────────────┘    │
                    │           │                          │
                    │           ▼                          │
                    │       最终答案                        │
                    └─────────────────────────────────────┘

4.3 查询增强 Hook

Agent 开始前检索文档，缓存到 config metadata：

@HookPositions({HookPosition.BEFORE_AGENT})
public class QueryEnhancementHook extends AgentHook {

    public static final String RAG_CONTEXT_KEY = "rag_context";

    @Override
    public CompletableFuture<Map<String, Object>> beforeAgent(
            OverAllState state, RunnableConfig config) {

        String userQuery = extractUserQuery(state);
        if (userQuery.isEmpty()) return CompletableFuture.completedFuture(Map.of());

        // 检索文档（只执行一次）
        List<Document> docs = vectorStore.similaritySearch(
                SearchRequest.builder().query(userQuery).topK(topK).build());
        String context = docs.stream()
                .map(Document::getText)
                .collect(Collectors.joining("\n\n"));

        // 缓存上下文
        config.metadata().ifPresent(meta -> meta.put(RAG_CONTEXT_KEY, context));

        return CompletableFuture.completedFuture(Map.of());
    }
}

4.4 答案验证 Interceptor

生成后检查答案质量：

public class AnswerValidationInterceptor extends ModelInterceptor {

    @Override
    public ModelResponse interceptModel(ModelRequest request, ModelCallHandler handler) {
        ModelResponse response = handler.call(request);

        AssistantMessage answer = (AssistantMessage) response.getMessage();
        boolean isValid = answer != null && answer.getText().length() > 20;

        if (!isValid) {
            // 质量不合格，重新生成
            ModelRequest retryRequest = ModelRequest.builder(request)
                    .systemMessage(new SystemMessage(
                            "请重新检查你的答案，确保基于上下文信息，准确完整。"))
                    .build();
            return handler.call(retryRequest);
        }

        return response;
    }
}

4.5 创建混合 RAG Agent

ReactAgent agent = ReactAgent.builder()
        .name("hybrid-rag")
        .model(chatModel)
        .instruction("""
                你是一个智能助手，可以访问多个信息源。
                1. 优先使用 document_search 搜索文档库
                2. 如果需要最新信息，使用 web_search
                3. 基于检索到的信息生成准确、完整的答案
                4. 如果信息不足，可以多次调用工具
                """)
        .tools(documentSearchCallback, webSearchCallback)   // 多工具
        .hooks(new QueryEnhancementHook(vectorStore, topK))  // 查询增强
        .interceptors(new AnswerValidationInterceptor())      // 答案验证
        .build();

4.6 调用示例

curl "http://localhost:8088/rag/hybrid/call?query=Spring AI Alibaba支持哪些向量数据库？"

4.7 执行过程

用户: "Spring AI Alibaba支持哪些向量数据库？"

[QueryEnhancementHook]
  → 检索相关文档
  → 缓存上下文到 metadata["rag_context"]

ReAct 循环:
  [Think] 分析问题 → 需要查文档
  [Act]   document_search("向量数据库支持")
  [Observe] 文档片段: "支持 Milvus、Pinecone、Redis、Elasticsearch..."
  [Think] 信息可能不完整，再查网络
  [Act]   web_search("Spring AI Alibaba 向量数据库")
  [Observe] 网络结果（模拟）
  [Think] 整合信息

[AnswerValidationInterceptor]
  → 答案长度 > 20 ✓
  → 通过验证

输出: "Spring AI Alibaba 支持多种向量数据库，包括：
      1. Milvus（开源向量数据库）
      2. Pinecone（托管向量数据库）
      3. Redis（支持向量搜索模块）
      4. Elasticsearch（支持向量检索）
      5. SimpleVectorStore（内存存储，适合开发测试）"

---

5. 三种架构对比总结

维度	两步 RAG	Agentic RAG	混合 RAG
检索方式	固定管道	Agent 自主	两者结合
工具数量	1（隐式）	1 或多个	多个
验证步骤	无	无	答案验证
查询增强	可选	无	有
延迟可预测性	高	低	中
实现复杂度	低	中	高
适用场景	FAQ、文档问答	研究助手	高精度领域问答

---

6. 最佳实践

6.1 架构选择

简单 FAQ ──────────────→ 两步 RAG
复杂研究任务 ──────────→ Agentic RAG
需要质量保证的问答 ────→ 混合 RAG

6.2 检索质量优化

• 使用合适的文本分割策略（chunkSize=500, overlap=50）
• 选择高质量的嵌入模型（如 text-embedding-v4）
• 实现查询重写（RewriteQueryTransformer）

6.3 上下文大小控制

• 限制检索文档数量（topK=3~5）
• 使用文档排序和过滤
• 考虑模型的上下文窗口限制

6.4 性能优化

• 查询不变时优先使用 AgentHook（只检索一次）
• 使用 MemorySaver 缓存多轮对话上下文
• 考虑对常见查询结果做应用层缓存

6.5 监控与评估

• 通过 enableLogging(true) 观察 Agent 的推理与工具调用过程
• 跟踪检索质量（相关性、召回率）
• 收集用户反馈持续优化

---

7. API 参考

# Agentic RAG --- 单工具
curl "http://localhost:8088/rag/agentic/single-tool?query=查询内容&threadid=user-001"

# Agentic RAG --- 多工具
curl "http://localhost:8088/rag/agentic/multi-tool?query=查询内容&threadid=user-001"

# 混合 RAG
curl "http://localhost:8088/rag/hybrid/call?query=查询内容&threadid=user-001"

# 查看向量存储中的文档
curl "http://localhost:8088/rag/documents?query=Spring AI Alibaba"