Spring AI ChatClient 详解

一、ChatClient 是什么

ChatClient是Spring AI 核心入口API，是对大模型对话能力的统一抽象，屏蔽了 OpenAI、智谱、通义千问、Ollama、DeepSeek 等各大模型厂商的接口差异。

一句话：用同一套代码，随便切换任意大模型，不用改业务代码。

它替代了原生底层的 ChatModel，提供流式链式调用、Prompt 组装、结构化输出、拦截器、默认配置等更优雅的 Builder 编程风格，是 Spring AI 推荐首选使用方式。

二、ChatClient 核心定位

上层应用直接使用，不用对接各模型原生 API
封装：提示词、模型参数、多轮对话、工具调用、返回值解析
完全适配 Spring Boot 自动配置，自动注入、开箱即用
支持同步返回 + 流式 SSE 返回

三、两种创建 ChatClient 方式

1. 自动注入

Spring AI 自动根据配置文件，创建好 ChatClient Bean，直接注入即可

@RestControllerpublic classAiController{    @Autowired    private ChatClient chatClient;}

2. 手动构建

// 先注入底层 ChatModel@Autowiredprivate ChatModel chatModel;// 手动构建 ChatClientChatClient customChatClient = ChatClient.builder(chatModel)        .defaultSystem("你是一名Java架构师，回答简洁专业")        .build();

四、ChatClient 完整链式调用结构

标准语法结构：

chatClient.prompt()          // 开始构建请求          .system("系统角色")  // 系统提示词          .user("用户问题")    // 用户提问          .options(模型参数)   // 温度、最大token等          .call()              // 同步调用          .content();          // 获取文本结果

核心链路节点说明

方法	作用
.prompt()	开启一次对话请求构建器
.system()	设置系统角色、人设、规则
.user()	设置用户输入
.assistant()	拼接历史助手回复，做多轮对话
.options(ChatOptions)	配置模型参数：temperature、maxTokens、topP 等
.call()	同步阻塞调用
.stream()	流式响应（逐字返回，适合前端SSE）
.content()	获取纯文本字符串
.entity(Class<T>)	自动把返回JSON转Java实体类
.chatResponse()	获取完整响应对象（含Token消耗、元数据）

五、常用实战用法

1. 最简单问答

String res = chatClient.prompt()        .user("介绍一下Spring AI")        .call()        .content();

2. 带系统人设

String res = chatClient.prompt()        .system("你是资深Java工程师，只用3句话回答")        .user("讲下Spring Boot核心特性")        .call()        .content();

3. 自定义模型参数

var options = ChatOptions.builder()        .temperature(0.7f)   // 随机性 0~1        .maxTokens(1024)     // 最大输出token        .build();String res = chatClient.prompt()        .user("写一个Redis分布式锁代码")        .options(options)        .call()        .content();

4. 流式输出（SSE 实时打字效果）

Flux<String> flux = chatClient.prompt()        .user("写一篇500字程序员文案")        .stream()        .content();

返回 Flux 可直接给前端 SSE 推送，实现聊天机器人实时输出。

5. 结构化输出自动转POJO

定义实体：

public class Article {    private String title;    private String content;    // getter/setter}

ChatClient 直接映射：

Article article = chatClient.prompt()        .user("生成一篇Java技术文章，返回JSON格式")        .call()        .entity(Article.class);

不用手动解析JSON，框架自动处理

6. 多轮上下文对话

String res = chatClient.prompt()        .system("你是聊天助手")        .user("我叫张三")        .assistant("好的张三，我记住了")        .user("我叫什么名字？")        .call()        .content();

手动拼接历史会话，实现记忆对话。

六、全局默认配置（统一人设、全局参数）

可以在构建时设置全局默认 system 提示词、默认参数，所有调用都生效：

@Beanpublic ChatClient chatClient(ChatModel chatModel) {    return ChatClient.builder(chatModel)            // 全局默认人设            .defaultSystem("你是企业智能客服，语气礼貌简洁")            // 全局默认模型参数            .defaultChatOptions(ChatOptions.builder()                    .temperature(0.5f)                    .maxTokens(800)                    .build())            .build();}

七、ChatClient 和 ChatModel 区别

组件	层级	特点	使用场景
ChatModel	底层	原生接口、偏底层、调用繁琐	底层自定义开发
ChatClient	上层封装	链式调用、优雅、自带模板/结构化/拦截器	业务开发99%用这个

八、ChatClient 核心优势总结

统一接口：一套代码跑通所有大模型
链式Builder：代码可读性极高
内置结构化输出：自动转POJO，免手动JSON解析
支持同步+流式：适配聊天、文案生成等场景
全局默认配置：统一人设、统一模型参数
无缝整合Spring：自动配置、依赖注入、AOP、拦截器扩展