Spring AI 升级推理模型差点翻车：一行配置切换到 OpenAI Responses API 全解决

Spring AI 升级推理模型差点翻车：一行配置切换到 OpenAI Responses API 全解决

换更强的模型本该让应用更聪明，而不是把工具调用搞坏。最近把 Spring AI 应用从 GPT-5-mini 升到 GPT-5.4 时踩了个坑——升级推理模型 + 开启 reasoning effort 后，工具调用直接报错。最后靠切到 OpenAI 的 Responses API 一行配置解决，过程挺有代表性，分享出来。

场景：一个桌游推荐助手

沿用之前的 Chat Loop 示例，做一个推荐桌游的助手。先定义一个领域类型：

record Game(
    String name,
    int minPlayers,
    int maxPlayers,
    int playTimeMinutes,
    boolean cooperative,
    double complexity) {}

再写个工具类，通过 @Tool 暴露给模型：

@Service
public class GameTools {

  @Tool(description = """
      Find board games suitable for a group.
      Returns games with player counts, play times,
      complexity, and whether they are cooperative.
      """)
  public List<Game> findGames() {
    return List.of(
        new Game("Pandemic", 2, 4, 45, true, 2.4),
        new Game("Forbidden Island", 2, 4, 30, true, 1.7),
        new Game("Just One", 3, 7, 20, true, 1.0),
        new Game("Codenames", 2, 8, 15, false, 1.3),
        new Game("7 Wonders", 3, 7, 30, false, 2.3)
    );
  }
}

工具故意写得简单——直接返回硬编码列表，不查库不过滤。因为我们要研究的是"模型怎么用工具"，而不是写推荐引擎。

注册工具用 ChatClientBuilderCustomizer：

@Bean
ChatClientBuilderCustomizer addGameTools(GameTools gameTools) {
  return builder ->
      builder.defaultTools(gameTools);
}

问模型："我们六个人玩桌游，三个新手，大约一小时，偏好合作类，玩什么好？" 模型会调用工具、筛选并推荐。列表里能容纳六人且是合作类的只有 Just One，回答正确，一切正常。

升级推理模型，翻车了

应用跑得好好的，但想象一下场景扩展：更多工具、更复杂的推荐逻辑、需要平衡多个偏好、决定工具调用顺序……这时候 GPT-5-mini 就不太够用了。

升级到 GPT-5.4 并开启中等推理力度，加两行配置：

spring.ai.openai.chat.model=gpt-5.4
spring.ai.openai.chat.reasoning-effort=medium

推理力度是个权衡：调高能提升复杂任务表现，但费 token、加延迟；调低则更快更便宜。medium 是比较均衡的选择。

重启应用，问同样的问题——结果不是推荐，而是报错：

Function tools with reasoning_effort are not supported for
gpt-5.4 in /v1/chat/completions. To use function tools,
use /v1/responses or set reasoning_effort to 'none'.

错误信息给了两条路：切 Responses API，或者把 reasoning_effort 设为 none。关掉推理力度确实能用，但这违背了升级推理模型的初衷——我们就是要更强的推理 + 工具调用。

一行配置切换到 Responses API

Spring AI 2.1 引入了对 OpenAI Responses API 的支持。先把版本升到 2.1.0-RC1：

ext {
    set('springAiVersion', "2.1.0-RC1")
}

注意：升级 Spring AI 只是让 Responses API 可用，并不会自动切换。默认仍然走 Chat Completions。

关键的一行配置：

spring.ai.openai.chat.api=responses

完事。聊天循环不用改，GameTools 不用改，注册工具的方式不用改。重启再问，模型成功调用工具并给出推荐——GPT-5.4 + medium 推理力度 + 工具调用，全部正常工作。

不只是换个 API 那么简单

表面看这像是对 GPT-5.4 限制的 workaround，实际不止：

OpenAI 官方推荐新应用使用 Responses API，尤其是涉及推理模型和 agentic 工作流的场景。它天生为模型、工具、应用之间更复杂的交互设计。

更深一层，Responses API 支持托管工具：让模型直接搜索网页、执行 Python 代码、搜索上传的文件等，不需要我们自己实现成 Spring AI 工具方法。这些能力是 Chat Completions 没有的，后续文章再展开。

核心收获

把 Spring AI 应用切换到 OpenAI Responses API，可能简单到只改一个配置属性。而这一步能让我们充分发挥推理模型的能力，也为更高级的 agentic 能力铺路。

升级模型踩坑不可怕，可怕的是不知道问题出在哪。这个案例的启发是：模型能力升级时，API 层的兼容性往往才是真正的瓶颈，优先查官方推荐的调用方式，往往比绕开功能更快。

完整代码在 https://github.com/habuma/spring-ai-recipes。