Spring AI 2.0 系列(三):ChatClient 与 ChatModel:Spring AI 2.0 的两层职责

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-ChatModel tool execution loops of Spring AI 1.x.

具体机制是:DefaultChatClient 会自动注册一个 ToolCallingAdvisor。它是递归 Advisor,拥有工具执行生命周期,驱动请求/响应循环,直到模型产出一个不含工具调用的响应为止。工具循环不再由每个 ChatModel 实现各自维护。

这意味着,2.0 的 ChatModel.call(prompt) 不再自动执行工具调用。官方文档明确说明:

ChatModel does not execute tool calls. ChatModel.call(prompt) and ChatModel.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, ChatClient is 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 --- use ChatClient.

注意"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 built ChatOptions instance of the concrete type expected by the model. The ChatModel does not merge options: if Prompt.getOptions() is non-null it is used as-is; if it is null, the model's own default options are used instead. No partial merging occurs at the ChatModel level.

翻译成两条规则:

  • 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:

  1. 你需要在"模型默认 Options"这个层面直接操作合并/路由,而不是走一次 ChatClient 请求。
  2. 你明确要排除 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。

相关推荐
syso_稻草人12 分钟前
qwen-image-2.1 姿态控制拆解:SDPose 提骨架 + Fun-ControlNet-Union 锁姿势,换人换景不换姿势
人工智能·stable diffusion·prompt·提示词优化·qwen-image
Baihai_IDP17 分钟前
大模型 API 真的在赔本赚吆喝吗?聊聊 Token 背后的真实成本
人工智能·llm·aigc
数字融合19 分钟前
透明化视频动态三维重建空间数据零核心技术
人工智能·python·virtualenv
谙弆悕博士31 分钟前
多智能体架构详解:黑板共享架构(共享存储交互型)
人工智能·架构·大模型·agent·多智能体·黑板架构·anggraph
AI创界者1 小时前
Python 进阶实战(五十四章):大模型推理网关终极架构——分布式全局前缀 Trie 缓存同步与多网关高可用协同调度
人工智能·python·aigc
后端小肥肠1 小时前
公众号里流量很夯的漫画赛道:趣味漫画创作全拆解
人工智能·aigc·agent
Rain的Java大神之路1 小时前
把数组本身变成哈希表:原地哈希搞定 LeetCode 41「缺失的第一个正数」
java·后端·leetcode
程序油菜花1 小时前
微软 ONNX Runtime 仓库突然 404:你的项目,可能并不真正属于你
人工智能
锋行天下2 小时前
LangGraph 对接 MCP 实战指南:从本地开发到线上部署与模型防坑
前端·人工智能·后端