更新日期：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 量身定制。

版本演进时间线

版本 时间 里程碑意义
1.0 GA 2025.05.20 首个正式版，稳定 API，标志 Spring 生态全面拥抱 AI
1.1 GA 2025.11 整合 MCP，850+ 项改进，241 个 bug 修复
1.1.3 2026.03 19 个新特性，升级至 Spring Boot 3.5.11
1.1.4 2026.05 运行时动态禁用结构化输出，稳定性优化
2.0.0-M4 2026 下一代版本开发中，兼容 Spring Framework 7.x / Java 21+

在经历了八个里程碑版本（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 月，主要特性包括：

能力矩阵

能力类型 支持的功能 代表模型/提供商
聊天完成 对话、代码生成、内容创作 OpenAI、通义千问、DeepSeek、Claude
嵌入 文本向量化、语义搜索 同上
多模态 图像识别、视频理解、音频转录 GPT-4o、Qwen-VL
函数调用 外部API集成、工具调用 主流模型均支持
向量数据库 相似性检索、RAG PGVector、Milvus、Redis、Chroma
MCP 模型上下文协议、外部工具集成 Spring AI 原生支持（1.1 起重磅特性）

关键特性详解

  • 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 如何选择？
特性维度 ChatModel ChatClient
API 复杂度 高（需手动构建 Prompt） 低（流式 DSL）
Advisor 支持 ❌ 不支持 ✅ 内置支持
记忆管理 需手动实现 ✅ 自动会话记忆
流式输出 需额外封装 ✅ 一行代码开启
错误处理 需自行捕获 ✅ 统一异常封装
推荐度 ⭐⭐ 特殊场景使用 ⭐⭐⭐⭐⭐ 首选方案

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（1.1.4 / 2.0-M4） LangChain4j（1.11）
设计哲学 约定优于配置，深度集成 Spring 模块化显式组合，高度灵活
Spring 生态整合 极强，深度嵌入 Spring Boot 核心启动流程 良好，需手工 wiring 多数组件
学习曲线 熟悉 Spring 则近乎零摩擦；否则偏陡 相对平缓，对非 Spring 项目友好
核心抽象 ChatClient、VectorStore、Advisor ChatLanguageModel、Tools、ChatMemory、Chains
模型支持 主流厂商齐全，多模态原生支持 20+ 供应商，含 ChatGLM 等，切换更灵活
工具调用 @Tool 注解声明式，支持流式、动态 Schema @Tool 注解显式定义，控制粒度更细
MCP 支持 原生集成，注解编程模型（1.1 起重磅特性） 有集成支持，但非核心卖点
RAG 内置模块化 RAG 库，Advisor 自动检索 ConversationalRetrievalChain，PgVector 原生混合检索
多步推理/Agent ReactAgent + Graph 工作流（2026 新增） 原生支持 Chains/Agents/Memory，成熟度高
企业级特性 原生安全/监控/熔断/Prompt Caching/可观测性 需自行实现或整合
原生镜像 支持 GraalVM（Spring Boot 3.4+） 需额外配置
成熟度 依托 Spring 社区，1.1 GA 后稳定成熟 1.0 GA 后稳定性提升，社区活跃

各自更适合的场景

优先选 Spring AI

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

  • ✅ 需要 MCP 工具生态集成

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

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

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

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

优先选 LangChain4j

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

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

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

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

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

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

六、优缺点总结

优点

优势 说明
与 Spring Boot 深度集成 遵循 Spring 开发者熟悉的配置和开发习惯
模型切换零成本 统一 API，改配置即可切换不同模型
企业级特性完备 支持事务、安全、监控等 Spring 生态能力
模块化设计 按需引入功能模块，避免依赖臃肿
官方文档完善 Spring 团队持续维护，1.0 GA 后稳定可靠
MCP 原生支持 1.1 起整合 Model Context Protocol，连接外部工具生态
Agent 工程就绪 ReactAgent + Graph 工作流，支持多智能体开发
GraalVM 支持 原生镜像编译，适合云原生/Serverless 场景

缺点

劣势 说明
学习曲线 需理解 ChatModel、ChatClient、Advisor 等抽象概念
Java 版本要求 需 JDK 17+（2.0 需 JDK 21+）
生态相对年轻 相比 Python 的 LangChain，社区规模仍需发展
复杂 Agent 场景 在自定义 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 步搞定）

  1. 创建 Spring Boot 3.4+ 项目，添加 BOM + OpenAI/Ollama starter

  2. 配置 API Key 或 Ollama 地址

  3. 注入 ChatClient.Builder，写一个 /chat 接口

推荐学习路径

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

📝 参考来源：

最后更新：2026 年 6 月 29 日

# 人工智能 # java # spring
Logo
MCP技术社区

欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！

更多推荐

cover

Agent Native 是什么？为什么 AI Agent 时代的软件不能只是“加一个聊天框”

avatar MCP技术社区

TRAE智能体如何高效集成MCPServer

TRAE任务执行引擎通过MCPServer实现多智能体协作，提供任务分解、分发与结果聚合功能。文章演示了Python代码示例，包括HTTP/WebSocket通信接口、任务注册分发机制、错误重试策略及性能优化建议（连接池、消息压缩、超时设置）。该技术方案适用于物流调度等分布式场景，开发者可根据需求调整通信协议和容错机制。核心价值在于标准化多智能体通信，提升系统可靠性和执行效率。

avatar MCP技术社区
cover

OpenMontage是什么？开源AI视频生产系统部署与使用指南

avatar MCP技术社区