Spring AI 2.0 接入 AI 大模型完全指南：Java 开发者从零到生产（2026）

摘要

• Spring AI 2.0.0-M4 于 2026 年 3 月 26 日发布，基于 Spring Boot 4.0，Java AI 开发进入原生时代
• 通过 OpenAI 兼容协议，一套 Spring Boot 配置接入 GPT-5.4、Claude Opus 4.6、Gemini 3.1 Pro 等 50+ 模型
• 附完整代码：流式聊天、Function Calling、RAG 知识库问答、结构化输出
• 覆盖生产要点：错误重试、超时控制、多模型切换、Docker 部署

目录

• 为什么 Java 开发者应该关注 Spring AI
• Spring AI 2.0 核心变化
• 环境准备与项目搭建
• 第一个 AI 对话：五分钟跑通
• 流式输出：实现打字机效果
• Function Calling：让大模型调用你的 Java 方法
• 结构化输出：AI 回复直接映射 Java 对象
• 多模型切换：一套代码调所有模型
• 生产环境最佳实践
• 总结与下一步

为什么 Java 开发者应该关注 Spring AI

Java 在 AI 应用开发领域一直被 Python 压着打。不是 Java 不行，而是缺一个真正懂 Java 生态的 AI 框架。

2026 年，这个局面变了。

Spring AI 2.0 是 Spring 官方推出的 AI 工程框架，不是第三方社区项目，是和 Spring Boot、Spring Security 同等级别的一等公民。它的设计哲学很简单：让 Java 开发者用最熟悉的方式（自动配置、依赖注入、配置文件）接入 AI 能力，而不是学一套全新的 API。

这意味着什么？

// 这就是 Spring AI 调用大模型的全部代码
@RestController
public class ChatController {
    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return chatClient.prompt(message).call().content();
    }
}

一个 Controller、一个注入、一行调用。配置文件里填好 API Key 和模型名，就完了。如果你写过 Spring Boot，这段代码你闭着眼睛都能理解。

Spring AI 2.0 核心变化

2026 年 3 月 26 日，Spring AI 发布了 2.0.0-M4 版本（同时发布了 1.1.4 和 1.0.5 维护版本），这是 2.0 正式版前的第四个里程碑版本。以下是最重要的变化：

基础设施升级

• Spring Boot 4.0 + Spring Framework 7.0：最低 Java 17，推荐 Java 21
• 原生集成 OpenAI 官方 Java SDK：不再自己造轮子，直接用 OpenAI 官方的 Java 客户端库
• 安全修复：CVE-2026-22738、CVE-2026-22742 等多个漏洞修复

核心 API 增强

• ChatClient 结构化输出：.entity(MyClass.class) 直接把 AI 回复映射成 Java 对象，告别手动解析 JSON
• Agent Skills：模块化的技能系统，AI Agent 可以按需加载工具和能力
• A2A 协议支持：Agent-to-Agent 通信，多个 AI Agent 之间可以协作

模型支持

Spring AI 2.0 内置支持的模型提供商包括 OpenAI、Anthropic（Claude）、Google Vertex AI（Gemini）、Amazon Bedrock、Mistral、Ollama 等。更重要的是，任何提供 OpenAI 兼容接口的平台都可以通过修改 base-url 接入——这正是我们用 Ofox.ai 一个配置接入 50+ 模型的基础。

环境准备与项目搭建

前置要求

• JDK 17+（推荐 JDK 21，Spring AI 2.0 的构建目标）
• Maven 3.9+ 或 Gradle 8.x
• Ofox.ai 账号：注册地址，注册即送免费额度
• 一个趁手的 IDE（IntelliJ IDEA 推荐）

使用 Spring Initializr 创建项目

访问 start.spring.io，选择：

• Spring Boot: 4.0.x
• Java: 21
• Dependencies: Spring Web, Spring AI OpenAI

或者直接用命令行：

curl https://start.spring.io/starter.tgz \
  -d type=maven-project \
  -d language=java \
  -d bootVersion=4.0.0 \
  -d javaVersion=21 \
  -d dependencies=web,spring-ai-openai \
  -d name=ai-demo \
  | tar -xzvf -

Maven 依赖配置

如果手动配置，在 pom.xml 中添加：

<properties>
    <java.version>21</java.version>
    <spring-ai.version>2.0.0-M4</spring-ai.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

<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>

