Spring AI ChatModel 与 ChatClient 完整核心解析

一、Spring AI 整体分层概览Spring AI 是 Spring 官方推出的大模型集成框架统一屏蔽 OpenAI、通义千问、文心一言、Claude、Ollama 等各类大模型厂商底层 API 差异提供一套标准化 AI 开发编程模型。 整个对话能力核心分为两层底层抽象ChatModel大模型统一能力接口定义所有对话模型通用行为上层门面ChatClient基于 ChatModel 封装的流式构建器简化调用、提示词管理、参数配置、工具调用业务开发首选。二者关系ChatClient 持有 ChatModel 实例是 ChatModel 的高阶封装不替代 ChatModel。二、ChatModel 底层核心抽象2.1 核心接口定义org.springframework.ai.chat.model.ChatModelpublic interface ChatModel { // 单次同步对话返回完整响应 ChatResponse call(ChatPrompt prompt); // 流式对话分段返回结果打字机效果 FluxChatResponse stream(ChatPrompt prompt); }所有厂商模型都实现该接口OpenAiChatModelOllamaChatModelTongYiChatModel阿里通义BaiduErnieChatModel文心一言AnthropicChatModelClaude2.2 配套核心数据模型ChatPrompt对话提示词载体承载多条消息ChatPrompt prompt new ChatPrompt( new SystemMessage(你是专业Java工程师), new UserMessage(解释Spring AI ChatModel) );Message 消息体系SystemMessage系统角色设定定义 AI 身份、规则UserMessage用户输入提问AssistantMessageAI 返回回答ToolMessage工具调用返回结果Function CallingChatResponse大模型统一返回体ListGeneration generationsAI 生成内容ChatMetadata metadatatoken 消耗、模型名称、请求 ID 等元数据ChatOptions模型参数统一配置温度、topP、最大 token、流式开关、工具列表等 各厂商提供对应实现OpenAiChatOptions、OllamaOptions2.3 ChatModel 原生使用示例底层原生写法适合底层自定义扩展、精细控制场景Bean public ChatModel ollamaChatModel(OllamaProperties properties) { return new OllamaChatModel(OllamaApi.builder() .baseUrl(properties.getBaseUrl()) .build(), OllamaOptions.builder() .model(qwen:7b) .temperature(0.7) .build() ); } // 业务调用 Autowired private ChatModel chatModel; public String rawChat() { // 构建提示词 ChatPrompt prompt new ChatPrompt( new SystemMessage(简洁回答问题), new UserMessage(什么是ChatModel) ); // 同步调用 ChatResponse response chatModel.call(prompt); return response.getResult().getOutput().getText(); } // 流式输出 public FluxString streamChat() { return chatModel.stream(prompt) .map(resp - resp.getResult().getOutput().getText()); }2.4 ChatModel 优缺点优势极致底层可控可手动组装所有消息、参数、工具无额外封装损耗适合框架二次开发、自定义拦截逻辑完全统一 API切换模型仅替换实现类业务代码无需大幅改动。劣势模板代码冗余每次调用都要手动构建ChatPrompt、Message提示词模板、变量替换、记忆管理、工具注册需要自己封装链式调用可读性差复杂对话逻辑代码臃肿。三、ChatClient 上层门面工具3.1 定位与设计目的ChatClient是 Spring AI 为业务开发提供的流畅构建器 API基于 ChatModel 封装解决原生 ChatModel 代码繁琐问题内置能力流式链式构建语法内置提示词模板、变量渲染一键配置系统提示词、模型参数统一对话记忆ChatMemory集成工具函数Function Calling快速注册拦截器Advisor全局切面管理同步 / 流式 / 实体类型返回一键切换。3.2 ChatClient 创建方式方式 1自动注入推荐自动装配Autowired private ChatClient chatClient;自动装配条件容器中存在ChatModelBeanSpring AI 自动生成ChatClient。方式 2手动构建自定义 ChatClientBean public ChatClient customChatClient(ChatModel chatModel) { return ChatClient.builder(chatModel) // 全局默认系统提示词 .defaultSystem(你是资深后端开发回答简洁) // 全局默认参数 .defaultOptions(OllamaOptions.builder().temperature(0.5).build()) // 全局拦截器 .defaultAdvisors(new SimpleLoggerAdvisor()) .build(); }3.3 ChatClient 完整核心用法示例3.3.1 基础同步问答String res chatClient.prompt() .system(你是Java技术博主) .user(讲解Spring AI ChatClient) .call() .content();3.3.2 提示词模板 变量占位String res chatClient.prompt() .system(根据{language}讲解{topic}简短输出) .user(u - u.param(language, Java).param(topic, ChatModel)) .call() .content();3.3.3 流式打字机输出Web 实时对话public FluxString streamReply(String question) { return chatClient.prompt() .user(question) .stream() .content(); }3.3.4 强类型实体返回结构化输出无需手动解析 JSON// 定义接收实体 record CodeResp(String title, String code, String explain) {} CodeResp resp chatClient.prompt() .user(写一段Spring AI调用代码) .call() .entity(CodeResp.class);3.3.5 集成对话记忆多轮上下文// 内存记忆支持会话隔离 ChatMemory memory new InMemoryChatMemory(); String reply1 chatClient.prompt() .advisors(new MessageChatMemoryAdvisor(memory)) .user(什么是ChatModel) .call() .content(); String reply2 chatClient.prompt() .advisors(new MessageChatMemoryAdvisor(memory)) .user(它和ChatClient区别) .call() .content();3.3.6 Function Calling 工具调用// 自定义工具 Tool public String getWeather(String city) { return city 今日25℃晴天; } // 注册工具调用 String res chatClient.prompt() .tools(this) .user(北京今天天气) .call() .content();3.4 ChatClient 核心内置能力Advisor 拦截器Advisor 是 ChatClient 的切面扩展点执行链路请求前置处理 → 调用ChatModel → 响应后置处理官方内置常用 AdvisorMessageChatMemoryAdvisor对话上下文记忆SimpleLoggerAdvisor打印请求 / 响应日志PromptTemplateAdvisor统一处理提示词模板RetrievalAugmentationAdvisorRAG 检索增强接入。支持自定义 Advisor 实现鉴权、限流、敏感词过滤、日志埋点。3.5 ChatClient 优缺点优势流畅链式 API业务代码极简可读性极强内置模板、记忆、工具、结构化输出开箱即用全局默认配置统一管理不用每个请求重复设置参数Advisor 切面统一拦截集中处理日志、RAG、上下文支持强类型返回省去 JSON 手动解析。劣势重度封装底层细节隐藏极端自定义场景不如原生 ChatModel 灵活多层封装轻微增加调用链路极致性能场景可选用原生 ChatModel。四、ChatModel vs ChatClient 核心对比表表格对比维度ChatModelChatClient定位底层标准接口统一大模型抽象上层业务门面简化开发工具依赖关系无依赖最底层持有 ChatModel封装其能力编码风格命令式手动组装 ChatPrompt、Message流式链式 Builder极简代码提示词模板需手动实现原生内置变量渲染多轮记忆手动拼接历史消息内置 ChatMemory Advisor 一键接入结构化输出手动解析 ChatResponse.entity(Class)自动映射实体工具调用手动组装 ToolDefinitiontools()快速注册 Tool 方法扩展方式自行封装工具类Advisor 切面统一拦截处理适用场景框架封装、底层中间件、精细控制业务接口、Web 对话、快速开发五、两者配合最佳实践方案企业级项目标准分层使用规范配置层注入对应厂商ChatModelBean统一管理模型地址、密钥、基础参数全局门面层基于 ChatModel 构建全局ChatClient统一配置系统提示词、日志 Advisor、全局工具业务层90% 场景直接使用自动注入的 ChatClient 完成问答、流式、RAG、多轮对话底层扩展场景10%自定义拦截、特殊模型参数、自研记忆逻辑时直接操作原生 ChatModel。标准完整配置示例Configuration public class SpringAiConfig { // 1. 底层ChatModel Bean public ChatModel ollamaChatModel(OllamaProperties props) { OllamaApi api OllamaApi.builder() .baseUrl(props.getBaseUrl()) .build(); OllamaOptions options OllamaOptions.builder() .model(qwen:7b) .temperature(0.6) .build(); return new OllamaChatModel(api, options); } // 2. 全局ChatClient基于ChatModel封装 Bean public ChatClient chatClient(ChatModel chatModel) { return ChatClient.builder(chatModel) .defaultSystem(你是专业后端开发回答精简专业) .defaultAdvisors(new SimpleLoggerAdvisor()) .build(); } // 3. 对话记忆Bean供业务注入 Bean public ChatMemory chatMemory() { return new InMemoryChatMemory(); } }六、常见开发误区总结只使用 ChatModel 写业务大量重复构建消息、模板代码维护成本高误以为 ChatClient 可以脱离 ChatModelChatClient 只是封装底层必须依赖 ChatModel全局配置重复定义不要每次 prompt 都重复设置 system、temperature统一在 ChatClient builder 全局配置多轮对话手动拼接历史消息优先使用 MessageChatMemoryAdvisor避免手动维护上下文流式输出自行拼接字符串ChatClient.stream().content()已分段返回直接返回给前端 SSE 即可。七、全文总结ChatModel 是标准底座Spring AI 所有对话模型的统一抽象抹平各大厂商 API 差异提供同步 / 流式基础调用能力面向底层扩展开发ChatClient 是业务工具基于 ChatModel 的高层封装流畅 Builder API内置模板、记忆、工具、结构化返回、切面拦截日常业务开发首选二者互补而非替代底层能力靠 ChatModel业务简化靠 ChatClient企业项目标准架构为「ChatModel 配置 ChatClient 全局门面 业务层调用 ChatClient」开发选型建议普通问答、流式对话、RAG、多轮聊天全部使用 ChatClient自研中间件、深度自定义模型请求逻辑、极致性能优化场景直接操作 ChatModel。