第一个 ChatClient------从注入到一次完整调用
一、ChatClient 是什么
1.1 简介
ChatClient 是 Spring AI 提供的一个链式(Fluent)API 入口 ,同时支持同步 call() 和流式 stream()。你用一串方法把"谁在问、问什么、怎么问、要什么格式回来"组装好,最后把请求发出去。
ChatClient 是你跟大模型打交道的"前台",不是模型本身。
把 ChatClient 的调用拆开看:
text
ChatClient → Prompt → Message → ChatModel → ChatResponse
ChatClient 负责组织请求,不负责"怎么调模型"。真正跟 OpenAI、Ollama 等供应商通信的是 ChatModel。ChatClient 站在 ChatModel 外面,让你用同一套写法面对不同的模型实现。
1.2 ChatClient 帮你做什么事
简单记住下面三件事就行:
- 收口系统提示词。 你可以在构建 ChatClient 时就固定"你是一个 xx 助手",后面每次调用不用重复写。
- 让同步和流式只差一个方法名。
call()是等完整结果返回,stream()是一边生成一边推。切换场景时业务逻辑不用推倒重来。 - 业务代码不跟模型供应商绑死。 今天用 OpenAI,明天换别的,只要换依赖和配置,Controller 里那一行调用可以原封不动。
1.3 与 Prompt 的关系
ChatClient 不是 Prompt,它产出 Prompt。你通过 .system(...)、.user(...) 这些方法把消息塞进去,ChatClient 把它们组装成一个 Prompt 发给模型。Prompt 才是"这一次请求的完整包裹"。
二、项目搭建:构建最小可运行骨架
2.1 框架版本说明
| 组件 | 版本 | 说明 |
|---|---|---|
| Java | 21 | Spring AI 2.0 的硬性底线,不是"推荐",是"必须" |
| Spring Boot | 4.0.x | 2.0.x 支持 Boot 4.0 和 4.1,本文取 4.0.6 这类稳定 4.0 版本即可 |
| Spring AI | 2.0.2 | 当前官方推荐稳定版本 |
| 模型 Starter | spring-ai-starter-model-openai |
用 OpenAI 兼容接口做演示,换其他供应商时只换 Starter |
| 构建工具 | Maven |
版本说明:Spring AI 2.0.x 官方支持的 Boot 范围是 4.0.x 和 4.1.x ,不支持 Boot 3.x。Java 21 是底层前提,不是可选项。
本文写作时使用 Spring Boot 4.0.6 + Spring AI 2.0.2;Spring AI 版本迭代较快,实际创建项目时请以官方文档和
mvn dependency:tree结果为准。
2.2 项目搭建与配置
本质还是一个 Maven Spring Boot 项目,所以使用 Initializr 生成或者手写 pom 都可以。
Initializr 可以在 start.spring.io 上勾选 Spring AI 相关 starter,但本文建议手写 pom 的关键部分,因为这样你能看清"到底哪几个依赖是必须的"。
pom.xml 关键片段
父 POM 锁定 Spring Boot 4.0.x:
xml
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.0.6</version>
</parent>
属性里写死 Java 21 和 Spring AI 2.0.2:
xml
<properties>
<java.version>21</java.version>
<spring-ai.version>2.0.2</spring-ai.version>
</properties>
dependencyManagement 引入 Spring AI BOM,统一版本:
xml
<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>
真正需要的依赖:
xml
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
完整 pom.xml 内容如下:
xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.0.6</version>
</parent>
<groupId>com.liaoyuan</groupId>
<artifactId>ChatClientDemo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>ChatClientDemo</name>
<properties>
<java.version>21</java.version>
<spring-ai.version>2.0.2</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-starter-model-openai</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</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>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
application.yaml
yaml
spring:
ai:
openai:
api-key: ${DEEPSEEK_API_KEY}
base-url: https://api.deepseek.com
chat:
temperature: 0.7
model: deepseek-chat
注:本次测试使用 DeepSeek 来进行,api-key 请前往具体大模型服务厂商获取,本地开发时在 IDE 的 Run Configuration 或 .env 里设置,或者设置为本地环境变量。不要把 key 直接写进 yml 提交到仓库。

