Skip to content

Spring AI 入门:ChatClient 与模型接入 ​

本篇要点:能独立搭起一个 Spring Boot 服务,用 ChatClient 完成同步调用与流式输出,并把多模型、模板与降级配到位。 前置:《Java 做 AI 的定位:能做什么、不做什么》讲过 Java 在推理侧的位置,本篇开始真正写代码;读完后你会具备做《结构化输出:让模型稳定返回对象》结构化输出的全部环境。

1. 为什么需要它 ​

2026 年 6 月,一个 CRM 项目要在工单页面加"AI 摘要"。团队的做法很直接:pom.xml 里同时加了 OpenAI 和 DeepSeek 两个 starter,想着"哪个便宜用哪个"。

启动直接失败,报的是一句让人一头雾水的话:

Parameter 0 of constructor in com.example.crm.web.AssistController required a
single bean of type 'org.springframework.ai.chat.model.ChatModel' but 2 were found

把其中一个改成 @Primary 之后起来了。上线第一周,网关开始报 504,日志里同一次请求重试了六次,前后四分多钟。查到最后发现是 spring.ai.retry 的默认值:最多 10 次,退避从 2 秒起、每次乘 5。

两件事都不是模型的问题。一件是容器里有两个 ChatModel 时该听谁的,一件是失败之后重试几次、退多久。这就是"接入"本身的复杂度,和选哪家模型无关。

Spring AI 把这层复杂度收进了三个地方:自动配置负责把模型装进容器,ChatClient 负责把一次调用写成一行链式代码,Advisor 负责在调用的前后插东西。这一章按这个顺序讲。

2. 核心概念 ​

2.1 自动配置:starter 的命名和开关 ​

Spring AI 的模型依赖有固定命名:spring-ai-starter-model-<provider>,比如 spring-ai-starter-model-openai、spring-ai-starter-model-deepseek、spring-ai-starter-model-ollama。版本统一交给 spring-ai-bom 管,不要在各个依赖上分别写版本号。

这里有个历史包袱要提醒:1.0 之前的老坐标是 spring-ai-openai-spring-boot-starter,现在搜到的很多博客还是那个写法。粘过来会得到一个找不到的依赖,而不是一条提示你改名的错误。

容器里只有一个模型时,自动配置直接给你一个 ChatClient.Builder。有多个时,Spring 无法决定注入哪一个,于是就有了本篇开头那段报错。解法有两个:给其中一个 ChatModel 标 @Primary,或者用 spring.ai.model.chat 显式声明走哪个 provider。我倾向前者配后者一起用——开关写死,@Primary 兜底,读代码的人不用猜。

还有一个版本约束值得单独记:Spring AI 2.0.x 要求 Spring Boot 4.0.x 或 4.1.x。把它塞进 Boot 3 的项目里不会有"版本不兼容"的友好提示,通常是运行时找不到某个类。

调试期还有一个开关很实用:把 spring.ai.model.chat 设成 none(或任意不匹配的值),对应的自动配置就不会生效。写单元测试时用它把真实模型关掉,比在每个测试上加 @MockBean 干净。

2.2 ChatClient 与 ChatModel 的分层 ​

官方文档做过一个类比:ChatModel 之于 ChatClient,相当于 JDBC 之于 JdbcClient。前者是协议层,后者是给业务代码用的门面。

ChatClient 提供的是链式 API:prompt() 起头,system() / user() 组织消息,call() 或 stream() 决定同步还是流式,最后用 content()、chatResponse() 收口。

中间那层是 Advisor,一条可插拔的链。常用的三个:MessageChatMemoryAdvisor 管对话历史,QuestionAnswerAdvisor 管 RAG 检索(《RAG 落地:向量库、切分与检索》),SimpleLoggerAdvisor 管打印请求与响应。顺序是有语义的,官方示例里记忆在前、检索在后,因为检索要用到刚补进来的历史。

先记住一条:SimpleLoggerAdvisor 会把请求和响应原文打出来,只在开发和排障时开。生产环境它会把用户输入写进日志,《可观测与护栏:成本、延迟与安全》讲脱敏时还要回来处理它。

2.3 流式输出必须有 Reactive 栈 ​

stream() 返回的是 Flux<String>,这是 Reactor 的类型。官方实现说明里写得很直白:流式只支持 Reactive 栈,同步只支持 Servlet 栈。所以一个既要同步接口又要流式接口的 Web 应用,spring-boot-starter-web 和 spring-boot-starter-webflux 两个都要在。

第一次跑流式报 NoClassDefFoundError: reactor/core/publisher/Flux,原因就是少了 webflux。加进去就好,不需要把整个应用改成响应式。

Java 21 的虚拟线程不改变这一点。虚拟线程解决的是阻塞线程太贵,Flux 解决的是 API 形状;一个 Web 应用能不能返回 SSE,取决于后者。

2.4 Prompt 模板:占位符和它的边界 ​

Spring AI 默认用 StTemplateRenderer(底层是 StringTemplate),占位符写成 {name},配合 .param("name", value) 或 PromptTemplate 的 variables 使用。

