Spring AI实战：统一抽象层与ChatClient构建首个AI对话接口

Spring AI 实战教程（一）入门示例

Spring AI 这个项目我盯了挺长时间，从它早期还是个雏形的时候就一直在关注。作为一个常年用 Spring 生态写业务系统的开发者，说实话，之前接 AI 能力的时候心里是有点抗拒的，OpenAI 的 SDK、Anthropic 的 SDK、各种模型的 SDK 各写各的，参数风格不一样，返回结构不一样，换个模型就要重新适配一遍。这感觉就像家里买了台新电器，结果每个电器都自带一个遥控器，桌面上一排遥控器，看着就头疼。

Spring AI 要解决的就是这个问题。它给 Java 开发者提供了一套统一的抽象层，把主流的 AI 模型、向量数据库这些资源全部包装成 Spring 风格的 Bean，你只需要通过配置注入，然后用统一的 API 去调用。这篇入门教程就是用最简单的代码把整个链路跑通，让还没接触过 Spring AI 的同学在半小时内就能做出自己的第一个 AI 对话程序。

适合谁来读呢？如果你已经熟悉 Spring Boot 的基本用法，会写 Controller、会配 application.yml，那完全够了。不需要你懂深度学习，也不需要你研究过大模型 API 的底层细节，这些都被框架帮你处理掉了。

1. Spring AI 到底是什么，为什么值得学

老规矩，先搞清楚一个框架解决什么问题，再决定要不要学它。

你回想一下自己在项目里对接第三方服务时的过程。对接短信平台，找一个 SDK，配置 appKey，封装一个 Service，发消息。过了两个月换了家短信服务商，又得换 SDK、换配置、改代码。这套流程我相信每个写业务系统的人都经历过，说实话挺烦人的。

Spring AI 干的事就相当于在你和多家人工智能服务之间加了一个适配层，它能让你用同样的代码风格去访问不同的模型供应商。今年的模型服务商是真的多，各家能力也各有侧重，有的擅长代码生成，有的偏逻辑推理，有的上下文窗口大。厂商多了之后，切换的成本就会成为项目选型时要考虑的重要因素，Spring AI 的价值在这里就被放大了。

用一段代码来说明。在不使用 Spring AI 的情况下，你直接调 OpenAI 的接口可能要这么写：

// 直接用 HTTP 客户端调用 String requestBody = "{ ... 一大堆参数拼装 ... }"; String response = httpClient.send(requestBody, headers); // 然后再解析那一大坨 JSON

而使用 Spring AI 之后：

@Autowired private ChatClient chatClient; public String chat(String message) { return chatClient.call(message); }

差距非常明显。前者你需要自己搞 HTTP 通信、接口鉴权、参数封装、结果解析，而后者这些都帮你封装好了。而且后面你想切换不同的模型，不用改业务代码，只需要调整配置文件。

Spring AI 项目本身的理念也很 Spring —— 可移植性、可配置性、可扩展性。它的编程模型跟 Spring 生态的经典组件做到了一脉相承的思路。

2. 搭建开发环境与项目骨架

2.1 前置条件准备，缺一不可

在开始写代码之前，建议先把环境准备好。我踩过的坑基本都是环境问题引起的，所以这部分认真说一下。

你需要准备的基础环境如下：

• JDK 17 及以上版本
• Maven 3.9+ 或 Gradle
• 一个支持 Java 17 的 IDE
• 一个可以正常访问 AI 模型服务的 API Key

JDK 版本这里划个重点 —— Spring AI 官方建议用 17 以上的版本。我之前图省事用了手头现成的 JDK 11，结果编译直接报错，查了半天才发现是版本不匹配。如果你本地已经有 JDK 8 或 JDK 11，稳妥起见还是单独装一个 JDK 17，免得在环境问题上浪费时间。

另外提一下 Maven 和 Gradle 的选择，两个都行，看你平时的习惯。我个人习惯用 Maven，后面讲配置的时候也都基于 Maven 来讲，用 Gradle 的读者配置思路是一样的，把依赖声明方式对照着改一下即可。

