SpringAI的那些事儿

张

张建站

2026/4/18 10:11:26

10分钟阅读

聊点儿实在的。Spring AI 这个框架网上的资料确实不少但很多要么太教条要么直接甩你一堆官方文档链接。今天这篇不谈空话就是把自己本地搭建的完整过程掰开揉碎了说连我掉进去的那些坑都一并扒出来。一、迈出第一步之前先把“地基”夯实说真的本地跑大模型比想象中简单得多。你不需要一台几十万的企业级服务器只要你手头的电脑配置不太拉跨就行。硬件到底需要啥根据我自己的经历如果你只是跑个本地 Demo不需要 GPUCPU 模式完全够用。我当初用的一台 8 核处理器、16G 内存的 MacBook Pro跑起来顺畅得很。但如果你想本地跑个大点的模型比如 7B 参数的 Llama 或者 Qwen那就得看你的 GPU 了——有个 8G 以上显存的显卡体验会舒服很多。如果你还在用 4G 显存的入门卡别灰心选个 1.5B 到 3B 的小模型照样能玩转。软件环境Spring AI 官方文档明确支持Spring Boot 3.4.x 和 3.5.x所以 JDK 必须是 17 或以上版本。构建工具我选的是 Maven个人习惯Gradle 也行IDE 用的 IntelliJ IDEA基本是 Java 开发的标配。本地大模型怎么选我强烈推荐用Ollama来部署本地模型。Ollama 是一个专门在本地跑大模型的工具安装极其简单一条命令就能把 Llama、Mistral、Qwen 这些模型拉下来跑起来。安装 Ollama去 https://ollama.com 下载对应的安装包双击一路 Next 就行。安装完成后打开终端输入这条命令来拉取一个比较轻量的模型ollama pull qwen2.5:3b这条命令会从 Ollama 的模型仓库里下载阿里通义千问 2.5 版本参数规模 3B。这个模型对中文的支持特别好而且 3B 的规模普通电脑 CPU 跑起来也毫无压力。下载完成后可以用ollama run qwen2.5:3b先在命令行里测试一下确保模型能正常对话再开始下一步。二、版本选择选错了后面全是坑这里我想多唠叨几句。Spring AI 的版本迭代速度非常快而且现在同时有1.x 稳定线和2.x 预览线在并行推进。当前版本的实际情况Spring AI 1.0 已在 2025 年 5 月 GA1.1 已在 2025 年 11 月 GA。1.1 版本带来了 MCP模型上下文协议集成、提示缓存等重量级功能。2.0.0-M2 和 M3 也已发布带来了向量存储的大幅升级、结构化输出增强、Redis 语义缓存等功能。我的建议如果你现在新建项目直接用 1.1.x 稳定版别去踩 0.x 版本的坑。2.0 虽然新功能多但还在里程碑阶段API 可能随时调整用在生产环境风险太大。使用 BOM 来统一管理版本是最稳妥的方式dependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion1.1.4/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagementdependencies!-- Ollama 模型支持 --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-ollama/artifactId/dependency!-- Spring AI 核心 Starter --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter/artifactId/dependency/dependencies注意这里的关键变化Spring AI 1.0 之后starter 模块的 artifact 名称发生了重大调整。我之前踩过这个坑——照着网上老教程写spring-ai-ollama-spring-boot-starter结果编译直接报错找不到。正确的 artifactId 是spring-ai-starter-model-ollama。三、第一个 Hello World让 Spring Boot 和大模型说上话依赖配好了写段代码跑起来试试。先配置application.ymlspring:ai:ollama:base-url:http://localhost:11434chat:options:model:qwen2.5:3btemperature:0.7然后写一个简单的 Serviceimportorg.springframework.ai.chat.client.ChatClient;importorg.springframework.stereotype.Service;ServicepublicclassAIService{privatefinalChatClientchatClient;publicAIService(ChatClient.BuilderchatClientBuilder){this.chatClientchatClientBuilder.build();}publicStringchat(StringuserMessage){returnchatClient.prompt().user(userMessage).call().content();}}再写个 Controller 测试一下RestControllerRequestMapping(/ai)publicclassAIController{privatefinalAIServiceaiService;publicAIController(AIServiceaiService){this.aiServiceaiService;}GetMapping(/chat)publicStringchat(RequestParamStringmessage){returnaiService.chat(message);}}跑之前千万记得确认一件事你的 Ollama 服务必须已经启动并且qwen2.5:3b模型已经下载完毕。如果 Ollama 没跑起来这段代码会直接报连接异常这个坑我当初踩了至少三回。如果你顺利跑通了访问http://localhost:8080/ai/chat?message用一句话介绍Java的特点应该能看到类似这样的输出Java 是一种跨平台的面向对象编程语言以其一次编写到处运行的特点而闻名。看到这个输出说明你的 Spring Boot 项目已经成功和本地大模型对话上了。四、对话记忆让 AI 不再“健忘”上面那个例子每次调用都是独立的AI 不记得你刚才说过什么。要让对话有上下文Spring AI 提供了Advisor机制来管理对话记忆。ServicepublicclassChatWithMemoryService{privatefinalChatClientchatClient;publicChatWithMemoryService(ChatClient.BuilderchatClientBuilder){// 配置对话记忆保留最近 10 条消息this.chatClientchatClientBuilder.defaultAdvisors(newMessageChatMemoryAdvisor(newInMemoryChatMemory(),10)).build();}publicStringchat(StringuserMessage,StringconversationId){returnchatClient.prompt().user(userMessage).advisors(advisor-advisor.param(conversationId,conversationId)).call().content();}}这里的关键是MessageChatMemoryAdvisor——它会自动管理对话上下文你只需要传入一个conversationId就能区分不同的会话。InMemoryChatMemory是内存版实现适合开发和测试生产环境可以换成 Redis 或数据库持久化版本。跑一下多轮对话试试// 用户我叫张三// AI你好张三有什么我可以帮你的吗// 用户我刚才说我叫什么来着// AI你刚才说你叫张三。// 用户我的名字里第一个字是什么// AI第一个字是张。看到没AI 能准确记住你之前说过的名字这就是对话记忆在背后起的作用。五、结构化输出从“废话”到“数据”大模型默认返回的是自然语言文本但在实际业务中你往往需要把模型输出映射成 Java 对象。Spring AI 对结构化输出的支持做得相当不错。假设你想让模型识别用户意图并返回一个结构化的结果publicrecordIntentResult(Stringintent,// 意图类型query / complaint / suggestionStringcategory,// 具体分类doubleconfidence// 置信度){}ServicepublicclassIntentService{privatefinalChatClientchatClient;publicIntentService(ChatClient.BuilderchatClientBuilder){this.chatClientchatClientBuilder.build();}publicIntentResultanalyzeIntent(StringuserMessage){returnchatClient.prompt().user(分析以下用户消息的意图\nuserMessage).call().entity(IntentResult.class);// 直接映射到 Java Record}}entity()方法会告诉模型以 JSON 格式输出并自动反序列化成你指定的 Java 类型。Spring AI 内部用的是 JSON Schema 验证确保返回的数据结构符合预期。这个能力在构建 Agent 或工作流时特别有用——你可以把模型的自然语言输出直接转化成结构化的业务数据不用手动写正则解析了。六、给 AI 配上“知识库”极简版 RAG对话记忆只是让 AI 记住你刚才说了什么但如果想让 AI 回答关于你公司内部文档、产品说明书之类的私有知识就需要 RAG检索增强生成。Spring AI 通过QuestionAnswerAdvisor和向量存储来支持 RAG。先添加向量存储依赖以 PGVector 为例dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-vector-store-pgvector/artifactId/dependency配置向量存储application.ymlspring:datasource:url:jdbc:postgresql://localhost:5432/vector_dbusername:postgrespassword:your_passwordai:vectorstore:pgvector:initialize-schema:truedimensions:384# 根据你的 Embedding 模型维度设置然后实现 RAG 服务ServicepublicclassRAGService{privatefinalChatClientchatClient;privatefinalVectorStorevectorStore;privatefinalEmbeddingModelembeddingModel;publicRAGService(ChatClient.BuilderchatClientBuilder,VectorStorevectorStore,EmbeddingModelembeddingModel){this.vectorStorevectorStore;this.embeddingModelembeddingModel;this.chatClientchatClientBuilder.build();}// 将文档向量化并存入向量库publicvoidindexDocument(Stringcontent,Stringmetadata){DocumentdocnewDocument(content,Map.of(source,metadata));ListDocumentdocsList.of(doc);vectorStore.add(docs);}// 基于知识库回答问题publicStringaskWithRAG(Stringquestion){returnchatClient.prompt().user(question).advisors(newQuestionAnswerAdvisor(vectorStore,embeddingModel)).call().content();}}QuestionAnswerAdvisor是 Spring AI 内置的 RAG Advisor它会自动完成“检索相关文档 → 构建增强 Prompt → 调用模型”这一整套流程省去了大量样板代码。这套系统跑起来之后你问“公司年假怎么申请”这种问题AI 就不再是瞎编了而是会从你导入的员工手册文档里找答案准确性提升不是一星半点。七、Tool Calling让 AI 学会“干活”RAG 让 AI 能“查资料”Tool Calling函数调用则让 AI 能“做事”——比如查数据库、调用外部 API、发邮件等。假设你想让 AI 能帮用户查询天气ConfigurationpublicclassToolConfig{BeanDescription(获取指定城市的天气信息)publicFunctionWeatherRequest,WeatherResponsegetWeather(){returnrequest-{// 这里调用真实的天气 APIreturnnewWeatherResponse(request.city(),晴,22,适合户外活动);};}publicrecordWeatherRequest(Stringcity){}publicrecordWeatherResponse(Stringcity,Stringcondition,inttemperature,Stringsuggestion){}}然后在调用时启用工具ServicepublicclassAgentService{privatefinalChatClientchatClient;publicAgentService(ChatClient.BuilderchatClientBuilder){this.chatClientchatClientBuilder.defaultFunctions(getWeather)// 注册工具函数.build();}publicStringchatWithTool(StringuserMessage){returnchatClient.prompt().user(userMessage).call().content();}}当用户问“上海今天天气怎么样”时模型会识别出这是一个天气查询需求自动调用你注册的getWeather函数拿到结果后再组织成自然语言回复。这个能力在构建 AI Agent 时特别关键——它让模型不再是一个“只能聊天的花瓶”而是能真正和业务系统交互的智能体。八、MCPAI 应用的“下一个大事件”如果你关注 Spring AI 的版本动态一定会注意到MCP模型上下文协议这个词。这是 Spring AI 1.1 最重要的功能集改进。MCP 是 Anthropic 提出的一个开放协议本质上是给 AI 模型提供了一套标准化的工具接入规范。Spring AI 对 MCP 的支持相当全面提供了基于注解的编程模型和 Spring Boot 自动配置。创建 MCP Server让外部系统能被 AI 调用McpToolpublicStringgetOrderStatus(McpToolParam(description订单号)StringorderId){// 查询订单状态return订单 orderId 状态已发货;}McpResource(urifile:///db/schema.sql)publicStringgetDatabaseSchema(){// 返回数据库 schemareturnCREATE TABLE orders...;}加上 MCP Server 启动器依赖dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-mcp-server-webflux/artifactId/dependency创建 MCP Client让 AI 能调用这些工具ConfigurationpublicclassMCPClientConfig{BeanpublicMcpClientmcpClient(){returnMcpClient.sync(http://localhost:8080).requestTimeout(Duration.ofSeconds(30)).build();}}MCP 的价值在于标准化。以前你要给 AI 接一个工具得自己封装 HTTP 接口、处理认证、解析响应。有了 MCP这些都有统一规范AI Agent 可以自动发现和调用可用的工具。官方提供了多种传输选项——STDIO用于本地进程通信HTTP SSE用于 Web 集成还支持 WebFlux 和 WebMVC 两种模式。九、别踩这些坑这几条是我用 Spring AI 过程中真实踩过的坑希望能帮你省下好几个小时的 debug 时间。坑一artifact 名称变了。Spring AI 1.0 之后starter 模块的命名发生了重大变化。如果你看到老教程里的spring-ai-ollama-spring-boot-starter千万别直接用。正确的依赖是spring-ai-starter-model-ollama。坑二BOM 版本管理。官方强烈建议通过 BOM 统一管理版本不要分别指定各个模块的版本号。不同模块版本不一致会导致各种奇奇怪怪的方法找不到。坑三Ollama 没启动就调用。这个坑我踩了好几次。代码写得再漂亮如果 Ollama 服务没跑起来或者模型没下载完调用时会直接报Connection refused异常。运行前先用ollama list确认模型已下载用ollama ps确认服务在运行。坑四Embedding 模型维度不匹配。配置 PGVector 向量存储时dimensions参数必须和 Embedding 模型输出的向量维度一致。比如用all-MiniLM-L6-v2是 384 维用text-embedding-ada-002是 1536 维。配错了向量存不进去但错误信息往往不明显排查起来很头疼。坑五Spring AI 和 Spring Boot 版本要对应。官方文档明确写了支持 Spring Boot 3.4.x 和 3.5.x。如果你用的是 Spring Boot 2.x那抱歉Spring AI 跑不起来。十、写在最后说实话Spring AI 这个框架确实不完美。1.x 版本刚 GA 没多久有些功能还在完善中文档也谈不上详尽。但话说回来作为一个 Spring Boot 开发者能在自己熟悉的生态里做大模型应用而不用被迫切换到 Python这本身就是一件很爽的事情。Spring AI 的核心价值不是“能调模型”而是把 Spring 的工程化理念带到了 AI 场景里。依赖注入、自动配置、AOP、可观测性——这些你熟悉的东西现在都能用在 AI 应用上了。我自己的经验是从一个最简单的 Hello World 开始先跑通单次对话然后慢慢引入 ChatMemory 做多轮对话再试试结构化输出和 RAG给应用加上知识库和工具调用能力。一步一步来每往前走一步你都会对这个框架的理解更深一点。最后提一嘴版本选择如果你现在就动手实践用Spring AI 1.1.x搭配Spring Boot 3.4.x是目前最稳妥的组合。2.0 虽然新功能诱人但等它 GA 之后再升级也不迟。希望这篇教程能帮你少走一些弯路。如果你在搭建过程中遇到什么问题或者有什么好玩的实践想分享欢迎留言交流——毕竟Java 圈做大模型应用的人还是少数咱们更需要互相帮衬。