深度拆解 Spring AI 的 ChatClient，实现多 Agent 的生产级 LLM 调用器

Spring AI 跟大模型打交道的两个核心 API，一个是 ChatModel，一个是 ChatClient。

ChatModel 是底层接口，一问一答，干净利落。但真到了生产环境，要结构化输出、要对话记忆、要日志审计、要工具调用，只用 ChatModel 会写出一大堆样板代码。

ChatClient 就是 Spring AI 给出的解决方案，在 ChatModel 之上包了一层 Fluent API，把这些高频需求内置了。

这篇内容从 ChatClient 的基础用法讲起，再拆解它的进阶能力，包括提示词模板、结构化输出、流式调用、Advisor 拦截链，最后看看求职派在生产环境中是怎么封装 ChatClient 的。

01、为什么需要 ChatClient？

先看一个具体场景，让大模型返回结构化数据。

用 ChatModel 的话，需要先创建 BeanOutputConverter，然后把格式描述拼进提示词，再从返回值里取文本，最后调转换方法。

4 个步骤，每一步都需要手动去完成。

换成 ChatClient，同样的事情一行代码就能搞定。

ActorsFilms films = ChatClient.create(chatModel)
        .prompt("帮我返回五个{actor}导演的电影名")
        .call().entity(ActorsFilms.class);

结构化输出的转换器创建、格式注入、结果解析，ChatClient 全部内置了。

这还只是冰山一角。

ChatClient 更有价值的地方在于它的 Advisor 机制，可以在请求和响应的处理流程上挂载拦截器，实现对话记忆、日志记录、工具调用等能力，而且支持链式组合。

02、ChatClient 怎么创建？

创建 ChatClient 有两种典型场景，分别对应两种写法。

单模型场景？

如果项目里只接了一个大模型供应商，并且用的是 Spring AI 官方的 starter（比如 spring-ai-openai-spring-boot-starter），Spring Boot 会自动装配一个 ChatClient.Builder，在构造方法里注入后调用 builder.build() 就能拿到 ChatClient 实例。

这种方式最省事，Spring Boot 帮我们搞定了模型配置、API Key 注入等所有细节。

不过自动装配的 Builder 只有在容器中恰好有一个 ChatModel Bean 时才会生效。

如果同时引入了多个模型 starter，启动时会因为无法确定注入哪个 ChatModel 而报错。

多模型场景？

求职派同时对接了 DeepSeek、智谱等多个供应商，一个 Builder 不知道该绑哪个模型。

这时候需要手动指定 ChatModel 来创建，写法是 ChatClient.builder(chatModel).build()。

求职派更进一步，会根据用户消息中有没有图片，自动切换 TEXT 和 VISION 模型。

ModelConfig.ModelType model = ModelConfig.ModelType.TEXT;
if (prompt.getUserMessages().stream()
        .anyMatch(m -> !CollectionUtils.isEmpty(m.getMedia()))) {
    model = ModelConfig.ModelType.VISION;
}
var chatMode...