老规矩不管学什么新技术先跑通一个Hello World心里才有底。SpringAI项目也是如此——别看它名字里挂着一个“AI”本质上它还是Spring生态里的一个子项目解决的是“Java开发者怎么用更熟悉的方式去对接大模型能力”这件事。我在上手SpringAI的第一个项目时踩了不少坑这篇文章就把整个实战过程完整拆开来写从思路到落地再到常见问题和排查技巧一次性讲透。适合谁看正在学Spring Boot、想接大模型但还没动过手的人或者已经写过LangChain/Python调用想看看Java这边怎么做的都可以参考。1. 项目整体设计与思路拆解1.1 SpringAI到底解决什么问题先说我个人的理解。SpringAI的定位不是把某个模型包一层API就完事而是一套面向AI应用的Spring风格抽象层。它把“调用大模型”这件听起来很玄幻的事变成了类似RestTemplate调用接口、JdbcTemplate操作数据库一样的基础操作。在写第一个项目之前我先理清了它解决的三个核心问题第一个问题是接入方式碎片化。OpenAI、Anthropic、Google Gemini、本地Ollama各自有不同的请求协议、鉴权方式、流式返回格式。如果没有统一封装业务代码里会散落一堆HttpClient调用、JSON解析和错误处理逻辑。SpringAI把这层差异收口在ChatClient或ChatModel接口后面切换模型厂商只需要改配置不动业务流程。第二个问题是AI能力与Spring生态的衔接。真实业务里我们不光要“聊天”还要把对话结果存到数据库、把向量存到向量数据库、把AI能力暴露成REST接口给前端调用。SpringAI提供了ChatMemory做会话记忆、EmbeddingModel做向量化、VectorStore做相似度检索这些都能直接注入到Spring容器里和业务代码无缝整合。第三个问题是标准化交互范式。无论底层是哪个模型对上层而言我需要的是稳定的几个操作给一段提示返回文本、给一组文档返回向量、给一个问题返回检索结果。SpringAI把这些都提炼成了几个核心接口预期非常明确。写第一个Hello World项目的时候不用急着研究所有模块只需要抓住Spring AI Chat Model这一条主线先把“请求→响应”这条路走通。1.2 为什么第一个项目从“无状态单轮对话”切入很多人在入门时一上来就想做完整的RAG检索增强生成、多轮对话、Agent工具调用。我的建议是第一个项目不要贪多。首选切入点应该是“无状态单轮对话”也就是最朴素的用户给一句提问程序调用大模型返回一句回答。选择这个切入点的理由很现实第一它依赖最少。只需要引入一个starter、配一个API Key或本地模型地址、写一个Controller不存在数据库、向量库、消息队列这些外围依赖。环境出问题的概率最低。第二它能完整展示SpringAI的核心调用链路。通过这一条链路你能直观看到客户端如何发起请求、ChatModel如何被自动配置、系统提示词和用户消息怎么组装、流式与阻塞两种返回方式的差异。把这些搞懂了后面学多轮对话、结构化输出都是在这一条链路上做加法。第三它方便做实验。比如调整temperature观察生成结果的变化、加一个system prompt看模型行为怎么变这些实验在极简项目里做起来非常顺手。我实际操作时的顺序是先跑通同步调用再换流式调用再分别调整提示词和模型参数一步步从“能跑”过渡到“懂原理”。1.3 技术选型的对比分析在做SpringAI项目前大多数人面临一个工具箱选择问题是直接用LangChain4j注意是Java社区常用的LLM框架还是用Spring官方这个SpringAI我两个都简单写过说说我的对比结论供你参考维度SpringAILangChain4j出身背景Spring官方持续迭代快社区驱动兼容LangChain概念Spring Boot集成原生自动配置完善良好但需要额外适配会话记忆内置ChatMemory实现内置不同记忆策略模型支持OpenAI、Ollama、Google等OpenAI、Ollama、Hugging Face等Java版本要求至少JDK17至少JDK17上手难度对Spring Boot用户更友好概念多需要时间消化选SpringAI还有一个很重要的原因它紧跟Spring Boot 3.x的生态节奏以后升级依赖、适配新版本JDK会更顺。花几天时间上手一个官方背书的框架长期维护成本相对可控。2. 环境准备与依赖引入2.1 确认JDK和Maven环境写SpringAI项目第一步其实是环境摸底这块出了问题后期排查很浪费时间。我实际用的是JDK 21和Maven 3.9.x项目基础框架是Spring Boot 3.3.x。这里有个重要提醒SpringAI的spring-ai-bom对Spring Boot版本有明确要求需要Spring Boot 3.2及以上。如果你的JDK还是Java 8或11建议先升级环境再继续否则一大堆编译错误会让人怀疑人生。我在最开始用JDK 11试过一次SpringApplication跑不起来的报错直接给我劝退了后来换了JDK 21才顺畅。工程结构上可以走两个方案一是用Spring Initializr直接生成基础工程然后再手动添加SpringAI依赖二是自己建一个空的Maven项目一点点加依赖。我更推荐第一种它能确保初始的Spring Boot版本是兼容的减少后面改版本的痛苦。注意SpringAI版本和Spring Boot版本是绑定发布的比如Spring AI 1.0.0对应Spring Boot 3.4.x版本对不上时会遇到自动配置不生效或者类加载异常。2.2 依赖坐标与配置解析我用的是Maven方式管理依赖核心配置长这样parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.3.2/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency /dependencies dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement我第一次写的时候只知道加starter没有引入spring-ai-bom结果依赖版本解析直接失败Maven报了一堆很抽象的Cannot resolve错误。原因在于必须通过BOM把SpringAI各组件的版本统一管理起来尤其当你后面还要引入spring-ai-pdf、spring-ai-tika-document-reader这类扩展组件时BOM能有效避免版本冲突。依赖引入后还需要在application.yml里做基础配置。我用OpenAI的模型做主线演示配置如下spring: application: name: spring-ai-hello ai: openai: api-key: ${OPENAI_API_KEY} base-url: https://api.openai.com chat: options: model: gpt-4o-mini temperature: 0.7 max-tokens: 1024需要注意两点第一是api-key别硬编码在配置文件里建议从环境变量读取避免密钥提交到代码仓库第二是model字段最好显式指定SpringAI虽然会有一个默认模型名但不同版本默认值可能变化我亲眼见过同事项目里因为没写model导致语义上和预期不符排查了半天。如果你手头没有OpenAI的Key也可以先走本地模型路径。SpringAI对Ollama支持得不错配置换成下面这样就行spring: ai: ollama: base-url: http://localhost:11434 chat: options: model: llama3.2本地模型的优势是调试成本低不消耗API额度缺点是对机器内存有要求8G内存跑小模型还行大一点的模型会明显变慢。2.3 仓库镜像与联网检查国内开发者在这步最容易被卡住的就是Maven下载依赖速度。我建议在~/.m2/settings.xml里配置阿里云镜像这个做法很通用也很稳妥能显著提升依赖拉取速度。配置文件大致是mirrors mirror idaliyun/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/central/url /mirror /mirrors网速这个问题见仁见智但SpringAI的依赖本身比较大像spring-ai-openai会拉很多jackson、reactor相关的包没有镜像的情况下第一次构建可能要等很久。配置好镜像后mvn dependency:resolve跑一遍确认所有依赖能正常解析再继续下一步。3. 从零到运行Hello World核心代码实现3.1 无状态ChatClient调用代码依赖配置好了接下来是核心环节写一段能跑通的Java代码。SpringAI里最常用的入口是ChatClient接口它提供了一套链式调用的API非常贴合Spring风格的编程体验。我先写的不是Controller而是一个极简的CommandLineRunner直接在应用启动时向模型发起一次请求把结果打到控制台。这样能最快验证“依赖有没有配对、API Key有没有问题、网络链路通不通”。代码如下package com.example.springaihello; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor; import org.springframework.boot.CommandLineRunner; import org.springframework.stereotype.Component; Component public class ChatRunner implements CommandLineRunner { private static final Logger log LoggerFactory.getLogger(ChatRunner.class); private final ChatClient chatClient; public ChatRunner(ChatClient.Builder builder) { this.chatClient builder .defaultAdvisors(new SimpleLoggerAdvisor()) .build(); } Override public void run(String... args) { String response chatClient.prompt() .system(你是一位耐心的Java技术助手回答要简洁准确。) .user(请用一句话介绍SpringAI是什么) .call() .content(); log.info(AI回复: {}, response); } }注意这里用的是构造函数注入ChatClient.Builder这是SpringAI自动配置提供的核心Bean。builder到chatClient的转换过程中我还挂了一个SimpleLoggerAdvisor它能把请求和响应日志打印出来调试时特别有用。我记得第一次跑的时候没挂Advisor模型返回的原始内容在日志里一点都看不到出了问题完全不知道模型有没有收到请求。运行这个Runner后控制台会先打印请求日志包括模型名称、消息内容、token数之类的信息然后输出模型的回复。看到类似“SpringAI是Spring生态系统中的一个AI应用开发框架用于将大语言模型能力集成到Java应用中”这样的内容说明整个链路已经通了。3.2 通过REST接口暴露服务CommandLineRunner只是验证链路实际开发中更多的还是做一个接口给前端调用。这里我写了标准的Controllerpackage com.example.springaihello.controller; import org.springframework.ai.chat.client.ChatClient; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController; import java.util.Map; RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient builder.build(); } PostMapping(/chat) public MapString, String chat(RequestBody MapString, String payload) { String question payload.getOrDefault(question, 你好); String answer chatClient.prompt() .user(question) .call() .content(); return Map.of(answer, answer); } }这时spring-boot-starter-web的作用就体现出来了SpringAI一起动/chat接口就能直接被调用。有一个容易忽略的点ChatClient的构建方式。如果在CommandLineRunner和Controller里各自用builder.build()会得到两个独立的ChatClient实例。对单轮对话这个场景没有影响但后续如果配置了会话记忆每个实例会各自维护对话历史容易造成混乱。更合理的做法是把ChatClient定义成一个Bean统一管理Configuration public class ChatConfig { Bean public ChatClient chatClient(ChatClient.Builder builder) { return builder.build(); } }然后其他组件都注入这个统一的Bean。这个习惯越早养成越好后面项目复杂了能省掉很多幺蛾子。3.3 流式返回的实现真实业务里阻塞式返回有一个很现实的问题大模型生成是逐token进行的如果全部生成完再返回用户的等待时长可能是十几秒甚至几十秒。这在一些聊天气泡场景里很难接受。SpringAI对流式返回的支持是内置的用FluxString来表示流式响应。Controller改成这样PostMapping(value /chat/stream, produces text/event-stream) public FluxString chatStream(RequestBody MapString, String payload) { String question payload.getOrDefault(question, 你好); return chatClient.prompt() .user(question) .stream() .content(); }前端通过EventSource或fetch流式接收数据用户看到的就是“逐字输出”的效果体验上会好不少。这一步虽然代码改动不大但意味着你已经从“能调用”进阶到“理解传输层”的层面了。3.4 提示词与关键参数拆解简单对话跑通后好奇心自然会驱使人去调参数、改提示词。这里聊聊我在实操中理解到的几个关键配置system prompt系统提示词是模型行为的总基调。它就像是给新员工发的“岗位说明”如果希望模型以“技术专家”口吻回答就把人设写在系统提示词里如果希望它严格遵守输出格式比如要求返回JSON也可以在系统提示词里明说。用户消息user才是实际的提问内容。temperature控制随机性取值范围一般是0到2之间OpenAI系列。数值越低输出越稳定、保守适合做分类、抽取等确定性任务数值越高输出越有创造性适合头脑风暴、文案生成。我做了一个小实验把temperature从0.1调到1.5让模型写一句文案结果0.1版本输出几乎每次结构雷同1.5版本每次都换了说法这个实验我强烈建议自己也跑一遍直观感受模型参数的影响力。max-tokens限制生成的最大token数。需要注意它限制的是“回答部分”的长度不会把提示词的计算量算进去。设置太大浪费资源太小则可能回答被截断。我常用1024作为默认值对大多数问答场景都够用。4. 结构化输出与多轮对话扩展4.1 让模型按Java对象返回结果Hello World做出来之后很多人第一个想要升级的点就是“我不想拿字符串了我想直接拿一个对象。”这是很合理的诉求因为真实业务里AI的回答经常要落到数据结构里比如提取简历里的姓名、年龄、技能列表。SpringAI的Structured Output功能就是干这个的。调用方指定一个返回类型框架会引导模型按JSON格式生成内容再用Jackson反序列化成Java对象。示例代码public record PersonInfo(String name, int age, ListString skills) { }PersonInfo person chatClient.prompt() .user(请从这段简历信息中提取人员信息张三28岁掌握Java、Python、Kubernetes) .call() .entity(PersonInfo.class);这里有个关键点SpringAI底层会往提示词里追加“输出必须是特定JSON格式、必须匹配指定字段名”的约束而不只是简单解析。我在实际测试中发现这个方式的稳定性比“自己写解析逻辑”高很多几乎不会出现字段名对不上的情况。如果后续要做信息抽取、关键词提取、意图识别完全可以沿用这套写法。需要注意record类型和JavaBean类型都有支持但字段名最好不要用过于口语化的词比如a、b这种模型对语义化字段名的遵守率明显更高。这算是一个模型层面的经验你在Java侧做得越规范模型输出的质量越容易稳定。4.2 多轮对话中的会话记忆单轮对话的项目到这就很好扩展成多轮对话了。SpringAI的多轮对话思路并不是把历史消息交给模型自己揣摩而是显式地管理一个ChatMemory对象每次调用前把历史记录注入到Prompt里。我在项目里用的方式是配置一个MessageChatMemoryAdvisorBean public ChatClient chatClientWithMemory(ChatClient.Builder builder, ChatMemory chatMemory) { return builder .defaultAdvisors(new MessageChatMemoryAdvisor(chatMemory)) .build(); }ChatMemory有内存实现类InMemoryChatMemory也有基于数据库和Redis的实现思路。对于生产环境InMemory毕竟有单机容量和重启丢失的限制更稳妥的是把对话记录存到Redis或者数据库里会话ID对应一套历史消息。这个改造就是SpringAI非常擅长的事Java生态的持久化方案直接往里堆就行。4.3 从模型调用到业务能力顺着这个思路你会发现SpringAI项目能够承载的已经不只是“AI聊天”了。我在Hello World之后做的一个小实验是把AI的回复结果自动记录到数据库再用定时任务生成每日问答摘要。这个实验的意义在于打通“AI能力”和“业务系统”之间的边界。在代码上只需要在拿到chatClient.call().content()之后把结果当作一个普通字符串走常规的Mapper、Service存入数据库。SpringAI不会绑架你的数据存储方案这也是它和一个全托管平台的差别。打通这一步后后续再接RAG、向量库、Agent也是同样的套路AI组件负责理解与生成Spring Boot业务代码负责编排与持久化。这个分层思维对新手非常重要它决定了你后续上课件、做项目时的基本架构方式。5. 实际运行中的坑与调试方法5.1 依赖版本与自动配置类加载问题用得多了就会知道Spring生态最大的坑从来不是语法而是版本匹配。SpringAI项目我更想分享这个经验如果你的application.yml里写了spring.ai.openai.api-key但启动后没有任何效果优先确认Spring Boot版本和SpringAI版本是否在兼容矩阵内。我遇到过的情况是项目从Spring Boot 3.3升到3.4后SpringAI的ChatClient自动配置没生效ChatClient.Builder注入直接报NoSuchBeanDefinitionException。排查结果是spring-ai-bom版本太低不匹配Boot 3.4的自动配置机制。解决办法是把BOM的version升到最新稳定版同时检查是否有多余的旧依赖需要清理。依赖冲突方面另一个高频报错是Jackson相关类冲突。SpringAI依赖的Jackson版本可能会和项目其他依赖冲突表现为反序列化异常或InvalidDefinitionException。建议用mvn dependency:tree查看依赖树确认SpringAI使用的是哪个Jackson版本再统一项目里的Jackson版本。如果启动后只看到日志里出现“No active profile set”别急着跑业务代码先确认应用是完整启动成功还是中途退出了。SpringAI的失败通常会在启动阶段直接暴露很少会等接口调用时才崩。5.2 调用模型时的常见报错下面是几个我实测常常遇到的报错整理成表格方便排查现象可能原因处理方式401 UnauthorizedAPI Key错误、未正确从环境变量读取检查环境变量名与api-key占位符是否一致404 Model Not Found模型名拼写错误或账号无权限访问该模型去平台核对可用模型名显式配置model调用超时网络不稳定或默认超时时间过短在spring.ai.openai.chat.options.timeout中调大超时时间内容被截断max-tokens太小增大max-tokens值返回JSON解析失败输出字段与Java对象字段名不匹配简化字段名使用record类型并加格式化约束针对超时这一项多说一句SpringAI底层基于Reactor WebClient默认超时时间可能比你预期的要短。如果在调用慢模型或长文档处理时频繁超时显式设置超时是划算的投资。但不要为了追求一次成功就无限放大超时时间否则接口阻塞时间过长会拖垮应用线程池。5.3 如何有效地调试Prompt调试Prompt也是一项硬技能。Hello World项目里我用SimpleLoggerAdvisor打印了完整请求和响应。但Advisor只是让你“看到”真正要做到“调明白”我建议你保留每次请求的原始输入输出最好能形成一条调试记录。实际操作中我是这么做的在调用ChatClient前后打印一个固定的分隔日志标记上请求ID把时间戳、模型、温度、max-tokens、输入输出全部打出来。这样复盘时能清楚知道是参数问题、提示词问题还是模型本身的随机性问题。有一次一个输出隔三差五就乱格式的问题我一直以为是提示词不够严后来通过日志对比发现同一个提示词在temperature低时输出稳定、高时就乱。最终把temperature从默认值降到0.3问题直接消失。这种排查思路比盯着代码看有效得多。6. 从Hello World到生产力的三段式进阶6.1 进阶第一步接入本地私有数据Hello World跑通后大多数人会自然想问“能不能让它回答我自己文档里的内容”这时候就进入RAG检索增强生成的范畴。大致流程是先把文档切块并向量化存入向量库用户提问时先在向量库里检索相似内容片段再把片段作为上下文塞进Prompt最后让模型基于给定上下文作答。SpringAI为这个流程提供了比较清晰的支持你可以把VectorStore注入到业务代码中配合EmbeddingModel完成向量化。这个阶段我不建议一上来就上太重的技术选型。可以先用文件存储或者内存向量库跑通全链路等数据量上来了再迁移到正式的向量数据库。迁移成本在SpringAI里相对可控因为VectorStore接口已经做了抽象。6.2 进阶第二步把AI能力封装成业务组件项目做多了会发现AI调的返回值直接横向铺在Controller层很难维护。我建议把“AI能力”封装成独立的Service组件例如Service public class AiAssistantService { private final ChatClient chatClient; public AiAssistantService(ChatClient chatClient) { this.chatClient chatClient; } public String askQuestion(String question) { return chatClient.prompt() .system(你是一位企业知识库助手如果不知道答案请明确说不知道不要编造。) .user(question) .call() .content(); } }这样Controller只负责接收HTTP参数Service负责拼装Prompt和调用模型后续要加RAG、加日志、加缓存都在Service里做。这个分层方式在任何Spring项目中都成立AI项目也不例外。6.3 进阶第三步评估与安全很多人把Hello World跑通后就急着上线但我用过一段时间后发现AI应用最耗精力的不是能不能生成而是生成得对不对。评估可以从几个简单维度开始对常见问题集合跑一批回归人工看回答质量用字符串相似度或关键词覆盖率做一个粗糙的自动化评估记录模型每次输出了多少token估算单次调用成本避免月底账单吓人。安全方面常规的做法包括对用户输入的Prompt注入做拦截对输出内容加审核关键词配置最大token限制防止过度消耗。这些不一定是SpringAI内置的能力但它完全不阻碍你落地这类机制。7. 常见问题速查与备查清单7.1 依赖与初始化问题速查问题检查点spring-ai-bom无法解析确认仓库镜像配置正确版本号是否存在ChatClient.Builder注入失败确认Starter依赖已引入且版本匹配启动后没有AI相关日志确认spring.ai.openai.api-key已正确配置NoClassDefFoundError查看mvn dependency:tree是否存在版本冲突7.2 运行调试阶段速查问题检查点响应内容始终是空字符串检查模型名称和账号权限测试最小Prompt流式接口前端无法接收确认produces是text/event-stream确认前端使用EventSource中文输出乱码在WebMVC配置中统一UTF-8编码日志中token数为0检查模型调用是否真的完成可能Prompt被中断8. 一点个人体会SpringAI的Hello World项目虽然代码量不多但它是理解整个框架的一扇门。从依赖引入、自动配置、ChatClient调用、再到参数调整和问题排查每一步背后其实都在回答一个朴素的问题Java世界里怎么把“接大模型”这件事做得更工程化。我个人的建议是第一次接触不要太在意“写了多少行代码”而是花时间把ChatClient.prompt().user().call().content()这条链路上的每个节点都搞清楚。你能独立解释清楚系统提示词是怎么传进去的、temperature为什么会改变输出、流式响应为什么是一个FluxString的时候这个Hello World才算真正跑透了。最后分享一个我在实际项目中用过很多次的小技巧把上面这个接口的请求日志和响应日志通过Advisor保留下来放在一个独立的日志文件里。后面无论是做问题复盘、写AI接口文档、还是给模型调优提供素材它都能派上用场。很多不起眼的配置用的时候才会觉得当初留一手是对的。