ChatClient 与 ChatModel:Spring AI 2.0 的两层职责
上一篇里,你已经用 ChatClient 对接 DeepSeek,跑通了第一次调用:
java
chatClient.prompt()
.user(message)
.call()
.content();
能跑通之后,自然会冒出一个问题:既然 ChatClient 已经够了,为什么 Spring AI 还要暴露一个 ChatModel?
这个问题的答案不在参数层面,而在架构层面。Spring AI 2.0 对两层的划分,首先是一个关于 Advisor 链归属 的决定;ChatOptions 的处理方式,是这个决定在参数传递上的结果。这篇先讲架构分界,再把 ChatOptions 完整讲清楚,最后讲下沉的边界。
一、一次请求的完整旅程
先看一次 ChatClient 调用内部发生了什么:
text
ChatClient.prompt()
│
▼
Advisor 链(工具调用循环、记忆、观测、重试、自定义拦截......)
│
▼
链的末端 → ChatModel.call(prompt) → 厂商 SDK → HTTP 请求
Advisor 链是 ChatClient 在把请求交给 ChatModel 之前经过的一条编排管道。它可能做的事包括:拼接历史对话、驱动工具调用循环、记录观测数据、执行重试、运行自定义拦截逻辑。
ChatModel 位于这条链的末端。它的职责范围比链窄得多:把链最终产出的 Prompt 翻译成厂商要求的格式,发出请求,拿回 ChatResponse。
"链的末端调用 ChatModel"这个位置,就是两层在运行时相遇的地方。 Advisor 链上的所有组件都在 ChatModel 之外运行,ChatModel 只接收链处理完毕之后的结果。
二、根本分界:Advisor 链的归属
Spring AI 2.0 最核心的架构决策,是把工具调用循环 从 ChatModel 内部整体移出,放到 ChatClient 的 Advisor 链上。
官方文档对此的表述是直接的:
Spring AI 2.0 makes the tool calling loop a first-class, composable component of the
ChatClient's advisor chain. ... This architecture replaces the per-ChatModeltool execution loops of Spring AI 1.x.
具体机制是:DefaultChatClient 会自动注册一个 ToolCallingAdvisor。它是递归 Advisor,拥有工具执行生命周期,驱动请求/响应循环,直到模型产出一个不含工具调用的响应为止。工具循环不再由每个 ChatModel 实现各自维护。
这意味着,2.0 的 ChatModel.call(prompt) 不再自动执行工具调用。官方文档明确说明:
ChatModeldoes not execute tool calls.ChatModel.call(prompt)andChatModel.stream(prompt)return the model's raw response, including any tool call requests, without executing them.
因此,两层在运行时行为上的分界,首先是一条关于"链是否存在"的分界:
| ChatClient | ChatModel | |
|---|---|---|
| Advisor 链 | 默认携带完整链(工具调用、记忆、观测等) | 不携带 |
| 工具调用循环 | 由 ToolCallingAdvisor 驱动,自动完成 |
不执行,原样返回含工具调用的响应 |
| 绕过链的后果 | --- | 同时失去链上的全部编排能力 |
官方在定义"何时直接使用 ChatModel"时,第一条标准正是"You don't want the advisor chain (no memory advisor, no observability advisor, no ToolCallingAdvisor)"。这条标准指向的是架构层面的选择:你是否需要那条链所承载的编排能力。
ChatModel 的定位:raw 模型通道
ChatModel 本身并没有被降级。它仍然是 ChatClient 的底座,仍然是框架扩展的注入点。但在 2.0 的职责划分中,它的角色被收窄为一个 raw 模型通道:只负责格式翻译和 HTTP 传输,不隐含链上的任何高层逻辑。
官方对两层的选型建议也是按这个维度切分的:
For most applications,
ChatClientis the recommended entry point... This page is for users who deliberately want the lower-level path.
For everything else --- chat applications, RAG, agentic workflows, tool-heavy assistants --- useChatClient.
注意"deliberately"这个词。2.0 把边界划清楚,意思是:日常业务代码的默认入口是 ChatClient;ChatModel 留给明确需要低层路径的场景。 2.0 之前两者的边界是模糊的,很多人直接 @Autowired ChatModel 就把业务逻辑写了,工具调用、重试、记忆统统往里面塞;2.0 通过把工具循环上移到链上,把这条线划清楚了。
需要说清楚的是:模型自身的推理仍然是 ChatModel 在做。 ChatModel 把 Prompt 翻译成厂商格式、发出请求、拿回 ChatResponse,这是它的核心职责,链不替代这一步。所谓"编排逻辑在链上",准确含义是:那些让单次模型调用变成一个完整可用会话的编排逻辑,由链完成,不由 ChatModel 内部完成。
三、ChatOptions:模型调用的参数载体
架构分界讲清楚之后,再进入日常开发中最频繁触碰的 ChatOptions。
3.1 ChatOptions 是什么
调用模型时,除了传入消息内容,还可以传入一组参数来控制模型怎么生成 。这组参数的载体就是 ChatOptions。
java
ChatOptions options = ChatOptions.builder()
.temperature(0.7)
.maxTokens(500)
.build();
它不改变你问什么,改变的是模型回答的方式。temperature 控制输出的随机程度,maxTokens 限制最多生成多少 token,model 指定使用哪个模型。
3.2 通用字段
ChatOptions 接口定义了一组跨供应商通用的参数:
| 参数 | 类型 | 作用 | 典型范围 |
|---|---|---|---|
model |
String | 指定使用哪个模型 | 供应商定义 |
temperature |
Double | 控制输出随机性,越低越确定 | 0.0 -- 2.0 |
maxTokens |
Integer | 限制生成的最大 token 数 | 模型相关 |
topP |
Double | 核采样概率阈值 | 0.0 -- 1.0 |
frequencyPenalty |
Double | 按 token 出现频率施加惩罚 | -2.0 -- 2.0 |
presencePenalty |
Double | 按 token 是否出现过施加惩罚 | -2.0 -- 2.0 |
stopSequences |
List<String> | 遇到这些序列时停止生成 | 供应商定义 |
ChatOptions.builder() 产出的是 DefaultChatOptions,属于通用类型,只覆盖跨供应商字段。
3.3 供应商特有字段
一旦需要供应商特有参数,就必须落到具体类型上。比如 OpenAiChatOptions 提供了 reasoningEffort 字段,对应请求中的 reasoning_effort;OllamaChatOptions 有 numCtx 这类硬件加载参数。各供应商的 Options 实现类继承或实现 ChatOptions,在此之上增加自己的字段。
这一点在后面的分层讨论中会反复出现:通用类型和供应商具体类型是两回事,2.0 对二者的处理方式不同。
3.4 Options 与 application.yaml 的关系
这是实际开发中最常问的一个问题:运行时 Options 能不能替换配置文件里的内容?
先明确一点:application.yaml 中的 spring.ai.openai.chat.* 本质上也是 Options,只不过是通过 Spring Boot 的配置绑定机制设置的基线值 。运行时传入的 ChatOptions 可以覆盖其中对应的参数。
例如,YAML 中写了:
yaml
spring:
ai:
openai:
chat:
temperature: 0.7
model: deepseek-chat
运行时这样写:
java
chatClient.prompt()
.options(OpenAiChatOptions.builder()
.temperature(0.2))
.user(message)
.call()
.content();
这次请求的 temperature 是 0.2,而不是 0.7。YAML 中的 model: deepseek-chat 仍然有效,因为这次 Options 没有设置 model。
所以准确的表述是:运行时 Options 覆盖 YAML 中同名的参数,未覆盖的参数继续使用 YAML 中的值。 它不是替换整个配置文件,而是按字段生效的覆盖。
版本细节:旧版本 Spring AI 中,模型参数位于
spring.ai.openai.chat.options.*这一层,即spring.ai.openai.chat.options.model、spring.ai.openai.chat.options.temperature。Spring AI 2.0 把.options.这一层拿掉了,模型参数直接写在chat下面。
3.5 三层配置与优先级
Spring AI 2.0 中,Options 有三个设置位置,优先级从低到高:
| 层级 | 配置位置 | 作用范围 | 典型用途 |
|---|---|---|---|
| 第一层:应用配置 | application.yaml 中的 spring.ai.openai.chat.* |
全局,该供应商的 ChatModel | 基线模型名、默认 temperature |
| 第二层:ChatClient 默认 | ChatClient.builder(chatModel).defaultOptions(...) |
该 ChatClient 实例的所有请求 | 某个业务场景的基线行为 |
| 第三层:单次请求运行时 | chatClient.prompt().options(...) |
仅本次请求,覆盖前两层同名字段 | 动态切模型、按请求调参数、供应商特有参数 |
优先级顺序:运行时 .options() > ChatClient 的 defaultOptions() > 应用配置 。应用配置中的值会被 defaultOptions() 覆盖,defaultOptions() 中的值又会被 .options() 覆盖。
第二层的写法:
java
@Bean
public ChatClient chatClient(ChatClient.Builder builder) {
return builder
.defaultSystem("你是一个简洁的技术助手。")
.defaultOptions(OpenAiChatOptions.builder()
.temperature(0.3)
.maxTokens(800)
.build())
.build();
}
注意 defaultOptions() 接受的是成品 ChatOptions ,不需要传 Builder。一旦 ChatClient 有了默认 Options,后续调用 .prompt().options(...) 时,框架会在 defaultOptions 的基础上合并,而不是替换掉它。
第三层运行时 .options() 通常传 Builder ,不 .build()。原因在第四节展开:框架需要在你提供的 Builder 和默认值之间做合并,成品 ChatOptions 是不可变对象,无法作为合并的载体。
3.6 运行时动态写入的三种典型场景
"动态"的含义是:同一个 ChatClient 实例被多个请求共享,每个请求可以带不同的 Options。不需要为每种模型或每组参数新建一个 ChatClient。
场景一:运行时动态切换模型
如果供应商支持通过 Options 指定模型(OpenAI 兼容接口、DashScope 等),可以直接在请求级覆盖:
java
@GetMapping("/chat")
public String chat(@RequestParam String message,
@RequestParam(defaultValue = "deepseek-chat") String model) {
return chatClient.prompt()
.options(OpenAiChatOptions.builder()
.model(model)
.temperature(0.5))
.user(message)
.call()
.content();
}
模型选择优先级是:运行时 .options() 中显式指定的模型 > defaultOptions() 中的模型 > application.yaml 中的 spring.ai.openai.chat.model 。只要请求里设了 model(...),前面的默认值就不会生效。
并非所有供应商都支持请求级动态切换模型。AWS Bedrock 集成不支持通过
ChatOptions动态指定模型,必须为不同模型单独创建客户端。OpenAI 兼容路线通常支持,具体以供应商文档为准。
场景二:按请求调整生成参数
这是最普通的动态用法:前端传 temperature、maxTokens,后端透传到 .options():
java
@PostMapping("/chat")
public String chat(@RequestBody ChatRequest request) {
var optionsBuilder = OpenAiChatOptions.builder()
.temperature(request.temperature())
.maxTokens(request.maxTokens());
return chatClient.prompt()
.options(optionsBuilder)
.user(request.message())
.call()
.content();
}
这里的 optionsBuilder 不 .build() ,直接传给 .options(),框架负责把它和默认值合并。
场景三:供应商特有的动态参数
通用 ChatOptions 只覆盖 model、temperature、maxTokens、topP 等跨厂商字段。一旦需要供应商特有参数,就必须落到具体类型上。OpenAiChatOptions 提供了 reasoningEffort 字段,对应请求中的 reasoning_effort。DeepSeek 的思考强度控制使用这个参数(取值 low / high / max,none 在部分接口中表示关闭思考模式)。
java
@GetMapping("/chat/reasoning")
public String reasoningChat(@RequestParam String message,
@RequestParam(defaultValue = "high") String effort) {
return chatClient.prompt()
.options(OpenAiChatOptions.builder()
.reasoningEffort(effort)
.temperature(0.7))
.user(message)
.call()
.content();
}
如果要关闭思考模式走标准对话路径,DeepSeek 侧的 OpenAI 格式控制参数是 thinking: {type: "disabled"} 或 reasoning_effort: "none"(取决于模型版本和接口)。在 Spring AI 的 OpenAiChatOptions 中,reasoning_effort 是一等字段;thinking 这类非标准字段通常需要通过 extraBody 传递(OpenAiChatOptions 有 extraBody 字段用于"OpenAI 兼容服务器额外参数")。如果使用 spring-ai-starter-model-deepseek 而不是 OpenAI Starter,DeepSeek 专属的 DeepSeekChatOptions 对这类参数的支持会更直接。
这一段的要点不是记住某个具体字段,而是看到模式:动态写入供应商特有配置时,要显式构建供应商具体类型的 Builder,而不是 ChatOptions.builder()。
3.7 Options 能做什么
到此可以完整回答开头的问题:
- Options 控制模型怎么生成,不改变问什么;
- 运行时 Options 覆盖
application.yaml中同名字段,未覆盖的继续用 YAML 值; - Options 可以写在三个层级,优先级从低到高:应用配置 →
defaultOptions()→ 运行时.options(); - 运行时
.options()可以动态切换模型、调整生成参数、触及供应商特有字段; - 供应商特有参数必须用供应商具体类型的 Builder(如
OpenAiChatOptions.builder()),不能用通用ChatOptions.builder()。
以上都是 ChatClient 层能做的事。接下来讲清楚 ChatClient 和 ChatModel 在 Options 处理上到底差在哪。这不是两层的根本差异,而是第二节架构分界在参数传递层面的直接结果。
四、Options 在两层中的处理差异
4.1 ChatClient 层:合并是它的职责
当你在 ChatClient 上写:
java
chatClient.prompt()
.options(OpenAiChatOptions.builder()
.temperature(0.2))
.user(message)
.call()
.content();
你只设置了 temperature。但最终交给 Advisor 链的 Prompt 中,model、maxTokens 等字段仍然有值。这些值来自模型实例的默认 Options。
ChatClient 在内部做的是合并:以模型默认 Options 为基线,用运行时设置的字段覆盖同名字段,未设置的字段保留默认值。框架内部做的事,等价于:
text
chatModel.getOptions().mutate() // 以模型默认 options 为基线
.combineWith(你的 Builder) // 你显式设置的字段覆盖默认
.build() // 得到完整 options,塞进 Prompt
Spring AI 的 PR 对此的说明是:
"options merging" is now implemented at the ChatClient level...
ChatModel.call()now expects the prompt it receives to already have the options merged OR to have a prompt with null options (in which case the model default options will be used).
这也解释了 3.5 节提到的问题:为什么运行时 .options() 要传 Builder。因为合并需要一个"在默认值基础上只表达修改"的载体,成品 ChatOptions 是不可变对象,无法承担这个角色。
合并发生在 ChatClient 层,在第一个 Advisor 被调用之前完成。
4.2 ChatModel 层:不合并,类型责任在调用方
直接调用 ChatModel.call(Prompt) 时,规则完全不同。
ChatModel 不做任何合并。官方 upgrade notes 的原话是:
When calling
ChatModel.call(Prompt)directly, the prompt must carry a fully builtChatOptionsinstance of the concrete type expected by the model. TheChatModeldoes not merge options: ifPrompt.getOptions()is non-null it is used as-is; if it isnull, the model's own default options are used instead. No partial merging occurs at theChatModellevel.
翻译成两条规则:
Prompt.getOptions() != null→ 原样使用,不做任何合并。Prompt.getOptions() == null→ 使用模型自己的默认 Options。
"全有或全无",没有"部分合并"这个中间状态。1.x 时代 ModelOptionsUtils.merge() 那种"模型默认 {model: gpt-4o, temperature: 0.7, maxTokens: 1000} + 运行时 {temperature: 0.2} → 合并为 {model: gpt-4o, temperature: 0.2, maxTokens: 1000}"的行为,在 2.0 的 ChatModel 层已经不存在了。如果你只传 {temperature: 0.2} 给 ChatModel,最终请求里 model 和 maxTokens 就是 null,由供应商端自行决定。
这意味着,如果你直接给 ChatModel 传一个只设置了 temperature 的 Options:
java
ChatOptions options = ChatOptions.builder()
.temperature(0.2)
.build();
Prompt prompt = new Prompt("你的问题", options);
chatModel.call(prompt);
最终请求中,model 和 maxTokens 就是 null,由供应商端自行决定。ChatModel 不会替你补上模型默认值。
4.3 类型也不再翻译
除了不合并,ChatModel 对 Options 的类型也不再做翻译。
ChatOptions.builder() 产出的是 DefaultChatOptions。而 OpenAiChatModel 在 2.0 中期望的是 OpenAiChatOptions 具体类型,因为它不再做"从通用到具体"的翻译。如果你直接传 DefaultChatOptions 给 OpenAiChatModel,会抛出 ClassCastException。
ChatClient 在内部完成了从通用 ChatOptions 到供应商具体类型的翻译,所以你在 ChatClient 层可以写 ChatOptions.builder() 而不需要关心具体类型。到了 ChatModel 层,这个责任回到你手上:必须传供应商具体类型的完整 Options。
这解释了为什么附件原文中提到的 ClassCastException 会发生:ChatOptions.builder() 产出的是 DefaultChatOptions,而 OpenAiChatModel 在 2.0 中期望的是 OpenAiChatOptions 具体类型,因为它不再做"从通用到具体"的翻译了。翻译和合并的责任,在 2.0 中被整体上移到了 ChatClient。
4.4 两条路径的责任对比
| ChatClient 路径 | ChatModel 直接路径 | |
|---|---|---|
| Options 合并 | 自动,以模型默认为基线 | 不合并,传什么用什么 |
| 类型具体化 | ChatClient 内部完成 | 你的责任,必须传供应商具体类型 |
| 传 Builder 还是成品 | 传 Builder (不 .build()) |
传 成品,且必须是完整 Options |
| 适合谁 | 业务代码 | 框架扩展 / low-level 用例 |
ChatClient 把"合并 + 类型翻译"这两件事收进了自己的调用链。 你用 ChatClient 时只表达"我要改什么",框架负责"在什么基础上改"以及"改成什么类型"。下到 ChatModel,这两件事就都回到了你手上。
这是第二节架构分界在参数传递层面的直接结果:因为 ChatModel 不再承担链上的编排职责,它也不应再承担链上的 Options 合并职责。
五、什么时候值得下沉到 ChatModel
5.1 你在写框架或底层集成
如果你的代码是给别人用的基础设施------一个自定义的模型 Starter、一个跨供应商的抽象适配层、一个需要直接持有 ChatModel 引用来做动态路由的组件------那么 ChatModel 是合适的注入点。官方对选型的描述正是这一条:"You're building infrastructure on top of Spring AI --- for example, a custom ChatClient implementation, or a library that exposes its own higher-level API"。
反过来,如果你在写 Controller、Service,或任何被业务逻辑驱动的代码,即使"觉得需要更细的控制",也应该优先通过 .options() 或自定义 Advisor 在 ChatClient 层表达,而不是下沉。
5.2 你需要在 ChatModel 层直接操作 Options
有些框架扩展场景需要在模型实例的默认 Options 上做调整,而不是走一次完整的 ChatClient 请求。2.0 中,ChatModel.getOptions() 返回的是强类型的供应商具体 Options (OpenAiChatModel.getOptions() 返回 OpenAiChatOptions),旧的 getDefaultOptions() 已废弃。你从模型实例的默认值出发,才能保留具体类型和未显式设置的字段。
mutate() :以模型默认为基线,改一两个字段:
java
var options = chatModel.getOptions().mutate()
.temperature(0.7)
.build();
Prompt prompt = new Prompt("你的问题", options);
ChatResponse response = chatModel.call(prompt);
mutate() 返回的是一个以当前 Options 为基准的新 Builder 。你只改 temperature,其余字段(model、maxTokens 等)原样保留。
combineWith() :把一组"可移植的"通用 Options 合并进具体类型:
java
ChatOptions portableOptions = ChatOptions.builder()
.temperature(0.3)
.maxTokens(500)
.build();
var merged = chatModel.getOptions()
.mutate()
.combineWith(portableOptions);
Prompt prompt = new Prompt("你的问题", merged);
chatModel.call(prompt);
combineWith 的语义是:参数中非 null 的字段,覆盖基线中的同名字段 ;标量字段是覆盖,集合字段是累加 。比如模型默认 stopSequences = ["###"],你 combineWith 一个 stopSequences = ["END"],最终结果是 ["###", "END"],不是 ["END"]。这一点在需要精确控制集合型参数时要特别留意。
一个需要知道的限制:
combineWith只识别DefaultChatOptionsBuilder的子类。绝大多数主流供应商的 Builder(如OpenAiChatOptions.Builder)都继承自它,但如果某个供应商的 Builder 独立实现,combineWith可能静默地什么都不做------不抛异常、不记日志,你的设置就是不生效。遇到"Options 设了但没反应"时,先检查这一点。
5.3 你需要绕过 Advisor 链
Advisor 链是 ChatClient 的核心资产,但它在某些场景下是"碍事"的。如果你在做框架扩展、需要精确观测单次模型调用的原始输入输出、或者需要在一个完全自定义的调用流程中排除所有默认 Advisor 的干预,那么走 ChatModel 是合理的。官方将这类场景归为 low-level use case。
但同样需要意识到:一旦绕过链,你就同时绕过了链上的工具调用循环、记忆管理、观测埋点。如果你仍然需要这些能力,你得自己在 ChatModel 外面重新组织------而重新组织的方式,本质上就是在重新发明一条 Advisor 链。
5.4 边界判断
一个工程判断:如果动态配置可以通过 .options(供应商Builder) 表达,就留在 ChatClient 上。 你依然能动态切换模型、调整参数、触及供应商特有字段,同时保留 Advisor 链、记忆、工具调用、观测等全部能力。
只有以下两种情况才考虑下沉到 ChatModel:
- 你需要在"模型默认 Options"这个层面直接操作合并/路由,而不是走一次 ChatClient 请求。
- 你明确要排除 Advisor 链 ,只需要 raw 的
ChatModel.call()。
对于绝大多数"动态写入配置"的需求,ChatClient 的运行时 .options() 是默认答案,不是备选答案。
六、ChatModel 的详细使用
前五节回答了"为什么要下沉"以及"下沉时参数责任如何变化"。这一节把 ChatModel 拿到手上实际用起来。由于 ChatModel 是 raw 通道,它的使用方式比 ChatClient 更"裸":没有 Advisor 替你兜底,每一步都需要你显式完成。
6.1 同步调用:call(Prompt) 与便捷重载
ChatModel 的同步入口是 call(Prompt),返回 ChatResponse。一个完整的最小调用如下:
java
ChatResponse response = chatModel.call(
new Prompt(List.of(
new SystemMessage("用中文简要回答"),
new UserMessage("ping")
), chatModel.getOptions().mutate()
.temperature(0.0)
.build())
);
String text = response.getResult().getOutput().getText();
注意这里直接使用了 chatModel.getOptions().mutate() 来构造 Options,而不是 ChatOptions.builder()。原因在第四节已经讲清楚了:ChatModel 不做合并,也不做类型翻译;从 getOptions() 出发,你拿到的是供应商具体类型的完整基线,mutate() 只改你关心的字段,其余原样保留。
ChatModel 接口还提供了两个便捷重载,本质上只是帮你组装 Prompt:
java
String text = chatModel.call("你好");
以及:
java
String text = chatModel.call(new UserMessage("你好"), new SystemMessage("用中文回答"));
call(String) 在响应为空时返回空字符串 "" 而不是 null,这一点和 call(Prompt) 取到的 getResult().getOutput().getText() 可能为 null 不同,判空逻辑需要区分。便捷重载适合快速验证或写单元测试;真实场景中如果需要控制 Options、SystemMessage 或工具定义,仍然要回到 Prompt。
6.2 流式调用:stream(Prompt) 与空帧处理
流式能力来自 StreamingChatModel,ChatModel 通常一并实现它。入口是:
java
Flux<ChatResponse> stream(Prompt prompt);
流式响应的中间帧可能没有完整的 Generation 或 Usage。读取增量文本时必须做空判断,不能假设每一帧都有有效内容:
java
Flux<String> tokens = chatModel.stream(prompt)
.map(cr -> {
Generation g = cr.getResult();
return (g == null || g.getOutput() == null)
? ""
: g.getOutput().getText();
})
.filter(s -> s != null && !s.isEmpty());
完整的使用统计(Usage)更常见于结束帧,不要假设每一帧都携带 token 计数。如果某个 ChatModel 实现并未真正支持流式,stream() 可能直接抛出不支持异常------这一点与 ChatClient 层的 stream() 行为一致,最终都会落到这里。
6.3 Options 在 ChatModel 层的传递方式
ChatModel 层传 Options 只有两种合法形态,对应第四节"全有或全无"的规则:
形态一:完全省略 Options,使用模型默认值。
java
Prompt prompt = new Prompt("你的问题");
chatModel.call(prompt);
Prompt.getOptions() 为 null,ChatModel 使用 getOptions() 返回的模型默认 Options。
形态二:传入完整构造的供应商具体 Options。
java
OpenAiChatOptions options = OpenAiChatOptions.builder()
.model("deepseek-chat")
.temperature(0.2)
.maxTokens(500)
.build();
Prompt prompt = new Prompt("你的问题", options);
chatModel.call(prompt);
如果你需要一个"在模型默认值基础上只改一两个字段"的完整 Options,用 getOptions().mutate():
java
var options = chatModel.getOptions().mutate()
.temperature(0.2)
.build();
Prompt prompt = new Prompt("你的问题", options);
不要试图在 ChatModel 层传一个"只设置了 temperature 的 Builder 产物"------ChatModel 不会把它和默认值合并,model、maxTokens 等字段会保持 null;如果传入的是通用 DefaultChatOptions 而非供应商具体类型,还会直接触发 ClassCastException。ChatModel 层没有"部分修改"这个选项。 你要么不给,要么给完整的。
6.4 多模态输入:在 ChatModel 层构造 Media
ChatModel层的多模态
多模态的载体是 UserMessage 的 media 字段。Media 由二进制数据和 MIME 类型组成,适配器会根据供应商能力把它转成模型可接受的请求。在 ChatModel 层,构造方式有两种。
从类路径资源加载图片:
java
Resource imageResource = new ClassPathResource("/static/image/product.png");
UserMessage userMessage = UserMessage.builder()
.text("请描述这张图片中的商品")
.media(MimeTypeUtils.IMAGE_PNG, imageResource)
.build();
ChatResponse response = chatModel.call(new Prompt(userMessage));
从远程 URL 加载:
java
UserMessage userMessage = UserMessage.builder()
.text("这张图片里有几只香蕉?")
.media(new Media(MimeTypeUtils.IMAGE_PNG,
URI.create("https://example.com/fruit-bowl.png")))
.build();
ChatResponse response = chatModel.call(new Prompt(userMessage));
音频输入同理,把 MIME 类型换成 audio/mpeg 即可:
java
Resource audioResource = new ClassPathResource("speech1.mp3");
UserMessage userMessage = new UserMessage(
"这段录音在讲什么内容?请总结成 3 个要点",
List.of(new Media(MimeTypeUtils.parseMimeType("audio/mpeg"), audioResource))
);
ChatResponse response = chatModel.call(new Prompt(
List.of(userMessage),
OpenAiChatOptions.builder()
.model("gpt-4o-audio-preview")
.build()
));
一个必须提前确认的前提:不是所有模型都支持多模态输入。 用纯文本模型接收图片,通常会直接报错或静默忽略图片内容。调用前需要核对所选模型的模态能力清单。
ChatClient层的多模态:.user() 内的 .media()
到了 ChatClient 层,你不需要自己构造 UserMessage 和 Media 列表。ChatClient 的 .user() 接受一个用户消息规格(user spec) lambda,在这个 lambda 里可以同时设置文本和媒体,框架在内部完成组装:
java
String response = chatClient.prompt()
.user(u -> u.text("请描述这张图片中的商品")
.media(MimeTypeUtils.IMAGE_PNG,
new ClassPathResource("/static/image/product.png")))
.call()
.content();
这与ChatModel层"先构造Media,再放进UserMessage"的方式在语义上等价,但责任划分不同:ChatModel层由你显式构造消息载体;ChatClient层由你描述消息内容,.user()规格负责把它变成链上的Prompt。
.media() 有两个常用重载,覆盖了6.4前面出现的两种ChatModel构造方式:
直接传 MimeType + Resource ,对应ChatModel层用ClassPathResource加载本地媒体的场景:
java
.media(MimeTypeUtils.IMAGE_PNG, new ClassPathResource("/images/chart.png"))
传一个已经构造好的 Media 对象,对应需要从远程URL或原始字节数组构造媒体的场景:
java
Media remoteImage = new Media(MimeTypeUtils.IMAGE_JPEG,
URI.create("https://example.com/photo.jpg"));
String response = chatClient.prompt()
.user(u -> u.text("这张图里有什么?").media(remoteImage))
.call()
.content();
音频输入的用法完全一致,只是MIME类型不同。ChatClient层不需要关心Media底层是Resource、URI还是字节数组,适配器会根据供应商能力做格式转换:
java
String response = chatClient.prompt()
.user(u -> u.text("请总结这段录音的要点")
.media(MimeTypeUtils.parseMimeType("audio/mpeg"),
new ClassPathResource("speech1.mp3")))
.call()
.content();
如果需要一次附加多个媒体 ,.media() 可以链式调用多次,或者通过对应的集合重载传入:
java
String response = chatClient.prompt()
.user(u -> u.text("比较这两张图中的差异")
.media(MimeTypeUtils.IMAGE_PNG, new ClassPathResource("/a.png"))
.media(MimeTypeUtils.IMAGE_PNG, new ClassPathResource("/b.png")))
.call()
.content();
和ChatModel层一样,媒体字段只对用户消息有意义,SystemMessage 和 AssistantMessage 不承载多模态输入。
两者的核心差异可以归纳为一点:在ChatModel层,Media是你亲手构造并塞进UserMessage的;在ChatClient层,你通过 .user(u -> u.text(...).media(...)) 声明"这条用户消息带有哪些媒体",链在内部替你完成同样的UserMessage + Media组装。 媒体对象本身------MimeType、Resource、URI、字节数组------在两层是同一套抽象,不存在ChatClient专属的媒体类型。
6.5 手动驱动工具调用循环
这是 ChatModel 与 ChatClient 差距最明显的地方。ChatClient 下 ToolCallingAdvisor 自动完成的事,在 ChatModel 下需要你逐行写出来。
工具定义通过 ToolCallingChatOptions.toolCallbacks(...) 传入,先用 ToolCallbacks.from(...) 把 @Tool 注解的对象转成回调:
java
ToolCallback[] tools = ToolCallbacks.from(new WeatherTools());
ChatOptions chatOptions = ToolCallingChatOptions.builder()
.toolCallbacks(tools)
.build();
Prompt prompt = new Prompt("What is the weather in Amsterdam and Paris?", chatOptions);
首次 call(prompt) 返回的 ChatResponse 如果包含工具调用请求,它不会被执行 。你需要用一个 ToolCallingManager 执行工具,把执行结果拼回对话历史,再次调用模型,直到响应不再包含工具调用为止:
java
ToolCallingManager toolCallingManager = ToolCallingManager.builder().build();
ChatResponse response = chatModel.call(prompt);
while (response.hasToolCalls()) {
ToolExecutionResult result = toolCallingManager.executeToolCalls(prompt, response);
if (result.returnDirect()) {
// 工具标记了 returnDirect=true,直接返回,不再回传模型
return result.conversationHistory();
}
prompt = new Prompt(result.conversationHistory(), chatOptions);
response = chatModel.call(prompt);
}
String finalAnswer = response.getResult().getOutput().getText();
几个关键组件的含义:
ToolCallingManager:执行工具调用。Spring Boot 自动配置会提供DefaultToolCallingManager;不走自动配置时用ToolCallingManager.builder().build()手动构建。response.hasToolCalls():模型是否请求了至少一个工具。executeToolCalls(prompt, response):查找并执行每个被请求的工具,返回包含更新后对话历史的ToolExecutionResult。result.conversationHistory():原始消息加上 assistant 的工具调用请求和工具响应,作为下一轮Prompt的消息列表。result.returnDirect():所有被调用工具都标记了returnDirect = true时为true,此时可以直接跳出循环,不必再回传模型。
流式场景下的手动循环更复杂一些:每一轮的 chunk 需要先用 MessageAggregator(或 ChatClientMessageAggregator)聚合,再判断是否包含工具调用;聚合的同时仍然可以把原始 chunk 转发给下游 SSE 端点。
最后是一个容易踩的语义差异:在 ChatModel 层,per-request 的工具列表会完全替换模型默认 Options 中的工具列表,而不是追加。 如果模型默认配置了 5 个工具,请求时只传 1 个,模型看到的就只有那 1 个。如果需要在保留默认工具的同时额外加一个,必须手动把默认工具合并进运行时列表:
java
List<ToolCallback> combined = new ArrayList<>(Arrays.asList(defaultTools));
combined.add(otherTool);
ChatOptions runtimeOptions = ToolCallingChatOptions.builder()
.toolCallbacks(combined)
.build();
而在 ChatClient 层,.tools(...) 对 .defaultTools(...) 的行为是追加,两层可以自然组合。这个差异本身,就是"ChatModel 不做链上编排"在工具参数上的直接体现。
七、两层在代码中如何连接
前面说两层在运行时通过"链的末端调用 ChatModel"相遇。在工程配置上,这个相遇只有一行代码:
java
@Bean
public ChatClient chatClient(ChatModel chatModel) {
return ChatClient.builder(chatModel)
.defaultSystem("你是一个简洁的技术助手。")
.build();
}
ChatClient.builder(ChatModel) 这个构造器就是两层在代码层面的唯一接合点。DefaultChatClientBuilder 的构造器接受的第一个参数就是 ChatModel。平时你注入 ChatClient.Builder,Builder 背后持有的正是自动配置好的 ChatModel;你自己写 @Bean 时,不过是在显式地完成同一件事。
依赖方向是单向的、收口的------ChatClient 依赖 ChatModel,业务代码依赖 ChatClient。依赖方向不反转,分层才成立。
八、总结
回到开头的问题:ChatClient 已经够了,为什么还要 ChatModel?
两层的根本分界不在参数,而在 Advisor 链的归属 :ChatClient 默认携带一条完整的链,驱动工具调用循环、记忆、观测等编排能力;ChatModel 不携带链,call() 直接触达模型,返回 raw 响应。
ChatOptions 的处理差异------ChatClient 合并、ChatModel 不合并------是这条架构分界在参数传递层面的结果。ChatClient 帮你"在默认值基础上合并并翻译类型";ChatModel 期望收到一个已经完整组装的请求,传什么就用什么。
ChatOptions 本身值得单独理解:它控制模型怎么生成,可以覆盖 application.yaml 中的同名字段,可以在三个层级设置,可以在运行时动态切换模型和调整参数。这些能力都在 ChatClient 层生效。
到了 ChatModel 层实际使用时,需要自己承担的责任也清楚了:同步 call(Prompt) 不合并 Options,要传就传完整的供应商具体类型,或者干脆用 getOptions().mutate() 从基线出发;流式 stream(Prompt) 要处理中间帧的空 Generation;多模态通过 UserMessage.media 构造;工具调用必须用 ToolCallingManager 手动驱动 while (response.hasToolCalls()) 循环------ChatClient 下 ToolCallingAdvisor 自动做的事,在这里一样不少地回到调用方手上。
日常业务代码留在 ChatClient。写框架、绕过 Advisor 链、或需要在模型默认 Options 上直接操作时,才下沉到 ChatModel。