模板有两个容易踩的地方。一是 prompt 里如果要放 JSON,{} 会和占位符语法撞车——模板里写 {"summary": "..."},渲染器会把 "summary" 当变量名去找。这时换成 <> 分隔符,用 StTemplateRenderer.builder().startDelimiterToken('<').endDelimiterToken('>').build() 替换默认渲染器,JSON 的大括号就能原样保留。

二是长模板别写在 Java 字符串里。放到 src/main/resources/prompts/*.st,用 @Value("classpath:/prompts/summary.st") Resource 注入。文案改动不再需要重新编译,也能单独做版本对比。

还有一个容易忽略的点:模板里的占位符和 .param() 传的参数对不上时,别指望它给你一句明确的报错。StringTemplate 对未知属性的处理取决于配置,可能是渲染成空字符串,也可能直接抛异常。前一种更麻烦:模型收到一段缺了关键信息的 prompt,照样会一本正经地答,你排查半小时才发现少传了一个参数。所以模板和参数最好放在同一个类里,改模板时顺手看一眼调用点。

2.5 异常与降级:默认值必须改 ​

spring.ai.retry 的默认值长这样:最多 10 次,首次退避 2 秒,退避乘数 5,单次上限 3 分钟。按这个算,一次持续失败的调用会依次等 2s、10s、50s、180s、180s……十次加起来十分钟以上。

放在一个 HTTP 请求里,这不是健壮,是把上游故障变成自己的线程堆积。

我的配置是:max-attempts: 3、initial-interval: 500ms、multiplier: 2.0、max-interval: 10s。再往外一层加熔断(Resilience4j 的 CircuitBreaker),最外一层加业务兜底——返回缓存、返回固定文案,或者转人工。

还有两个语义要清楚。重试是整体重试,不是续写,所以对"再生成一次"的请求会重复计费;对写操作则要求幂等,否则就会重出《MCP Server:让模型安全调用 Java 业务能力》开头那种脏数据。

图 2-1 一次 ChatClient 调用走过的四层,以及重试发生的位置

如图 2-1 所示,重试发生在模型实现内部,业务代码看不见。你在 catch 里看到异常时,前面可能已经等了四分钟——这也是为什么必须改默认值。

3. 动手实践 ​

版本基线:本篇与《结构化输出:让模型稳定返回对象》用 Spring AI 2.0.x + Spring Boot 4.0.x,Maven 坐标走 BOM。《工具调用:把 Java 方法暴露给模型》起的示例把基线定在 1.1.8(《MCP Server:让模型安全调用 Java 业务能力》还要加 org.springaicommunity 的 MCP 注解库),差异在各自文章里标注;本篇这套 ChatClient 写法两代通用。

xml
<properties>
  <java.version>17</java.version>
  <spring-ai.version>2.0.2</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>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <!-- 流式输出需要 Reactive 栈,这个 starter 不能省 -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
  </dependency>
</dependencies>

配置。DeepSeek、通义千问等服务都提供 OpenAI 兼容的 /chat/completions,所以官方 OpenAI starter 改个 base-url 就能用;通义走的是阿里云百炼的兼容模式,端点以控制台文档为准。具体型号、上下文长度与价格以厂商官网为准(截至 2026 年 11 月),代码里只写系列名。

DeepSeek 其实也有自己的 starter:spring-ai-starter-model-deepseek,属性前缀是 spring.ai.deepseek.*。本篇用 OpenAI starter 是因为它一套配置能同时接通义、Kimi 等兼容端点,换厂商只改 base-url 和 model。如果你的项目只接一家,用专用 starter 的属性更短。

yaml
spring:
  ai:
    model:
      chat: openai          # 多 provider 时显式写死,避免注入时二选一
    openai:
      base-url: https://api.deepseek.com
      api-key: ${AI_API_KEY}
      chat:
        options:
          model: deepseek-chat
          temperature: 0.3
    retry:
      max-attempts: 3
      backoff:
        initial-interval: 500ms
        multiplier: 2.0
        max-interval: 10s

这份配置本身不打印任何东西,验证放在下面两个接口上。

第一个 Java 类:一个 ChatClient bean,加一个返回 token 用量的同步接口。usage 字段现在看着没用,《可观测与护栏:成本、延迟与安全》做成本看板时你会庆幸当时加了。

java
package com.example.crm.ai;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor;
import org.springframework.ai.chat.metadata.Usage;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

@Configuration
class AiConfig {

    @Bean
    ChatClient chatClient(ChatClient.Builder builder) {
        return builder
                .defaultSystem("你是 CRM 客服助手,回答控制在 80 字以内,不要编造订单信息。")
                .defaultAdvisors(new SimpleLoggerAdvisor())   // 仅开发环境开启
                .build();
    }
}

@RestController
@RequestMapping("/api/ai")
class AssistController {

    private final ChatClient chatClient;

    AssistController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @GetMapping("/summary")
    Map<String, Object> summary(@RequestParam String ticket) {
        ChatResponse resp = chatClient.prompt()
                .user(u -> u.text("把这段工单压成一句中文摘要,不超过 40 字:{ticket}")
                        .param("ticket", ticket))
                .call()
                .chatResponse();

        Usage usage = resp.getMetadata().getUsage();
        return Map.of(
                "summary", resp.getResult().getOutput().getText(),
                "inputTokens", usage.getPromptTokens(),
                "outputTokens", usage.getCompletionTokens());
    }
}

运行结果:

$ curl -s 'http://localhost:8080/api/ai/summary?ticket=电饭煲内胆有划痕,要求换货'
{"summary":"客户反馈电饭煲内胆划痕,要求换货。","inputTokens":186,"outputTokens":14}

想看到重试真的发生,把 base-url 改成一个不存在的域名。异常会在十几秒后抛出,日志里三次尝试的时间戳相差 500ms 和 1s——这就是 initial-interval 配 multiplier 的效果。默认值下,同样一次故障要等十分钟。

再把域名换成一个能解析、但服务不回包的地址,考的就是读超时。两种故障生产上都会出现,都验一次:连接失败通常是网络或 DNS,读超时通常是上游排队卡住,后者更常见,也更难查。

第二个 Java 类:流式接口。注意三件事:produces 要声明 text/event-stream,stream() 返回 Flux,超时与降级都接在 Flux 的算子上。

java
package com.example.crm.ai;

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

import java.time.Duration;

@RestController
class StreamController {

    private final ChatClient chatClient;

    StreamController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @GetMapping(value = "/api/ai/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    Flux<String> stream(@RequestParam String question) {
        return chatClient.prompt()
                .user(question)
                .stream()
                .content()
                .timeout(Duration.ofSeconds(30))            // 整条流的总时长上限
                .onErrorResume(e -> Flux.just("【降级】模型暂时不可用,请稍后再试。"));
    }
}

运行结果:

$ curl -N 'http://localhost:8080/api/ai/stream?question=换货流程要几天'
data:换货申请
data:提交后
data:3 个工作日
data:内完成审核

浏览器里 EventSource 会逐块收到;用 curl 时 -N 不能省,否则你看到的是攒够一个缓冲区才吐一次。

多模型切换不需要改业务代码:定义两个 ChatClient bean,用 @Qualifier 区分,运行时按 Map<String, ChatClient> 注入就是一个天然的路由表。要连第二家 OpenAI 兼容服务,用 OpenAiChatModel.builder().options(OpenAiChatOptions.builder().baseUrl(...).build()) 直接造实例——但要注意,官方文档提醒这条路绕过了自动配置,ChatClientBuilderCustomizer 和可观测埋点会失效,所以更好的做法是注入 ChatClientBuilderConfigurer 再 build()。

常用配置的对照放在一张表里,配错时先来这里对一遍。

配置项默认值生产建议说明
spring.ai.model.chat随 starter 决定显式写死多个 provider 时决定注入谁
spring.ai.openai.chat.options.model随版本变化写系列名型号、上下文长度以厂商官网为准
spring.ai.openai.chat.options.temperature1.0(多数 provider)摘要类 0.2–0.4越高越发散
spring.ai.retry.max-attempts102–3含首次调用在内的总次数
spring.ai.retry.backoff.initial-interval2s500ms第一次退避时长
spring.ai.retry.backoff.multiplier52.0退避倍增系数
spring.ai.retry.backoff.max-interval3min10s单次退避上限
spring.ai.retry.on-client-errorsfalse保持 false4xx 不重试,直接失败

4. 常见误解 ​

"call() 就是发请求。" 官方文档写得很清楚:call() 只决定用同步还是流式,真正发起调用的是 content()、chatResponse() 这些终结方法。所以 try/catch 要包住终结方法,只包住 call() 什么都抓不到。

"重试次数调大一点更稳。" 默认 10 次配上乘数 5,等于把一次上游抖动放大成十分钟的线程占用,还会重复计费。生产上先改小,再用熔断挡住整片失败。两件事都要做,只改一个不够。

"流式只是前端打字机效果。" 它同时改变了超时窗口和首字延迟:同步调用要等整段生成完才算一次成功,流式在第一个 token 到达时就已经在返回数据。代价是流式路径拿不到结构化对象,这一点《结构化输出:让模型稳定返回对象》会展开。

5. 小结 ​

  • starter 命名是 spring-ai-starter-model-<provider>,版本交给 spring-ai-bom;2.0.x 要求 Spring Boot 4.0.x / 4.1.x。
  • 多个模型共存时,用 spring.ai.model.chat 加 @Primary 同时约束,别让 Spring 去猜。
  • ChatModel 是协议层,ChatClient 是门面,Advisor 是插槽;顺序有语义,日志 advisor 只在开发环境开。
  • 流式必须有 Reactive 栈,同步必须有 Servlet 栈;一个应用同时要两种能力,就把两个 starter 都加上。
  • spring.ai.retry 的默认值必须改,改完还要加熔断与业务兜底。

6. 相关文章 ​

现在模型能稳定返回一段文字了,但业务代码要的是对象:分类、金额、布尔判断。[《结构化输出:让模型稳定返回对象》 结构化输出](/guide/java-ai/spring-ai-structured-output.html)处理这件事——把文本变成类型,并且让它在字段缺失、格式跑偏时自己纠正一次再失败。