ChatClient 和 ChatModel 有什么区别？为什么日常开发用 ChatClient？
一、基础定位
1.ChatModel
底层核心接口，负责纯粹调用大模型服务
- 定位：基础设施层，直接对接各大厂商大模型接口（OpenAI、通义千问、文心一言、Ollama、DeepSeek 等）
- 核心能力：只做一件事：组装请求报文、发起 HTTP/grpc 请求、解析模型返回结果、处理基础鉴权、流式返回、基础参数（temperature、topP、maxTokens）
- 职责边界：
- 封装各厂商差异化的 API 协议、请求体、响应体格式；
- 基础对话消息收发（
Prompt→ChatResponse）； - 简单的同步 / 流式返回；
- 没有内置：对话记忆、提示词模板、工具调用编排、拦截器、日志、重试、上下文管理等能力。
- 使用方式偏向原生 API 调用：
// 原生 ChatModel 写法 ChatResponse response = chatModel.call( new Prompt("帮我写一段Java代码") );2.ChatClient
上层封装的门面工具类，基于 ChatModel 构建的业务开发客户端
- 定位：应用业务层，对
ChatModel做高阶封装，面向开发者日常业务开发； - 本质：内部持有一个
ChatModel实例，所有最终的模型请求依旧委托给底层ChatModel； - 额外叠加大量工程化能力：提示词模板、对话记忆、拦截器、工具调用、构建者流式链式调用、结构化输出、上下文复用、全局配置、日志埋点、安全校验等。
// ChatClient 链式优雅写法 String result = chatClient.prompt() .user("写一个冒泡排序") .call() .content();二、核心维度详细对比
| 对比项 | ChatModel | ChatClient |
|---|---|---|
| 层级 | 底层基础接口 | 上层业务门面，包装 ChatModel |
| 核心职责 | 原生对接大模型接口，收发原始对话报文 | 业务场景封装，简化开发流程 |
| 编码风格 | 命令式，需要手动组装Prompt、解析ChatResponse，代码啰嗦 | 流式 Builder 链式调用，语义清晰，代码简洁 |
| 提示词模板 | 需要手动引入PromptTemplate拼接参数 | 原生内置.prompt().user("模板{name}").param("name","张三") |
| 对话记忆（ChatMemory） | 需要手动绑定、手动存取上下文 | 一行配置挂载全局 / 局部记忆，自动管理历史对话 |
| 拦截器、链路增强 | 无原生支持，需自己包装代理 | 原生interceptors()全局拦截，统一做日志、鉴权、限流、敏感词过滤 |
| 函数调用 / 工具调用 | 原生支持，但编排繁琐 | 高度简化工具注册、自动判断何时调用工具、自动回填结果 |
| 结构化输出（POJO 映射） | 手动解析 JSON 再序列化 | 内置entity(XXX.class)一键把模型返回转 Java 实体类 |
| 全局统一配置 | 需手动注入各个配置项 | 全局统一构建 ChatClient Bean，项目复用统一规则 |
| 适用场景 | 框架二次开发、自定义深度改造模型调用逻辑 | 业务 CRUD、AI 对话、智能问答等常规业务开发 |
三、关键运行链路
业务代码 → ChatClient（组装模板、拼接记忆、执行拦截器） → 封装成标准 Prompt → 委托内部持有的 ChatModel → ChatModel 发起真实网络请求到大模型服务商 → 原路逐层返回结果ChatClient 不会替代 ChatModel，只是在它外面套了一层工程化外壳。
四、为什么日常业务开发优先用 ChatClient？
1. 开发效率极高，样板代码极少
使用原生ChatModel时： 你要手动创建Prompt、手动填充模板参数、手动拼接历史对话、手动解析返回内容、捕获异常；ChatClient链式调用语义直观，一行代码完成对话，大幅减少重复模板代码。
2. 内置高频刚需能力，开箱即用
实际业务几乎都会用到的功能，ChatClient原生集成：
- 对话上下文记忆：聊天机器人多轮对话，不用自己写 Redis / 数据库存历史消息；
- 提示词模板管理：业务提示词统一抽模板，动态注入变量，便于后期统一维护、热更新；
- 统一拦截切面：全局记录入参出参日志、耗时统计、敏感词审核、权限校验、异常兜底重试；
- 结构化返回：AI 返回 JSON 直接映射为 Java 实体，不用手写 JSON 解析；
- 工具调用轻量化接入：给大模型绑定查询数据库、调用接口等工具极度简单。
3. 全局统一管控，项目规范化
项目中只需要构建一个全局ChatClientBean：统一模型参数、统一拦截规则、统一记忆策略，全项目复用，避免各个业务模块各自写一套模型调用逻辑，风格混乱、配置不统一。
4. 降低出错概率
ChatModel 偏向底层，稍有不慎就会出现： 消息格式组装错误、上下文丢失、忘记携带系统提示词、没有统一异常处理； ChatClient 做了标准化封装，约束规范用法，规避大量低级问题。
5. 后续维护与迭代友好
后续需要统一切换大模型（OpenAI 切阿里云通义、切本地 Ollama），只需要替换底层注入的ChatModel，上层业务的ChatClient代码完全不用改动，做到上层业务无感知切换模型。
五、什么场景才需要直接使用 ChatModel？
只有做深度定制化开发时才会直接操作ChatModel：
- 自研一套专属 AI 调用 SDK、中间件；
- 需要极致精细控制 HTTP 请求细节（自定义请求头、超时、代理、重试策略）；
- 自研特殊的对话上下文管理、自定义消息序列化逻辑；
- 封装公司内部统一 AI 网关，做一层自研适配层。
六、最简示例对照
方式 1：原生 ChatModel
@Autowired private OpenAiChatModel chatModel; public String chat(String msg) { PromptTemplate template = new PromptTemplate("你是助手，回答：{msg}"); Prompt prompt = template.create(Map.of("msg", msg)); ChatResponse resp = chatModel.call(prompt); return resp.getResult().getOutput().getText(); }方式 2：ChatClient（推荐业务写法）
@Bean public ChatClient chatClient(ChatModel chatModel) { return ChatClient.builder(chatModel) .defaultSystem("你是专业Java技术助手") .build(); } // 业务调用 chatClient.prompt() .user("解释AQS原理") .call() .content();总结
- ChatModel = 底层驱动，负责和大模型通信；
- ChatClient = 业务开发脚手架，包装驱动，补齐工程化能力；
- 绝大多数业务场景无脑选用
ChatClient，简洁、规范、扩展性强；只有框架级深度改造才直接操作ChatModel。