2024年Java圈子聊AI绕不开Spring AI这个名字。它出现的时间点其实很妙——大模型API越来越标准化但Java后端接入的方式依然是一团散沙要么自己写HTTP客户端硬调OpenAI、通义这些服务要么参考LangChain的思路在Java里东拼西凑一套轮子。Spring AI一出来直接把ChatClient、Prompt模板、结构化输出、函数调用、向量检索这些能力按Spring Boot的惯用风格封装成了一套标准化组件接入大模型的体验和写一个普通Rest接口差不多了。这篇文章从实际项目落地的视角出发把Spring AI的核心概念、最小可用配置、常用高阶功能以及我在生产环境里踩过的坑都过一遍。无论你是刚听说这个名字还是已经在项目里用了一两个版本应该都能从中建立一张相对完整的Java侧AI开发知识地图。1. 先搞清楚Spring AI到底解决了什么问题1.1 它不是大模型而是“Java与大模型之间的JDBC”很多初看Spring AI的人最容易搞混的一点就是框架本身并不包含任何大模型它更像Spring体系里的JDBC抽象层。JDBC把MySQL、Oracle、PostgreSQL的差异屏蔽在Driver背后让应用层用同一种Connection和SQL方言去操作数据库Spring AI则把OpenAI、通义千问、Ollama、Azure OpenAI这些不同服务的协议差异藏到了ChatModel、EmbeddingModel这些统一接口背后。这套抽象的价值在项目真正接入多家模型时才会体现。你只需要在配置文件里切换base-url、api-key、model三个参数业务代码里的ChatClient调用基本不用动。我见过不少团队前期贪方便直接用第三方SDK或手写Feign调模型后面想从A家切到B家业务代码里全是Authorization头和响应体解析逻辑改起来非常痛。Spring AI这个统一模型出口的价值和当年大家从直接写JDBC细节转向JdbcTemplate是一个道理。1.2 一条主线请求链路贯穿全部功能Spring AI的设计里有一条极其清晰的主线理解它就能读懂80%的框架用法Message组装成Prompt交给ChatModel执行得到ChatResponse再被封装成人话版AiResponse。所有复杂功能——函数调用、多模态、结构化输出、Agent——本质都是在这条链路上做拦截或增强。比如函数调用是在ChatModel执行前把本地Java方法注册成工具清单一起塞进请求结构化输出是在模型返回后对文本做类型转换聊天记忆是在组装Prompt之前把历史会话窗口拼接进去。只要主线通往上叠功能就不乱。这是Spring AI和LangChain最大的区别LangChain给了你一堆可组合的链式工具Spring AI则把所有东西都收编进了Spring容器用Bean、Starter、AutoConfiguration这套体系管理Java开发者几乎没有认知负担。1.3 2024年的Spring AI处于什么阶段2024年是Spring AI从孵化走向成熟的关键一年。官方在年初发布了1.0 M1随后每隔几个月迭代一个M系列自动配置能力越来越强第三方集成也逐步归拢。到2024年底社区讨论已经从“要不要用”变成了“怎么用好”spring-ai-alibaba等项目也补齐了国内模型链路的短板加上阿里云百炼平台不断放出新模型Java侧做AI应用的工具链在2024年底基本成型。对技术人员来说这个阶段恰恰是最好的学习窗口API还未被大量历史包袱拖累官方文档和示例都比较干净社区里能搜到的坑也多是新鲜出炉的实战经验而不是十年前的远古FAQ。2. 5分钟跑通第一个ChatClient2.1 依赖引入与最小配置用Spring Boot 3.x新建项目后引入Spring AI最直接的方式是加官方Starter。以3.2.x项目为例Maven里加两段就行dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0-M6/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency这里有个细节值得注意Spring AI的依赖必须走BOM统一管理版本。我见过有人在网上抄示例直接写version结果和Spring Boot版本、模块内部版本撞车启动时一堆类加载冲突。用BOM是省心最稳的办法。配置文件里只需要调三个关键项spring.ai.openai.api-key${AI_API_KEY} spring.ai.openai.chat.base-url${AI_BASE_URL} spring.ai.openai.chat.options.modelqwen-plus如果只是本地体验base-url可以指向Ollama的http://localhost:11434/v1如果接国内云厂商的模型服务就填对应的兼容地址。总而言之只要目标服务提供OpenAI兼容协议Spring AI的标准Starter基本都能直接吃下。2.2 第一段能聊天的代码配置好后打开一个Controller注入ChatClient就可以开始对话了RestController RequestMapping(/ai) public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient builder.build(); } GetMapping(/hello) public String hello(String input) { return chatClient.prompt(input) .call() .content(); } }这里ChatClient不是简单的HTTP Client而是Spring AI面向开发者提供的门面。它内置了Prompt构建、消息组装、ChatModel调用、响应后处理等一条龙逻辑。你每次调用prompt()其实是在背后构建一个Prompt对象并交给ChatModel执行只是框架把细节藏好了。如果你需要流式对话把.call()换成.stream()返回值就从ChatResponse变成了FluxString对接SSE输出很方便GetMapping(value /stream, produces text/event-stream) public FluxString stream(String input) { return chatClient.prompt(input) .stream() .content(); }2.3 入口对象选型ChatClient优先于ChatModelSpring AI同时暴露了ChatModel和ChatClient两层入口。有人觉得ChatModel更底层、更灵活就直接到处注ChatModel其实在新版本官方推荐的是ChatClient。原因很简单ChatClient内部封装了与模型协商格式、构建系统Prompt、处理响应映射的细节而ChatModel要求你自己拼Prompt和解析返回值。举个直观例子用ChatModel拿到ChatResponse后你需要自己从response.getResult().getOutput().getText()这串链条里取值用ChatClient一行.content()直接拿字符串。到了结构化输出、函数调用这些进阶场景ChatModel手写代码的复杂度更是几何级上升ChatClient则提供了.entity()这类现成方法。因此新手和大多数业务场景直接认准ChatClient就好ChatModel留作框架扩展或深度定制时再用。3. 核心功能拆解从结构化输出到函数调用3.1 结构化输出让AI返回Java对象而不是一坨文本做AI业务最痛苦的一件事就是解析模型返回的自由文本。以前大家写正则写JSON修复逻辑遇到格式稍微偏移就崩。Spring AI内置的结构化输出能力把这一步简化成了类型转换。假设你要让模型从一句自然语言里抽出一部电影的信息public record Movie(String title, String director, ListString actors) {}调用方式极其直观Movie movie chatClient.prompt(请解析这句话卧虎藏龙是由李安导演、周润发和杨紫琼主演的电影。) .call() .entity(Movie.class);拿到手的Movie就直接是正确填充的Java记录。Spring AI底层会在请求里附加一套严格的JSON Schema指令提醒模型必须输出对应结构的JSON文本再在应答阶段把JSON反序列化成目标类型。实际操作中建议把所有要返回的模型写成只含字段的record或POJO字段命名尽量和被训练的常见语义保持一致否则模型容易把字段名改掉。另外一个高频踩坑点是嵌套泛型比如MapString, ListProcessedItem直接用entity()会遇上类型擦除导致反序列化困难。我的替代方案是定义一层薄薄的包装recordpublic record ResultWrapper(ListProcessedItem items) {}这层包装多写一行却能省掉大把JsonTypeInfo调试时间。3.2 提示词模板像封装SQL一样封装Prompt工程化项目里提示词会频繁变化同时里面常带着用户参数、上下文数据。如果全靠字符串拼接满屏的加号和占位符会让代码很快烂掉。Spring AI提供了PromptTemplate思路和JdbcTemplate的参数绑定很像。String input 帮我写一段Python实现快速排序的代码; MapString, Object params Map.of(task, input); PromptTemplate template new PromptTemplate(你是资深程序员请针对任务完成编码{task}, params); Prompt prompt template.create(); String answer chatClient.prompt(prompt).call().content();模板里的大括号占位符会自动被参数替换。更关键的是你可以把不同业务场景的提示词放进src/main/resources/prompts目录用Resource方式加载Value(classpath:/prompts/code-review.st) private Resource systemPromptTemplate; public String reviewCode(String code) { PromptTemplate template new PromptTemplate(systemPromptTemplate); return chatClient.prompt(template.create(Map.of(code, code))).call().content(); }把提示词和代码分离是让AI功能进入可维护状态的入门动作。团队里的同学可以不用改Java代码只调整模板文件就能优化效果这在工作流里非常实用。3.3 函数调用让模型通过Java方法补齐实时数据大模型不知道你系统里的订单状态也不可能实时了解“当前时间”和“库存数量”这类动态信息必须靠函数调用让模型反向询问应用。Spring AI的函数调用抽象在2024年的版本里做得很顺滑。最省事的做法是直接注册一个Function接口的BeanBean public FunctionGetWeatherRequest, GetWeatherResponse currentWeather() { return request - weatherService.query(request.city(), request.date()); }然后在调用时声明这个工具String answer chatClient.prompt(北京明天天气怎么样适合跑步吗) .functions(currentWeather) .call() .content();背后发生的事情是Spring AI在构建请求时把currentWeather的工具描述、入参JSON Schema一并发给模型模型判断需要天气数据后在响应里带上一个函数调用指令框架拦截后执行Bean方法再把结果作为工具消息回传给模型继续生成最终答案。函数调用是Agent在单次对话层面的基座能力但有一个安全边界必须守住轻易不要把一个能删库、能改配置的方法直接暴露给模型。模型的能力只是做选择恶意输入依旧可能把它诱导到危险的函数上。稳妥做法是在函数入口做参数白名单校验、增加确认机制只开放只读或幂等的查询接口。3.4 多模态输入从纯文本到图文理解Spring AI在2024年的版本里把多模态支持做成了消息内容的一部分。ChatClient的message方法不再只接受字符串而是可以接受多个对象。一段带图片理解的调用大概是var response chatClient.prompt() .user(u - u .text(这张照片显示的是哪个城市的地标) .media(MimeTypeUtils.IMAGE_PNG, new URL(https://example.com/photo.png))) .call() .chatResponse();框架会把图片转成模型所需的格式比如OpenAI风格的image_url内容块。如果对接的多模态模型不支持某类输入配置阶段就会收到明确的错误。做知识库时我喜欢拿它处理截图类文档效果比纯OCR拼文本进Prompt好不少尤其遇到图表、流程图时模型能直接“看”全貌。4. 进阶玩法记忆、检索增强与Agent编排4.1 会话记忆别把聊天记录死磕在Session里无状态调用是很多大模型接口的默认形态但业务上一个优秀客服机器人显然需要能记住上下文。Spring AI提供的ChatMemory接口正是干这个的与ChatClient联动时几乎零成本ChatMemory chatMemory MessageWindowChatMemory.builder() .maxMessages(20) .build(); ChatClient chatClient ChatClient.builder(chatModel) .defaultChatMemory(chatMemory) .build();之后每次调用ChatClient会自动从ChatMemory读取历史消息拼进新一轮Prompt再在新响应结束后把最新消息写回去。这里需要留神的是Token窗口。maxMessages控制的是消息条数不是Token数量。DeepSeek、通义这些模型的上下文窗口虽然动辄几十万但消息条数过多仍会挤占有效输出空间。我习惯同时估算历史消息的Token总量大致控制在上下文窗口的三分之一以内给系统Prompt、工具定义和用户最新输入留足余量。条件允许的话还可以把ChatMemory换成基于Redis的实现让多实例共享会话状态否则负载均衡一开每个实例各存各的上下文就乱了。4.2 RAG检索增强给大模型接上企业私有知识库2024年几乎每个AI应用都在聊RAGSpring AI对这块的封装同样沿用了Boot风格一个EmbeddingModel负责文本向量化一个VectorStore负责存储和相似度检索查询端通过Query对象把搜索结果塞进Prompt。一个典型流程是String question 新员工的报销流程是什么; // 向量化用户问题 float[] queryVector embeddingModel.embed(question); // 从向量库检索TopK相关内容 ListDocument documents vectorStore.similaritySearch( SearchRequest.builder(queryVector) .withTopK(3) .build()); // 将检索内容注入Prompt再交给大模型 String context documents.stream() .map(Document::getText) .collect(Collectors.joining(\n\n)); String answer chatClient.prompt() .system(基于检索资料回答资料中无答案时明确说明不知道。) .user(【资料】\n context \n\n【问题】\n question) .call() .content();向量库选型上生产环境我优先考虑PgVector和Milvus。PgVector胜在少引入一套中间件与现有事务库共用Milvus适合文档量过千万级、对查询延迟有苛刻要求的场景。Spring AI对这些都有现成Starter切换成本基本就是改依赖和连接配置。RAG真正的难点倒不在框架而在文档拆分的粒度与清洗质量。直接丢PDF全文进向量库检索时拿到的往往是碎片模型给出的答案自然支离破碎。我在实践中对文本块设了五六百字左右的合理阈值并保留标题层级前缀让每个被检出的文本块自带上下文语境效果比追求高精度嵌入模型明显得多。4.3 Agent编排从可视化工作流到Java代码Agent在2024年的定义早已不是“聊天机器人”那么单薄而是“模型根据目标自行决定调用哪些工具、按什么顺序执行”。Spring AI把这一层能力建立在函数调用之上模型在做完一次推理后如果发现需要外部信息就会发起函数调用请求框架把结果填回去模型再次推理直到不再需要工具为止。这其实就是“ReAct循环”的具象化。写起来比想象中简单String answer chatClient.prompt(查一下订单20241202001的物流状态如果已签收就感谢用户购买) .functions(queryOrderStatus, sendThankMessage) .call() .content();模型自动判断调用哪个函数、传什么参数甚至还能决定要不要两连招。如果你们团队之前用的是Dify这类可视化工作流其实完全可以把流程迁移成Spring AI代码。Dify里的“开始节点、大模型节点、条件分支、工具节点”在Spring中分别对应Controller入口、ChatClient调用、if/switch业务判断、FunctionBean。迁移思路很直白把每个可视化节点落成Java对象方法再把连线关系翻译成代码里的调用顺序。社区里也有人专门做这类转换项目能在天级别把中型工作流迁成可测试、可版本管理的Java工程。用代码编排工作流的好处是一切变更都进Git可以写单测可以被标准CI/CD流程覆盖这是可视化拖拽难以替代的工程优势。5. 多模型适配与生产级定制5.1 自己写一个定制引擎逻辑ChatClient虽好用但某些场景需要你控制更底层的行为比如统一给所有请求加审计日志、统计Token消耗、微调重试策略。方案是不要再用ChatClient.builder(chatModel).build()一把梭而是在Builder上叠加定制ChatClient chatClient ChatClient.builder(chatModel) .defaultSystem(你是一个严谨的技术助手) .defaultAdvisors(new SimpleLoggerAdvisor()) .defaultOptions( OpenAiChatOptions.builder().temperature(0.3).build()) .build();Advisor是Spring AI很有价值的一个扩展点。它类似WebMVC里的拦截器能包在每次模型请求的前后做横切逻辑。比如你可以在Advisor里统计耗时、缓存相同问题的结果、对敏感词做前置过滤。我见过有人专门写了一个AuditAdvisor把每次调用的输入输出和Token开销落库对管理层审计和成本月结都很有帮助。5.2 Spring AI Alibaba 与多模型生态国内接大模型时直连OpenAI不一定通畅这时候spring-ai-alibaba的价值就体现出来了。基于它接入阿里云百炼平台上的通义千问系列模型几乎是一行依赖的事。百炼的OpenAI兼容地址与通义模型在中文任务上表现扎实加上国内链路顺畅很多生产项目2024年都是用它完成Java侧的AI改造。经常有人问spring-ai-alibaba是不是停更了。这个问题要分两层看Spring AI官方主线一直在迭代而像Alibaba这样的社区衍生项目更新节奏往往取决于其自身版本阶段与主干同步情况。判断项目是否值得用打开GitHub看最近提交和Issues比听传言靠谱得多。Spring AI本身开放了ChatModel扩展接口理论上任何模型服务商都能写出适配器无非是协议转换和options映射的工程量问题。所以就算某个第三方集成的Master分支暂时没动静也不用慌可以自己在项目里写一个适配ChatModel的薄实现成本可控。5.3 用统一出口管理模型切换与降级无论接几家模型我都强烈建议在业务和ChatClient之间再包一层门面Service。别让Controller直接依赖ChatClient而是让业务层面向一个AiAssistant接口。换模型、调参数、做熔断降级的逻辑都收敛在这一层。例如定义public interface Assistant { String chat(String userMessage); } Service public class DefaultAssistant implements Assistant { Nullable private final ChatClient primaryClient; Nullable private final ChatClient fallbackClient; Override public String chat(String userMessage) { try { return primaryClient.prompt(userMessage).call().content(); } catch (Exception ex) { return fallbackClient.prompt(userMessage).call().content(); } } }这样主模型挂了自动切备用模型对上层完全透明。对线上成本控制也同样适用普通问题走轻量模型复杂任务走高端模型切换逻辑集中在门面里而不是散落在各业务方法中。6. 2024版版本演进与社区热议话题6.1 从M1到m系列版本迭代带来了什么关键变化Spring AI 2024年度的版本演进核心变化集中在三件事自动配置增强、模型接入标准化、API收敛。早期示例里还经常要手写OpenAiChatModel到了M系列后期一个Starter加三行配置就能全量可用。函数的注册也从早期繁琐的Schema手工声明逐步演进到通过FunctionBean和Tool注解直接暴露开发体验向Spring MVC注解看齐。6.2 社区热议Spring AI 2.0与百炼、通义新模型的深度整合2024年底社区讨论最热烈的话题之一就是Spring AI后续大版本大家习惯叫它2.0相关的迭代方向与阿里云百炼平台的深度组合。开发者特别关注的是通义千问新模型能否像OpenAI一样被Spring AI“一等公民”式接入以及国产模型在Java侧的函数调用、Agent链路是否足够顺畅。从搜到的资料和反馈看百炼平台在做OpenAI兼容协议上花了大力气配合spring-ai-alibaba很多原本跑在OpenAI API上的项目几乎不改代码就能切换到通义模型。这背后其实是模型服务供给逻辑的变化模型平台不再只卖API而是希望把自己嵌入到主流开发框架的依赖体系里让Spring开发者感觉“通义本身就是Spring AI的一个方言”。工具链的融合度越高Java团队越不需要在业务代码里关注模型厂商差异。6.3 为什么Java生态比起Python更依赖这类框架有人说Python那边LangChain已经很成熟何必再拥抱Spring AI。但如果你的应用是一个运行在Spring Cloud体系里的订单、审批系统Python AI服务要接入Java业务要么走HTTP拆分要么引入一套异构技术栈。难度从对接、部署到链路追踪层层叠加。Spring AI把大模型能力变成Java工程内的一等公民利用同样的注册中心、配置中心、监控体系去治理AI请求这在企业级Java项目里是决定性的优势。团队不必维护两个技术栈AI调用也能被标准日志、Metrics和Trace体系覆盖。7. 高频问题排查与避坑速查7.1 常见异常场景与处理方式把2024年社区和我个人遇到的高频问题按现象排了一张速查表现象根因处理建议请求报401 Unauthorizedapi-key填错或未生效检查环境变量注入确认配置键名重启应用让自动配置重新读取请求超时频繁默认超时时间过短在options里设置timeout或调整重试策略百炼等平台长上下文首token较慢返回结果频繁截断显式maxTokens数值太小按业务长度需求增大输出Token上限同时观察总Token消耗结构化输出序列化失败record字段与模型输出语义不一致统一字段命名、增加包装record、必要时在提示词中附JSON示例函数调用时模型使用错误参数参数描述不清晰给入参类型添加描述注释可显著提升模型参数补全准确率依赖冲突或类找不到不同模块版本不一致全局使用BOM管理版本配合Maven依赖树排查7.2 调试技巧让模型请求过程可见大模型应用调试最怕“黑盒”。Spring AI里有两个实用手段可以快速看清请求和响应一是打开org.springframework.ai.*的DEBUG日志看模型请求的完整Payload二是使用内置的SimpleLoggerAdvisor或自定义Advisor把Prompt、响应摘要、Token用量打到控制台。如果怀疑结构化输出转换有问题还可以临时让.entity()改成.call().content()输出模型原始文本验证模型是否真的按JSON格式返回。流式请求的调试也比较特殊。.stream()返回的是Flux如果想知道完整返回可以在测试里用StepVerifier订阅并打印每个内容块。线上环境可以统计内容块数量如果输出中途断开多半是上游连接被意外关闭需要检查网关Idle超时设置。7.3 避坑心得版本锁定、模型命名与上下文空间最后写几条花了真金白银才换来的经验对症常量配置。第一版本锁定优先。Spring Boot 3.3.x与Spring AI BOM版本有对应关系随意升级到不匹配版本很容易触发构造器参数不匹配或自动配置失效。我的习惯是每次升级都先查官方发布说明的兼容矩阵再决定是否升级。第二模型命名看清楚。同一个模型在不同服务商那里命名可能不同比如有些平台叫qwen-plus有些叫qwen-plus-latest配置错一个字就是400。模型名应该放到配置项里管理别硬编码在代码里。第三上下文空间别塞满。把体系Prompt、历史记忆、RAG检索结果和用户问题加在一起估算Token务必给模型输出留足缓冲否则会出现“回答到一半戛然而止”的尴尬情况而这种截断往往不报任何异常排查起来特别隐蔽。我在实际项目里被这类“静默截断”坑过好几次后来统一加了一层输出完整性校验如果响应文本意外在JSON中间断开就自动重试一次并调低历史消息条数。这类防御逻辑写在门面Service里成本很低效果却非常直接。Spring AI的体系放在那里真正体现工程水平的地方恰恰是这些模型能力之外的防御细节。