Spring AI：Java 生态的生成式 AI 应用框架（2026 最新版）

更新日期：2026 年 6 月 29 日 适用版本：Spring AI 1.1.4 / 2.0-M4

一、Spring AI 是什么

Spring AI 是 Spring 官方推出的、专为构建人工智能（尤其是生成式 AI）应用而设计的框架，旨在将 Spring 生态多年积累的简洁性、模块化设计和 POJO 编程模型带入 AI 工程领域。

核心定位

它的核心使命可以概括为一句话："将企业的数据和 API 与 AI 模型连接起来"，把所有主流 AI 模型的 API 统一成一致的高层抽象，开发者只需学会一套接口，就能调用 OpenAI、通义千问、DeepSeek、Ollama 等各种模型，切换模型只需改配置文件。

需要特别强调的是，Spring AI 并非 Python 生态中 LangChain、LlamaIndex 等项目的直接移植，而是借鉴了它们的设计思想，专门为 Java/Spring 量身定制。

版本演进时间线

在经历了八个里程碑版本（M1~M8）的打磨后，Spring AI 1.0 正式版于 2025 年 5 月 20 日发布；仅仅半年后的 2025 年 11 月，1.1 版本正式 GA；进入 2026 年，1.1.3（3 月）和 1.1.4 相继发布，同时 2.0.0 已推进到 M4 里程碑版本，预计不久将正式 GA。至此，Spring AI 已成为 Java 开发者构建企业级 AI 应用的首选框架。

二、核心特性概览（2026 年现状）

Spring AI 的能力围绕可移植性和易用性两大设计原则展开，截至 2026 年 6 月，主要特性包括：

能力矩阵

关键特性详解

• ChatClient API：框架的核心入口，提供流式 DSL 风格的流畅 API，支持同步/流式调用、Advisor 拦截、自动会话记忆，是官方推荐的首选交互方式。

• 可移植的服务抽象：统一接口让你可以一致地访问各类聊天模型、嵌入模型、转录模型、图像模型，切换模型供应商时业务代码几乎不变。

• MCP（Model Context Protocol）集成：这是 1.1 版本最具显著特色的功能集改进，提供了基于注解的编程模型（@McpTool、@McpResource、@McpPrompt），支持 HTTP/gRPC/STDIO 多种传输方式，实现"AI 可调用你的业务能力"。

• Tool Calling（工具调用）：通过 @Tool 和 @ToolParam 注解声明式定义工具，模型可自动判断何时调用，支持自定义 JSON Schema、动态增强工具 Schema、流式响应等。

• 向量存储集成：支持 PGVector、Milvus、Redis、Chroma、Neo4j、Azure AI Search 等主流向量数据库，并支持自定义过滤表达式。

• RAG 模块化库：通过 QuestionAnswerAdvisor 开箱即用地实现检索增强生成，与 Spring Data 生态协同。

• Agent 工程：2026 年全面拥抱 Agent 工程，通过 ReactAgent、Graph 工作流构建多智能体系统，可将 Multi-Agent 开发周期从数天压缩到数小时。

• Spring Boot 深度集成：在 Spring Boot 3.4+ 中，spring-ai 模块已深度嵌入核心启动流程，一个标准的 Spring Boot 应用天然具备调用 LLM、处理 Embedding 和构建 Agent 的能力，同时支持 GraalVM 原生镜像。

• Prompt Caching（提示缓存）：1.1 引入的降本特性，可大幅降低 API 调用成本。

三、代码实现

下面从最基础的对话到 RAG、工具调用、多模态、Agent，展示基于 2026 年最新 API 的典型用法。

3.1 环境准备

pom.xml 配置

<repositories>
   <repository>
       <id>spring-milestones</id>
       <name>Spring Milestones</name>
       <url>https://repo.spring.io/milestone</url>
   </repository>
</repositories>
​
<properties>
   <spring-ai.version>1.1.4</spring-ai.version>
