把 Spring AI 的 OpenAI starter 接到 Router One

引入 Spring AI BOM 和 OpenAI starter

Spring AI 的正式版发布在 Maven Central，不需要额外配置仓库。导入 spring-ai-bom，再添加 spring-ai-starter-model-openai；这个 starter 会带上 OpenAI 聊天模型实现、自动配置，以及本指南要注入的 ChatClient.Builder。BOM 版本要和你的 Spring Boot 版本线匹配：Spring AI 2.0.x（写作时为 2.0.1）支持 Spring Boot 4.0.x 和 4.1.x，Spring AI 1.1.x（1.1.8）支持 Spring Boot 3.4.x 和 3.5.x。两条版本线的依赖坐标相同，只有版本号不同。

<!-- pom.xml: Spring AI 2.0.x on Spring Boot 4.x; use 1.1.8 with Spring Boot 3.4/3.5 -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-bom</artifactId>
      <version>2.0.1</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>

把 Spring AI 配置到 Router One base URL

Spring AI 2.0.x 只需在 src/main/resources/application.yml 里设置三个属性。base-url 填 https://api.router.one/v1，要带 /v1：2.0 会把这个值原样传给 openai-java SDK，由 SDK 自行在后面拼接 /chat/completions（SDK 自己的默认地址本来就以 /v1 结尾，虽然 2.0.1 文档的属性表仍写着旧的纯主机默认值）。api-key 通过 Spring 占位符读取 ROUTER_ONE_API_KEY，这个变量名是本指南定义的，刻意不用 OPENAI_API_KEY——因为属性留空时，2.0 会回退读取环境里的 OPENAI_API_KEY 和 OPENAI_BASE_URL。chat.model 填目录里的精确模型 ID，若 ID 自带 provider 前缀也要保留；2.0 去掉了原来 chat.options.* 里的 options 这一层，旧名字仍能绑定，但已标记为弃用：

# src/main/resources/application.yml: Spring AI 2.0.x (Spring Boot 4.x)
spring:
  ai:
    openai:
      base-url: https://api.router.one/v1
      api-key: ${ROUTER_ONE_API_KEY}
      chat:
        model: <model-id-from-/models>

# Shell (macOS/Linux) before starting the app:
# export ROUTER_ONE_API_KEY=sk-your-router-one-key

Spring AI 1.x：主机根地址加 completions-path

Spring AI 1.0.x 和 1.1.x 自己拼接请求地址：base-url 加上 chat.completions-path 属性，后者默认值是 /v1/chat/completions。所以在 1.x 上，base-url 填不带 /v1 的主机根地址 https://api.router.one，模型 ID 写在 chat.options.model 下。如果这里仍然带着 /v1，请求会被发到 /v1/v1/chat/completions。下面的 completions-path 一行就是默认值，写出来只是为了让拼接方式一目了然。另外，1.x 会通过属性默认把 temperature 设为 0.7，而 2.0 只在你设置时才发送 temperature：

# application.yml: Spring AI 1.0.x / 1.1.x (Spring Boot 3.4 / 3.5)
spring:
  ai:
    openai:
      base-url: https://api.router.one
      api-key: ${ROUTER_ONE_API_KEY}
      chat:
        completions-path: /v1/chat/completions
        options:
          model: <model-id-from-/models>

各版本线该填什么

两条版本线都是 Maven Central 上的正式版（写作时为 2.0.1 和 1.1.8），依赖坐标相同；1.0 之前里程碑版本使用的 spring-ai-openai-spring-boot-starter 这个名字止步于 1.0.0-M6。按你运行的 Spring Boot 版本线对照下表：

用 ChatClient 各做一次普通调用和流式调用

注入自动配置的 ChatClient.Builder，构建 ChatClient，先做一次普通 call()——模型和端点都来自上面的属性，代码里不用重复。然后调用 stream().content()，它返回 Reactor 的 Flux<String>；Spring AI 的 ChatClient 文档说明流式输出运行在响应式技术栈上。启动应用，确认两段输出都正常，再去加工具调用、对话记忆或结构化输出；这些都留在你的应用里，网关只记录每次模型请求：

package com.example.demo;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
class RouterOneSmokeTest {

  @Bean
  CommandLineRunner routerOneSmokeTest(ChatClient.Builder builder) {
    ChatClient chatClient = builder.build();
    return args -> {
      // One plain call first; the model comes from spring.ai.openai.chat.model
      String reply = chatClient.prompt()
          .user("Reply with one short greeting.")
          .call()
          .content();
      System.out.println(reply);

      // Then streaming: a Flux<String> from the same ChatClient
      chatClient.prompt()
          .user("Count from 1 to 5, one number per line.")
          .stream()
          .content()
          .doOnNext(System.out::print)
          .blockLast();
    };
  }
}

Spring AI 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Spring AI 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

Spring AI 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

在 trace 里验证 Spring AI 的调用

先在 Spring AI 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

常见问题