我之所以把这篇文章命名为“摸索实践”是因为Spirng AI这条路我确实是一步步踩出来的不是看两眼文档就能直接写代码的那种顺滑体验。Spring AI是Spring官方在AI应用开发领域给出的一套抽象框架目标是把大模型接入、结构化输出、向量检索这些事从“自己拼HTTP请求”变成“像写Spring Data一样面向接口”。对已经在用Spring Boot的Java开发者来说它是目前和技术栈融合最自然的AI集成方式没有之一。这篇文章更适合两类人一类是Java背景扎实但没碰过AI应用的开发者你可以照着操作把一个对话Demo跑起来另一类是已经用Python调过模型接口、现在想把能力搬回业务系统的后端工程师你关心的配置切换、结构化输出、RAG落地这些坑我都会讲到。我的所有经验都来自实际项目中两个星期的反复折腾踩坑记录和代码示例会一起给出来。1. Spring AI到底解决什么问题1.1 它和直接调模型SDK有什么本质差别先说一个很直观的场景。假设你的业务代码里要接入一个聊天模型最原始的做法是写一个服务类里面拼HTTP请求、带鉴权头、处理超时重试、解析响应JSON。刚开始只有一个供应商的时候这套代码勉强能用。可一旦你想从A厂商切换到B厂商或者想在A和B之间做负载分流你会发现业务代码里到处散落着厂商SDK的类型和方法改动成本高得吓人。Spring AI做的事情和Spring Data对数据库的抽象非常像。你写JpaRepository的时候根本不用关心底层是MySQL还是PostgreSQL同样使用Spring AI时你面向的是ChatClient、ChatModel这类统一接口供应商之间的差异被隔离在依赖和配置层面。框架内部帮你管理了请求构造、鉴权注入、响应解析、超时与重试策略甚至把“让模型返回JSON”这件事做成了类型安全的映射。这个设计还有一个容易被忽略的好处测试变得好写了。以前你Mock一个HTTP客户端或者SDK对象现在只需要Mock一个ChatModel接口配合Mockito就能把业务逻辑完整跑一遍完全不需要真实调用模型。1.2 什么场景值得引入什么场景反而没必要不是所有AI需求都应该无脑上Spring AI。我根据实际项目经验画了一条明显的分界线适用场景不建议用的场景团队已经是Spring技术栈希望AI调用能和现有业务代码统一管理公司自研了高性能模型网关已有完善的流式转发和限流机制需要结构化输出比如从模型返回中直接映射业务对象只是做一次性的脚本调用不值得引入框架要搭建RAG流水线希望文本切分、向量化、检索能被规范管理对延迟极度敏感要求毫秒级直连模型API需要快速切换不同模型供应商不想改业务代码已有成熟的Prompt工程平台业务层完全不需要感知模型细节我个人的判断标准很简单如果你的复杂度在于“AI能力怎么被业务复用”那就值得用如果复杂度在于“底层链路怎么调度”框架帮不了你太多该自己写网关还是得自己写。2. 从零搭建把第一个Spring AI应用跑起来2.1 环境准备和版本选择是第一个大坑Spring AI到现在仍然没有发布正式稳定版版本号一直处在里程碑M和快照Snapshot之间。我一开始图新鲜选了最新快照版本结果发现不仅API和文档对不上还间接牵连了Spring Boot等其他依赖的版本解析折腾了一个晚上才把问题定位清楚。这里给一个非常务实的版本策略选择当前官方文档明确推荐的里程碑版本不要追求最新。实际项目中我用的是Spring Boot 3.2及以上版本配合JDK 17这套组合在兼容性和稳定性上表现不错。生成工程时可以直接用Spring Initializr在依赖搜索框里输入Spring AI相关选项如果用的IDE版本比较老找不到就手动在pom里加BOM和依赖。dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version你的版本号/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-xxx-spring-boot-starter/artifactId /dependencyBOM的作用是统一管理所有Spring AI子模块的版本避免你自己去记每个artifact的版本号。如果你用的是Maven记得检查仓库配置有些里程碑版本不在默认中央仓库里需要额外配置Spring的里程碑仓库这个细节很多人会漏。2.2 最小化对话Demo代码比想象中简单配置文件的写法是第一个容易出错的地方。在application.yml里你需要配置模型提供商的接口地址、API Key和模型名称。有一个细节我印象特别深接口地址base-url只填域名会导致404必须包含到/v1这个路径前缀因为大部分厂商的REST接口都挂在版本前缀下面。spring: ai: model-provider: base-url: https://api.example.com/v1 api-key: ${AI_API_KEY} chat: options: model: example-chat-model temperature: 0.7这里我特意把配置前缀写成了model-provider实际项目中前缀取决于你引入的starter的artifactId通常就是供应商名称。API Key一定要走环境变量直接写死在配置文件里是迟早要出事的坏习惯。写好配置后注入ChatModel就能发起第一次对话了Service public class ChatService { private final ChatModel chatModel; public ChatService(ChatModel chatModel) { this.chatModel chatModel; } public String ask(String question) { return chatModel.call(question); } }这段代码虽然能跑但我建议你从第一行代码开始就用ChatClient而不是ChatModel裸调。因为后续你要用到的结构化输出、流式响应、Prompt模板基本都是基于ChatClient展开的。早期版本里ChatClient的构造方式出现过大改版我之前照着旧博客写ChatClient.builder()结果在新版本里compile都过不去后来才发现官方已经把构造方式统一到了自动配置的Bean上面。2.3 配置管理里那些不起眼但致命的细节除了API Key和base-url还有几个连接参数我建议在一开始就配好否则跑着跑着就会遇到玄学超时spring: ai: model-provider: connection-timeout: 60s read-timeout: 60s之前我遇到过对话稍长一点就报超时的问题排查了很久才发现是默认读取超时太短生成型模型响应本来就慢短超时等于自己给自己埋雷。另外_model参数名不要想当然不同供应商的模型名称规则差异很大填错了通常会报model not found一类的错误中文资料里满天飞的模型名不一定适配你用的供应商以官方模型列表为准。注意API Key不要提交到Git仓库。我在实际项目里吃过亏某次随手提交了一个带Key的配置文件第二天就收到账单异常通知。现在我的习惯是本地建一个application-local.yml并加入.gitignore里面放置真实配置主配置文件只保留环境变量占位符。3. 核心API的理解、调优和典型翻车现场3.1 ChatClient从同步调用到流式响应当你把ChatModel升级为ChatClient后代码会变得更有框架感。我最常用的是这两种调用方式Service public class ChatService { private final ChatClient chatClient; public ChatService(ChatClient.Builder builder) { this.chatClient builder.defaultSystem(你是一个乐于助人的中文助手).build(); } public String syncAsk(String question) { return chatClient.prompt() .user(question) .call() .content(); } public FluxString streamAsk(String question) { return chatClient.prompt() .user(question) .stream() .content(); } }同步调用适合后台任务、批处理这类不需要实时反馈的场景流式调用则适合面向用户的对话接口让内容像打字机一样逐字输出大幅降低用户的等待焦虑。Flux本身是响应式编程里的概念如果你没接触过先理解成“一个异步流”就够了前端接SSE时非常顺手。我在Controller里直接返回Flux配合Server-Sent Event浏览器端只用EventSource就能收到消息。3.2 结构化输出从String里硬解析JSON是最蠢的写法最早的摸索阶段我让模型返回JSON字符串然后在代码里用正则把被markdown围栏包住的内容抠出来再用Jackson反序列化。这个思路在小样本下勉强能跑一旦模型偶尔在JSON前后多输出一句解释性文字整个解析就崩了。后来我才发现Spring AI提供了结构化输出的能力相当于让模型按照指定格式输出再由框架自动完成反序列化。public record QueryResponse( String answer, ListString references ) {} Entity public class QaService { private final ChatClient chatClient; public QueryResponse askWithStructure(String question) { return chatClient.prompt() .user(question) .call() .entity(QueryResponse.class); } }这段代码看起来简单但有几个细节值得单独拎出来说。第一如果你定义的是普通class而不是record一定要给它一个无参构造器否则反序列化阶段大概率会抛异常。第二类字段名尽量和你的中文需求描述一致否则模型在语义推断时容易跑偏。第三建议在类上加上JsonIgnoreProperties(ignoreUnknown true)因为模型有时候会额外多输出一些字段没有这个注解可能直接映射失败。我还踩过一个更隐蔽的坑当返回内容比较复杂比如嵌套泛型或者List里面套对象时默认的类型解析可能出错。解决办法是把期望结构写清楚并在Prompt里明确告诉模型“只输出JSON不要输出任何解释文字”。如果框架版本支持也可以在调用级别配置JSON Schema约束这样模型侧会严格遵守输出格式几乎不会出现格式漂移。3.3 流式输出的SSE对接和中文乱码上一节提到的流式响应放到Web接口里还有个常见坑。你如果直接返回Flux 前端收到的Content-Type可能不是text/event-stream导致EventSource连接直接报错。正确的做法是需要按SSE协议包装数据事件。另外中文环境下如果响应里出现了非法字符很容易被浏览器截断表现为“消息说一半就停了”。我的处理方法是定义统一的响应包装每次发送一个完整句子再换行前端按事件完整接收。同时给流式接口配置合理的超时时间避免模型端长时间不返回时连接一直挂着占用线程。4. 进阶实践把RAG跑通才算真正入门4.1 不懂RAG就先用一句话理解它RAGRetrieval-Augmented Generation检索增强生成。官方解释很绕我的白话理解是大模型有知识盲区尤其是你公司内部的文档它根本没见过如果你直接把问题丢给它它只能瞎编。RAG的思路是先检索把你的文档切碎、向量化、存入向量库用户提问时先从库里找出相关片段再把这些片段塞进Prompt让模型基于这些材料作答。Spring AI把这条流水线抽象成了几个清晰的角色文档读取器负责解析源文件文本切分器负责把长文切片嵌入模型负责把文本变成向量向量存储负责检索相似内容。对我这样习惯了分层架构的Java工程师来说这套抽象用起来真的很顺。4.2 一个最小可运行的RAG Demo我建议新手不要在第一步就引入复杂的向量数据库先用内存版跑通链路后续再迁移。下面是一个能直接运行的最小实现思路Configuration public class RagConfig { private final EmbeddingModel embeddingModel; public RagConfig(EmbeddingModel embeddingModel) { this.embeddingModel embeddingModel; } Bean public VectorStore vectorStore() { return new SimpleVectorStore(embeddingModel); } }然后从本地文档构建索引Service public class RagService { private final VectorStore vectorStore; private final ChatClient chatClient; // 构造函数省略 public void buildIndex(String filePath) throws IOException { String content Files.readString(Path.of(filePath)); TextSplitter splitter new TokenTextSplitter(300, 50); ListDocument documents splitter.split(new Document(content)); vectorStore.add(documents); } public String ask(String question) { ListDocument matches vectorStore.similaritySearch(question); String context matches.stream() .map(Document::getContent) .collect(Collectors.joining(\n)); String prompt 请基于以下资料回答问题\n context \n问题 question; return chatClient.prompt().user(prompt).call().content(); } }代码非常简单但已经涵盖了RAG的核心链路切分、向量化、存储、检索、增强、推理。我特别说一下chunkSize也就是文本切分大小。太小了会导致上下文碎片化模型看不到完整逻辑太大了会导致检索出来的片段包含大量噪音。我实操下来300到500个token是比较稳的区间overlap重叠50左右保证相邻片段之间不丢关键语句。4.3 向量存储选型与资源控制的经验教训内存版向量库适合验证逻辑但项目一旦进入联调阶段我建议立刻切换到独立服务型向量库否则重启一次就要重新灌数据而且内存占用会持续增长。嵌入模型的选择也很关键如果你用的是远程API检索延迟受限于网络质量稳定如果你选择本地嵌入模型需要注意加载到内存后对JVM堆的冲击。我在“本地嵌入远程对话”这个组合上踩过一个大坑嵌入模型加载完占了一部分堆内存再叠加流式对话的并发压力应用直接就OutOfMemoryError了。后来在启动参数里把最大堆内存调大并限制了向量检索的返回条数情况才稳定下来。另外别贪心把所有文档一次性切碎全部入库先小批量验证检索效果再逐步扩充否则问题会被淹没在海量数据里排查效率极低。5. 常见问题与排查技巧实录5.1 把日志级别调起来是第一步遇到任何调用异常我的第一反应不是改代码而是把Spring AI的日志级别调到TRACE看清完整的请求体和响应体。很多所谓“玄学错误”只要看到真实响应文本原因立刻浮出水面。比如模型返回的JSON被倒进了某个说明性字段、请求头里没带上API Key、base-url拼写多了一个斜杠这些都能在日志里一目了然。调日志的方式很简单在application.yml里把对应包的level设置成trace就行。排查完问题再调回INFO避免生产环境日志爆炸。5.2 高频报错速查表我把这两个星期里遇到的高频问题做了个速查表希望能帮你节省排查时间异常现象可能原因处理办法401 Unauthorizedapi-key没生效、base-url路径错误检查环境变量是否注入确认路径是否包含/v1404 model not found模型名填错、当前账户无权限到官方模型列表核对名称换一个可用的模型读取超时默认read-timeout太短、模型响应慢在配置里调大读取超时到60秒以上反序列化失败返回内容被模型加了多余文字、实体类无无参构造启用结构化输出约束补无参构造器加ignoreUnknown内存溢出本地嵌入模型占堆、向量库数据量过大调大JVM堆内存控制检索条数和文档切分批大小依赖缺失ClassNotFound只引入了核心starter缺对应功能模块按需补充文档解析器、向量库等模块依赖流式响应断帧中文字符被截断、SSE数据格式不标准按完整句子输出事件确认Content-Type和换行格式5.3 我收藏的几个调试习惯有几个调试习惯我后来每次写AI功能都会带上。第一把系统提示词和用户消息拼好后先打印出来人工读一遍再发给模型很多“效果不好”的问题其实出在Prompt本身。第二调试阶段把温度调到0排除随机性干扰先确认逻辑通不通最后再调高温度追求多样性。第三做文本切分实验时不要用完整的大文件挑几段代表性内容试观察检索命中质量。第四流式响应录完日志后一定要确认“完成”事件有被消费否则连接会被框架挂起前端永远等不到结束信号。提示遇到网上流传的Spring AI代码片段先检查它对应的版本再试。这个框架目前API变动还比较频繁很多旧文章里的写法在新版本已经废弃了。6. 一点个人经验总结最后说点很实在的。Spring AI是一个解决“接入”痛点的框架它不会让你的模型变得更聪明也不能替你写出更好的Prompt。它的价值在于把模型供应商切换、结构化输出、RAG链路这些重复劳动变成标准化的配置和接口让你能把精力放回业务本身。根据我自己的体会如果你现在准备入坑不要一上来就追向量数据库和高阶流式编排。先把最小的对话Demo跑通体会Spring Boot如何把大模型封装成一个看起来平平无奇的Bean接着尝试结构化输出让模型返回能被业务代码直接使用的对象然后再加上RAG把文档问答这个几乎每个企业都会遇到的场景走一遍。每走一步都确认它能稳定运行再往下一步走。这个顺序看起来慢但恰恰是踩坑最少、产出最快的路径。我印象最深的一点是框架替你解决了百分之八十的复杂度剩下百分之二十仍然要靠你理解AI本身的工作原理。当你掌握了这套组合之后Spring AI给你的不止是一个能调用聊天模型的工程而是一条把AI能力平滑嵌入Java生态的成熟路径。