<!-- Spring AI 里程碑版本需要额外仓库 -->
<repositories>
    <repository>
        <id>spring-milestones</id>
        <url>https://repo.spring.io/milestone</url>
    </repository>
</repositories>

配置 Ofox.ai 作为 API 提供商

这是最关键的一步——只需要在 application.yml 中配置三个参数，就能通过 Ofox.ai 接入所有主流大模型：

spring:
  ai:
    openai:
      api-key: ${OFOX_API_KEY}       # 你的 Ofox.ai API Key
      base-url: https://api.ofox.ai  # 指向 Ofox.ai
      chat:
        options:
          model: anthropic/claude-opus-4.6  # 默认模型
          temperature: 0.7

把 OFOX_API_KEY 设为环境变量：

export OFOX_API_KEY=sk-your-ofox-api-key

就这样。Spring AI 的 OpenAI 模块会自动识别 base-url，所有 API 请求都会发往 Ofox.ai，后者再路由到对应的模型提供商。你的代码不需要做任何改动。

为什么选 Ofox.ai？ 直连 OpenAI/Anthropic 的 API 在国内存在网络不稳定问题，而 Ofox.ai 提供国内加速节点，延迟低至 200ms。更重要的是，一个 API Key 就能调用 GPT、Claude、Gemini、DeepSeek、Qwen 等 50+ 模型，免去了注册多个平台、管理多套密钥的麻烦。支持人民币支付，注册即送免费额度。

第一个 AI 对话：五分钟跑通

最简 Controller

package com.example.aidemo.controller;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/chat")
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder
            .defaultSystem("你是一个专业的技术助手，用简洁清晰的中文回答问题。")
            .build();
    }

    @GetMapping
    public String chat(@RequestParam String message) {
        return chatClient.prompt(message)
            .call()
            .content();
    }
}

启动并测试

mvn spring-boot:run

curl "http://localhost:8080/api/chat?message=用一句话解释什么是Spring+AI"

响应：

Spring AI 是 Spring 官方推出的 AI 工程框架，让 Java 开发者通过熟悉的
Spring Boot 自动配置和依赖注入方式接入 GPT、Claude 等大语言模型。

带对话历史的多轮对话

单轮对话只是起步，实际应用需要维护上下文：

@RestController
@RequestMapping("/api/conversation")
public class ConversationController {

    private final ChatClient chatClient;

    public ConversationController(ChatClient.Builder builder) {
        this.chatClient = builder
            .defaultSystem("你是一个 Java 技术专家，擅长 Spring 生态。")
            .build();
    }

    @PostMapping
    public String conversation(@RequestBody ConversationRequest request) {
        // 构建包含历史消息的 Prompt
        var promptBuilder = chatClient.prompt();

        // 添加历史消息
        for (var msg : request.history()) {
            if ("user".equals(msg.role())) {
                promptBuilder.user(msg.content());
            } else {
                promptBuilder.assistant(msg.content());
            }
        }

        // 添加当前用户消息
        promptBuilder.user(request.message());

        return promptBuilder.call().content();
    }

    record ConversationRequest(
        String message,
        List<Message> history
    ) {}

    record Message(String role, String content) {}
}

流式输出：实现打字机效果

非流式请求需要等模型生成完整回复（通常 5-30 秒）才返回。流式输出让每个 Token 生成后立即推送给客户端，用户几百毫秒就能看到第一个字。

后端：SSE 流式端点

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Flux;

@RestController
@RequestMapping("/api/stream")
public class StreamController {

    private final ChatClient chatClient;

    public StreamController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @GetMapping(produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> stream(@RequestParam String message) {
        return chatClient.prompt(message)
            .stream()
            .content();
    }
}

没看错，就这么几行。Spring AI 的 stream() 方法返回 Flux<String>，Spring WebFlux 自动将其转为 SSE（Server-Sent Events）流。

需要 WebFlux 依赖

在 pom.xml 中添加：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

测试流式输出

curl -N "http://localhost:8080/api/stream?message=写一首关于Java的五言绝句"

你会看到内容逐字输出，而不是等完整回复。

前端对接：EventSource

const eventSource = new EventSource(
  `/api/stream?message=${encodeURIComponent(userInput)}`
);

let fullResponse = '';

eventSource.onmessage = (event) => {
  fullResponse += event.data;
  document.getElementById('response').innerText = fullResponse;
};

eventSource.onerror = () => {
  eventSource.close();
};

Function Calling：让大模型调用你的 Java 方法

Function Calling 是大模型最实用的能力之一——模型不再只能”说”，还能”做”。Spring AI 用 Java 的方式实现了这个能力：定义一个 Function Bean，模型会在需要时自动调用。

定义工具函数

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Description;

import java.util.function.Function;

@Configuration
public class AiTools {

