如果你是一名Java开发者看着铺天盖地的AI新闻和招聘JD上越来越多的“AI应用开发”、“Agent工程师”要求心里是不是有点慌感觉自己的技术栈突然不香了想学又不知从何下手——是去啃晦涩的论文还是从Python重头开始别急你的Java经验非但不是累赘反而是快速切入AI应用层的绝佳跳板。Spring AI和Spring AI Alibaba这两个框架的出现正是为了解决这个问题让Java开发者能用自己熟悉的Spring生态像集成一个数据库驱动一样去集成和调用大模型能力。这篇文章要解决的就是Java开发者转型AI应用开发最核心的困惑如何在不抛弃Spring技术栈的前提下快速、系统地上手大模型应用开发我们将围绕Spring AI和Spring AI Alibaba从环境搭建、核心概念、到RAG知识库、智能体Agent实战手把手带你跑通一个完整的AI应用。你会发现所谓的“AI大模型开发”其工程化部分和你熟悉的CRUD、微服务集成并无本质不同。1. 为什么Java开发者现在必须关注Spring AI不是制造焦虑而是看清趋势。大模型正在从“炫技”走向“落地”而落地的关键是将AI能力嵌入现有企业系统。这些系统尤其是金融、电信、政企等领域后端大量由Java构建。这意味着需求正在从“研究型AI科学家”向“工程型AI应用开发者”倾斜。Spring AI和Spring AI Alibaba扮演的就是“胶水”和“脚手架”的角色Spring AISpring官方项目提供了对接OpenAI、Azure OpenAI、Ollama等各类AI模型供应商的通用抽象和模板。它定义了ChatClient、EmbeddingClient、ImageClient等标准接口让开发者无需关心底层HTTP调用细节。Spring AI Alibaba阿里云在Spring AI标准之上提供的阿里云百炼、灵积等国产模型服务的深度集成。它更懂国内开发者的环境网络、合规、模型选择并提供了图形化编排Spring AI Alibaba Graph等高级特性。学习它们你获得的不是几个API调用技巧而是一套符合Spring哲学约定大于配置、依赖注入、模板模式的AI应用开发范式。你可以把大模型看作一个特殊的“数据源”或“服务”用Bean来配置用Autowired来注入用RestTemplate或WebClient那样的思维去使用。这极大地降低了认知门槛和集成成本。2. 核心概念快速理解告别玄学开始实操前必须厘清几个高频术语。它们不是魔法只是解决特定问题的工具。2.1 大模型LLM与提示词工程是什么大模型是一个经过海量文本训练的、能够理解和生成自然语言的复杂程序。你可以把它理解为一个拥有“世界知识”但需要明确指令的超级实习生。提示词工程就是给这位“实习生”写工作说明书Prompt。它的核心是通过精心设计的输入文本来引导模型输出高质量、符合预期的结果。这不是玄学而是有模式可循的例如角色设定“你是一位资深的Java架构师...”任务描述“请为以下需求设计一个微服务模块...”上下文提供“这是当前的数据库表结构...”输出格式约束“请以JSON格式输出包含serviceName,apiList等字段。”在Spring AI中提示词被封装为Prompt对象其中包含Message消息的集合。你可以方便地构建和复用各种提示词模板。2.2 RAG让大模型“读懂”你的私有数据大模型有知识盲区比如你公司内部的规章制度、产品手册和幻觉问题一本正经地胡说八道。RAG就是为了解决这个问题。全称检索增强生成。核心流程类比图书馆管理员索引将你的私有文档PDF、Word、数据库切块转换成向量一串数字表示语义存入向量数据库如Chroma、Milvus。这相当于给图书编目上架。检索当用户提问时将问题也转换成向量去向量数据库里查找最相关的几个文档片段。这相当于管理员根据问题去书架上找最相关的几本书。增强把找到的相关片段和用户原始问题一起组合成一个新的、信息更丰富的提示词交给大模型。生成大模型基于这个“问题参考资料”生成最终答案。答案的准确性和针对性大幅提升。在Spring AI中提供了VectorStore接口和RetrievalAugmentor等组件可以极简地实现整个RAG流程。2.3 Agent从“工具人”到“智能体”如果RAG是给模型“开书”那么Agent就是给模型“配工具箱”。是什么一个能理解用户目标、自主规划步骤、调用外部工具如搜索、计算、执行API来完成复杂任务的AI程序。核心思想“ReAct”模式Reasoning Acting。模型会先思考“要解决这个问题我需要先查天气再计算温差”再行动调用天气查询工具根据结果继续思考或给出最终答案。在Spring AI Alibaba中通过Tool注解你可以将任何一个Spring Bean的方法暴露为Agent可调用的工具。框架负责协调模型思考与工具执行的循环。2.4 Ollama本地部署大模型的利器对于不想或无法连接公有云API的开发者Ollama是福音。是什么一个用于在本地你的Mac、Windows、Linux机器上运行、管理和服务大型语言模型的工具。它简化了模型下载、加载和提供API接口的过程。常用模型llama3、qwen、mistral等开源模型。与Spring AI的关系Spring AI可以将Ollama作为一个模型提供商来连接让你用完全本地的方式开发AI应用保证数据隐私。3. 环境准备搭建你的AI开发工作台我们从一个最实用的组合开始Spring Boot Spring AI Ollama本地模型。这个组合能让你在断网环境下也能完成所有实验。3.1 基础环境JDK17 或 21推荐21长期支持版本。Maven3.6 或 Gradle。IDEIntelliJ IDEA首选或 VS Code with Java插件。操作系统Windows/macOS/Linux均可。3.2 安装并启动Ollama这是本地模型运行的核心。访问Ollama官网下载对应操作系统的安装包。如果下载慢可以使用国内镜像源加速。安装并启动。安装后Ollama服务通常会自动在后台运行默认端口11434。拉取模型。打开终端执行以下命令拉取一个中等尺寸的模型例如qwen2.5:7b约4.5GBollama pull qwen2.5:7b如果下载缓慢可以配置Ollama使用国内镜像源。验证运行。运行模型进行简单对话测试ollama run qwen2.5:7b在出现的提示符后输入“你好”看到模型回复即表示成功。3.3 创建Spring Boot项目使用 Spring Initializr 或IDE的创建向导。ProjectMavenLanguageJavaSpring Boot3.2.x 或 3.3.x确保与Spring AI版本兼容DependenciesSpring Web构建Web接口Spring AI核心AI能力Lombok选装简化代码生成的pom.xml中需要添加Spring AI的BOM物料清单和Ollama依赖。4. 项目配置与依赖管理这是关键一步版本不对很容易踩坑。4.1 添加Spring AI BOM在pom.xml的dependencyManagement部分添加以当前稳定版为例dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0-M5/version !-- 请检查最新稳定版 -- typepom/type scopeimport/scope /dependency /dependencies /dependencyManagementBOM会统一管理所有Spring AI相关组件的版本避免冲突。4.2 添加具体依赖在dependencies中添加dependencies !-- Spring Boot 基础依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring AI 核心 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-core/artifactId /dependency !-- Spring AI Ollama 连接器 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama-spring-boot-starter/artifactId /dependency !-- 向量数据库以内存向量库为例用于RAG -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-pgvector-store-spring-boot-starter/artifactId /dependency !-- 方便起见引入内存向量库仅用于演示 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-transformers-spring-boot-starter/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-chroma-store-spring-boot-starter/artifactId /dependency !-- Lombok -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies注意spring-ai-pgvector-store需要真实的PostgreSQL数据库。为了演示简便我们后续会先用内存向量库生产环境请务必替换。4.3 配置Ollama连接在application.yml或application.properties中配置# application.yml spring: ai: ollama: base-url: http://localhost:11434 # Ollama服务地址 chat: options: model: qwen2.5:7b # 指定使用的模型与pull的模型名一致 temperature: 0.7 # 创造性0-1越高越随机5. 第一行AI代码与本地大模型对话让我们写一个最简单的接口验证整个链路是否打通。5.1 创建Controllerpackage com.example.ai.demo.controller; import org.springframework.ai.chat.client.ChatClient; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; RestController public class ChatController { private final ChatClient chatClient; // ChatClient 会被Spring AI自动配置并注入 public ChatController(ChatClient chatClient) { this.chatClient chatClient; } GetMapping(/chat) public String chat(RequestParam(value message, defaultValue 你好) String message) { // 调用ChatClient进行对话 String response chatClient.prompt() .user(message) .call() .content(); return 模型回复: response; } }5.2 启动并测试确保Ollama服务正在运行且qwen2.5:7b模型已加载。启动你的Spring Boot应用。打开浏览器或使用curl测试http://localhost:8080/chat?message用Java写一个快速排序算法你应该能看到模型返回的Java代码。恭喜你的Java应用已经成功调用了本地大模型这短短几行代码的意义你没有处理任何HTTP请求细节没有解析JSON只是通过一个注入的ChatClient接口就完成了对话。这就是Spring AI的威力——将AI能力基础设施化。6. 构建你的第一个RAG知识库现在我们来解决“模型不懂内部知识”的问题。假设我们想做一个公司产品FAQ助手。6.1 准备知识文档创建一个文本文件product_faq.txt放在src/main/resources目录下内容如下产品A是一款智能客服系统支持多渠道接入包含工单管理、知识库和机器人功能。 产品A的定价分为三个版本基础版99元/坐席/月、专业版199元、企业版需联系销售。 产品B是一款低代码开发平台主要用于快速构建企业内部审批流和报表系统。 产品B目前仅提供企业版许可按年度订阅。 公司技术支持电话是400-xxx-xxxx工作时间为工作日9:00-18:00。6.2 创建RAG服务我们将使用内存向量库InMemoryVectorStore来演示避免引入外部数据库的复杂度。package com.example.ai.demo.service; import jakarta.annotation.PostConstruct; import lombok.RequiredArgsConstructor; import org.springframework.ai.document.Document; import org.springframework.ai.reader.TextReader; import org.springframework.ai.transformer.splitter.TokenTextSplitter; import org.springframework.ai.vectorstore.InMemoryVectorStore; import org.springframework.ai.vectorstore.SearchRequest; import org.springframework.ai.vectorstore.VectorStore; import org.springframework.core.io.Resource; import org.springframework.core.io.ResourceLoader; import org.springframework.stereotype.Service; import java.util.List; import java.util.stream.Collectors; Service RequiredArgsConstructor public class RagService { private final ResourceLoader resourceLoader; private final InMemoryVectorStore vectorStore; // Spring AI会自动配置一个内存向量库Bean /** * 初始化加载文档、切分、转换为向量并存储 */ PostConstruct public void init() { // 1. 加载资源文件 Resource resource resourceLoader.getResource(classpath:product_faq.txt); // 2. 使用文本阅读器解析 TextReader textReader new TextReader(resource); ListDocument documents textReader.get(); // 3. 文本分割防止文档过长 TokenTextSplitter splitter new TokenTextSplitter(); ListDocument splitDocuments splitter.apply(documents); // 4. 存入向量库 vectorStore.add(splitDocuments); System.out.println(知识库初始化完成加载了 splitDocuments.size() 个文本块。); } /** * 检索根据问题查找相关文档片段 */ public ListDocument retrieve(String query) { // 搜索最相关的3个片段 SearchRequest request SearchRequest.query(query).withTopK(3); return vectorStore.similaritySearch(request); } /** * 构建增强提示词将检索结果和用户问题结合 */ public String buildAugmentedPrompt(String userQuery, ListDocument relevantDocs) { String context relevantDocs.stream() .map(Document::getContent) .collect(Collectors.joining(\n\n)); return 请根据以下上下文信息回答问题。如果上下文信息不足以回答问题请直接说“根据现有资料无法回答”。 上下文 %s 问题%s 答案 .formatted(context, userQuery); } }6.3 创建增强的聊天接口修改之前的ChatController注入RagService。package com.example.ai.demo.controller; import com.example.ai.demo.service.RagService; import lombok.RequiredArgsConstructor; import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.document.Document; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import java.util.List; RestController RequiredArgsConstructor public class EnhancedChatController { private final ChatClient chatClient; private final RagService ragService; GetMapping(/chat/rag) public String chatWithRag(RequestParam String message) { // 1. 检索相关文档 ListDocument relevantDocs ragService.retrieve(message); // 2. 构建增强提示词 String augmentedPrompt ragService.buildAugmentedPrompt(message, relevantDocs); // 3. 调用模型 String response chatClient.prompt() .user(augmentedPrompt) .call() .content(); return String.format( 问题%s 参考上下文%s --- 答案%s , message, relevantDocs.stream().map(Document::getContent).toList(), response); } }6.4 测试RAG效果重启应用访问http://localhost:8080/chat/rag?message产品A多少钱一个月观察返回结果。模型应该能准确从我们提供的TXT文件中找到定价信息并回答。再问一个文件外的问题比如“产品C是什么”模型应该回答“根据现有资料无法回答”。至此一个最简可用的RAG系统已经完成。你可以将TextReader替换为PdfReader、MarkdownReader来支持更多格式将InMemoryVectorStore替换为ChromaVectorStore或PgVectorStore来持久化向量数据。7. 进阶实战用Spring AI Alibaba Graph构建智能体工作流当任务变得复杂需要多步骤决策和工具调用时就需要Agent。Spring AI Alibaba Graph提供了一个可视化的方式来编排AI智能体工作流。7.1 引入Spring AI Alibaba依赖在pom.xml中添加dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-spring-boot-starter/artifactId version1.0.0-M1/version !-- 请查看最新版本 -- /dependency7.2 配置阿里云灵积模型在application.yml中增加配置需要阿里云账号和API Keyspring: ai: alibaba: chat: enabled: true base-url: https://dashscope.aliyuncs.com/compatible-mode/v1 api-key: ${ALIBABA_API_KEY:你的API_KEY} # 建议使用环境变量 options: model: qwen-max # 或其他阿里云模型7.3 定义一个工具Tool假设我们有一个查询用户订单状态的服务。package com.example.ai.demo.tools; import org.springframework.ai.alibaba.tool.annotation.Tool; import org.springframework.stereotype.Component; Component public class OrderTools { Tool(description 根据订单ID查询订单状态。订单ID格式为ORD-2024-XXXXX) public String queryOrderStatus(String orderId) { // 这里模拟一个数据库或服务调用 // 实际项目中这里可能是FeignClient调用或MyBatis查询 if (orderId.startsWith(ORD-2024-1001)) { return 订单状态已发货物流单号SF123456789; } else if (orderId.startsWith(ORD-2024-1002)) { return 订单状态待付款; } else { return 未找到订单ID: orderId; } } Tool(description 计算商品总价。参数单价元数量) public double calculateTotalPrice(double unitPrice, int quantity) { return unitPrice * quantity; } }Tool注解会将该方法注册到AI模型的“工具箱”中。7.4 创建Graph工作流编程式Spring AI Alibaba Graph支持DSL编程式定义和YAML声明式定义。这里展示编程式package com.example.ai.demo.graph; import com.alibaba.cloud.ai.graph.Graph; import com.alibaba.cloud.ai.graph.node.agent.AgentNode; import com.alibaba.cloud.ai.graph.node.tool.ToolNode; import org.springframework.ai.alibaba.chat.AlibabaChatModel; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class CustomerServiceGraphConfig { Bean public Graph customerServiceGraph(AlibabaChatModel chatModel, OrderTools orderTools) { return Graph.builder() .addNode(AgentNode.builder() .id(classifier) .model(chatModel) .prompt( 你是一个客服请求分类器。 用户输入可能是1. 查询订单 2. 计算价格 3. 其他咨询。 请只输出一个分类数字1, 2, 或 3。 用户输入{input} ) .outputKey(category)) .addNode(ToolNode.builder() .id(queryOrder) .tool(orderTools, queryOrderStatus) .inputKey(orderId) // 需要从上游获取orderId .outputKey(orderStatus)) .addNode(AgentNode.builder() .id(responseBuilder) .model(chatModel) .prompt( 你是客服助手。根据分类和工具执行结果生成友好回复。 分类{category} 工具结果{toolResult} 原始用户问题{input} 请生成最终回复。 ) .outputKey(finalResponse)) // TODO: 需要添加路由逻辑根据category决定走向queryOrder还是其他节点 .build(); // 注这是一个简化示例完整的Graph需要定义边Edges和路由来决定执行流程。 } }注意完整的工作流需要定义节点之间的连接关系边和路由条件。Spring AI Alibaba Graph提供了强大的可视化编辑器但编程式定义更灵活。对于复杂流程建议结合使用。7.5 调用Graph创建一个Service来执行这个Graphpackage com.example.ai.demo.service; import com.alibaba.cloud.ai.graph.Graph; import com.alibaba.cloud.ai.graph.GraphResponse; import lombok.RequiredArgsConstructor; import org.springframework.stereotype.Service; import java.util.Map; Service RequiredArgsConstructor public class GraphService { private final Graph customerServiceGraph; // 注入上面定义的Graph public String processCustomerRequest(String userInput) { // 构建输入 MapString, Object inputs Map.of(input, userInput); // 执行Graph GraphResponse response customerServiceGraph.execute(inputs); // 获取最终输出 return (String) response.getOutput(finalResponse); } }然后就可以在Controller中调用这个Service。当用户输入“帮我查一下订单ORD-2024-1001的状态”时Graph会先由分类Agent判断意图然后路由到queryOrder工具节点执行查询最后由回复Agent整合信息生成最终答案。8. 常见问题与排查指南在整合过程中你大概率会遇到以下问题。问题现象可能原因排查方式解决方案启动报错Failed to configure a DataSource引入了需要数据源的starter如pgvector但未配置数据库。检查pom.xml中的依赖和application.yml配置。1. 排除相关依赖exclusion。2. 配置正确的数据库连接信息。3. 使用内存向量库InMemoryVectorStore做演示。调用/chat接口超时或连接拒绝Ollama服务未启动或端口不对。1. 终端执行ollama list查看模型。2. 访问http://localhost:11434看是否通。1. 启动Ollama服务。2. 检查spring.ai.ollama.base-url配置。3. 确认模型已下载ollama pull。模型回复乱码或非中文模型本身对中文支持不好或Prompt未指定语言。检查模型是否支持中文如qwen系列。1. 换用对中文友好的模型如qwen2.5:7b。2. 在Prompt中明确要求用中文回复。RAG检索结果不相关文本分割策略不当或Embedding模型不适合。1. 查看splitter分割后的文本块是否合理。2. 检查检索到的文档内容。1. 调整TokenTextSplitter的块大小和重叠度。2. 尝试不同的Embedding模型Spring AI支持多种。3. 优化检索的topK参数。Spring AI Alibaba Graph报No such nodeGraph节点ID配置错误或路由边未正确定义。仔细检查Graph DSL或YAML中节点的id和inputKey/outputKey。使用IDE的图形化工具如果可用或打印Graph结构来调试节点连接。依赖版本冲突Spring Boot、Spring AI、Spring AI Alibaba版本不兼容。查看启动日志中的Description或使用mvn dependency:tree。1.严格遵守官方文档的版本对应关系。2. 使用Spring AI BOM统一管理版本。3. 排除冲突的传递依赖。9. 生产环境最佳实践与学习路线将Demo变成可上线的系统还需要考虑很多工程问题。9.1 安全与合规API密钥管理永远不要将api-key硬编码在代码或配置文件中。使用环境变量、配置中心如Nacos、Apollo或云厂商的密钥管理服务。输入输出过滤对用户输入和模型输出进行必要的敏感词过滤和内容审核防止滥用。权限控制AI能力接口应纳入统一的API网关和认证授权体系。9.2 性能与稳定性向量数据库选型InMemoryVectorStore仅用于开发。生产环境选择PgVector与PostgreSQL集成、Chroma开源专用、Milvus高性能分布式或云服务。缓存策略对常见的用户问答对进行缓存减少对模型和向量库的调用提升响应速度并降低成本。限流与降级对AI服务接口实施限流防止突发流量击垮模型服务。当主要模型服务不可用时应有降级方案如返回静态FAQ。异步处理对于耗时的文档解析、向量化入库操作应采用异步任务如SpringAsync避免阻塞主线程。9.3 可观测性链路追踪集成Micrometer、SkyWalking等追踪一次AI调用经过的各个组件模型、向量库、工具。日志与监控详细记录Prompt、模型响应、Token使用量、耗时。监控模型服务的可用性和延迟。效果评估设计机制评估RAG检索的相关性、答案的准确性持续优化提示词和文档质量。9.4 持续学习路线建议巩固基础深入理解Spring AI的核心接口ChatClient、EmbeddingClient、VectorStore阅读其源码设计。掌握提示词系统学习提示词设计模式Chain of Thought, Few-Shot等这是成本最低的优化手段。深入RAG研究更高级的RAG技术如HyDE生成假设文档再检索、Rerank对检索结果重排序、多向量检索等。玩转Agent学习ReAct、Plan-and-Execute等智能体范式尝试用Graph编排复杂的业务工作流。关注生态Spring AI生态在快速演进关注对Function Calling、Structured Output、Evals评估等新特性的支持。工程化拓展将AI能力与你的微服务、消息队列、定时任务等现有系统深度集成解决真实的业务痛点。从Java开发者到AI应用开发者最大的障碍不是技术而是思维转换。你不需要成为训练模型的专家但要成为利用模型解决业务问题的工程师。Spring AI和Spring AI Alibaba为你铺平了这条路。现在就从运行文中的第一个示例开始亲手感受AI能力如何像流水一样注入你的Spring应用。