2.2 初始化项目，两种方式任选

创建项目有两种方式。

第一种方式，使用 Spring Initializr 网站。打开 Spring Initializr，选择对应的构建工具（Maven 或 Gradle）、语言（Java）、Spring Boot 版本，然后在依赖列表里搜索并勾选 Spring AI。

第二种方式，直接在 IDE 里新建 Spring 项目，比如 IDEA 的 Spring Initializr 向导，操作基本一样。

不过我建议你自己手动创建一个工程，把 pom.xml 里的依赖直接配置进去。为什么这么建议？因为这样你能清楚地知道到底引入了哪些东西，尤其是 Spring AI 的依赖结构，看到依赖树之后心里会更有底。

一个最小化的 pom.xml 核心内容大致长这样：

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.4.1</version> <relativePath/> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-openai</artifactId> </dependency> </dependencies>

有几点细节值得注意。Spring AI 的版本号发布节奏很快，版本更新时不一定要选最前沿的正式版本，建议选择一个经过社区验证的稳定版，运行起来会更省心。另外 Spring AI 和相关组件都引入了模块化的管理，在 Spring Boot 3.x 的项目里，Boot 版本与 Spring AI 版本之间最好保持对应的搭配，避免出现不兼容的情况。

2.3 配置 application.yml 和 API Key

项目创建好之后，接着就是核心配置环节。在使用 OpenAI 的情况下，需要在 application.yml 里配置好模型服务的 key 和基础地址。

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

有些同学可能习惯把 key 直接硬编码在配置文件里，本地演示的时候确实方便，但任何时候都不建议在生产环境这么做。建议用环境变量的方式来注入，也就是我上面写法里的${OPENAI_API_KEY}，这样即使代码传到仓库里也不会把 key 泄露出去。

如果你使用的是国内的模型服务商或者开源模型的托管服务，只需要把 base-url 替换成对应的服务地址，同时调整一下 key 的获取方式，就好比你在用短信服务商时换一个平台地址一样，都是很常规的操作。后续讲到更多模型时再详细展开。

3. 完成第一个 AI 问答接口

3.1 使用 ChatClient 装配核心客户端

Spring AI 封装了多种编程风格，官方主推的是 ChatClient。可以把它理解为“面向 AI 模型的一个客户端”，类似 JDBC 帮你屏蔽了不同数据库的差异一样。

通过在配置类里注入相关 Bean，然后在 Service 层注入 ChatClient：

@Configuration public class AIConfig { @Bean public ChatClient chatClient(ChatClient.Builder builder) { return builder.build(); } }

如果你的需求比较简单，也可以直接在用到的地方直接注入 ChatClient.Builder 然后 build。Spring Boot 的自动配置会自动把可用的模型处理器装配进来，底层具体调的是哪家服务，从你当前的代码层面来看其实已经感知不到了。

使用它的核心方式非常直接，就是调用 call 方法：

@Service public class ChatService { private final ChatClient chatClient; public ChatService(ChatClient chatClient) { this.chatClient = chatClient; } public String chat(String message) { return chatClient.call(message); } }

3.2 设计一个简洁明快的 Controller 接口

有了 Service 之后，再把访问入口暴露出来，一个 HTTP 接口就完成了。

@RestController @RequestMapping("/api/chat") public class ChatController { private final ChatService chatService; public ChatController(ChatService chatService) { this.chatService = chatService; } @GetMapping("/message") public String chat(@RequestParam("msg") String message) { return chatService.chat(message); } }

到这里，你已经拥有一个能通过浏览器或 Postman 访问的对话接口了。在浏览器里输入：

http://localhost:8080/api/chat/message?msg=你好，介绍一下你自己

然后耐心等一下，返回的内容就是模型生成的回答结果。这个接口就是这么简单，从启动到跑通，理论上用不了多少行代码。

如果只想做极简验证，也可以直接在启动类里写一个 CommandLineRunner，在应用启动时立刻发一句测试，看控制台输出结果。这种方式适合先快速确认配置没有问题。