    // 天气查询工具
    @Bean
    @Description("查询指定城市的实时天气信息")
    public Function<WeatherRequest, WeatherResponse> getWeather() {
        return request -> {
            // 实际项目中调用天气 API
            return new WeatherResponse(
                request.city(),
                "晴",
                26,
                "东南风 3 级"
            );
        };
    }

    // 数据库查询工具
    @Bean
    @Description("查询订单状态，输入订单号返回订单信息")
    public Function<OrderRequest, OrderResponse> queryOrder() {
        return request -> {
            // 实际项目中查询数据库
            return new OrderResponse(
                request.orderId(),
                "已发货",
                "2026-03-28 预计送达"
            );
        };
    }

    record WeatherRequest(String city) {}
    record WeatherResponse(String city, String weather, int temperature, String wind) {}
    record OrderRequest(String orderId) {}
    record OrderResponse(String orderId, String status, String estimatedDelivery) {}
}

在 ChatClient 中注册工具

@GetMapping("/with-tools")
public String chatWithTools(@RequestParam String message) {
    return chatClient.prompt(message)
        .tools("getWeather", "queryOrder")  // 注册可用工具
        .call()
        .content();
}

测试

curl "http://localhost:8080/api/chat/with-tools?message=杭州今天天气怎么样"

Spring AI 会自动完成以下流程：

1. 把用户消息和工具定义发给大模型
2. 模型判断需要调用 getWeather，返回参数 {"city": "杭州"}
3. Spring AI 自动调用你的 Java 方法
4. 把结果回传给模型
5. 模型基于工具返回值生成自然语言回复

整个过程对你的代码来说是透明的——你只需要定义好工具函数。

结构化输出：AI 回复直接映射 Java 对象

让 AI 返回 JSON 并不难，难的是可靠地把 JSON 映射成 Java 对象。Spring AI 2.0 的结构化输出功能让这件事变得极其简单。

定义响应类型

public record MovieRecommendation(
    String title,
    String genre,
    int year,
    double rating,
    String reason
) {}

public record MovieList(
    List<MovieRecommendation> movies
) {}

使用 entity() 直接映射

@GetMapping("/recommend")
public MovieList recommend(@RequestParam String genre) {
    return chatClient.prompt("推荐 3 部" + genre + "类型的经典电影，包含名称、类型、年份、评分和推荐理由")
        .call()
        .entity(MovieList.class);  // 直接映射到 Java 对象
}

返回值已经是类型安全的 Java 对象，可以直接序列化为 JSON 返回给前端：

{
  "movies": [
    {
      "title": "盗梦空间",
      "genre": "科幻",
      "year": 2010,
      "rating": 9.3,
      "reason": "克里斯托弗·诺兰执导，层层嵌套的梦境设计令人叹为观止"
    },
    {
      "title": "星际穿越",
      "genre": "科幻",
      "year": 2014,
      "rating": 9.4,
      "reason": "硬科幻与父女情感的完美结合，黑洞可视化震撼人心"
    },
    {
      "title": "银翼杀手2049",
      "genre": "科幻",
      "year": 2017,
      "rating": 8.3,
      "reason": "视觉美学巅峰之作，对人工智能与人性的深度探讨"
    }
  ]
}

不需要手动写 JSON Schema，不需要解析 JSON 字符串，不需要处理格式错误——Spring AI 在底层帮你搞定了一切。

多模型切换：一套代码调所有模型

这是 Ofox.ai + Spring AI 最强大的组合能力——不改代码，只改配置，就能切换底层模型。

运行时动态切换模型

@GetMapping("/with-model")
public String chatWithModel(
    @RequestParam String message,
    @RequestParam(defaultValue = "anthropic/claude-opus-4.6") String model
) {
    return chatClient.prompt(message)
        .options(OpenAiChatOptions.builder()
            .model(model)
            .temperature(0.7)
            .build())
        .call()
        .content();
}

# 用 Claude Opus 4.6
curl "http://localhost:8080/api/chat/with-model?message=你好&model=anthropic/claude-opus-4.6"

# 用 GPT-5.4
curl "http://localhost:8080/api/chat/with-model?message=你好&model=openai/gpt-5.4"

# 用 Gemini 3.1 Pro
curl "http://localhost:8080/api/chat/with-model?message=你好&model=google/gemini-3.1-pro"

# 用 DeepSeek V4
curl "http://localhost:8080/api/chat/with-model?message=你好&model=deepseek/deepseek-chat-v4"

同一个端点、同一套代码，通过参数切换任意模型。这在 A/B 测试、灰度发布、成本优化等场景下非常实用。

通过配置文件管理多环境

# application-dev.yml（开发环境用便宜模型）
spring:
  ai:
    openai:
      base-url: https://api.ofox.ai
      api-key: ${OFOX_API_KEY}
      chat:
        options:
          model: openai/gpt-4.1-mini
          temperature: 0.7

---
# application-prod.yml（生产环境用旗舰模型）
spring:
  ai:
    openai:
      base-url: https://api.ofox.ai
      api-key: ${OFOX_API_KEY}
      chat:
        options:
          model: anthropic/claude-opus-4.6
          temperature: 0.3

Ofox.ai 支持的热门模型

生产环境最佳实践

1. 超时与重试配置

spring:
  ai:
    openai:
      base-url: https://api.ofox.ai
      api-key: ${OFOX_API_KEY}
      chat:
        options:
          model: anthropic/claude-opus-4.6
      # 连接和读取超时
      connect-timeout: 10s
      read-timeout: 120s
    retry:
      max-attempts: 3
      backoff:
        initial-interval: 1s
        multiplier: 2
        max-interval: 10s

2. API Key 安全

// ❌ 千万不要硬编码
spring.ai.openai.api-key=sk-xxx

// ✅ 用环境变量
spring.ai.openai.api-key=${OFOX_API_KEY}

// ✅ 或 Spring Vault / AWS Secrets Manager
spring.ai.openai.api-key=${sm://ofox-api-key}

3. 异步处理 + 限流

@RestController
@RequestMapping("/api/chat")
public class RateLimitedChatController {

    private final ChatClient chatClient;
    private final Semaphore semaphore = new Semaphore(10); // 最多 10 个并发

    public RateLimitedChatController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @PostMapping
    public ResponseEntity<String> chat(@RequestBody ChatRequest request) {
        if (!semaphore.tryAcquire()) {
            return ResponseEntity.status(429)
                .body("服务繁忙，请稍后重试");
        }
        try {
            String response = chatClient.prompt(request.message())
                .call()
                .content();
            return ResponseEntity.ok(response);
        } finally {
            semaphore.release();
        }
    }
}

4. 可观测性：日志与监控

# 开启 Spring AI 请求日志
logging:
  level:
    org.springframework.ai: DEBUG

# Actuator 监控端点
management:
  endpoints:
    web:
      exposure:
        include: health,metrics,prometheus

5. Docker 部署

FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY target/ai-demo-0.0.1-SNAPSHOT.jar app.jar
ENV OFOX_API_KEY=""
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

docker build -t ai-demo .
docker run -p 8080:8080 -e OFOX_API_KEY=sk-your-key ai-demo

常见报错与排查

总结与下一步

Spring AI 2.0 让 Java 开发者终于拥有了一个原生、优雅、生产就绪的 AI 开发框架。核心收获：

1. 零学习成本：如果你会 Spring Boot，你就会 Spring AI——自动配置、依赖注入、配置文件，全是熟悉的套路
2. 一套配置通吃：通过 Ofox.ai 的 OpenAI 兼容接口，改一个 base-url 就能接入 50+ 模型
3. 从 PoC 到生产：流式输出、Function Calling、结构化输出、重试机制——生产环境需要的能力全部内置

推荐的下一步

• 注册 Ofox.ai：ofox.ai，注册即送免费额度，五分钟跑通本文所有示例
• Spring AI 官方文档：docs.spring.io/spring-ai
• 源码仓库：github.com/spring-projects/spring-ai
• Spring AI Agentic Patterns 系列：Spring 官方博客的 Agent 开发模式深度解读

Spring AI 2.0 GA 预计 2026 年中发布。现在上手 M4 版本，等正式版发布时你已经是老手了。