## 01、痛点

你有没有遇到过：大模型接口在 Demo 里跑得好好的，一接进业务系统就卡成“等等等”？我是老李，最近在带团队给客服工单系统加智能摘要。第一版很直接，Controller 里 new 了一个 OpenAiChatModel，前端把问题发过来，后端同步调用，再把完整文本返回去。

问题很快来了。第一，接口经常超时，模型生成三五百字要十几秒，前端一直转圈。第二，产品希望做出打字机效果，前端同学说需要 SSE 流式，但当前接口只是一个普通 JSON，没法接。第三，公司评估要换一个性价比更高的模型服务，结果发现 Controller、Service 里到处写着 OpenAi 的类名，替换起来像拆地雷。

这不是个例。很多团队第一次接大模型，都卡在“能调通”和“能上线”之间。今天专门聊 Spring AI 里最该先抓住的入口：ChatClient。

## 02、是什么

ChatClient 是 Spring AI 官方设计的统一对话客户端入口。如果你用过 Spring 的 WebClient 或 RestClient，会发现它的手感很熟悉：通过一连串方法把请求参数、消息内容、返回类型串起来，最后用 call 或 stream 触发。

它不是某个模型供应商的客户端，而是站在更高一层的抽象。为了理解它，需要把一条调用链拆开：

ChatClient -> Prompt -> Message -> ChatModel -> ChatResponse。

ChatClient 负责组织一次对话请求，你可以往里面塞系统消息、用户消息、模型参数。Prompt 是一次完整请求的载体，包含一个或多个 Message，也可以包含 temperature、max tokens 等选项。Message 是具体角色和内容，常见角色有 system、user、assistant。ChatModel 是模型能力接口，OpenAI、Ollama、Azure 等供应商都有自己的实现。ChatResponse 是模型返回结果，里面不仅包含文本，还包含 token 用量、结束原因等元数据。

这里有两个容易混淆的触发方式。

.call() 是同步调用。请求发出去后，当前线程会一直等到模型生成完整结果才返回。适合短文本、后台任务、生成结果后再处理的场景。

.stream() 是流式调用。它返回的是一个响应式流，模型每生成一小段，就推给调用方。前端配合 SSE，可以做出逐字输出的效果。适合对话页面、长时间生成、需要尽快给用户反馈的场景。

返回方式也有三种常见选择。content() 只返回纯文本，适合大多数业务。chatResponse() 返回完整 ChatResponse，适合需要 token 统计、结束原因、额外元数据的场景。entity() 可以把文本内容映射成自定义结构体，适合让模型输出 JSON 后直接转成对象。

## 03、为什么

为什么优先掌握 ChatClient，而不是某个模型供应商的专用类？

第一，业务代码不应该绑死在某个模型服务上。OpenAiChatModel 这类类名一旦散落在 Controller 和 Service 里，切换供应商就是一场灾难。ChatClient 把具体实现藏到配置层，业务代码面对的是一套稳定接口。

第二，Fluent API 让人一眼能看懂请求是怎么组装的。prompt、user、call、content，这一串方法名本身就是文档。团队里新人接手成本会低很多。

第三，同步和流式切换几乎只改一个方法名。call 和 stream 对应两套场景，但业务逻辑不需要推倒重来。

第四，Spring AI 的自动配置已经把 ChatClient.Builder 准备好了。你只需要注入、构建，不用自己去管连接池、超时、序列化等细节。

第五，可测试性。依赖 ChatClient 或 ChatModel 抽象，可以在测试时替换成假实现。如果 Controller 直接 new OpenAiChatModel，每次测试都要打真实模型，慢且不稳定。

## 04、架构

一个合理的架构其实不复杂：Controller 负责 HTTP 协议，Service 负责业务编排，ChatClient 负责模型调用，模型供应商负责真正推理。

推荐做法是，Controller 只依赖自己的 Service，Service 依赖 ChatClient 或 ChatModel，不直接依赖 OpenAiChatModel。配置放在 application.yml 里，通过 Spring 的自动装配生成对应的 Bean。