DeepSeek 的 API 本身就是 OpenAI 兼容的,当然,Spring AI 2.0.2 也提供了
spring-ai-starter-model-deepseek依赖,会注册DeepSeekChatModelBean。配置前缀从spring.ai.openai.*变成spring.ai.deepseek.*,理论上对 DeepSeek 特有参数(比如推理模式)的支持更完整。
关于 application.yaml 相关配置项的解释:
| 配置项 | 本文的值 | 解释 | 备注 |
|---|---|---|---|
spring.ai.openai.api-key |
${DEEPSEEK_API_KEY} |
调用 API 时的身份凭证。Spring AI 会把它放进 HTTP 请求的 Authorization: Bearer 头里。 |
不配置则启动或调用时报 401 |
spring.ai.openai.base-url |
https://api.deepseek.com |
API 的根地址。Spring AI 的 OpenAI 客户端会在这个地址后面拼接具体的接口路径 | 默认值为 api.openai.com,因为选择 DeepSeek,所以需要单独配置服务厂商的地址。如果遇到 404,可以尝试 https://api.deepseek.com/v1 |
spring.ai.openai.chat.model |
deepseek-chat |
选择用哪个模型回答 | 用 Starter 的默认模型名,可能不适用于 DeepSeek 端点 |
spring.ai.openai.chat.temperature |
0.7 |
控制输出的"随机程度",0 最确定,越高越活 | 通常 0 到 2 之间。对于技术类助手场景,0.7 是一个温和的起点------不会死板到每次回答一模一样,也不至于发散到跑题。 |
关于
spring.ai.openai.chat.model和spring.ai.openai.chat.temperature两项配置,旧版本 Spring AI 中还多了一个层级:options,即spring.ai.openai.chat.options.model、spring.ai.openai.chat.options.temperature。Spring AI 2.0 把.options.这一层拿掉了,模型参数直接写在chat下面。
上述配置也可以在编码阶段通过 ChatOptions 覆盖,入门阶段先用 YAML 配置即可。
2.3 启动类之前,先确认依赖版本是否存在冲突
依赖拉下来之后,先别急着写 Controller。用 mvn compile 或 mvn dependency:tree 确认没有版本冲突,再往下走。Boot 4 + Spring AI 2.0 的依赖树比较干净,但提前确认一次比运行时报 NoSuchMethodError 再回头排查要省时间。
三、编码
3.1 消息类型
在正式编码之前,我们需要先了解一下大模型的四种核心消息类型:
Spring AI 通过 MessageType 枚举定义了这四种消息,它们各自承担不同的职责。
System Message------设定"人设"和规则
它不参与具体问答,而是给整段对话定调子。比如"你是一个回答不超过三句话的技术助手",这类指令就放在 System Message 里。
User Message------代表"你"说的话
终端用户的实际输入。在 ChatClient 里,.user(message) 就是把内容包装成 User Message 发出去。多模态场景下,UserMessage 还可以携带图片、音频等媒体内容,这是它相对其他类型的一个特殊能力。
Assistant Message------模型输出回复
它代表模型在对话历史中说过的内容。在一问一答的简单调用里你感知不到它,但多轮对话中,正是把历史的 Assistant Message 带上,模型才能"记得"自己之前说过什么。另外,当模型决定调用工具时,AssistantMessage 里会携带 toolCalls 信息,告诉后续流程"我要调什么"。
Tool Message------工具执行后的结果回传
当模型发起工具调用(比如查天气),本地代码执行完,需要把结果包成 Tool Message 塞回对话,模型才能基于这个结果继续生成最终回答。它的职责很单纯:把外部世界的返回值告诉模型。
3.2 最小接口跑通 ChatClient
Spring AI 自动配置给你的是一个 ChatClient.Builder ,不是一个现成的 ChatClient。即注入的是 Builder,不是 ChatClient。
最简例子:
java
@RestController
public class ChatController {
private final ChatClient chatClient;
public ChatController(ChatClient.Builder builder) {
this.chatClient = builder.build();
}
}
这里发生了两件事:
- Builder 是 prototype 作用域的,每个注入点拿到一个新的 Builder,你可以在构建时给它设置只属于这个 ChatClient 的默认值。
.build()之后你拿到的是一个"已经带好默认配置"的 ChatClient,后面每次调用不用重复设默认项。
下面,在上述 ChatController 类中创建一个完整的 GET 接口:
java
@GetMapping("/chat")
public String chat(@RequestParam(name = "message", defaultValue = "你是谁") String message) {
return chatClient.prompt()
.system("你是一个助手")
.user(message)
.call()
.content();
}
启动项目,调用接口可以获得 DeepSeek 关于"你是谁"的回答。
一行一行拆:
-
prompt():开始组装一次请求。 -
.system("你是一个助手"):给整段对话定调的系统提示词。如果每个请求都需要同一句系统提示词,不要在每次调用里重复写
.system(...),而应该放在构建阶段:javapublic ChatController(ChatClient.Builder builder) { this.chatClient = builder .defaultSystem("你是一个简洁的技术助手,回答控制在三句话以内。") .build(); } -
.user(message):把用户输入放进 User Message。 -
.call():同步调用,当前线程等到模型返回完整结果。如果想流式,这里换成.stream(),后面接Flux<String>。 -
.content():从响应里只取纯文本。如果后面需要 token 用量或结束原因,可以换成.chatResponse();如果要直接映射成 Java 对象,后面讲.entity()。
3.3 把"注入 + 构建"收进配置类(推荐但不必强制)
Controller 里直接构建 Builder 适合"先跑通"。更常见的做法是把 ChatClient 的构建收进一个 @Configuration,让 Controller 只依赖一个已经成型的 ChatClient:
java
@Configuration
public class ChatClientConfig {
@Bean
public ChatClient chatClient(ChatClient.Builder builder) {
return builder
.defaultSystem("你是一个简洁的技术助手。")
.build();
}
}
Controller 变成:
java
@RestController
public class ChatController {
private final ChatClient chatClient;
public ChatController(ChatClient chatClient) {
this.chatClient = chatClient;
}
@GetMapping("/chat")
public String chat(@RequestParam String message) {
return chatClient.prompt()
.user(message)
.call()
.content();
}
}
注意:如果已经在构建 ChatClient 时设置了 defaultSystem,调用时就不要重复写 .system(...),除非你明确要覆盖或追加系统提示词。入门阶段建议只保留一种写法,避免混淆。
四、同步调用与流式调用
在上述接口中使用的是 call() 同步调用,也就是等待模型生成完整之后才回复;而 stream() 流式调用,则是立即返回,逐个 token 返回到请求端,像打字机效果。
4.1 整体对比
.call() 同步 |
.stream() 流式 |
|
|---|---|---|
| 请求发出后 | 当前线程阻塞,等模型生成完才返回 | 立即返回,生成一段推一段 |
| 返回类型 | .content() 返回 String;.chatResponse() 返回 ChatResponse;.entity(Class<T>) 返回 T |
.content() 返回 Flux<String>;.chatResponse() 返回 Flux<ChatResponse>;没有直接等价的 entity() |
| 适合场景 | 短文本、后台任务、结果需要再处理 | 对话页面、长文本生成、需要"打字机效果" |
| 前端配合 | 普通 JSON 响应 | SSE(Server-Sent Events) |
结构化输出 entity() |
支持 | 不支持直接调用,需要手动聚合后再转换 |
注意:call() 和 stream() 本身返回的是"结果规格对象",通常还要继续链式调用 .content()、.chatResponse() 或 .entity() 才能拿到最终结果。
4.2 各自解释
同步调用:call()
同步调用适合"我等模型全部生成完,再一次性返回给前端"的场景。代码最短,也最容易调试:
java
@GetMapping("/chat")
public String chat(@RequestParam(name = "message", defaultValue = "你是谁") String message) {
return chatClient.prompt()
.user(message)
.call()
.content();
}
这里的 .content() 只取模型回复的纯文本。如果还需要 token 用量、结束原因等元数据,不要用 .content(),而要用 .chatResponse()。
同步调用的特点是:
- 当前请求线程会等待模型返回;
- 返回类型简单,通常是
String; - 适合短文本、后台任务、结果还要继续处理的场景;
- 不适合需要"打字机效果"的前端页面。
流式调用:stream()
流式调用会把模型生成的内容一段一段推给前端,常见形式是 SSE:
java
@GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> stream(@RequestParam(name = "message", defaultValue = "你是谁") String message) {
return chatClient.prompt()
.user(message)
.stream()
.content();
}
这里 .stream().content() 返回的是 Flux<String>。前端可以用 EventSource 接收:
javascript
const es = new EventSource('/chat/stream?message=你好');
es.onmessage = (event) => {
// 把 event.data 追加到页面上,形成打字机效果
console.log(event.data);
};
es.onerror = () => {
es.close();
};
流式调用适合:
- 聊天页面;
- 长文本生成;
- 需要边生成边展示的场景;
- 前端使用 SSE 或 WebFlux 响应式流的场景。
4.3 返回值类型解释
ChatClient 的调用链一般长这样:
text
chatClient.prompt()
.user(...)
.call() / .stream()
.content() / .chatResponse() / .entity(...)
.call():发起同步调用,返回同步结果规格对象,后面要继续取结果。.stream():发起流式调用,返回流式结果规格对象,后面要继续取结果。.content():只取文本内容。同步时是String,流式时是Flux<String>。.chatResponse():取完整响应对象。同步时是ChatResponse,流式时是Flux<ChatResponse>。.entity(Class<T>):把模型返回的文本尝试映射成 Java 对象,适合结构化输出;流式调用下不能直接这样用。
示例:同步取完整响应:
java
ChatResponse response = chatClient.prompt()
.user("用一句话解释什么是 Spring AI")
.call()
.chatResponse();
示例:同步映射成 Java 对象:
java
public record Answer(String answer) {
}
Answer answer = chatClient.prompt()
.system("只返回 JSON,格式为 {\"answer\":\"...\"}")
.user("用一句话解释什么是 Spring AI")
.call()
.entity(Answer.class);
结构化输出时,建议在系统提示词中明确要求 JSON 格式,并且生产环境要加异常处理和格式校验。
4.4 可以获取的结果类型解释
| 结果方法 | 同步 call() |
流式 stream() |
用途 |
|---|---|---|---|
.content() |
String |
Flux<String> |
只要纯文本,最常用 |
.chatResponse() |
ChatResponse |
Flux<ChatResponse> |
需要 token 用量、结束原因、完整结果等元数据 |
.entity(Class<T>) |
T |
不支持直接调用 | 结构化输出,把文本映射成 Java 对象 |
如果流式场景下确实要结构化结果,可以先聚合再转换:
java
public Mono<Answer> streamThenMap(@RequestParam String message) {
return chatClient.prompt()
.user(message)
.stream()
.content()
.collectList()
.map(parts -> String.join("", parts))
.map(text -> {
// 这里可以接入 Jackson 做 JSON 反序列化
// 示例略:return objectMapper.readValue(text, Answer.class);
return new Answer(text);
});
}
实际项目中更推荐:流式只负责展示,结构化解析放到聚合完成之后做。
五、常见问题与排错
5.1 401:API Key 没配置或无效
检查:
- 环境变量
DEEPSEEK_API_KEY是否在启动应用的环境中可见; - IDE 的 Run Configuration 是否设置了这个环境变量;
- 不要把 key 直接写进 yml 并提交到仓库。
5.2 404:base-url 路径问题
使用 OpenAI Starter 接 DeepSeek 时,常见写法是:
yaml
base-url: https://api.deepseek.com
如果遇到 404,可以尝试:
yaml
base-url: https://api.deepseek.com/v1
不同客户端拼接路径的方式可能不同,以实际厂商文档为准。
5.3 NoSuchMethodError:依赖版本冲突
先执行:
bash
mvn dependency:tree
确认 Spring Boot、Spring AI、模型 Starter 的版本是否匹配。本文使用 Spring Boot 4.0.6 + Spring AI 2.0.2,Spring AI 2.0.x 不支持 Boot 3.x。
5.4 流式调用不能直接用 entity()
.stream() 返回的是流式结果,不能直接 .entity(Class<T>)。如果需要结构化结果,先聚合流式文本,再手动反序列化。