Spring Boot 4.1 + Spring AI 2.0：RAG 供文、图谱供关系、MCP 供工具的 Java Agent 平台

把一个业务问答系统接上大模型，两周就能跑通：向量库塞文档、ChatClient 一调，答案立刻出来。可一上线问题就冒头------问「张三的报销单卡在谁手里」时模型只能复述制度文档，答不出关系链；想让它顺手查一下订单状态，又只能靠后端硬编码一个接口。

常规做法停在「向量检索 + Prompt 拼接」这一层：它能召回语义相近的段落，却给不出跨实体的多跳关系；工具用 HTTP 接口写死在服务里，既不能被其他 Agent 复用，也拿不到统一的权限与审计口径。知识图谱和 MCP 各补一块，但三者如何在一套 Java 微服务里协同，很少有人给出可运行的装配方式。

本文分享一套以 Spring Boot 4.1 与 Spring AI 2.0 为底座的组装方案：向量库供文、知识图谱供关系、MCP 协议供工具，配合统一编排与观测，可直接落地。

一、三块拼图各自补哪块盲区

先把三种能力的分工摆清楚，避免在一个服务里重复造轮子：

能力	擅长回答	天然盲区	平台里的落点
RAG 向量检索	口语化问法、长文本语义匹配	跨实体多跳、数值关系	供文：答案正文与引用编号
知识图谱	谁和谁有关、关系路径	口语理解、原文细节	供关系：实体补边与跳数扩展
MCP 协议	查单、写单、审批等动作	非结构化知识	供工具：跨服务动作调用

• 供文的 RAG：负责把制度、手册、工单原文召回出来，输出必须强制带来源编号，否则引用无法回溯。
• 供关系的图谱：把人、单据、审批节点建成边，回答「卡在谁手里」这类问题时按跳数走路径。
• 供动作的 MCP：把下游微服务的能力声明成工具，模型只看到工具名与描述，实际鉴权留在服务端。

核心结论：RAG 决定答得像不像，图谱决定答得对不对，MCP 决定能不能动手。

二、工程骨架：依赖与配置怎么装配

平台底座先立起来，四类依赖缺一不可：

• 模型接入 ：spring-ai-starter-model-openai 统一走 ChatClient，换供应商只改 application.yml。
• 向量存储 ：spring-ai-starter-vector-store-pgvector 与业务库同实例部署，少运维一套组件。
• 工具接入 ：spring-ai-starter-mcp-client 负责发现远端工具并自动生成 ToolCallback。
• 图数据库 ：spring-boot-starter-data-neo4j，用 Neo4jClient 直接跑 Cypher。

这段是平台的 Maven 依赖骨架，适配 Spring Boot 4.1 + Spring AI 2.0 环境：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.0</version>
</parent>
<dependencies>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
        <version>2.0.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-vector-store-pgvector</artifactId>
        <version>2.0.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-mcp-client</artifactId>
        <version>2.0.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-neo4j</artifactId>
    </dependency>
</dependencies>

一句话：模型、向量、图、工具四条线各挂一个 Starter，业务代码只写编排。

三、RAG 管线：从切分到引用回填

检索质量决定回答上限，管线按这条链路固定下来：

读取 → 切分 → 向量化 → 入库 → 检索 → 拼装 → 生成

• 切分粒度：800 token 一段、120 token 重叠，段落太长会稀释相似度，太短会丢上下文。
• 阈值兜底：相似度低于 0.55 的段落直接丢弃，宁可答「没查到」也不让模型编造。

下面这段代码定义切分参数与带引用约束的问答客户端，适配 Spring AI 2.0 的 Advisor 链：

@Configuration
public class RagPipelineConfig {

    @Bean
    TokenTextSplitter docSplitter() {
        return TokenTextSplitter.builder()
                .withChunkSize(800)
                .withChunkOverlap(120)
                .withMinChunkSize(80)
                .build();
    }

    @Bean
    ChatClient ragChat(ChatClient.Builder builder, VectorStore store) {
        return builder
                .defaultSystem("只依据检索结果作答，末尾列出引用编号")
                .defaultAdvisors(r -> r
                        .advisors(new QuestionAnswerAdvisor(store,
                                SearchRequest.defaults().withTopK(6)
                                        .withSimilarityThreshold(0.55)))
                        .advisors(new SafeGuardAdvisor()))
                .build();
    }
}

强约束生成 → 相似度过滤 → 低分段落直接丢弃，三段都在 Advisor 里可单独开关。

四、知识图谱：让实体关系参与召回

图谱不替代向量库，而是给召回结果补上关系边，四个参数决定补多少：

参数	作用	建议起点
起始实体数	从问题中抽几个实体进图	1~3 个
扩展跳数	沿关系向外走几层	2 跳封顶
向量阈值	相似度召回下限	0.55
融合权重	文本分与图谱分占比	0.6 / 0.4

• 实体抽取 ：用 JsonSchema 约束模型只输出人名、单号、部门三类实体，作为 Cypher 的查询入口。
• 双路融合：向量分与图谱分按 0.6/0.4 加权排序；图谱命中为 0 时自动退回单路，避免空结果。

核心结论：图谱补的是「谁和谁有关」，向量补的是「话怎么说」，两路都空才降级。

五、MCP 协议：工具接入与权限边界

工具一旦跨服务，就先定协议再谈调用：

• 服务即工具 ：订单、审批各起一个 MCP Server，用 @Tool 注解声明工具名、入参与中文描述。
• 白名单控制：客户端只连接配置里登记的服务，未登记的工具不会出现在模型可见列表里。
• 失败降级：工具超时或报错时返回结构化错误对象，编排层把动作降级为只读文本回答。

这段是 MCP 客户端连接配置，放在 application.yml 中即可挂载两个远端工具服务：

spring:
  ai:
    mcp:
      client:
        toolcallback-provider: dynamic
        sse:
          connections:
            order-service:
              url: http://order-mcp:8080/sse
            approval-service:
              url: http://approval-mcp:8080/sse

工具接入从「改代码」变成「改配置」，权限边界落在配置白名单与网关鉴权两层。

六、编排与观测：一次请求走完全链路

一次请求要过六个阶段，每段都得有观测点和兜底策略：

路由 → 召回 → 图谱补边 → 工具调用 → 答案合成 → 落观测

阶段	观测点	兜底策略
向量召回	topK、相似度分布	低于阈值转图谱单路
图谱补边	实体命中率	命中为 0 则跳过该节点
工具调用	MCP 延迟、失败率	超时降级为只读文本
答案合成	首字延迟、Token 数	截断历史控制预算

• 状态编排：每个阶段写成独立节点，失败节点记录原因后跳到降级分支，整条链路可回放。
• 观测口径：把 topK 分布、图谱命中率、MCP 延迟、首字延迟打到同一张看板，慢在哪一段一眼可见。

核心结论：链路可回放 + 每段可降级，Agent 平台才敢接到生产流量上。

结语

这套结构的价值在于把三块能力拆成清晰的输入输出：RAG 输出带编号的文本片段，图谱输出可计权的关系路径，MCP 输出可鉴权的工具调用结果，编排层只负责按状态机把它们串起来。任何一块要换实现------向量库换引擎、图库换厂商、工具服务扩容器------都只动配置和单一节点，业务问答逻辑不受牵连。

先从一条最短链路跑通（RAG + 单个 MCP 工具），再逐步把图谱补边和观测看板加进来，比一次性搭全平台更稳。

供文、供关系、供动作三条线各司其职，Java 微服务也能把 Agent 平台做成可维护的工程。