ChatClient 和 ChatModel 有什么区别？为什么日常开发用 ChatClient？

2026/8/5 0:16:42

一、基础定位

1.`ChatModel`

底层核心接口，负责纯粹调用大模型服务

定位：基础设施层，直接对接各大厂商大模型接口（OpenAI、通义千问、文心一言、Ollama、DeepSeek 等）
核心能力：只做一件事：组装请求报文、发起 HTTP/grpc 请求、解析模型返回结果、处理基础鉴权、流式返回、基础参数（temperature、topP、maxTokens）
职责边界：
1. 封装各厂商差异化的 API 协议、请求体、响应体格式；
2. 基础对话消息收发（Prompt→ChatResponse）；
3. 简单的同步 / 流式返回；
没有内置：对话记忆、提示词模板、工具调用编排、拦截器、日志、重试、上下文管理等能力。
使用方式偏向原生 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();