4. 深入 ChatClient 的核心 API 机制

4.1 call 方法的内部行为逻辑

把 call 方法当成黑盒直接来用，当然没问题。但如果你稍微深挖一层，理解它内部的流转流程，后面处理复杂问题时就不会两眼一抹黑。

整个调用过程大致可以拆解为几个环节。当你调用chatClient.call(message)时，框架会把消息对象封装成内部的标准消息结构，传给模型网关，由网关根据当前配置中的模型名称和模型类型找到对应的适配器，然后通过适配器向模型服务发起 HTTP 调用。模型服务返回结果后，框架解析出回答文本，最终通过响应对象返回给你。

这个过程中所有细节都被隐藏了，这也是框架本身最大的价值。如果你对这些细节感兴趣，可以在 debug 模式下运行时观察调用栈，会发现框架底层帮你处理了很多容易出错的环节。

4.2 用 prompt() 方法自定义消息上下文

单纯的 call 方法虽然简单，但实用性有限。更多时候你需要给模型设定角色、提供背景信息、传递上下文，甚至设置输出格式。这个时候就需要改用 prompt() 方式了。

public String chatWithContext(String userMessage) { return chatClient.prompt() .system("你现在是一名经验丰富的 Java 架构师，请用专业且简洁的语言回答问题。") .user(userMessage) .call() .content(); }

这里 system 方法设置的是系统提示词，相当于给模型做一个“角色设定”。user 方法传递用户输入。call 之后拿到的是一个 ChatResponse 对象，调用 content() 方法取出回答文本。

还有一个使用频率很高的场景是给 prompt 填充参数。比如你有一个模板化的提问需求，只需要把动态内容填进去：

String template = "请用一段话解释什么是{concept}，并给出一个实际应用场景。"; String content = chatClient.prompt() .user(u -> u.text(template).param("concept", "依赖注入")) .call() .content();

这种方式在处理重复性业务问答、批量生成报告、变体内容生成等场景时特别好用，可以让代码保持简洁，又能灵活适应不同的入参。

4.3 用流式响应改善用户等待体验

不知道你有没有遇到过这样的情况：请求发出去了，界面转圈圈转好几秒，结果突然一次性蹦出一大段文字。如果是内部工具倒还好，如果是面向用户的聊天产品，这体验说实话有点拉跨。

更好的方式是使用流式响应，也就是 streaming。模型每生成一个 token，就把它立刻推给前端，用户能感受到内容一个词一个词蹦出来，就像在跟真人聊天一样。

Spring AI 对流式输出提供了几个使用方式。简单场景下可以使用 stream 方法配合 Flux：

@Service public class StreamingChatService { private final ChatClient chatClient; public StreamingChatService(ChatClient chatClient) { this.chatClient = chatClient; } public Flux<String> streamChat(String message) { return chatClient.prompt().user(message).stream().content(); } }

Controller 侧对应改造一下返回类型：

@GetMapping(value = "/stream", produces = "text/event-stream") public Flux<String> streamChat(@RequestParam("msg") String message) { return streamingChatService.streamChat(message); }

注意这里使用了text/event-stream作为响应类型，这是标准的事件流格式。前端用 EventSource 或 fetch API 的流式读取就能直接接住这个数据源。

不过有一点需要提醒：流式输出的调试难度会明显比一次性返回要高一些，很多代理和网关默认会缓存响应，导致你在本地调试的时候收不到流式效果，所以如果没看到逐字输出的效果，先检查一下自己的网络链路是最自然的排查方向。

5. 为模型配置合适的参数与提示词

5.1 最核心的参数，temperature 和 model 怎么理解

配置里最常见的两个参数是 model 和 temperature。

model 参数很好理解，它告诉框架要调用哪个模型。单论 OpenAI 这边的模型，不同模型专精方向不一样，价格和响应速度差别也比较大。作为开发者，需要根据自己的业务场景选择成本与效果之间的平衡点。