</properties>
​
<dependencyManagement>
   <dependencies>
       <dependency>
           <groupId>org.springframework.ai</groupId>
           <artifactId>spring-ai-bom</artifactId>
           <version>${spring-ai.version}</version>
           <type>pom</type>
           <scope>import</scope>
       </dependency>
   </dependencies>
</dependencyManagement>
​
<dependencies>
   <!– Web 支持 –>
   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-web</artifactId>
   </dependency>
​
   <!– 以 OpenAI 为例，也可换成 deepseek、ollama、dashscope 等 starter –>
   <dependency>
       <groupId>org.springframework.ai</groupId>
       <artifactId>spring-ai-starter-model-openai</artifactId>
   </dependency>
</dependencies>

注意：1.1.x 版本的 jar 包托管在 Spring Milestones 仓库中，必须添加该仓库地址。

application.yml 配置

spring:
ai:
  openai:
    api-key: ${OPENAI_API_KEY}
    chat:
      options:
        model: gpt-4o
        temperature: 0.7

对于国内开发者，也可以使用阿里云通义千问：

spring:
ai:
  dashscope:
    api-key: ${AI_DASHSCOPE_API_KEY}

如果想本地免费体验，可以使用 Ollama：

spring:
ai:
  ollama:
    base-url: http://localhost:11434
    chat:
      options:
        model: qwen2.5:latest
<dependency>
   <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>

3.2 基础对话与流式输出

Spring AI 通过自动配置注入 ChatClient.Builder，可以设置默认系统提示词：

@RestController
@RequestMapping("/api/ai")
public class ChatController {
​
   private final ChatClient chatClient;
​
   public ChatController(ChatClient.Builder builder) {
       this.chatClient = builder
              .defaultSystem("你是一个专业的Java技术专家")
              .build();
  }
​
   // 同步对话
   @GetMapping("/chat")
   public String chat(@RequestParam String message) {
       return chatClient.prompt()
              .user(message)
              .call()
              .content();
  }
​
   // 流式输出（打字机效果）
   @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
   public Flux<String> stream(@RequestParam String message) {
       return chatClient.prompt()
              .user(message)
              .stream()
              .content();
  }
}

ChatModel vs ChatClient 如何选择？

3.3 多轮对话：让 AI 拥有"记忆"

通过 Advisor 机制实现会话记忆，MessageChatMemoryAdvisor 会自动管理对话历史：

@Service
public class ChatMemoryService {
​
   private final ChatClient chatClient;
​
   public ChatMemoryService(ChatClient.Builder builder) {
       ChatMemory chatMemory = new InMemoryChatMemory();
       this.chatClient = builder
              .defaultAdvisors(new MessageChatMemoryAdvisor(chatMemory))
              .build();
  }
​
   public String chat(String sessionId, String message) {
       return chatClient.prompt()
              .user(message)
              .advisors(a -> a.param("chat_memory_conversation_id", sessionId))
              .call()
              .content();
  }
}

3.4 Tool Calling：让 AI 调用外部 API

2026 年的推荐写法使用 @Tool 注解，比早期的 @Description + Function 方式更简洁直观：

@Component
public class WeatherTools {
​
   @Tool(description = "根据城市名称查询当前天气")
   public String getWeather(@ToolParam(description = "城市名称，如'北京'") String city) {
       Map<String, String> weatherMap = Map.of(
               "北京", "晴天，25°C，北风2级",
               "上海", "多云，22°C，东风3级",
               "深圳", "阵雨，28°C，南风2级"
      );
       return weatherMap.getOrDefault(city, "天气数据暂不可用");
  }
}

在 ChatClient 中注册工具：

@RestController
@RequestMapping("/api/tools")
public class ToolController {
​
   private final ChatClient chatClient;
​
   public ToolController(ChatClient.Builder builder) {
       this.chatClient = builder
              .defaultSystem("你是一个专业的天气助手")
              .build();
  }
​
   @GetMapping("/weather")
   public String askWeather(@RequestParam String question) {
       return chatClient.prompt()
              .user(question)
              .tools(new WeatherTools())
              .call()
              .content();
  }
}

