GPT-5.5 在 Spring Boot 项目中的集成实战

2601_96016718

442人浏览 · 2026-05-08 09:49:05

2601_96016718 · 2026-05-08 09:49:05 发布

概要

GPT-5.5 是 OpenAI 最新的旗舰推理模型，支持 reasoning_effort 四档推理力度控制（minimal/low/medium/high），Terminal-Bench 2.0 得分 82.7%。该模型沿用 Chat Completions API 接口格式，兼容 OpenAI SDK 和第三方 SDK，Java 生态有成熟的接入方案。

Spring Boot 是 Java 生态中使用最广泛的 Web 框架。Spring AI 是 Spring 官方推出的 AI 集成框架，提供 ChatClient 统一抽象层，支持 OpenAI、Ollama、Anthropic、Google 等多个模型提供商。通过 Spring AI 接入 GPT-5.5，开发者可以用 Spring 熟悉的编程模型（自动配置、Bean 注入、属性配置）完成 AI 能力集成，不需要手动管理 HTTP 连接、JSON 序列化、重试策略等底层细节。

本文将从环境搭建、Spring AI 集成、多轮对话管理、Function Calling 实现、流式输出、生产配置六个环节，完整记录 GPT-5.5 在 Spring Boot 项目中的集成实战。

KULAAI（c.877ai.cn）作为 AI 模型聚合平台，支持接口调用 GPT-5.5、Gemini 3.1 Pro、Claude、DeepSeek 等多个主流大模型，Spring Boot 项目通过修改 baseUrl 和 apiKey 即可接入多个模型。

整体架构流程

Spring Boot + Spring AI + GPT-5.5 的集成架构：

text

text

┌─────────────────────────────────────────────────┐ │ Spring Boot Application │ │ │ │ ┌───────────────────────────────────────────┐ │ │ │ Controller Layer │ │ │ │ @RestController │ │ │ │ ├── /chat （同步对话） │ │ │ │ ├── /chat/stream （流式输出） │ │ │ │ └── /chat/function （工具调用） │ │ │ ├───────────────────────────────────────────┤ │ │ │ Service Layer │ │ │ │ ChatClient chatClient │ │ │ │ ├── prompt() （构建 Prompt） │ │ │ │ ├── tools() （注册函数工具） │ │ │ │ └── stream() （流式调用） │ │ │ ├───────────────────────────────────────────┤ │ │ │ Spring AI Auto-Configuration │ │ │ │ OpenAiChatModel │ │ │ │ ├── ChatClient.Builder │ │ │ │ ├── OpenAiApi (Retrofit/RestClient) │ │ │ │ └── Retry / Timeout / Token Tracking │ │ │ ├───────────────────────────────────────────┤ │ │ │ application.yml │ │ │ │ spring.ai.openai.api-key=xxx │ │ │ │ spring.ai.openai.base-url=xxx │ │ │ │ spring.ai.openai.chat.options.model=xxx │ │ │ └───────────────────────────────────────────┘ │ └─────────────────────────────────────────────────┘  ↓  GPT-5.5 API (Chat Completions)

请求处理流程：

text

text

HTTP Request → Controller → ChatClient.builder().build()  ↓  .prompt(new Prompt(messages, options))  .tools(functionCallbacks)  .call()  ↓  OpenAiChatModel → OpenAiApi  ↓  POST /v1/chat/completions  ↓  Response → ChatResponse → Entity

技术名词解释

Spring AI Spring 官方推出的 AI 集成框架。提供 ChatClient 统一抽象层，支持 OpenAI、Ollama、Anthropic、Google 等多个模型提供商。开发者用同一套代码就能在不同模型之间切换，只需修改配置文件。

ChatClient Spring AI 提供的流式 Fluent API，用于与 AI 模型通信。通过 ChatClient.Builder 构建实例，支持 prompt()、tools()、call()、stream() 等链式调用。

OpenAiChatModel Spring AI 中对接 OpenAI 接口的 ChatModel 实现。底层通过 OpenAiApi（基于 RestClient 或 Retrofit）发送 HTTP 请求到 Chat Completions 端点。

