Spring AI ChatClient
Spring AI ChatClient 全解：统一大模型调用客户端实战文档
一、技术背景
在大模型开发早期，开发者对接不同厂商大模型会面临极高的接入成本：
接口标准不统一：OpenAI、阿里百炼、DeepSeek、Ollama、通义千问每家 API 请求体、响应字段、鉴权规则完全独立，一套业务代码只能绑定单一模型；
重复编码冗余：同步对话、流式输出、参数配置、多模态逻辑每个厂商都要重新实现，维护成本高；
切换成本巨大：业务需要更换模型厂商时，全量改写调用代码，回归测试工作量极大；
底层细节繁琐：每个模型需要单独处理超时、重试、令牌统计、异常捕获，重复造轮子。
Spring AI 官方推出ChatClient统一客户端，核心目标就是抹平各大模型厂商 API 差异，提供一套标准化、流式、可配置、链式调用的统一编程接口。无论本地 Ollama、云端 DeepSeek、阿里百炼、通义千问，全部复用同一套调用逻辑，仅修改配置即可无感切换模型。
二、发展历程
初代阶段：分模型独立 ModelSpring AI 早期版本仅提供分模型专用
ChatModel（OllamaChatModel、DeepSeekChatModel 等），注入不同 Bean 实现多模型切换，但代码写法分散，参数构建繁琐，多模型共存场景代码臃肿。迭代阶段：ChatClient 统一抽象推出Spring AI 1.0-M 系列正式发布
ChatClient顶层统一封装，基于建造者模式提供链式 API，内置提示词模板、参数覆、流式、工具调用、多模态统一能力，将所有模型能力收敛至同一套 API。成熟阶段：多实例动态切换当前版本支持运行时动态构建多
ChatClient实例，无需重启服务即可切换模型；内置全局默认客户端 + 动态临时客户端双模式，适配复杂多模型共存业务，成为 Spring AI 官方推荐标准调用方式。
三、ChatClient 核心优缺点
3.1 优点
跨模型统一 API一套同步 / 流式 / 多模态代码兼容所有厂商，切换模型仅修改配置，业务逻辑无需改动。
极简链式建造者编程无需手动组装 Prompt、Options，链式调用可读性强，参数灵活覆写，支持全局默认配置 + 单次临时参数覆盖。
内置全套通用能力原生支持提示词模板、记忆上下文、函数工具调用、令牌统计、超时重试、异常拦截，不用自行封装工具类。
多实例灵活管理支持全局默认
ChatClient，也可运行时动态创建独立客户端，实现同一项目同时调用 Ollama、DeepSeek 多个模型。低学习成本屏蔽各厂商底层 JSON 请求细节，开发者只关注业务提问内容，不用处理底层 HTTP 通信、字段映射。
天然适配单元测试无强制 Web 容器依赖，搭配
SpringBootTest可直接离线调试各类模型能力。
3.2 缺点
底层厂商特有高级能力访问繁琐厂商独有的扩展字段（如 DeepSeek 深度思考 reasoning_content、阿里百炼专属绘图参数）需要通过
extraHeaders/extraBody透传，不如原生 Model 直接扩展简洁。版本迭代较快Spring AI 尚处于里程碑版本，少量 API 存在微调，大型生产项目需锁定稳定版本。
简单单一模型场景存在轻微封装损耗仅固定使用某一个云端模型时，直接使用厂商原生 SDK 会少一层抽象，极致性能场景原生 SDK 略占优势。
四、适用业务场景
4.1 优先选用 ChatClient 场景
多模型动态切换业务平台支持用户自选大模型（本地 Ollama / 云端 DeepSeek / 通义），一套业务代码适配全部厂商；
企业标准化 AI 中台统一封装 AI 能力对外提供服务，底层可按需切换成本 / 性能最优模型；
研发频繁调优提示词需要快速替换不同模型对比回答效果，单元测试批量验证 Prompt；
兼顾私有化 + 云端双部署内网 Ollama 处理敏感数据，云端模型处理高并发公网业务，共用一套调用代码；
通用问答、知识库 RAG、简单 Agent 场景基础文本、流式对话需求，不需要厂商独有高阶能力。
4.2 不推荐使用场景
重度依赖厂商专属独有能力高频使用厂商独有的深度思考、专属多模态、私有工具链扩展，透传参数代码繁琐；
极致低延迟、超高 QPS 线上核心链路追求极致性能，需要去掉中间抽象层，直接使用厂商原生 SDK 直连 API；
固定单一模型且长期无替换计划项目永久只使用某一款商用模型，无需兼容其他厂商。
五、环境准备与通用配置
5.1 Maven 依赖
<!-- Spring AI 核心统一依赖 --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter</artifactId> <version>1.1.2</version> </dependency> <!-- Ollama 本地模型适配（示例1） --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-ollama</artifactId> <version>1.1.2</version> </dependency> <!-- DeepSeek 云端模型适配（示例2） --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-deepseek</artifactId> <version>1.1.2</version> <!-- 流式Flux响应式依赖 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> <scope>test</scope> </dependency> <!-- 单元测试依赖 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency>5.2 application.yml 全局基础配置（双模型示例：Ollama+DeepSeek）
# 全局默认选用Ollama本地模型 spring: ai: ollama: base-url: http://localhost:11434 chat: options: model: qwen3:7b temperature: 0.3 num-ctx: 4096 deepseek: api-key: ${DEEPSEEK_API_KEY} base-url: https://api.deepseek.com/v1 chat: options: model: deepseek-chat temperature: 0.4六、入门实战（全部基于 SpringBootTest）
6.1 测试公共说明
@SpringBootTest加载 Spring 上下文，自动注入全局默认ChatClient；同步对话：一次性获取完整回答，适合离线批量处理；
流式对话：Flux 分段输出，模拟打字机效果；
多模型动态切换：运行时手动构建 DeepSeek 专用 ChatClient，实现同一测试类同时调用本地 / 云端模型。
实战 1：基础同步 ChatClient 单元测试
完整导入、零报错可运行
import org.junit.jupiter.api.Test; import org.springframework.ai.chat.client.ChatClient; import org.springframework.boot.test.context.SpringBootTest; import javax.annotation.Resource; /** * ChatClient 同步对话测试 * 全局默认Ollama客户端，一次性返回完整回答 */ @SpringBootTest public class ChatClientSyncTest { // 注入全局默认ChatClient（yml配置的Ollama） @Resource private ChatClient chatClient; @Test void testSyncChat() { // 链式调用：设置提问、全局参数、同步调用获取完整字符串 String response = chatClient.prompt() .user("请简要介绍Spring AI ChatClient作用") .call() .content(); System.out.println("====同步完整回答===="); System.out.println(response); } @Test void testSyncWithCustomParam() { // 单次请求临时覆写模型参数，不影响全局配置 String response = chatClient.prompt() .options(opt -> opt.temperature(0.1).maxTokens(1024)) .user("写一段严谨的接口设计规范") .call() .content(); System.out.println("====自定义参数回答===="); System.out.println(response); } }实战 2：流式输出 ChatClient 单元测试
import org.junit.jupiter.api.Test; import org.springframework.ai.chat.client.ChatClient; import org.springframework.boot.test.context.SpringBootTest; import reactor.core.publisher.Flux; import javax.annotation.Resource; import java.util.StringJoiner; /** * ChatClient 流式分段输出测试 * 逐块返回内容，适合交互式对话场景 */ @SpringBootTest public class ChatClientStreamTest { @Resource private ChatClient chatClient; @Test void testStreamChat() { StringJoiner fullText = new StringJoiner(""); // 获取流式Flux数据流 Flux<String> flux = chatClient.prompt() .user("详细讲解大模型同步与流式调用的区别") .stream() .content(); // 逐块打印，拼接完整文本 flux.doOnNext(chunk -> { System.out.print(chunk); fullText.add(chunk); }).blockLast(); // 阻塞等待流结束 System.out.println("\n====流式拼接完整内容===="); System.out.println(fullText); } }实战 3：运行时动态切换多模型（Ollama ↔ DeepSeek）
核心能力：不修改 yml、不重启上下文，代码手动构建另一厂商 ChatClient，实现多模型共存调用
import org.junit.jupiter.api.Test; import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.model.deepseek.DeepSeekChatModel; import org.springframework.boot.test.context.SpringBootTest; import javax.annotation.Resource; /** * 多模型动态切换测试 * 默认客户端：Ollama本地 * 手动构建：DeepSeek云端客户端，同一方法切换模型 */ @SpringBootTest public class ChatClientMultiModelTest { // 全局默认Ollama ChatClient @Resource private ChatClient localChatClient; // 自动注入DeepSeek底层ChatModel，用于构建独立客户端 @Resource private DeepSeekChatModel deepSeekChatModel; @Test void testMultiModelSwitch() { String question = "什么是CQRS架构设计思想"; // 1、使用本地Ollama模型回答 String localAnswer = localChatClient.prompt() .user(question) .call() .content(); System.out.println("【本地Ollama回答】\n" + localAnswer); System.out.println("---------------------------------------"); // 2、动态构建DeepSeek云端ChatClient，切换模型 ChatModel cloudChatClient = ChatClient.builder(deepSeekChatModel).build(); String cloudAnswer = cloudChatClient.prompt() .user(question) .options(opt -> opt.temperature(0.3)) .call() .content(); System.out.println("【云端DeepSeek回答】\n" + cloudAnswer); } }七、核心设计思想总结
统一抽象为核心：ChatClient 屏蔽各厂商 API 差异，一套业务代码适配所有大模型，大幅降低多模型项目维护成本；
链式建造者简化编码，参数、提示词、流式、工具调用语义清晰，可读性远优于传统 Prompt 组装；
双层客户端模式：全局默认客户端满足绝大多数场景，运行时动态构建客户端实现多模型灵活切换；
测试友好：完全脱离 Web 容器，依托 SpringBootTest 快速批量验证不同模型、不同提示词效果；
取舍思维：通用 AI 业务首选 ChatClient，重度依赖厂商私有高阶能力时，再选用对应原生 ChatModel 直连。
八、落地使用建议
新项目统一使用
ChatClient作为标准调用层，禁止直接注入各厂商原生 ChatModel；全局通用参数写进 yml，单次业务特殊参数通过链式
options临时覆写；需要同时使用本地私有化 + 云端模型时，采用「全局默认 + 动态构建」双客户端方案；
批量提示词验证、模型效果对比全部使用 SpringBootTest 单元测试，无需启动服务；
若业务高频使用厂商独有扩展字段，可封装统一工具方法透传 extraBody/extraHeaders，减少重复代码。