当用户问"北京天气怎么样"时，模型会自动决定调用 getWeather 方法，填好参数，拿到返回结果后再组织成自然语言回复。

1.1.3 新增增强：

• ToolCallAdvisor 支持流式响应，函数调用场景下的实时交互体验更好

• 可运行时动态增强工具 Schema

• 新增 conversationHistoryEnabled 选项，控制工具调用时是否带上对话历史

3.5 RAG：检索增强生成

以 PGVector 为向量数据库为例，QuestionAnswerAdvisor 会自动完成向量检索并增强 Prompt：

添加 RAG 依赖

<dependency>
   <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-pgvector-store</artifactId>
</dependency>

配置向量数据库

spring:
datasource:
  url: jdbc:postgresql://localhost:5432/vectordb
  username: postgres
  password: password
ai:
  vectorstore:
    pgvector:
      index-type: HNSW
      distance-type: COSINE_DISTANCE
      dimensions: 1536

实现 RAG 问答

@Service
public class RagService {
​
   @Autowired
   private VectorStore vectorStore;
​
   @Autowired
   private ChatClient chatClient;
​
   // 1. 导入文档：读取 → 切分 → 嵌入 → 写入向量库
   public void ingest(Resource doc) {
       DocumentReader reader = new TextReader(doc);
       List<Document> docs = new TokenTextSplitter().apply(reader.get());
       vectorStore.add(docs);   // 自动调用 EmbeddingModel 向量化
  }
​
   // 2. 问答：检索相关片段 → 拼入提示 → 调用模型
   public String ask(String question) {
       // QuestionAnswerAdvisor 会自动完成向量检索并增强 Prompt
       return chatClient.prompt()
              .user(question)
              .advisors(new QuestionAnswerAdvisor(vectorStore))
              .call()
              .content();
  }
}

1.1.3 对向量检索的多项增强：

• Neo4j Vector Store 支持自定义过滤表达式转换器

• SimpleVectorStore 支持按过滤条件删除

• Azure Vector Store 支持配置字段名（兼容已有索引）

• TokenTextSplitter 支持自定义标点符号

3.6 结构化输出（POJO 映射）

生成式 AI 经常返回自然语言，但业务系统需要结构化数据。Spring AI 支持把模型输出直接映射为 Java 对象：

record FlightInfo(String flightNo, String departure, String arrival) {}
​
@GetMapping("/flight")
public FlightInfo extractFlight(@RequestParam String text) {
   return chatClient.prompt()
          .user(u -> u.text("从以下文本中提取航班信息：{text}").param("text", text))
          .call()
          .entity(FlightInfo.class);   // 自动按 JSON 解析为 POJO
}

底层借助 Jackson 的 ObjectMapper 完成类型转换，省去了手写解析逻辑。

1.1.4 新增：运行时可动态禁用原生结构化输出，增强了配置和使用场景的灵活性。

3.7 多模态：让 AI"看懂"图片

多模态 AI 能同时理解文本和图像。以 GPT-4o 为例，Spring AI 支持将图片与文本一起发送给模型：

@Service
public class MultimodalService {
​
   private final ChatClient chatClient;
​
   public MultimodalService(ChatClient.Builder builder) {
       this.chatClient = builder.build();
  }
​
   public String analyzeReceipt(byte[] imageBytes) {
       return chatClient.prompt()
              .user(userSpec -> userSpec
                      .text("请分析这张收据图片，提取商户名称、消费总额和明细列表，以JSON格式返回")
                      .media(MimeTypeUtils.IMAGE_JPEG, new ByteArrayResource(imageBytes))
              )
              .call()
              .content();
  }
}

3.8 MCP 集成：连接外部工具生态

MCP（Model Context Protocol）是连接 AI 模型与外部工具的标准化协议，Spring AI 1.1 提供了完整的 MCP 集成支持，这是 1.1 版本最显著的特色功能。

添加 MCP 依赖

<dependency>
   <groupId>org.springframework.experimental</groupId>
   <artifactId>spring-ai-mcp</artifactId>
   <version>1.0.0</version>
</dependency>