temperature 参数是模型生成随机性的一个控制旋钮。它的取值范围通常在 0 到 1 之间。值越低，模型的输出越保守、越确定，适合代码生成、数据提取、分类处理等要求稳定的场景。值越高，模型的输出越有创造性，适合写文案、头脑风暴、创意生成这类需要灵活度的场景。

举几个实际例子感受一下。比如你要模型帮你写一段 SQL，或者做一份信息抽取，temperature 设成 0.2 左右比较稳妥。如果你想让它帮忙生成一段营销口号、写一个小红书风格的种草文案，temperature 调到 0.8 甚至更高，出来的文字会更加放飞。

5.2 在配置类里动态设置参数

参数除了写在 yml 里做全局配置，也支持在代码里按需覆盖：

public String creativeChat(String message) { return chatClient.prompt() .user(message) .options(OpenAiChatOptions.builder() .withModel("gpt-4o-mini") .withTemperature(0.9) .build()) .call() .content(); }

这样做的好处是同一个应用里可以根据不同业务场景切换不同模型配置。比如一个接口走精准回答模式，另一个接口走创意发散模式，两者互不影响。

这里要注意一下，新版 SDK 中 OpenAiChatOptions 的具体名称和 builder 风格可能会随版本变化，不同版本的 API 存在差异。我在文档里看到过新旧版本写法的切换提醒，所以如果你发现 withModel 方法在当前版本里报错，查一下对应版本的 release note 就能找到原因。

5.3 让系统提示词发挥应有的作用

系统提示词是决定模型输出质量和风格的重要组件，但也是最容易被新手忽略的。很多人一上来直接把用户问题扔给模型，然后抱怨结果不够理想，其实大概率是系统提示词没写好。

一个好的系统提示词应该具备这些特征：明确角色定位、说明任务目标、界定输出格式、针对错误情况做约束。举个具体例子，如果你希望模型帮你做信息抽检：

String systemPrompt = """ 你是一个信息提取助手。请从用户输入中提取出： 1. 日期（格式为 YYYY-MM-DD） 2. 金额（以元为单位） 3. 相关主体名称 如果找不到对应信息，请返回"未提取到"。 只输出 JSON 格式的结果，不要输出其他内容。 """;

在实际项目里，系统提示词通常会放在配置中心或单独的提示词管理模块里，方便运营人员或产品同学调整，同时也方便做版本管理。这也是有经验的团队和刚开始接触 AI 应用的团队在工程化程度上的一个常见差异。

6. 结合大模型开发中常见的扩展点

6.1 让模型输出结构化数据，不走 JSON 解析的老路

如果你只是简单地让模型返回文本，然后用正则去抠里面的信息，那你很快就会遇到问题 —— 模型的回答格式天然不稳定，偶尔多一个解释、少一个字段，你的解析代码就会出错。

Spring AI 提供了结构化输出的能力，你可以在调用时直接告诉模型你想要的返回类型，框架会负责把模型返回的内容转换成对应的对象。

public record StockInfo(String name, String code, double latestPrice) { } public StockInfo getStockInfo(String stockName) { return chatClient.prompt() .user("查询" + stockName + "的最新信息") .call() .entity(StockInfo.class); }

当你调用 entity 方法时，框架会要求模型按照适合转化为这个类型的方式来组织回答内容，然后再做解析。这样一来，输出的数据可以直接输入到业务代码里使用，省掉了面对文本时棘手的处理工作。

有一点需要说明：在实际使用中，模型返回内容的可解析性并不总是百分百保证。即使框架有人工干预能力，模型也可能偶尔输出一些不符合预期的内容，导致转换报错。所以生产环境里，强烈建议对转换结果做一次数据校验兜底，也就是设置用户提示与模型输出之间的约束，结合异常捕获和重试机制。

6.2 给对话注入记忆能力，让多轮问答保持连贯

默认情况下，每次 call 都是没记忆的独立请求。这就相当于你在跟一个初次见面的陌生人说话，你说一句，他答一句，但完全不记得你们刚才说过什么。

要让对话有记忆，就需要引入 ChatMemory。Spring AI 提供了内存版本的实现，适合单机小规模场景，同时也支持接入向量数据库来做大规模持久化。