ChatClient.Builder ChatClient 的构建器，由 Spring 自动配置。注入后可创建多个 ChatClient 实例，每个实例可配置不同的默认选项。

Function Calling（函数调用） 让模型输出结构化的函数调用请求。在 Spring AI 中通过 @Description 注解声明函数，模型会自动判断何时调用。

reasoning_effort GPT-5.5 的推理力度控制参数。minimal 档位响应最快，high 档位推理深度最大。Spring AI 中通过 ChatOptions 设置。

SSE（Server-Sent Events） 服务端向客户端单向推送数据的协议。Spring AI 的 stream() 方法返回 Flux，配合 SSE 实现流式输出。

OpenAiApi Spring AI 内部的 HTTP 客户端封装。基于 RestClient（Spring 6.1+）或 Retrofit（OkHttp）实现，负责发送请求到 OpenAI 的 Chat Completions 端点。

技术细节

一、环境搭建与依赖配置

Spring Boot 3.x + Spring AI 的依赖配置。

pom.xml 中添加 Spring AI BOM 和 OpenAI starter：

xml

xml

<dependencyManagement>  <dependencies>  <dependency>  <groupId>org.springframework.ai</groupId>  <artifactId>spring-ai-bom</artifactId>  <version>1.0.0</version>  <type>pom</type>  <scope>import</scope>  </dependency>  </dependencies> </dependencyManagement>  <dependencies>  <dependency>  <groupId>org.springframework.ai</groupId>  <artifactId>spring-ai-starter-model-openai</artifactId>  </dependency> </dependencies>

application.yml 配置：

yaml

yaml

spring:  ai:  openai:  api-key: ${OPENAI_API_KEY}  base-url: https://api.openai.com # 或聚合平台地址  chat:  options:  model: gpt-5.5  temperature: 0.3  max-tokens: 2048

通过聚合平台接入时只需修改 base-url 和 api-key，model 参数改为对应的模型标识即可。切换到 Gemini 3.1 Pro 或其他模型时同样只改配置文件，代码不需要变动。

二、ChatClient 基础用法

Spring AI 推荐通过 ChatClient.Builder 构建 ChatClient 实例。

java

java

@Configuration public class AiConfig {   @Bean  public ChatClient chatClient(ChatClient.Builder builder) {  return builder  .defaultSystem("你是一个专业的技术助手，回答简洁准确。")  .defaultOptions(OpenAiChatOptions.builder()  .model("gpt-5.5")  .temperature(0.3)  .build())  .build();  } }

注入 ChatClient 后即可在 Service 层使用：

java

java

@Service public class ChatService {   private final ChatClient chatClient;   public ChatService(ChatClient chatClient) {  this.chatClient = chatClient;  }   public String chat(String userMessage) {  return chatClient.prompt()  .user(userMessage)  .call()  .content();  } }

Controller 层暴露 REST 接口：

java

java

@RestController @RequestMapping("/api") public class ChatController {   private final ChatClient chatClient;   public ChatController(ChatClient chatClient) {  this.chatClient = chatClient;  }   @PostMapping("/chat")  public String chat(@RequestBody ChatRequest request) {  return chatClient.prompt()  .user(request.getMessage())  .call()  .content();  } }

三、多轮对话管理

Spring AI 中多轮对话通过维护 Message 列表实现。

java

java

