Spring AI 2.0 系列(二):第一个 ChatClient——从注入到一次完整调用

第一个 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 帮你做什么事

简单记住下面三件事就行:

  1. 收口系统提示词。 你可以在构建 ChatClient 时就固定"你是一个 xx 助手",后面每次调用不用重复写。
  2. 让同步和流式只差一个方法名。 call() 是等完整结果返回,stream() 是一边生成一边推。切换场景时业务逻辑不用推倒重来。
  3. 业务代码不跟模型供应商绑死。 今天用 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 依赖,会注册 DeepSeekChatModel Bean。配置前缀从 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(...),而应该放在构建阶段:

    java 复制代码
    public 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>)。如果需要结构化结果,先聚合流式文本,再手动反序列化。

相关推荐
郝学胜-神的一滴41 分钟前
Effective Python 条款35:用类封装替代生成器异常注入
开发语言·人工智能·python·金融·pandas·scikit-learn·matplotlib
火山引擎开发者社区1 小时前
豆包工作,3 个月,800 万,20 亿
人工智能
Chuck.li1 小时前
AI 长篇创作工具选型:工作流对照与自测清单
人工智能·大模型·ai写作·网文作者·ai网文·豆包写作
aleimu1 小时前
Windows 11 右键打开 Cmder 2.0:从找不到菜单到默认使用 Cmder
前端·人工智能·后端
SwanArc技术笔记1 小时前
读技术文档,先用哪个 AI?模型指南筛选与 GPT-6.2 Astra 实操
人工智能
深海鱼在掘金1 小时前
深入浅出RAG——第21章:回顾与展望
人工智能
羲云网络1 小时前
GPT Image 2.6 GIF 交付排障:上线后为什么只剩第一帧?
图像处理·人工智能·前端开发·gif
安爹前沿AI2 小时前
Seedance 有个文档里没写的参数:开了码率涨 3.9 倍,费用一分没多
人工智能
深海鱼在掘金2 小时前
深入浅出RAG——第20章:端到端实战:企业级知识库问答系统
人工智能