@Configuration public class ChatMemoryConfig { @Bean public ChatMemory chatMemory() { return new InMemoryChatMemory(); } }

然后在构建 ChatClient 时指定：

@Bean public ChatClient chatClient(ChatClient.Builder builder, ChatMemory chatMemory) { return builder .defaultSystem("你是一个友好的 AI 助手") .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build()) .build(); }

使用这个模式后，后续的对话上下文就会自动带上之前的部分。需要注意的一个坑是：内存是有上限的，而且不带持久化，服务一重启历史对话就全部清空。所以当你发现对话时间长了之后，发出去的内容越来越长、费用越来越高，就要考虑对话窗口管理策略，比如接向量数据库做历史记录归档，或者只装配最近几轮对话。

6.3 Output Content 的自定义与内容安全

使用框架时还需要注意内容输出侧的合规控制。Spring AI 允许我们通过配置来对输出进行过滤和审核，比如对包含敏感信息的响应进行屏蔽。这是面向真实用户的产品上线时必经的一环，不要等到上线被反馈了才想起来处理。

一个简单的过滤实现示例：

public class SafeWordFilter implements ContentFilter { private final List<String> blacklist = List.of("违禁词1", "违禁词2"); @Override public String filter(String content) { for (String word : blacklist) { if (content.contains(word)) { return "抱歉，无法回答该问题。"; } } return content; } }

从更广义的角度来说，AIGC 应用的安全是个系统工程，需要在提示词约束、输入过滤、输出审核多个层面做防御。作为开发者，这个意识从第一个应用上线前就要建立起来。

7. 实际落地运行与常见问题排查实录

7.1 完整跑通一次推理过程

从创建项目到最后的实际操作，建议按这个顺序走一遍：

1. 创建 Spring Boot 3.x 项目
2. 在 pom.xml 中加入 Spring AI 依赖
3. 在 application.yml 中写入模型供应商配置和 API Key
4. 启动应用，观察控制台日志
5. 编写一个最简单的测试接口，验证连通性

我第一次跑通的时候其实卡在了依赖版本上，花了十几分钟才意识到是 Spring AI 版本不兼容。后来学聪明了，统一到官方文档对应的版本组合上再动手，这样最省时间。

7.2 高频踩坑点整理，按优先级排列

这里总结一些我实际开发中遇到过的问题和解决办法。

问题一：配置文件不生效

症状表现是服务能启动，但调用时报出模型相关错误。排查思路：优先检查 spring.ai 的配置前缀路径是否正确，版本较低时配置项路径经历过调整，很可能你已经配了但框架压根没读到。解决办法：在配置类中临时加一个日志输出，确认配置属性是否被正确加载。

问题二：API Key 无效或过期

异常信息通常会直接提示鉴权失败。排查方式：先手工调一下模型服务商提供的测试接口，确认 key 本身可用，再确认 base-url 是否正确。常见的低级错误包括 key 前后带了空格、环境变量没生效。

问题三：请求超时

企业网络环境下比较常见。默认的 HTTP 客户端超时时间可能太短，大模型推理本身又比较慢。解决办法：给 RestClient 配置或底层 HTTP 客户端设置更长的连接和读取超时时间。

问题四：返回内容被截断

这一般和 maxTokens 参数有关。这个参数控制模型最多生成的 token 数量，如果设置过小，长回答就会被截断。适当调大即可。注意这个值同时影响响应速度和成本。

问题五：中文乱码或 Unsupported Media Type

排查一下 Content-Type 的编码设置，以及是否引入了正确的消息转换器。Spring Boot 默认配置一般没问题，但如果你手动改了消息转换链，就容易出这种问题。

7.3 对比一次调用与流式调用的表现差异

为了更直观地感受两种方式的区别，我做了一组简单对比。同样的提问、同样的模型、同样的 temperature，不同调用方式在客户端观察到的体验差异明显：

个人建议：面向用户交互的界面优先考虑流式实现，后端内部逻辑用一次调用即可。至于是用 WebFlux 还是 SSE，取决于你的整体技术栈，不要为了流式而流式。