例如：

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com
      chat:
        options:
          model: gpt-4o-mini

启动后，Spring AI 会根据这些配置准备好 ChatClient.Builder。Service 里再调用 builder.build() 得到 ChatClient 实例。

如果未来要接第二个模型供应商，可以再增加一段配置，给不同 ChatClient Bean 加限定名，在 Service 里按业务选择，甚至用 Map 一次性注入所有实现。

这个分层带来的最大好处是：上层业务代码只面向 ChatClient 抽象，不关心底下是 OpenAI、Azure 还是本地模型。

## 05、实战

下面完成两个接口：/chat 返回普通回答，/chat/stream 返回 SSE 流式回答。

第一步，引入 Spring AI 相关依赖。这里假设 Spring Boot 版本与 Spring AI 版本已经匹配，主要引入 OpenAI 对应的 starter 以及 WebFlux 支持，因为流式返回需要响应式能力。

第二步，写配置。上面的 application.yml 已经展示了基础配置。如果需要本地模型，可以把 base-url 指向本地服务，模型名改成对应名称。

第三步，写 Service。核心代码如下：

@Service
public class ChatService {

    private final ChatClient chatClient;

    public ChatService(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    public String answer(String question) {
        return chatClient.prompt()
                .user(question)
                .call()
                .content();
    }

    public Flux<String> stream(String question) {
        return chatClient.prompt()
                .user(question)
                .stream()
                .content();
    }
}

注意 answer 方法是同步调用，返回 String。stream 方法返回 Flux<String>，每一次模型输出片段都会被推送出去。

第四步，写 Controller。对外暴露两个 GET 接口：

@RestController
public class ChatController {

    private final ChatService chatService;

    public ChatController(ChatService chatService) {
        this.chatService = chatService;
    }

    @GetMapping("/chat")
    public String chat(@RequestParam String question) {
        return chatService.answer(question);
    }

