1. 项目概述为什么2026年的Java开发者必须拥抱Spring AI如果你是一位Java开发者最近可能被各种AI新闻和工具搞得有点焦虑。感觉全世界都在用Python搞大模型Java的生态似乎慢了半拍。别急这种局面正在被彻底改变。Spring AI项目的出现就像是给Java这座稳重的大厦装上了最先进的智能引擎。它不是一个简单的SDK包装而是一个旨在将生成式AI能力深度、优雅地集成到Spring Boot应用中的官方项目。这意味着你熟悉的依赖注入、自动配置、模板抽象等Spring哲学现在可以无缝应用到AI开发领域。到2026年AI能力将不再是应用的“加分项”而是像数据库连接、HTTP请求处理一样的“基础设施”。无论是为电商系统增加一个智能客服聊天窗口还是为内容平台构建一个自动摘要生成服务亦或是开发一个能理解用户意图的智能助手Agent这些都将成为Java后端开发的常规需求。Spring AI的目标就是让Java开发者无需深入钻研Python和复杂的AI框架细节就能以自己最擅长的方式快速、可靠地构建生产级的AI应用。它解决了模型接口不统一、配置复杂、提示词管理混乱、上下文处理棘手等核心痛点让开发者能聚焦于业务逻辑本身。2. Spring AI核心架构与设计哲学解析2.1 统一抽象的“连接器”模型Spring AI最核心的设计在于其抽象层。它没有把自己绑定在某个特定的AI模型提供商如OpenAI、Anthropic上而是定义了一套统一的API接口主要是ChatClient和EmbeddingClient。你可以把这套接口理解为Java数据库连接中的JDBC。无论底层用的是MySQL、PostgreSQL还是Oracle上层的Java代码写法都大同小异。Spring AI也是如此无论你背后调用的是OpenAI的GPT-4、Anthropic的Claude还是开源的Llama 3、通义千问甚至是本地部署的模型对于业务代码来说调用的方式几乎是一致的。这种设计带来了巨大的灵活性。今天你的应用可能基于成本考虑使用GPT-3.5-Turbo明天可能因为数据安全要求切换到本地部署的Llama 3。在Spring AI架构下你通常只需要在application.yml中更改一下配置项比如把spring.ai.openai.api-key换成spring.ai.ollama.base-url业务代码几乎无需改动。这极大地降低了技术锁定的风险也使得A/B测试不同模型的性能效果变得非常简单。2.2 提示词Prompt工程模板化与模型交互的核心是“提示词”Prompt。写一个好的提示词就像是在和一位才华横溢但有点“轴”的外国专家沟通需要清晰的指令、充足的上下文和明确的格式要求。在原始开发中提示词常常以字符串拼接的方式散落在代码中难以维护和复用。Spring AI引入了PromptTemplate的概念这类似于Spring MVC中的视图模板如Thymeleaf。你可以将提示词定义在一个模板文件中其中包含变量占位符。例如一个用于文本总结的模板可能长这样请为以下文章生成一个简洁的摘要要求不超过{maxLength}个字。 文章标题{title} 文章内容{content}在代码中你只需要注入PromptTemplate并通过create()方法传入一个Map来填充变量。这种方式不仅使提示词管理变得清晰还便于进行国际化为不同语言用户提供不同风格的提示词和版本控制。2.3 结构化输出与函数调用Function Calling集成让AI模型返回一个结构化的JSON对象而不是一段自由文本是构建可靠应用的关键。例如你希望模型从一段用户反馈中提取“实体”如产品名、问题类型、情感倾向并填充到一个预定义的Java Bean中。Spring AI通过OutputSchema注解和StructuredOutputConverter提供了开箱即用的支持。更强大的是它对“函数调用”的深度集成。你可以将你的业务方法如“查询订单状态”、“创建待办事项”注册为模型可以调用的“工具”。当用户的自然语言请求涉及这些操作时模型会主动请求调用相应的函数并将执行结果返回给模型由模型组织成最终的自然语言回复给用户。这为实现真正的“智能体”Agent——能够感知、规划、执行复杂任务的AI系统——奠定了坚实基础。Spring AI将这些交互封装得非常简洁你只需要定义好工具接口和实现剩下的路由和调用逻辑由框架处理。3. 从零开始构建你的第一个Spring AI应用3.1 环境准备与项目初始化我们从一个最经典的场景开始构建一个智能聊天服务。假设你使用IntelliJ IDEA或VS Code并且已经安装了JDK 17或更高版本Spring AI 2.x 推荐使用JDK 21以获得最佳性能。首先通过 Spring Initializr 创建项目。关键依赖选择如下Spring Web提供RESTful API能力。Spring AI OpenAI这是我们连接OpenAI模型的“连接器”starter。如果你计划使用其他模型如Azure OpenAI、Anthropic Claude或Ollama本地模型则选择对应的starter例如spring-ai-azure-openai-spring-boot-starter。Lombok可选但推荐减少样板代码。生成的pom.xml中会包含类似下面的依赖dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency接下来你需要获取一个API密钥。如果你使用OpenAI请前往其平台创建。安全提示永远不要将API密钥硬编码在代码或提交到版本库中。正确做法是将其配置在环境变量或Spring Boot的配置文件中。在application.yml中配置spring: ai: openai: api-key: ${OPENAI_API_KEY:你的测试密钥} # 优先从环境变量OPENAI_API_KEY读取 chat: options: model: gpt-3.5-turbo # 默认使用的模型可根据需要改为gpt-4等这里${OPENAI_API_KEY}是环境变量引用在生产环境中你应在服务器或容器环境中设置该变量。3.2 核心服务层开发与AI对话创建一个服务类ChatService它将封装与AI交互的核心逻辑。import org.springframework.ai.chat.client.ChatClient; import org.springframework.stereotype.Service; import lombok.RequiredArgsConstructor; Service RequiredArgsConstructor public class ChatService { private final ChatClient chatClient; public String chat(String message) { return chatClient.prompt() .user(message) // 用户输入 .call() // 发起调用 .content(); // 获取文本回复 } public String chatWithSystemPrompt(String userMessage) { // 更复杂的交互加入系统指令设定AI的角色 return chatClient.prompt() .system(你是一位资深的Java技术专家回答要专业且简洁。) // 系统指令 .user(userMessage) .call() .content(); } }ChatClient是Spring AI自动配置注入的核心Bean。chatClient.prompt()流式API的调用方式非常直观支持链式调用清晰地分离了系统指令、用户消息、上下文等角色。3.3 控制器层与API暴露创建一个简单的REST控制器来提供HTTP接口。import org.springframework.web.bind.annotation.*; import lombok.RequiredArgsConstructor; RestController RequestMapping(/api/ai) RequiredArgsConstructor public class ChatController { private final ChatService chatService; PostMapping(/chat) public String chat(RequestBody ChatRequest request) { return chatService.chat(request.getMessage()); } // 简单的请求体 public record ChatRequest(String message) {} }现在启动你的Spring Boot应用。你可以使用curl、Postman或任何HTTP客户端向http://localhost:8080/api/ai/chat发送一个POST请求Body为{message: 用Java写一个快速排序算法}几秒钟内你就会收到一个格式工整的Java代码回复。实操心得模型选择与成本控制在application.yml中配置的model是关键。对于代码生成、逻辑推理等复杂任务gpt-4或gpt-4-turbo效果显著更好但价格昂贵。对于简单的聊天、文本转换gpt-3.5-turbo性价比极高。在项目初期建议在配置文件中将模型设置为可动态切换的参数如spring.ai.openai.chat.options.model${AI_MODEL:gpt-3.5-turbo}方便根据不同的环境开发/测试/生产或功能模块进行切换和成本评估。4. 进阶实战构建具备记忆与工具的智能体Agent一个只会单轮对话的AI用处有限。真正的价值在于能进行多轮交互、记住上下文、并能调用外部工具完成任务的智能体。下面我们构建一个简单的“会议纪要助手”Agent。4.1 设计系统提示与工具这个Agent的目标是用户可以用自然语言描述会议讨论点Agent能结构化地记录并在用户询问时进行总结。首先我们定义一个工具接口用于“记录会议条目”。import org.springframework.ai.tool.annotation.Tool; import org.springframework.stereotype.Component; import java.util.concurrent.ConcurrentHashMap; Component public class MeetingNoteTool { private final MapString, ListString meetingNotes new ConcurrentHashMap(); Tool(description 记录一条会议讨论要点到指定的会议记录中。) public void addNote( ToolParam(description 会议的唯一标识ID) String meetingId, ToolParam(description 要记录的讨论要点内容) String note) { meetingNotes.computeIfAbsent(meetingId, k - new ArrayList()).add(note); System.out.printf(已为会议[%s]记录要点%s%n, meetingId, note); } Tool(description 获取指定会议的所有记录要点。) public ListString getNotes(ToolParam(description 会议的唯一标识ID) String meetingId) { return meetingNotes.getOrDefault(meetingId, List.of()); } }Tool注解告诉Spring AI这是一个可被模型调用的工具。ToolParam注解为参数提供描述帮助模型理解何时以及如何调用它。4.2 配置智能体与上下文管理接下来我们配置一个具备记忆能力的ChatClient。Spring AI内置了多种记忆存储实现如简单的InMemoryChatMemory或可持久化的VectorStoreChatMemory。这里使用内存版本。import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.chat.memory.InMemoryChatMemory; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class AgentConfig { Bean public ChatClient meetingAgent(ChatClient.Builder builder, MeetingNoteTool noteTool) { InMemoryChatMemory memory new InMemoryChatMemory(); // 创建内存记忆体 return builder .defaultSystemPrompt( 你是专业的会议纪要助手。你的任务是 1. 当用户描述会议讨论内容时主动调用工具将其记录下来。 2. 当用户询问会议内容时调用工具查询并总结。 3. 保持对话友好、专业。 ) .defaultTools(noteTool) // 注册工具 .defaultMemory(memory) // 启用记忆 .build(); } }defaultMemory(memory)是关键它使得本次对话的所有历史消息包括AI的回复和工具调用结果都会被自动记录并作为上下文在下一轮对话中发送给模型从而实现多轮对话的连贯性。4.3 实现智能体服务与交互创建一个使用这个智能体的服务。Service public class MeetingAgentService { private final ChatClient meetingAgent; public MeetingAgentService(Qualifier(meetingAgent) ChatClient meetingAgent) { this.meetingAgent meetingAgent; } public String interact(String sessionId, String userInput) { // 在调用时传入sessionId记忆体会根据此ID隔离不同会话的上下文 return meetingAgent.prompt() .user(userInput) .options(ChatOptionsBuilder.builder() .withMemoryId(sessionId) // 绑定会话ID .build()) .call() .content(); } }现在当你通过控制器调用interact(“project-review-001”, “我们今天讨论了Spring AI的项目架构决定采用统一抽象层。”)Agent会理解意图自动调用addNote工具进行记录。接着你再问“project-review-001会议的要点有哪些”它会调用getNotes工具获取记录并组织成一段总结性回复。注意事项Token限制与记忆管理大模型有上下文窗口限制如GPT-4通常是128K tokens。InMemoryChatMemory会无限制地增长历史记录可能导致后续请求因超长而失败。生产环境中你需要使用WindowChatMemory只保留最近N条消息或SummaryChatMemory定期将旧对话总结成一段摘要。务必根据模型的实际上下文长度和你的对话复杂度来配置记忆策略这是避免“对话失忆”或请求失败的关键。5. 向量数据库集成实现私有知识库问答当你的AI应用需要处理公司内部文档、产品手册等非公开信息时就需要“检索增强生成”RAG技术。其核心是将私有文档切片、向量化后存入向量数据库在提问时先从中检索相关片段再连同问题和片段一起发给模型生成答案。5.1 文档加载与向量化Spring AI提供了统一的DocumentReader和VectorStore接口。我们以处理PDF文件并存入PGVectorPostgreSQL的向量扩展为例。首先添加依赖dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-pdf-document-reader/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-pgvector-store/artifactId /dependency dependency groupIdorg.postgresql/groupId artifactIdpostgresql/artifactId /dependency配置数据源和Vector Storespring: datasource: url: jdbc:postgresql://localhost:5432/vectordb username: postgres password: yourpassword ai: vectorstore: pgvector: index-type: HNSW # 使用HNSW索引加速相似性搜索 dimensions: 1536 # OpenAI text-embedding-3-small的向量维度编写文档入库服务import org.springframework.ai.reader.pdf.PagePdfDocumentReader; import org.springframework.ai.transformer.splitter.TokenTextSplitter; import org.springframework.ai.vectorstore.VectorStore; import org.springframework.core.io.Resource; import org.springframework.stereotype.Service; import java.io.IOException; Service RequiredArgsConstructor public class DocumentEmbeddingService { private final VectorStore vectorStore; public void embedDocument(Resource pdfResource) throws IOException { // 1. 读取PDF每页作为一个Document PagePdfDocumentReader pdfReader new PagePdfDocumentReader(pdfResource); ListDocument documents pdfReader.get(); // 2. 文本分割防止单段过长 TokenTextSplitter splitter new TokenTextSplitter(500, 100, 10, 1000); // 参数块大小、重叠大小等 ListDocument splitDocs splitter.apply(documents); // 3. 调用Embedding模型向量化并存储 vectorStore.add(splitDocs); } }TokenTextSplitter的参数需要仔细调优块大小决定了每个向量片段的文本长度太小会丢失上下文太大会降低检索精度。重叠大小可以避免在句子中间被切断导致语义断裂。5.2 实现RAG检索与问答链文档入库后实现问答服务。Service RequiredArgsConstructor public class RagQaService { private final VectorStore vectorStore; private final ChatClient chatClient; public String answerQuestion(String question) { // 1. 相似性检索从向量库中找到与问题最相关的文档片段 ListDocument relevantDocs vectorStore.similaritySearch(question); // 2. 构建包含上下文的提示词 String context relevantDocs.stream() .map(Doc::getContent) .collect(Collectors.joining(\n\n)); PromptTemplate promptTemplate new PromptTemplate( 请基于以下上下文信息回答问题。如果上下文信息不足以回答问题请直接说“根据提供的信息无法回答”。 上下文 {context} 问题{question} 答案 ); Prompt prompt promptTemplate.create(Map.of( context, context, question, question )); // 3. 调用Chat模型生成答案 return chatClient.prompt(prompt).call().content(); } }5.3 效果优化与调参实战简单的RAG可能效果不佳常见问题及优化策略如下检索不准问题“Spring AI如何配置记忆”可能检索到关于“Spring Boot内存配置”的无关段落。优化方法尝试不同的Embedding模型。OpenAI的text-embedding-3-large比small版本在语义区分上通常更精确尽管向量维度更高、成本更贵。也可以尝试开源模型如BAAI/bge-large-zh针对中文优化。调整检索数量similaritySearch(question, k)中的k值。一开始可以设为5观察返回的片段质量如果前3个都不相关可能需要优化嵌入模型或文档预处理。答案胡编乱造幻觉即使提供了上下文模型仍可能生成不存在于上下文中的信息。优化方法强化系统提示词。在提示词中明确指令“你的回答必须严格、仅基于提供的上下文。不要在答案中添加任何上下文之外的知识。” 同时可以要求模型在答案中引用来源片段的序号便于人工复核。上下文过长导致核心信息被稀释当检索到多个长片段时关键信息可能被淹没。优化方法采用“重排序”Re-ranking策略。先使用向量检索召回较多的候选片段如20个再用一个专门的、轻量级的重排序模型如BAAI/bge-reranker-large对这些片段针对问题进行相关性打分只保留Top-K个最相关的片段送入大模型。Spring AI目前原生支持尚在完善但你可以通过组合ChatClient调用重排序模型的API来实现这一流程。踩坑记录向量维度对齐这是一个极易出错的地方。不同的Embedding模型产生的向量维度不同如OpenAI text-embedding-ada-002是1536维text-embedding-3-large是3072维。你在配置spring.ai.vectorstore.pgvector.dimensions以及创建数据库向量字段时必须确保维度数与实际使用的Embedding模型输出完全一致否则存储和检索都会失败。最佳实践是将维度数作为配置文件中的一个变量与Embedding模型的选择联动配置。6. 生产环境部署与性能调优指南将Spring AI应用投入生产需要考虑的远不止功能实现。6.1 配置管理、安全与监控API密钥管理绝对不要提交到代码库。使用Spring Cloud Config、HashiCorp Vault或云服务商如AWS Secrets Manager, Azure Key Vault的秘密管理服务。在Kubernetes中使用Secret资源。请求超时与重试AI API调用可能因网络或模型服务方不稳定而失败。务必配置合理的超时和重试策略。spring: ai: openai: client: connect-timeout: 10s read-timeout: 30s # 生成长文本需要更长时间 max-attempts: 3 # 失败重试次数限流与熔断使用Resilience4j或Sentinel为AI服务调用添加熔断器防止因下游服务缓慢或失败导致自身线程池耗尽。同时根据AI服务商的费率限制在应用层或网关层实施限流。监控与可观测性集成Micrometer将AI调用的耗时、Token使用量输入/输出、成功率等关键指标暴露给Prometheus和Grafana。监控Token消耗是成本控制的核心。6.2 性能优化策略异步与非阻塞AI调用是典型的I/O密集型操作。务必使用Spring WebFlux响应式编程或Async注解将AI调用异步化避免阻塞Web容器线程大幅提升应用吞吐量。Async public CompletableFutureString asyncChat(String message) { return CompletableFuture.completedFuture(chatClient.prompt().user(message).call().content()); }流式响应Streaming对于生成较长文本的场景如生成报告、长文翻译使用流式响应可以极大改善用户体验实现“打字机”效果。Spring AI的ChatClient支持返回FluxChatResponse。GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString streamChat(String message) { return chatClient.prompt() .user(message) .stream() .map(ChatResponse::getOutput) // 或 .getContent() .map(content - content.replace(\n, br/)); // 简单处理换行 }缓存策略对于常见、重复的问题如产品FAQ其答案相对固定。可以将“问题”的Embedding向量或哈希值作为Key将生成的答案缓存起来使用Redis或Caffeine。下次遇到相似问题时先检查缓存命中则直接返回能显著降低成本和延迟。6.3 成本控制与模型选型AI API调用是应用的主要可变成本。必须建立成本意识监控与告警实时监控Token消耗并设置每日/每周预算告警。分级策略根据功能重要性采用不同模型。核心功能用高性能模型如GPT-4边缘或实验性功能用低成本模型如GPT-3.5-Turbo或开源模型。开源模型本地部署对于数据敏感或长期成本考量高的场景使用Ollama、LocalAI等工具在本地或私有云部署Llama 3、Qwen等开源模型通过Spring AI的Ollama连接器调用实现零API成本。虽然需要自己维护基础设施但长期来看可控性更强。7. 常见问题排查与调试技巧实录在实际开发中你肯定会遇到各种“坑”。这里记录一些典型问题及其解决思路。问题1调用AI API返回超时或连接被拒绝。排查步骤检查网络确保服务器能访问外部AI服务地址如api.openai.com。在公司内网环境下代理设置是常见问题。Spring AI的HTTP客户端通常遵循JVM或Spring环境的标准代理配置。检查配置确认spring.ai.openai.api-key配置正确且未过期。密钥错误通常会返回401状态码。查看日志开启Spring AI的Debug日志logging.level.org.springframework.aiDEBUG查看详细的HTTP请求和响应信息。调整超时如6.1节所述适当增加read-timeout特别是使用gpt-4生成长文本时。问题2模型回复内容不符合预期比如不遵循系统指令。排查步骤检查提示词首先确认系统提示词system()是否被正确设置。流式API调用中system()必须在user()之前。检查消息顺序确保对话历史记忆中的消息角色user,assistant,system顺序正确没有错乱。调整温度Temperature通过ChatOptions设置temperature参数。该值越高接近1.0回复越随机、有创造性越低接近0回复越确定、保守。对于需要严格遵循指令的任务将其设为0.1或0.2。使用更强大的模型如果gpt-3.5-turbo经常“不听话”尝试切换到gpt-4它在遵循复杂指令方面能力显著更强。问题3使用向量数据库进行RAG时检索到的文档完全不相关。排查步骤检查Embedding一致性确保入库文档和查询问题时使用的是同一个Embedding模型。混合使用不同模型产生的向量没有可比性。检查向量维度确认数据库表结构中向量字段的维度数与实际模型输出维度一致。可视化分析进阶对少量样本数据可以将查询问题和文档片段的向量通过PCA或t-SNE降维后画图直观查看它们在向量空间中的距离。如果问题向量和所有文档向量聚在不同区域说明Embedding模型可能不适合你的领域需要微调或更换。尝试关键词检索作为兜底在向量检索的同时可以并行一个基于BM25等算法的传统关键词检索。如果向量检索Top结果的相关性得分都低于某个阈值则降级到使用关键词检索的结果或对两者结果进行融合。问题4智能体Agent陷入循环或重复调用工具。原因与解决这通常是由于系统提示词不够清晰或模型对任务规划能力不足导致。强化指令在系统提示词中明确限制工具调用的条件和次数。例如“在获得所需信息后必须停止调用工具直接给出最终答案。”结构化输出约束要求模型在每次思考后必须输出一个特定JSON结构包含“是否调用工具”、“调用哪个工具”、“工具参数”和“最终答案”等字段然后在代码中解析并执行。这给了你更强的控制逻辑。设置超时和最大步数在Agent执行循环中设置最大迭代次数如10步超过则强制终止避免无限循环消耗资源。从简单的聊天集成到复杂的智能体与RAG系统Spring AI为Java开发者铺平了通往AI应用开发的道路。它最大的价值在于将AI能力“Spring化”让你能用熟悉的模式和工具解决新的问题。2026年掌握Spring AI不再是前瞻而是Java后端开发者保持竞争力的必备技能。开始动手吧从一个简单的/chat接口出发逐步探索其强大的抽象能力和生态集成你会发现为你的应用注入智能比想象中要简单得多。