@Service public class MultiTurnChatService {   private final ChatClient chatClient;  private final Map<String, List<Message>> sessionStore = new ConcurrentHashMap<>();   public String chat(String sessionId, String userMessage) {  List<Message> history = sessionStore  .computeIfAbsent(sessionId, k -> new ArrayList<>());   history.add(new UserMessage(userMessage));   String response = chatClient.prompt()  .messages(history)  .call()  .content();   history.add(new AssistantMessage(response));   // 滑动窗口：保留最近 10 轮  if (history.size() > 20) {  List<Message> recent = history.subList(  history.size() - 20, history.size()  );  sessionStore.put(sessionId, new ArrayList<>(recent));  }   return response;  } }

UserMessage 和 AssistantMessage 是 Spring AI 提供的消息类型。SystemMessage 用于系统级指令。三种消息类型组合构成完整的对话上下文。

多轮对话中需要控制历史长度。10 轮对话约消耗 3000-5000 tokens（取决于每轮长度）。建议保留最近 10 轮，更早的历史做摘要压缩或直接丢弃。

四、Function Calling 实现

Spring AI 中通过 @Description 注解声明函数工具。

java

java

public class OrderTools {   @Description("根据订单号查询订单状态和物流信息")  public OrderInfo queryOrder(  @Description("订单号，格式如 ORD-20240101-001") String orderId  ) {  // 调用订单服务查询  return orderService.queryByOrderId(orderId);  }   @Description("为用户创建售后工单")  public WorkOrder createAfterSales(  @Description("订单号") String orderId,  @Description("问题类型：退货/换货/维修") String type,  @Description("问题描述") String description  ) {  return workOrderService.create(orderId, type, description);  } }

注册工具并调用：

java

java

String response = chatClient.prompt()  .user("帮我查一下订单 ORD-20240501-123 的物流状态")  .tools(new OrderTools())  .call()  .content();

模型会自动判断是否需要调用工具。如果用户问题需要查询订单信息，模型会输出 queryOrder 函数的调用请求。Spring AI 自动执行函数并将结果回传给模型，模型基于结果生成最终回答。

敏感操作（退款、删除）需要在应用层加二次确认逻辑，不能让模型直接执行不可逆操作。

五、流式输出

Spring AI 的 stream() 方法返回 Flux，配合 SSE 实现流式输出。

java

java

@GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<String> chatStream(@RequestParam String message) {  return chatClient.prompt()  .user(message)  .stream()  .content(); }

前端用 EventSource 或 fetch + ReadableStream 接收流式数据。Nginx 反向代理需要配置 proxy_buffering off，否则流式效果会失效。

流式输出的首字响应时间约 0.5 秒，比同步调用的 3-5 秒快很多。用户体验提升明显。

六、生产环境配置

超时配置。 Spring AI 底层的 OpenAiApi 基于 RestClient（Spring 6.1+）或 Retrofit（OkHttp）实现。默认超时可能不够——复杂推理任务在 high 模式下可能需要 10 秒以上。建议设置连接超时 5 秒、读取超时 60 秒。

重试策略。 网络抖动或 API 限流（429）时需要自动重试。Spring AI 支持通过 Spring Retry 配置重试策略——最多重试 3 次，间隔指数退避。

Token 消耗监控。 ChatResponse 中包含 usage 信息（prompt_tokens、completion_tokens、total_tokens）。记录每次调用的 token 消耗，按用户维度聚合统计，设置每日预算上限。

多模型路由。 通过 ChatClient.Builder 创建多个实例，每个实例配置不同的 model 和 base-url。简单任务路由到低成本模型（Gemini 3.1 Pro low 模式），复杂任务路由到 GPT-5.5 high 模式。

java

java

@Bean public ChatClient gptClient(ChatClient.Builder builder) {  return builder.clone()  .defaultOptions(OpenAiChatOptions.builder()  .model("gpt-5.5")  .build())  .build(); }  @Bean public ChatClient geminiClient(ChatClient.Builder builder) {  return builder.clone()  .defaultSystem("...")  .defaultOptions(OpenAiChatOptions.builder()  .model("gemini-3.1-pro")  .build())  .build(); }

小结

GPT-5.5 在 Spring Boot 项目中的集成通过 Spring AI 框架可以大幅简化。ChatClient 提供统一的 Fluent API，开发者不需要手动管理 HTTP 连接、JSON 序列化、重试策略等底层细节。Function Calling 通过 @Description 注解声明，模型自动判断调用时机。流式输出通过 stream() 方法返回 Flux，一行代码实现 SSE 推送。

生产环境中需要关注四个工程细节：超时配置要覆盖 high 模式的长推理场景、重试策略要处理 429 限流、Token 消耗要按用户维度监控、多模型路由要根据任务复杂度动态选择。

建议先在聚合平台上验证 GPT-5.5 的接口兼容性——修改 base-url 和 api-key 即可接入，代码不需要变动。用实际业务场景做测试，对比不同 reasoning_effort 档位下的回答质量和响应时间。