1. 项目概述为什么我们需要“潜入”Spring AI如果你是一名Java开发者最近肯定没少听到“AI”、“大模型”、“智能应用”这些词。从ChatGPT引爆市场开始整个技术圈都在思考如何将大模型的强大能力集成到自己的应用中。然而当你真正动手时往往会发现一个尴尬的局面官方SDK如OpenAI、Anthropic的虽然强大但它们是语言无关的你需要处理HTTP请求、JSON解析、错误重试、流式响应等一系列繁琐的底层细节。更头疼的是一旦你想切换一个模型提供商或者同时支持多个模型代码就会变得臃肿且难以维护。这就是qifan777/dive-into-spring-ai这个项目存在的意义。它不是一个全新的框架而是一个深度实践指南旨在带领开发者“潜入”Spring AI这个官方项目探索如何利用Spring生态的优雅与高效来构建企业级的AI应用。Spring AI是Spring官方在2023年底推出的一个项目它的目标很明确为Java开发者提供一套统一的、声明式的API来集成各种AI大模型服务就像Spring Data统一了数据库访问Spring AI试图统一AI模型的调用。这个项目仓库的名字“dive-into”已经说明了它的性质——它不是浅尝辄止的Hello World而是深入原理、剖析源码、分享最佳实践的“潜水”之旅。它适合那些已经对Spring Boot有基本了解并且迫切希望将AI能力落地到实际业务中的开发者。通过跟随这个项目的探索你将学会的不仅仅是如何调用一个API而是如何设计一个健壮、可扩展、易于测试的AI赋能应用架构。2. 核心架构与设计哲学解析Spring AI的核心设计哲学深深植根于Spring框架一贯的“约定大于配置”和“面向接口编程”的理念。理解这一点是高效使用它的关键。2.1 统一的ChatClient接口屏蔽底层差异Spring AI最精妙的设计之一是定义了ChatClient和Prompt等核心接口。无论底层是OpenAI的GPT-4、Anthropic的Claude还是本地的Ollama甚至是Hugging Face上的某个模型你作为应用开发者面对的都是同一个ChatClient接口。public interface ChatClient { ChatResponse call(Prompt prompt); FluxChatResponse stream(Prompt prompt); }这个简单的接口定义了两个核心操作同步调用 (call) 和流式调用 (stream)。Prompt对象封装了你的输入消息列表、可选参数等ChatResponse则封装了模型的输出。这种设计带来了巨大的好处可移植性你的业务逻辑代码完全与具体的模型服务商解耦。今天用OpenAI明天想换成Azure OpenAI或Google的Gemini你只需要更换依赖和配置核心的调用代码一行都不用改。可测试性你可以轻松地为ChatClient创建Mock或Stub实现在单元测试中模拟AI模型的响应而无需连接真实的、昂贵的API服务。学习成本低你只需要学习一套API就能操作几乎所有主流的大模型。2.2 丰富的PromptTemplate告别字符串拼接噩梦与大模型交互本质上是在构造精心设计的提示词Prompt。在原始代码中我们常常会看到各种字符串拼接既容易出错又难以维护。// 传统方式 - 脆弱且丑陋 String prompt 请将以下用户反馈分类反馈内容是\ userFeedback \。分类选项有 String.join(, , categories) 。;Spring AI引入了PromptTemplate它借鉴了Spring MVC中视图模板的思想让你可以像写Thymeleaf或FreeMarker模板一样来构造提示词。PromptTemplate promptTemplate new PromptTemplate( 请将以下用户反馈分类。 反馈内容{feedback} 可选分类{categories} 请只输出分类名称。 ); MapString, Object model new HashMap(); model.put(feedback, userFeedback); model.put(categories, 功能建议, 性能问题, 界面体验, 其他); Prompt prompt promptTemplate.create(model);这种方式清晰、安全避免了注入风险并且模板本身可以外部化到配置文件中便于管理和国际化。dive-into-spring-ai项目会深入展示如何利用PromptTemplate构建复杂的、带有多轮上下文和系统指令的对话场景。2.3 函数调用Function Calling的Spring式集成大模型的函数调用能力允许模型在对话中决定调用开发者预定义的工具函数这是构建智能Agent智能体的基础。Spring AI为此提供了优雅的支持。你不需要手动去解析模型返回的JSON来决定调用哪个函数。相反你只需要定义一个个普通的Bean方法并通过Description注解来描述这个函数的功能Spring AI就能自动将它们注册为模型可用的“工具”。Component public class WeatherService { Description(根据城市名称查询实时天气情况) // 这个描述对于模型理解函数用途至关重要 public String getWeather(Description(要查询天气的城市名称例如北京) String city) { // 调用真实的天气API return 北京晴25°C微风; } }在配置中启用函数调用后当用户问“北京天气怎么样”时模型会识别出需要调用getWeather函数并自动将“北京”作为参数传入。你的代码接收到的就是一个直接的Java方法调用完全屏蔽了中间复杂的JSON格式协商过程。dive-into-spring-ai会详细剖析这一过程的实现原理并分享如何设计高质量的函数描述来提升模型调用的准确性。3. 从零到一构建你的第一个Spring AI应用理论讲得再多不如动手实践。让我们跟随dive-into-spring-ai的指引一步步搭建一个具备AI对话能力的Web应用。3.1 环境准备与项目初始化首先确保你有一个Java 17或更高版本的开发环境。使用Spring Initializrstart.spring.io创建项目是最佳选择。依赖选择是关键Spring Web构建RESTful API。Spring AI这是核心。在Initializr中你可能需要手动添加依赖因为Spring AI相对较新。更常见的做法是直接编辑pom.xml。特定模型Starter例如如果你使用OpenAI就添加spring-ai-openai-spring-boot-starter。这体现了Spring Boot“starter”理念的便捷性一个依赖就带来了客户端、自动配置和默认属性。你的pom.xml核心依赖部分可能看起来像这样dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version0.8.1/version !-- 请使用最新稳定版本 -- /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency注意Spring AI的版本迭代较快API可能在稳定版发布前有较大调整。dive-into-spring-ai项目通常会锁定在某个稳定的里程碑版本进行讲解并提示版本差异这是阅读此类前沿技术实践指南时需要特别留意的地方。3.2 核心配置安全地管理API密钥AI模型服务通常是按量付费的API密钥就是你的“钱包”。绝对不能将它硬编码在代码中或提交到版本控制系统。标准做法是使用环境变量或Spring Boot的配置文件在application.yml中配置spring: ai: openai: api-key: ${OPENAI_API_KEY:} # 优先从环境变量读取为空则使用后面的默认值这里为空 chat: options: model: gpt-3.5-turbo # 默认使用的模型 temperature: 0.7 # 创造性程度设置环境变量Linux/macOS:export OPENAI_API_KEYyour_key_hereWindows (PowerShell):$env:OPENAI_API_KEYyour_key_here或者在IDE的运行配置中直接添加环境变量。这种方式既安全密钥不进入代码库又灵活不同环境可以使用不同的密钥和模型配置。3.3 编写第一个AI服务与控制器配置完成后编写业务逻辑变得异常简单。Spring Boot的自动配置会为你创建一个基于OpenAiChatClient的ChatClientBean。1. 创建Service层Service public class AIChatService { private final ChatClient chatClient; // 构造器注入依赖关系清晰 public AIChatService(ChatClient chatClient) { this.chatClient chatClient; } public String chat(String userMessage) { // 构建Prompt这里使用了简单的用户消息 Prompt prompt new Prompt(new UserMessage(userMessage)); // 调用ChatClient ChatResponse response chatClient.call(prompt); // 从响应中提取结果 return response.getResult().getOutput().getContent(); } // 流式响应版本用于需要逐字输出效果的场景如聊天界面 public FluxString chatStream(String userMessage) { Prompt prompt new Prompt(new UserMessage(userMessage)); return chatClient.stream(prompt) .map(chunk - chunk.getResult().getOutput().getContent()); } }2. 创建Web控制器RestController RequestMapping(/api/ai) public class AIChatController { private final AIChatService chatService; public AIChatController(AIChatService chatService) { this.chatService chatService; } PostMapping(/chat) public ResponseEntityString chat(RequestBody ChatRequest request) { String response chatService.chat(request.getMessage()); return ResponseEntity.ok(response); } // 使用Server-Sent Events (SSE) 推送流式响应 GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString chatStream(RequestParam String message) { return chatService.chatStream(message); } }3. 定义简单的请求体public class ChatRequest { private String message; // getter 和 setter }启动应用用Postman或curl向/api/ai/chat发送一个POST请求你就能收到AI模型的回复了。流式接口/api/ai/chat/stream则会以SSE流的形式逐步返回内容前端可以实时显示。实操心得在开发初期强烈建议在application.yml中开启Spring AI的调试日志以便观察实际发送和接收的请求内容。这能帮你快速定位问题是出在提示词构造、网络连接还是API密钥上。logging: level: org.springframework.ai: DEBUG4. 深入实战构建一个智能客服分类器一个简单的对话机器人只是开始。dive-into-spring-ai项目的价值在于引导我们解决更实际的业务问题。假设我们有一个电商平台需要将海量的用户在线留言自动分类到不同的处理部门如“物流问题”、“商品质量”、“售后咨询”、“表扬建议”等。4.1 设计系统提示词System Prompt系统提示词是引导模型行为的关键。一个好的系统提示词应该清晰、具体并定义好输出格式。Component public class CustomerServiceClassifier { private static final String SYSTEM_PROMPT_TEXT 你是一个专业的电商客服工单分类助手。 你的任务是根据用户的留言内容将其精确分类到以下类别之一 - LOGISTICS: 物流相关问题如发货慢、快递丢失、配送错误等。 - QUALITY: 商品质量问题如破损、瑕疵、与描述不符等。 - AFTER_SALES: 售后咨询如退货、换货、退款流程等。 - COMPLAINT: 投诉与纠纷。 - SUGGESTION: 产品或服务建议。 - OTHER: 无法归入以上类别的内容。 请严格按以下JSON格式输出不要有任何其他解释 { category: 分类英文标识, confidence: 一个0到1之间的小数表示你的分类置信度, reason: 一句话说明分类理由 } ; private final ChatClient chatClient; private final PromptTemplate promptTemplate; public CustomerServiceClassifier(ChatClient chatClient) { this.chatClient chatClient; // 将用户留言作为变量嵌入到系统提示词之后 this.promptTemplate new PromptTemplate(SYSTEM_PROMPT_TEXT \n\n用户留言{message}); } public ClassificationResult classify(String userMessage) { Prompt prompt promptTemplate.create(Map.of(message, userMessage)); ChatResponse response chatClient.call(prompt); String jsonOutput response.getResult().getOutput().getContent(); // 使用Jackson或Gson解析JSON字符串为ClassificationResult对象 ObjectMapper mapper new ObjectMapper(); try { return mapper.readValue(jsonOutput, ClassificationResult.class); } catch (JsonProcessingException e) { throw new RuntimeException(解析AI分类结果失败, e); } } }ClassificationResult类public class ClassificationResult { private String category; private Double confidence; private String reason; // getters and setters }4.2 处理非确定性输出与错误大模型的输出是非确定性的即使你要求了JSON格式它偶尔也可能返回一些额外的文本或格式错误。生产级代码必须考虑这种健壮性。策略一使用Spring AI的输出解析器Spring AI提供了BeanOutputParser等工具可以更可靠地将模型输出绑定到Java对象上。public ClassificationResult classifyWithParser(String userMessage) { BeanOutputParserClassificationResult parser new BeanOutputParser(ClassificationResult.class); String systemPrompt SYSTEM_PROMPT_TEXT \n\n{format}; // 预留格式占位符 PromptTemplate template new PromptTemplate(systemPrompt); template.add(format, parser.getFormat()); // 将JSON Schema注入提示词 template.add(message, userMessage); Prompt prompt template.create(); ChatResponse response chatClient.call(prompt); // 使用解析器进行解析容错性更好 return parser.parse(response.getResult().getOutput().getContent()); }策略二重试与降级机制如果解析失败或者置信度过低比如低于0.6我们可以设计重试或降级逻辑。public ClassificationResult classifyRobustly(String userMessage, int maxRetries) { for (int i 0; i maxRetries; i) { try { ClassificationResult result classifyWithParser(userMessage); if (result.getConfidence() 0.6) { return result; // 置信度足够高返回结果 } // 置信度低记录日志准备重试 log.warn(分类置信度过低: {} 进行第{}次重试, result.getConfidence(), i1); } catch (Exception e) { log.error(第{}次分类失败, i1, e); } } // 多次尝试后仍失败返回兜底分类 return new ClassificationResult(OTHER, 0.0, 系统自动分类失败转入人工处理); }4.3 性能优化与成本控制直接调用远程AI API有延迟和成本。对于分类这种相对简单的任务我们可以采用以下策略缓存对完全相同的用户留言分类结果在短时间内是稳定的。可以使用Spring Cache如Cacheable将结果缓存几分钟大幅减少API调用。批量处理如果需要在后台处理大量历史数据不要逐条调用。Spring AI的ChatClient虽然主要面向单次交互但你可以通过组织批量任务并利用Async进行异步处理同时注意遵守API的速率限制。模型选择对于分类任务可能不需要使用最强大也最贵的GPT-4。gpt-3.5-turbo甚至更小的专用模型如果服务商提供可能以更低的成本和更快的速度达到相近的效果。这需要在application.yml中灵活配置spring.ai.openai.chat.options.model参数并针对业务进行效果评估。5. 高级主题RAG检索增强生成与AI记忆当你的AI应用需要基于私有知识库如公司内部文档、产品手册进行问答时简单的对话模型就力不从心了。这时就需要引入RAG架构。dive-into-spring-ai对此有深入探讨。5.1 RAG的核心工作流程文档加载与分割将PDF、Word、Markdown等文档加载进来并分割成大小适宜的文本块Chunk。Spring AI提供了DocumentReader和TextSplitter等抽象。向量化与存储使用嵌入模型Embedding Model将每个文本块转换为一个高维向量Vector然后存入向量数据库如Chroma、Pinecone、Weaviate或Spring AI内置的简单内存向量库。检索当用户提问时将问题也向量化然后在向量数据库中搜索与之最相似的几个文本块。增强生成将检索到的相关文本块作为上下文与用户问题一起构成新的提示词发送给大模型让它生成基于上下文的答案。5.2 使用Spring AI实现简易RAGSpring AI极大地简化了RAG的实现。以下是一个高度简化的示例Service public class KnowledgeBaseQAService { private final VectorStore vectorStore; private final EmbeddingClient embeddingClient; private final ChatClient chatClient; public KnowledgeBaseQAService(VectorStore vectorStore, EmbeddingClient embeddingClient, ChatClient chatClient) { this.vectorStore vectorStore; this.embeddingClient embeddingClient; this.chatClient chatClient; } // 初始化知识库通常只需运行一次 PostConstruct public void initKnowledgeBase() { ListDocument documents /* 从文件系统或数据库加载你的文档 */; vectorStore.add(documents); // VectorStore会自动调用EmbeddingClient进行向量化并存储 } // 基于知识库问答 public String answerQuestion(String question) { // 1. 将问题向量化 // 2. 在向量库中做相似性搜索获取Top K个相关文档片段 ListDocument relevantDocs vectorStore.similaritySearch(SearchRequest.query(question).withTopK(3)); // 3. 构建包含上下文的提示词 String context relevantDocs.stream() .map(Document::getContent) .collect(Collectors.joining(\n\n)); String promptText 请基于以下上下文信息回答问题。如果上下文信息不足以回答问题请直接说“根据现有信息无法回答”。 上下文 %s 问题%s 答案 .formatted(context, question); Prompt prompt new Prompt(new UserMessage(promptText)); ChatResponse response chatClient.call(prompt); return response.getResult().getOutput().getContent(); } }注意事项向量搜索的精度严重依赖于文本分割策略和嵌入模型的质量。块Chunk太大会包含无关信息太小会丢失完整语义。需要根据你的文档类型技术文档、法律条文、客服对话反复调试分割大小和重叠度。5.3 为聊天添加“记忆”能力默认情况下ChatClient的每次调用都是独立的。要实现多轮对话你需要自行管理对话历史。一个常见的模式是使用ChatMemory组件。Spring AI提供了InMemoryChatMemory等实现它可以自动维护一个会话窗口内的消息历史。Service public class ChatSessionService { private final ChatClient chatClient; private final MapString, ChatMemory sessionMemories new ConcurrentHashMap(); public FluxString streamChat(String sessionId, String userMessage) { // 获取或创建该会话的记忆体 ChatMemory memory sessionMemories.computeIfAbsent(sessionId, id - new InMemoryChatMemory()); // 将用户消息添加到记忆 memory.add(new UserMessage(userMessage)); // 从记忆中获取所有消息作为上下文 Prompt prompt new Prompt(memory.getMessages()); // 流式调用 return chatClient.stream(prompt) .doOnNext(response - { // 将AI的回复也添加到记忆中以便后续对话使用 memory.add(new AssistantMessage(response.getResult().getOutput().getContent())); }) .map(response - response.getResult().getOutput().getContent()); } }这样在同一sessionId下的多次对话AI就能记住之前的交流内容实现连贯的对话。对于Web应用可以使用用户的唯一标识或前端生成的UUID作为sessionId。6. 生产环境部署与监控考量将Spring AI应用部署到生产环境除了常规的Spring Boot应用注意事项外还有一些AI特有的点需要关注。6.1 配置管理多环境配置使用Spring Profiles为开发、测试、生产环境配置不同的AI模型、API端点甚至供应商。例如开发环境可以使用便宜的模型或Mock生产环境使用稳定、高性能的模型。# application-prod.yml spring: ai: openai: api-key: ${PROD_OPENAI_KEY} chat: options: model: gpt-4 # application-dev.yml spring: ai: openai: api-key: ${DEV_OPENAI_KEY} chat: options: model: gpt-3.5-turbo连接池与超时AI API调用可能较慢。务必配置合理的HTTP客户端超时连接超时、读取超时和重试策略如使用Spring Retry避免线程被长时间阻塞。6.2 可观测性与监控日志记录记录每一次AI调用的请求脱敏后的提示词、响应时间、消耗的Token数如果API返回和模型名称。这对于成本核算、性能分析和调试至关重要。指标收集利用Micrometer将调用次数、延迟、错误率等指标暴露给Prometheus或监控系统。可以自定义一个ChatClient的装饰器来实现。Component Primary // 确保这个Bean被优先注入 public class MeteredChatClient implements ChatClient { private final ChatClient delegate; private final MeterRegistry meterRegistry; private final Timer chatCallTimer; public MeteredChatClient(ChatClient delegate, MeterRegistry meterRegistry) { this.delegate delegate; this.meterRegistry meterRegistry; this.chatCallTimer Timer.builder(ai.chat.call) .description(AI聊天调用耗时) .register(meterRegistry); } Override public ChatResponse call(Prompt prompt) { return chatCallTimer.record(() - delegate.call(prompt)); } // ... 同样实现 stream 方法 }链路追踪在微服务架构中将AI调用纳入分布式链路追踪如Zipkin/Sleuth以便清晰看到AI服务在整个请求链路中的耗时和影响。6.3 限流与降级API速率限制所有AI服务商都有调用频率限制。在客户端你的应用实现限流如使用Resilience4j或Sentinel防止意外的高并发请求导致API被禁。降级策略当AI服务不可用或响应超时时应有降级方案。例如分类服务可以降级到基于关键词的规则引擎或者直接返回“需要人工处理”的状态。7. 常见问题与排查技巧实录在实际开发中你一定会遇到各种问题。以下是dive-into-spring-ai项目中总结的一些典型问题及其解决方法。7.1 问题调用API返回401或403错误可能原因1API密钥错误或未设置。排查检查环境变量OPENAI_API_KEY是否正确设置。在代码中打印或通过/actuator/env端点查看配置是否生效。可能原因2API密钥权限不足或已过期。排查登录AI服务商的控制台检查密钥状态、剩余额度以及是否绑定了正确的IP白名单如果设置了的话。可能原因3请求的模型在你的账户下不可用。排查确认spring.ai.openai.chat.options.model配置的模型名称拼写正确并且你的API套餐支持该模型。7.2 问题应用启动失败报No qualifying bean of type ChatClient可能原因1没有添加对应模型Starter的依赖。解决确保pom.xml或build.gradle中包含了如spring-ai-openai-spring-boot-starter的依赖。可能原因2配置了多个模型Starter但未指定主用哪个。解决Spring AI支持多模型你需要使用Qualifier来注入特定的ChatClientBean或者在配置中指定一个默认的。示例spring: ai: openai: enabled: true # 启用OpenAI azure-openai: enabled: false # 禁用Azure OpenAI7.3 问题模型回复内容不符合预期或“胡言乱语”可能原因1提示词Prompt设计不佳。排查与解决这是最常见的原因。尝试以下方法更清晰的指令在系统提示词中明确角色、任务和输出格式。提供示例在提示词中加入一两个输入输出的例子Few-shot Learning。调整参数降低temperature如从0.7调到0.3可以减少随机性使输出更稳定、更可预测。可能原因2上下文长度超限。排查检查发送的提示词总Token数是否超过了模型的最大上下文长度。可以估算或使用模型的Tokenizer工具检查。解决精简提示词或者对于长文档使用RAG检索相关片段而不是发送全文。7.4 问题流式响应SSE在前端不工作或中断可能原因1网络代理或网关超时。解决流式响应是长连接。确保你的Nginx、API Gateway等中间件配置了足够长的代理超时时间如proxy_read_timeout。可能原因2服务器端处理异常导致流中断。排查在服务器端添加全局异常处理确保即使AI API调用出错也能向SSE流发送一个错误事件或完成事件而不是让连接静默中断。ControllerAdvice public class SseExceptionHandler { ExceptionHandler(Exception.class) public FluxString handleExceptionInSse(Exception ex) { log.error(SSE流处理异常, ex); // 返回一个错误信息事件然后结束流 return Flux.just(data: [ERROR] ex.getMessage() \n\n) .concatWith(Flux.empty()); } }7.5 性能问题应用响应变慢可能原因1AI API调用延迟高。排查通过监控指标确认延迟来源。使用MeteredChatClient记录每次调用耗时。解决缓存对相同或相似的请求进行缓存。异步化将AI调用改为异步非阻塞如使用Async或 WebFlux避免阻塞HTTP处理线程。模型降级评估是否可以使用更快、更便宜的模型。可能原因2向量数据库检索慢针对RAG应用。解决优化向量索引如果使用的向量库支持。调整检索的Top K值在精度和速度间取得平衡。考虑使用更快的嵌入模型。遵循dive-into-spring-ai项目所倡导的深入实践路径从理解核心抽象开始逐步构建应用再到处理生产环境中的各种复杂情况你将能真正掌握使用Spring AI构建稳健、高效AI应用的能力。记住关键在于将AI能力当作一个普通的、可通过优雅抽象来调用的服务而Spring AI正是提供了这样一把利器让你能专注于业务逻辑本身而非繁琐的集成细节。