Spring AI ChatClient 全解统一大模型调用客户端实战文档一、技术背景在大模型开发早期开发者对接不同厂商大模型会面临极高的接入成本接口标准不统一OpenAI、阿里百炼、DeepSeek、Ollama、通义千问每家 API 请求体、响应字段、鉴权规则完全独立一套业务代码只能绑定单一模型重复编码冗余同步对话、流式输出、参数配置、多模态逻辑每个厂商都要重新实现维护成本高切换成本巨大业务需要更换模型厂商时全量改写调用代码回归测试工作量极大底层细节繁琐每个模型需要单独处理超时、重试、令牌统计、异常捕获重复造轮子。Spring AI 官方推出ChatClient统一客户端核心目标就是抹平各大模型厂商 API 差异提供一套标准化、流式、可配置、链式调用的统一编程接口。无论本地 Ollama、云端 DeepSeek、阿里百炼、通义千问全部复用同一套调用逻辑仅修改配置即可无感切换模型。二、发展历程初代阶段分模型独立 ModelSpring AI 早期版本仅提供分模型专用ChatModelOllamaChatModel、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 groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter/artifactId version1.1.2/version /dependency !-- Ollama 本地模型适配示例1 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-ollama/artifactId version1.1.2/version /dependency !-- DeepSeek 云端模型适配示例2 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-deepseek/artifactId version1.1.2/version !-- 流式Flux响应式依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId scopetest/scope /dependency !-- 单元测试依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency5.2 application.yml 全局基础配置双模型示例OllamaDeepSeek# 全局默认选用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六、入门实战全部基于 SpringBootTest6.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 { // 注入全局默认ChatClientyml配置的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数据流 FluxString 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减少重复代码。
Spring AI ChatClient 全解统一大模型调用客户端实战文档一、技术背景在大模型开发早期开发者对接不同厂商大模型会面临极高的接入成本接口标准不统一OpenAI、阿里百炼、DeepSeek、Ollama、通义千问每家 API 请求体、响应字段、鉴权规则完全独立一套业务代码只能绑定单一模型重复编码冗余同步对话、流式输出、参数配置、多模态逻辑每个厂商都要重新实现维护成本高切换成本巨大业务需要更换模型厂商时全量改写调用代码回归测试工作量极大底层细节繁琐每个模型需要单独处理超时、重试、令牌统计、异常捕获重复造轮子。Spring AI 官方推出ChatClient统一客户端核心目标就是抹平各大模型厂商 API 差异提供一套标准化、流式、可配置、链式调用的统一编程接口。无论本地 Ollama、云端 DeepSeek、阿里百炼、通义千问全部复用同一套调用逻辑仅修改配置即可无感切换模型。二、发展历程初代阶段分模型独立 ModelSpring AI 早期版本仅提供分模型专用ChatModelOllamaChatModel、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 groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter/artifactId version1.1.2/version /dependency !-- Ollama 本地模型适配示例1 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-ollama/artifactId version1.1.2/version /dependency !-- DeepSeek 云端模型适配示例2 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-deepseek/artifactId version1.1.2/version !-- 流式Flux响应式依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId scopetest/scope /dependency !-- 单元测试依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency5.2 application.yml 全局基础配置双模型示例OllamaDeepSeek# 全局默认选用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六、入门实战全部基于 SpringBootTest6.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 { // 注入全局默认ChatClientyml配置的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数据流 FluxString 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减少重复代码。
