SpringAI 实战：从手写调用到框架化 AI 应用开发

1. 从一次版本升级踩坑说起SpringAI 到底解决了什么问题去年冬天我接手了一个企业内部知识库问答系统的重构任务。当时的方案是用原生 HTTP 客户端直接调大模型接口自己拼 JSON、自己处理流式返回、自己写重试逻辑。代码写了不到两千行维护成本却高得离谱——换个模型供应商几乎要重写整个调用层。后来团队决定迁移到 SpringAI我才真正体会到“框架”两个字的价值。SpringAI 是 Spring 生态里专门面向 AI 应用开发的框架它的定位有点像当年 Spring Boot 对传统 Java Web 的改造把模型调用、提示词模板、向量检索、工具调用这些重复性极高的工作抽象成统一的 API让开发者把精力放在业务逻辑上而不是浪费在适配不同厂商的接口差异上。这篇文章适合已经有一定 Java 和 Spring 基础、正在考虑或刚刚开始用 SpringAI 做项目的同学也适合那些还在观望、想知道它到底比手写调用强在哪里的开发者。我打算从整体设计思路、核心升级点、实战落地过程、常见问题排查四个维度把这段时间积累的经验完整地梳理一遍。里面既有官方文档里不会写的踩坑记录也有我反复调试后总结出来的参数配置心得。读完之后你应该能独立搭起一个可用的 SpringAI 工程并且知道遇到问题该往哪个方向查。2. 整体设计思路与方案选型为什么是 SpringAI 而不是手写调用2.1 手写模型调用的三个致命痛点在迁移之前我们的老系统有三个绕不过去的问题。第一个是接口适配成本高。不同厂商的请求体结构、鉴权方式、流式返回格式都不一样每接一家就要写一套适配代码测试用例也要重写。第二个是流式输出处理复杂。大模型的流式返回是基于 SSE 的手动解析事件流、处理粘包、管理连接生命周期稍不注意就会出现内容截断或者连接泄漏。第三个是提示词管理混乱。提示词散落在各个 Service 类里改一个措辞要翻好几个文件版本追溯基本靠 Git 提交记录。SpringAI 的设计思路正好对应这三个痛点。它用统一的ChatModel接口屏蔽了底层厂商差异用ChatClient的流式 API 把 SSE 处理封装成FluxString用PromptTemplate把提示词外置成模板文件。这套抽象不是简单的包装而是真正站在应用开发者的角度重新组织了调用链路。2.2 核心抽象层的设计哲学SpringAI 最核心的抽象是ChatModel和ChatClient两层。ChatModel是底层接口负责实际的模型通信不同厂商有不同的实现类。ChatClient是上层门面提供流式、同步、结构化输出等便捷方法。这种分层的好处是业务代码只依赖ChatClient切换模型时只需要换掉依赖实现业务逻辑一行不用改。我特别喜欢它对结构化输出的处理。以前让模型返回 JSON经常遇到格式不对、字段缺失的问题要写一堆容错代码。SpringAI 提供了BeanOutputConverter可以把模型返回的文本直接映射成 Java 对象配合提示词里的格式说明成功率能到九成以上。这个设计背后其实是对提示词工程的封装——框架帮你把“请以 JSON 格式返回”这类指令自动拼进提示词里。2.3 版本选型与依赖管理策略SpringAI 的版本迭代比较快选版本的时候要注意和 Spring Boot 版本的对应关系。我目前用的是 Spring Boot 3.2.x 搭配 SpringAI 1.0.0-M 系列这个组合相对稳定。如果你还在用 Spring Boot 2.x那基本可以放弃 SpringAI 了因为它强依赖 JDK 17 和 Spring Framework 6。依赖管理上我建议用 BOM 的方式引入避免版本冲突dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0-M4/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement然后按需引入具体模块比如spring-ai-openai-spring-boot-starter或者spring-ai-ollama-spring-boot-starter。这里有个坑不同 starter 之间可能有传递依赖冲突特别是涉及到 WebFlux 和 WebMVC 的时候建议在引入前先跑一遍mvn dependency:tree看看。提示如果你只是做本地测试用 Ollama 跑一个轻量模型就够了不需要申请外部 API Key调试起来也更快。3. 核心升级点深度拆解从对话到工具调用的能力跃迁3.1 ChatClient 流式输出的实现细节流式输出是对话类应用体验的关键。用户等三秒看到完整回答和逐字看到回答感受完全不同。SpringAI 的流式 API 用起来很简单GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString streamChat(RequestParam String message) { return chatClient.prompt() .user(message) .stream() .content(); }但简单背后有几个细节要注意。第一produces必须指定为TEXT_EVENT_STREAM_VALUE否则浏览器不会按 SSE 处理。第二返回的Flux要确保在请求线程外订阅避免阻塞。第三如果中间经过了网关或反向代理要检查它们是否支持 SSE 长连接有些默认配置会缓冲响应导致流式失效。我实测下来流式输出的首字延迟主要取决于模型本身框架层的开销可以忽略不计。但如果你的应用同时处理多个流式请求要注意线程池配置WebFlux 默认的事件循环线程数可能不够用。3.2 提示词模板与参数化设计把提示词硬编码在 Java 代码里是维护噩梦。SpringAI 的PromptTemplate支持从资源文件加载模板用占位符传参Value(classpath:/prompts/system.st) private Resource systemPrompt; PromptTemplate template new PromptTemplate(systemPrompt); Prompt prompt template.create(Map.of(role, 技术支持, context, contextText));模板文件里可以这样写你是一个{role}助手。请根据以下背景信息回答用户问题 {context} 如果背景信息中没有相关内容请如实告知用户你不知道。这里的关键是系统提示词和用户提示词要分开管理。系统提示词定义角色和行为边界用户提示词传递具体问题。我见过有人把两者混在一起结果模型经常忽略角色设定。另外模板里的占位符命名要有意义别用{0}{1}这种后期根本看不懂。3.3 Tool Calling让模型学会调用你的方法Tool注解是 SpringAI 比较有特色的功能它允许你把 Java 方法暴露给模型调用。比如你有一个查询天气的方法加上注解后模型在需要时会自动触发调用Component public class WeatherService { Tool(name getWeather, description 查询指定城市的当前天气) public String getWeather(ToolParam(description 城市名称) String city) { // 实际查询逻辑 return city 今天晴气温25度; } }name属性是模型识别工具的标识description是模型判断何时调用的依据。这两个字段写得好不好直接决定工具调用的准确率。我的经验是description要写得像给新人解释一样清楚把使用场景和参数含义都说明白。比如“查询指定城市的当前天气”就比“天气查询”要好因为前者明确了输入是什么。工具调用的执行流程是模型返回一个工具调用请求框架解析后执行对应方法再把结果回传给模型模型据此生成最终回答。这个过程对开发者是透明的但调试时可以通过日志观察每一步的输入输出。3.4 结构化输出与类型安全让模型返回结构化数据是很多业务场景的刚需。SpringAI 的BeanOutputConverter可以配合ChatClient直接返回对象record BookInfo(String title, String author, int year) {} BookInfo info chatClient.prompt() .user(请介绍《三体》这本书) .call() .entity(BookInfo.class);框架会自动在提示词里追加格式说明并把返回文本解析成对象。但这里有个坑如果模型返回的 JSON 里有额外字段或者格式偏差解析会失败。我的做法是在提示词里明确给出字段列表和示例并且给BeanOutputConverter配置一个宽松的ObjectMapper忽略未知字段。注意结构化输出的成功率跟模型能力关系很大。小参数模型经常漏字段或者多加解释性文字建议用能力较强的模型来做这类任务。4. 实战落地从零搭建一个可用的对话机器人4.1 工程初始化与依赖配置新建一个 Spring Boot 3.2 项目JDK 选 17 或更高。核心依赖包括spring-boot-starter-webflux流式输出需要、spring-ai-openai-spring-boot-starter或对应厂商的 starter。配置文件里至少要配三项spring: ai: openai: api-key: ${AI_API_KEY} base-url: https://api.example.com chat: options: model: gpt-4o-mini temperature: 0.7temperature控制输出的随机性对话场景建议 0.7 左右需要确定性回答时调到 0.2 以下。base-url如果用的是兼容接口要确认路径拼接规则有些厂商需要带/v1有些不需要。4.2 对话机器人的核心代码实现先定义一个ChatController提供同步和流式两个接口RestController RequestMapping(/api/chat) public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient builder .defaultSystem(你是一个乐于助人的助手回答要简洁准确。) .build(); } PostMapping(/sync) public String sync(RequestBody ChatRequest request) { return chatClient.prompt() .user(request.message()) .call() .content(); } PostMapping(value /stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString stream(RequestBody ChatRequest request) { return chatClient.prompt() .user(request.message()) .stream() .content(); } }ChatClient.Builder是框架自动注入的defaultSystem设置全局系统提示词。如果不同接口需要不同的角色设定可以在每次调用时用.system()覆盖。4.3 多轮对话的上下文管理大模型本身是无状态的多轮对话需要把历史消息一起传进去。SpringAI 提供了ChatMemory接口最简单的实现是InMemoryChatMemoryChatMemory memory new InMemoryChatMemory(); ChatClient client builder .defaultAdvisors(new MessageChatMemoryAdvisor(memory)) .build();这样每次调用会自动带上历史消息。但要注意内存实现只适合单机测试生产环境要换成基于 Redis 或数据库的实现。另外历史消息不能无限增长否则会超出模型的上下文窗口。我的做法是保留最近十轮对话更早的做摘要压缩。4.4 前端联调与流式渲染前端用EventSource接收流式数据const source new EventSource(/api/chat/stream?message encodeURIComponent(msg)); source.onmessage (event) { document.getElementById(output).textContent event.data; }; source.onerror () source.close();这里有个细节SpringAI 返回的流式内容默认是纯文本不是 JSON。如果前端需要区分内容块和结束标记可以在后端做一层包装把每个 chunk 包成 JSON 对象再发送。提示调试流式接口时用 curl 加-N参数可以禁用缓冲直接看到逐字输出效果。5. 常见问题与排查技巧实录5.1 模型调用超时与重试策略超时是最常见的问题。默认超时时间可能只有几秒长回答很容易触发。可以在配置文件里调整spring: ai: openai: chat: options: timeout: 60s但光调超时不够还要考虑重试。SpringAI 本身没有内置重试机制我一般用 Spring Retry 包一层Retryable(maxAttempts 3, backoff Backoff(delay 1000)) public String callWithRetry(String message) { return chatClient.prompt().user(message).call().content(); }重试要注意幂等性查询类操作可以重试涉及写操作的场景要谨慎。5.2 流式输出中断的排查思路流式输出中途断掉原因通常有三类网络层缓冲、线程池耗尽、模型侧限流。排查顺序建议从外到内先用 curl 直连后端确认是不是网关问题再看应用日志有没有异常堆栈最后检查模型服务商的限流策略。我遇到过一次是 Nginx 的proxy_buffering没关导致所有流式响应被攒成一个大包才返回关掉之后立刻正常。5.3 工具调用不触发的调试方法Tool注解的方法没有被调用先检查三件事description是否足够清晰、方法参数是否有ToolParam注解、工具类是否被 Spring 扫描到。如果都没问题可以打开框架的调试日志看看模型返回的原始响应里有没有工具调用请求。有时候是模型能力不够换个更强的模型就好了。问题现象可能原因排查方向流式输出一次性返回网关缓冲检查 Nginx 或网关配置工具调用不触发description 不清晰优化描述换更强模型结构化输出解析失败模型返回格式偏差提示词加示例配置宽松 ObjectMapper多轮对话丢失上下文ChatMemory 未配置检查 Advisor 是否注册调用超时默认超时太短调整 timeout 配置并加重试5.4 生产环境部署的注意事项生产环境有几个点必须注意。第一API Key 不能硬编码在配置文件里要用环境变量或配置中心。第二要加限流防止单个用户刷爆额度。第三日志里不能打印完整的请求和响应可能包含敏感信息。第四建议加一层缓存相同问题短时间内重复提问可以直接返回缓存结果既省钱又快。我在实际项目里还加了一个降级策略当模型服务不可用时返回预设的兜底话术而不是直接报错。这个体验上的差别很大用户不会因为一次服务波动就流失。6. 我踩过的坑和几条实用建议第一个坑是版本兼容性。SpringAI 的里程碑版本之间 API 变动比较大升级前一定要看 Release Notes。我有一次从 M1 升到 M3ChatClient的构建方式完全变了改了半天。第二个坑是流式接口的异常处理。Flux里抛出的异常不会走普通的ExceptionHandler需要用onErrorResume单独处理否则前端会一直转圈。第三个坑是提示词注入。用户输入如果直接拼进系统提示词可能被恶意引导。我的做法是把用户输入放在独立的 user 消息里系统提示词只定义角色和边界不拼接用户内容。最后分享一个小技巧调试提示词的时候把最终发给模型的完整提示词打印出来看一遍经常能发现占位符没替换或者格式错乱的问题。这个习惯帮我省了很多排查时间。这套东西后续还可以往 RAG 方向扩展把向量检索和对话结合起来做企业知识库问答。那块内容比较多等我把检索精度调优的经验整理好了再单独写一篇。