    @GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> chatStream(@RequestParam String question) {
        return chatService.stream(question);
    }
}

浏览器访问 /chat?question=你好，会得到一个普通文本响应。访问 /chat/stream?question=你好，会看到响应头变成 text/event-stream，内容一段一段地到达。这里 produces 的 MediaType.TEXT_EVENT_STREAM_VALUE 很关键，少了它，浏览器和前端客户端就无法按 SSE 协议解析。

如果只是想看效果，可以直接用 curl 访问这两个地址。普通接口会等到完整结果返回；流式接口会看到数据陆续输出。

## 06、洞见

回到开头的问题：Controller 是否应该直接依赖某个 OpenAiChatModel？

答案很明确：不应该。

Controller 的职责是处理 HTTP 请求和响应，它不应该知道底层模型供应商是谁。一旦 Controller 直接依赖某个具体模型类，就会出现三个问题：一是换供应商必须改 Controller；二是无法在不启动真实模型的情况下做单元测试；三是模型专属参数会污染协议层。

业务应用优先依赖 ChatClient 或 ChatModel 抽象。只有真正需要模型专属能力时，才向下穿透。比如某个供应商的模型支持特殊参数、特殊返回结构，或者需要按供应商调整重试策略。这时也应该把这些能力隔离在一个独立的适配层里，而不是让 Controller、Service 到处散落供应商专属代码。

一个简单判断标准：如果你的 Controller 或核心 Service 里出现了 OpenAi、Azure、Ollama 这类名字，基本就说明抽象放错了位置。把具体供应商关进配置和适配层，业务代码才能保持稳定。

## 07、行动

光知道不够，建议做一次切换验证。

目标是用同一套 Service 切换两个模型 Provider，看看核心业务代码是否保持稳定。

第一步，把 Service 定义为只依赖 ChatClient 抽象。上面的 ChatService 已经满足。

第二步，准备两个模型供应商配置。比如一个指向 OpenAI，一个指向本地 Ollama。Ollama 可以用本地地址，模型名改成本地已拉取的模型。

第三步，先启动 OpenAI 配置，跑通 /chat 和 /chat/stream，记录响应结果。

第四步，修改 application.yml 的 base-url、api-key 和 model，指向第二个供应商。注意不要改 Controller 和 Service 代码。

第五步，重启服务，再跑同一组请求。如果业务代码稳定，两个接口应该都能按预期返回，普通回答完整，流式回答逐段输出。

如果你希望两个供应商同时在线，可以定义两个 ChatClient Bean，使用 @Qualifier 区分。或者在 Service 中注入 Map<String, ChatClient>，根据业务配置动态选择。但无论怎么选，核心 Service 的方法体基本不用动，因为业务语言只有“提问并获取回答”和“提问并流式获取回答”。

这个验证做完，你会对“抽象”两个字有更实际的感受：切换供应商不再是大工程，而是配置变更。

## 08、小结

ChatClient 是 Spring AI 里最值得优先掌握的入口。它把模型调用抽象成了一条清晰的 Fluent API 链：ChatClient -> Prompt -> Message -> ChatModel -> ChatResponse。

同步用 call，流式用 stream。返回时按需选择 content、chatResponse 或 entity。完成 /chat 和 /chat/stream 两个接口，普通回答与 SSE 流式回答就能同时覆盖。

更重要的是，不要让 Controller 直接依赖某个具体模型类。业务代码优先依赖 ChatClient 或 ChatModel 抽象，只有真正需要模型专属能力时才向下穿透，并且要隔离在适配层里。用同一套 Service 切换两个模型 Provider，验证核心业务代码是否保持稳定，是理解这套抽象价值的最快方式。

## 09、链接与概念说明

概念说明：

- ChatClient：Spring AI 提供的统一对话客户端入口，使用 Fluent API 组织请求。
- Prompt：一次完整模型请求，包含一个或多个 Message 以及可选参数。
- Message：角色与内容的结构，常见角色有 system、user、assistant。
- ChatModel：聊天模型能力抽象，不同供应商提供不同实现。
- ChatResponse：模型返回结果，包含文本、token 统计、结束原因等元数据。
- SSE：Server-Sent Events，一种基于 HTTP 的单向流式推送协议，适合模型逐步输出。
- Flux：响应式流类型，用于承载流式返回的内容序列。

推荐链接：Spring AI 官方文档中的 ChatClient 部分，搜索 ChatClient API 即可；Spring Framework 的 WebClient、RestClient 文档可帮助理解 Fluent API 风格。

注意：由于 Spring AI 版本迭代较快，具体配置项和 starter 名称请以你项目使用的版本官方文档为准。

你有没有遇到过：大模型接口在 Demo 里跑得好好的，一接进业务系统就卡成“等等等”？我是老李，最近在带团队给客服工单系统加智能摘要。第一版很直接，Controller 里 new 了一个 OpenAiChatModel，前端把问题发过来，后端同步调用，再把完整文本返回去。

《Spring AI 2.0实战》第2招 跑通ChatClient

从一次接口阻塞讲起，拆解 ChatClient 调用链，完成 /chat 与 /chat/stream 两个接口，并验证切换模型供应商时业务代码保持稳定。

架构师

编程语言

本文介绍SpringAI的ChatClient如何解决大模型接口超时、SSE流式输出及供应商切换难题。通过分层架构和FluentAPI，展示同步call与流式stream两种调用方式，实现普通回答与打字机效果。业务代码仅依赖ChatClient抽象，配置隔离供应商，配合示例代码快速落地。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

《Spring AI 2.0实战》第2招 跑通ChatClient-腾讯云开发者社区-腾讯云

《Spring AI 2.0实战》第2招跑通ChatClient

《Spring AI 2.0实战》第2招跑通ChatClient

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

《Spring AI 2.0实战》第2招 跑通ChatClient

《Spring AI 2.0实战》第2招 跑通ChatClient

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

《Spring AI 2.0实战》第2招跑通ChatClient

《Spring AI 2.0实战》第2招跑通ChatClient