基于注解的 MCP 编程模型

@Service
public class WeatherService {
​
   @McpTool(description = "Get current weather for a location")
   public String getCurrentWeather(String location) {
       return "Sunny, 22°C in " + location;
  }
​
   @McpResource(description = "Database schema of users table")
   public String getDatabaseSchema() {
       return """
           CREATE TABLE users (
               id BIGINT,
               name VARCHAR(100),
               email VARCHAR(100)
          );""";
  }
​
   @McpPrompt(template = "Write a SQL query to {{intent}}")
   public String generateSqlQuery(@PromptVariable("intent") String userIntent) {
       return "";  // 实际由模板渲染
  }
}

启动后，MCP 服务自动注册这些能力，供 AI Agent 调用（支持 HTTP/gRPC/STDIO 多种传输方式）。

将 MCP 工具注入 ChatClient

@Configuration
public class McpConfig {
​
   @Bean
   public McpClient mcpClient() {
       var stdioParams = ServerParameters.builder("npx")
              .args("-y", "@modelcontextprotocol/server-brave-search")
              .addEnvVar("BRAVE_API_KEY", System.getenv("BRAVE_API_KEY"))
              .build();
​
       return McpClient.using(new StdioClientTransport(stdioParams)).sync();
  }
​
   @Bean
   public ChatClient chatClient(ChatClient.Builder builder, McpClient mcpClient) {
       var init = mcpClient.initialize();
​
       return builder
              .defaultFunctions(mcpClient.listTools().tools().stream()
                      .map(tool -> new McpFunctionCallback(mcpClient, tool))
                      .toArray(McpFunctionCallback[]::new))
              .build();
  }
}

3.9 Agent 智能体开发

Spring AI Alibaba 在 1.1.2.x 版本中提供了完整的 Agent 开发能力，基于 Graph 工作流和 Agent Framework 可将 Multi-Agent 开发周期从数天压缩到数小时。

添加依赖

<dependency>
   <groupId>com.alibaba.cloud.ai</groupId>
   <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
   <version>1.1.2.0</version>
</dependency>

创建 ReactAgent

@Component
public class WeatherAgent {
​
   private final ReactAgent agent;
​
   public WeatherAgent(ChatModel chatModel, WeatherTools weatherTools) {
       this.agent = ReactAgent.builder()
              .name("weather_assistant")
              .model(chatModel)
              .tools(weatherTools)
              .systemPrompt("你是一个专业的天气助手，帮用户查询天气信息")
              .build();
  }
​
   public String ask(String question) {
       return agent.call(question);
  }
}

四、Spring AI 的好处

4.1 与 Spring 生态零摩擦

这是 Spring AI 最核心的优势。对于已经使用 Spring Boot 的团队，接入 AI 能力就像新增一个 starter 一样自然。在 Spring Boot 3.4+ 中，spring-ai 模块已深度嵌入核心启动流程，依赖注入、自动配置、配置中心、Spring Security 鉴权、Spring AOP 监控、Actuator 健康检查等现成能力可直接复用，无需为 AI 应用单独搭建一套运维体系。

4.2 可移植的模型抽象

统一的 ChatClient、EmbeddingModel、VectorStore 接口，让你在 OpenAI、Anthropic、Azure、Ollama、DeepSeek、通义千问等模型之间切换时，业务代码几乎不变——多数情况只改配置文件。这对规避供应商锁定、做多云部署非常关键。

4.3 低学习成本、高开发效率

熟悉 Spring 的开发者几乎可以"开箱即用"。ChatClient 提供流式 DSL，实现一个带记忆和工具调用的对话接口只需十几行代码。对比需要手动 wiring 各组件的方案，开发效率显著提升。

4.4 企业级就绪

框架原生提供可观测性（模型调用链路追踪、令牌用量统计）、工具调用、RAG 流水线、Prompt Caching 降本、评估框架等，直面企业最关心的幻觉控制和安全合规问题。

4.5 GraalVM 原生镜像支持