7.4 ChatClient 还支持哪些实用 API

ChatClient 除了基础的 call、stream、prompt，还有几个实用操作值得关注。

比如你可以为它设置默认消息顾问或默认系统提示词，这样在构建 Client 的时候就把统一规范定好，不用每次调用都重复写：

@Bean public ChatClient chatClient(ChatClient.Builder builder) { return builder .defaultSystem("你是一个乐于助人的助手") .defaultAdvisors(new SimpleLoggerAdvisor()) .build(); }

另外在流式的调用中，可以使用stream().response()获取包含更多元数据的响应对象，而不只是纯文本。这在做调用链追踪和计费统计的时候比较好用。

还能通过.entity()方法配合 Java Record 或自定义 POJO 实现强类型数据映射，前面已经提到过。建议把这几个 API 组合起来用，能覆盖绝大多数业务需求。

8. 从入门到进阶，还有哪些方向值得探索

首篇教程做的是最基础的对话链路。当你把这套流程跑通之后，后续可以沿着如下几个方向继续深入：

第一个方向是接入更多的模型服务商。Spring AI 的抽象层已经让切换成本大幅降低，你可以把多家模型供应商都配置好，然后做模型路由，根据不同的任务类型选择不同性价比的模型。比如一个应用里，简单情感分析走快而省的小模型，复杂逻辑推理走能力强的大模型，配合路由策略能省不少钱。

第二个方向是结合向量数据库做私有知识库问答。这是目前企业落地最广的场景之一。简单说说思路：把企业文档切块、向量化后存入向量数据库，用户提问时先做相似度检索，再把检索结果连同问题一起发给大模型，让它基于这些资料进行回答。这也就是 RAG 的基本过程。Spring AI 在这个方向也有对应的组件支持。

第三个方向是把 AI 能力接入更复杂的业务流程。比如让模型自主决定调用哪些工具，这就是 Function Calling 或者说 Tool Calling。你把自己的业务方法注册为 AI 可调用的工具，让模型根据用户的意图自主选择并调用这些工具，再把得到的结果组织成自然语言回复。这对企业内部的信息整合、任务自动化非常有价值。

第四个方向是关注工程化治理。AI 应用上线后的可观测性、提示词的版本管理、调用链追踪、成本监控、模型评估等，这些在 demo 阶段不会被注意到，但进入生产环境后每一个都足以让团队头疼。Spring AI 提供了部分可观测性接口，也可以接入主流日志平台来完善。

最后再聊一点我在实践中的体会

教程到了这里，核心的入门内容已经完整覆盖了。从配置项目到跑通对话接口，从理解内部运行逻辑到处理常见报错，已经能够支撑你完成一个具备基本功能的应用。最后想分享一点个人的经验：刚开始接触 Spring AI 的时候，不建议一上来就追着新特性跑，先把最基础的能力吃透，特别是 ChatClient 的 API 风格和配置原理，后面碰到任何问题都能顺着链路去排查。

实际开发中我自己的体会是，Spring AI 最大的魅力不是帮你省几行代码，而是给了 Java 生态一个拥抱 AI 的标准方式。过去 Java 在 AI 应用开发领域相对于 Python 生态存在感弱一些，大部分人的第一反应是 Python + FastAPI + LangChain。Spring AI 的成熟让后端团队可以直接在原有的 Spring Cloud、微服务架构里平滑地融入 AI 能力，不需要额外搭建一套新的服务架构，这对大量存量系统来说价值非常高。

如果你正准备在现有项目里接入 AI 能力，我的建议是：先不要急着把模型接入核心链路，可以先搭一个独立的小模块，把这篇教程的示例跑通，然后逐步探索多轮对话、流式输出、结构化输出这些基础能力，等技术积累到一定程度再考虑大规模引入。知识库问答和工具调用这些进阶玩法，等基础打得足够牢之后再慢慢推进也不迟。

后续我还会继续分享更多实战内容，希望能对你的项目落地带来切实的帮助。