Spring Boot 3.4+ 对 GraalVM 原生镜像的支持达到新高度，Spring AI 应用可以编译为原生镜像，实现毫秒级启动和更低内存占用，非常适合 Serverless 和云原生部署场景。

4.6 模块化设计

按需引入功能模块，避免依赖臃肿。你可以只用 ChatClient 做简单对话，也可以逐步叠加 RAG、Tool Calling、MCP、Agent 等能力。

五、与 LangChain4j 的对比（2026 版）

LangChain4j 是 Java 生态中另一个主流 AI 框架，灵感来自 Python 的 LangChain、Haystack 和 LlamaIndex 的融合。截至 2026 年，LangChain4j 已发布 1.0 GA 正式版，最新迭代到 1.11.0，其 PgVector 模块原生支持了混合检索（Hybrid Search），将关键词检索与向量语义检索融合以提升 RAG 准确率。

两者设计哲学不同：Spring AI 强调"约定优于配置，深度集成 Spring 生态"，LangChain4j 侧重"模块化与显式组合，提供高度灵活性"。

核心能力对比表

各自更适合的场景

优先选 Spring AI

• ✅ 现有 Spring Boot 项目要扩展 AI 功能

• ✅ 需要 MCP 工具生态集成

• ✅ 需要多模态或复杂 RAG 流水线

• ✅ 要求与企业级安全、监控、配置中心深度集成

• ✅ 追求 GraalVM 原生镜像和云原生部署

• ✅ 追求长期稳定演进的企业级应用

优先选 LangChain4j

• ✅ 快速原型开发或模型实验

• ✅ 需要复杂 Agent 调度、工具链组合、多步推理且对控制粒度要求高

• ✅ 需要小众模型（如 ChatGLM）或多云部署

• ✅ 项目本身不在 Spring 生态内（如 Quarkus）

• ✅ 需要原生混合检索等特定 RAG 能力

💡 值得一提的是：两者并非互斥——可以在 Spring 应用中用 Spring AI 做基础模型调用和向量检索，再引入 LangChain4j 处理更复杂的链式任务或 Agent 逻辑，各取所长。

六、优缺点总结

优点

缺点

适用场景

• Spring Boot / Cloud 技术栈的企业

• 企业级 RAG 知识库系统

• AI 智能客服、内容生成应用

• 需要多模型切换或国内模型接入的项目

• 需要 MCP 工具生态集成的 Agent 应用

• 追求云原生/GraalVM 原生镜像的高性能场景

七、选型小结

2026 年的 Java AI 生态已经相当成熟。Spring AI 凭借与 Spring Boot 的深度集成、MCP 生态、Agent 工程和 GraalVM 支持，已成为企业级 Java AI 应用的主流选择；LangChain4j 则以灵活性和复杂智能体构建能力见长。

没有绝对"更好"的框架，关键看项目上下文：

• 如果你的团队已深度使用 Spring Boot，Spring AI 几乎是不二之选

• 如果你更看重灵活性、复杂智能体的构建能力，或项目脱离 Spring 体系，LangChain4j 会让你更得心应手

理解两者的设计哲学差异，比纠结"哪个更强"更有价值——它们解决的是 Java AI 落地的不同侧面。

附录：快速上手清单

最小可用项目（3 步搞定）

推荐学习路径

基础对话（ChatClient）
↓
结构化输出（entity()）
↓
多轮对话（MessageChatMemoryAdvisor）
↓
Tool Calling（@Tool 注解）
↓
RAG（QuestionAnswerAdvisor + VectorStore）
↓
多模态（media() 方法）
↓
MCP 集成（@McpTool / @McpResource / @McpPrompt）
↓
Agent 开发（ReactAgent + Graph 工作流）

📝 参考来源：

• Spring AI 官方文档

• Spring AI 1.1 正式发布 – 博客园

• Spring AI 1.1.3 19个新特性 – 博客园

• Spring AI 1.1.4 发布 – SegmentFault

• SpringAI入门指南 – 苏三说技术

• LangChain4j 官方文档

• LangChain4j 混合检索 – CSDN

最后更新：2026 年 6 月 29 日