Spring AI 详细指南
一、Spring AI 概述
1.1 什么是 Spring AI
Spring AI 是一个旨在简化包含人工智能功能应用程序开发的框架项目，它消除了不必要的复杂性。该项目借鉴了著名的 Python 项目（如 LangChain 和 LlamaIndex）的灵感，但并非这些项目的直接移植。
Spring AI 的核心理念是：生成式 AI 应用的下一波浪潮不仅限于 Python 开发者，而是将在多种编程语言中普及。
1.2 Spring AI 干什么用
Spring AI 主要用于以下场景：
- 快速集成 AI 模型：支持 OpenAI、Microsoft、Amazon、Google、Hugging Face 等主要模型提供商
- 构建智能应用：支持聊天、文本生成图像、音频转录、文本转语音等多种模型类型
- 数据向量化存储：支持 Apache Cassandra、Azure Vector Search、Chroma、Milvus、MongoDB Atlas 等主流向量数据库
- 企业级应用开发：通过 Spring Boot 自动配置和启动器简化 AI 集成
1.3 为什么选择 Spring AI
核心优势：
- 提供跨 AI 提供商的可移植 API
- 支持 POJO 映射，简化开发
- 内置函数调用机制，便于与外部系统集成
- 完善的 Spring Boot 集成，降低学习成本
二、Spring AI 核心特性
2.1 模型支持
Spring AI 提供了丰富的模型类型支持：
支持的模型类型：
- Chat Models：对话模型，支持同步和流式 API
- Text to Image Models：文本生成图像模型
- Audio Transcription Models：音频转录模型
- Text to Speech Models：文本转语音模型
- Embedding Models：嵌入模型，用于文本向量化
支持的提供商：
- OpenAI（包括 Azure OpenAI）
- Microsoft
- Amazon Bedrock
- Google Vertex AI
- Hugging Face
- ZhiPu AI
- 以及更多…
2.2 向量数据库集成
Spring AI 提供了统一的向量存储抽象，支持：
主流向量数据库：
- Apache Cassandra
- Azure Vector Search
- Chroma
- Milvus
- MongoDB Atlas
- Neo4j
- PostgreSQL/PGVector
- PineCone
- Qdrant
- Redis
- Weaviate
特色功能：
- 跨提供商的便携式 API
- SQL 样式的元数据过滤 API
- 自动化的向量存储配置
2.3 函数调用机制
函数调用是 Spring AI 的一个核心特性，它允许：
- 将自定义 Java 函数注册到 AI 模型
- AI 模型智能选择调用已注册的函数
- 连接 LLM 能力与外部工具和 API
- 实现复杂的业务逻辑集成
三、实际开发场景与实战案例
3.1 智能客服系统
场景描述
在企业实际开发中，智能客服是最常见的 AI 应用场景。我们需要构建一个能够理解用户问题、查询知识库并提供准确回答的客服系统。
实现步骤
第一步：配置项目依赖
下面这段代码是 Spring Boot 项目的 pom.xml 配置，它引入了 Spring AI 的核心依赖，包括 OpenAI 集成和向量数据库支持。这是我们构建智能客服系统的基础。
<dependencies><!-- Spring Boot Starter --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- Spring AI OpenAI 集成 --><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-openai-spring-boot-starter</artifactId><version>1.0.0-M3</version></dependency><!-- Spring AI 向量数据库支持 --><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-pgvector-store-spring-boot-starter</artifactId><version>1.0.0-M3</version></dependency></dependencies>第二步：配置文件设置
这个配置文件设置了 OpenAI 的 API 密钥和 PostgreSQL 向量数据库的连接信息。在实际项目中，这些配置通常通过环境变量或配置中心管理，而不是硬编码。
# application.ymlspring:ai:openai:api-key:${OPENAI_API_KEY:your-api-key-here}chat:options:model:gpt-3.5-turbotemperature:0.7vectorstore:pgvector:dimension:1536distance-type:cosineindex-type:ivfflatdatasource:url:jdbc:postgresql://localhost:5432/customer_serviceusername:${DB_USERNAME:postgres}password:${DB_PASSWORD:password}第三步：创建客服服务类
这个服务类是智能客服系统的核心，它整合了文档检索和 AI 对话能力。通过 VectorStore 查询相关文档，然后让 ChatModel 基于检索到的内容生成回答。
@Service@RequiredArgsConstructorpublicclassCustomerServiceAI{privatefinalChatClientchatClient;privatefinalVectorStorevectorStore;publicStringhandleCustomerQuery(StringcustomerQuery){// 1. 将用户查询向量化并搜索相关文档List<Document>relevantDocs=vectorStore.similaritySearch(SearchRequest.query(customerQuery).withTopK(5));// 2. 构建上下文信息Stringcontext=relevantDocs.stream().map(Document::getContent).collect(Collectors.joining("\n"));// 3. 生成回答Stringprompt=""" 作为专业的客服人员，请根据以下知识库内容回答用户问题。 如果知识库中没有相关信息，请礼貌地说明并提供合理的建议。 知识库内容： {context} 用户问题：{query} 请提供准确、友好的回答： """;returnchatClient.prompt().user(prompt).param("context",context).param("query",customerQuery).call().content();}}第四步：实现文档向量化服务
这个服务负责将企业文档（如产品手册、FAQ、政策说明等）转换为向量并存储到数据库中。在实际项目中，这通常是一个批处理任务，定期更新知识库。
@Service@RequiredArgsConstructorpublicclassDocumentIndexingService{privatefinalVectorStorevectorStore;privatefinalEmbeddingModelembeddingModel;@Scheduled(cron="0 0 2 * * ?")// 每天凌晨2点更新publicvoidindexDocuments(){// 1. 读取需要索引的文档List<Document>documents=loadDocumentsFromSources();// 2. 向量化并存储vectorStore.add(documents);log.info("成功索引 {} 个文档",documents.size());}privateList<Document>loadDocumentsFromSources(){List<Document>documents=newArrayList<>();// 从数据库加载FAQdocuments.addAll(loadFAQs());// 从文件系统加载产品手册documents.addAll(loadProductManuals());// 从CMS加载政策文档documents.addAll(loadPolicyDocuments());returndocuments;}}第五步：创建 REST 控制器
这个控制器提供 HTTP API 接口，允许前端应用调用智能客服功能。在实际项目中，还需要添加用户认证、请求限流、日志记录等功能。
@RestController@RequestMapping("/api/customer-service")@RequiredArgsConstructorpublicclassCustomerServiceController{privatefinalCustomerServiceAIcustomerServiceAI;@PostMapping("/query")publicResponseEntity<QueryResponse>handleQuery(@RequestBodyQueryRequestrequest){Stringanswer=customerServiceAI.handleCustomerQuery(request.getQuery());QueryResponseresponse=QueryResponse.builder().query(request.getQuery()).answer(answer).timestamp(LocalDateTime.now()).build();returnResponseEntity.ok(response);}}3.2 电商商品推荐系统
场景描述
在电商系统中，基于用户的浏览历史和行为数据，通过 AI 模型生成个性化的商品推荐。这个场景展示了 Spring AI 函数调用功能的实际应用。
实现代码
第一步：定义推荐服务函数
这个 Java 函数将被注册为 AI 可调用的函数，用于获取用户推荐商品。在实际的电商系统中，这个函数会访问用户行为数据库和商品库存系统。
@ComponentpublicclassProductRecommendationFunctions{privatefinalUserRepositoryuserRepository;privatefinalProductRepositoryproductRepository;@Bean@Description("根据用户ID获取个性化商品推荐")publicFunction<ProductRecommendationRequest,List<Product>>getRecommendations(){returnrequest->{// 1. 获取用户历史行为数据Useruser=userRepository.findById(request.getUserId()).orElseThrow(()->newUserNotFoundException("用户不存在"));// 2. 基于用户偏好生成推荐List<Product>recommendations=generateRecommendations(user);returnrecommendations;};}privateList<Product>generateRecommendations(Useruser){// 实际项目中这里会有复杂的推荐算法// 这里简化为基于用户标签的商品过滤returnproductRepository.findByCategoryIn(user.getPreferredCategories()).stream().filter(Product::isInStock).limit(10).collect(Collectors.toList());}}第二步：推荐对话服务
这个服务整合了商品推荐功能与 AI 对话能力，能够理解用户的自然语言查询并提供相应的商品推荐。
@Service@RequiredArgsConstructorpublicclassShoppingAssistantService{privatefinalChatClientchatClient;publicStringgetShoppingAdvice(StringuserId,StringuserQuery){Stringprompt=""" 你是一个专业的购物助手，能够根据用户的需求和偏好提供个性化的商品推荐。 请使用 getRecommendations 函数获取推荐商品，然后基于这些推荐给用户提供建议。 用户查询：{query} 用户ID：{userId} 请提供友好的购物建议： """;returnchatClient.prompt().user(prompt).param("query",userQuery).param("userId",userId).functions("getRecommendations").call().content();}}3.3 文档分析工具
场景描述
企业文档管理系统需要自动分析和提取文档中的关键信息，如合同条款、财务数据等。这个案例展示了 Spring AI 在文档处理方面的应用。
实现代码
第一步：文档分析服务
这个服务能够处理各种格式的文档，提取关键信息并生成摘要。在实际项目中，这通常集成到企业的文档管理系统中。
@Service@RequiredArgsConstructorpublicclassDocumentAnalysisService{privatefinalChatClientchatClient;privatefinalDocumentParserdocumentParser;publicDocumentAnalysisResultanalyzeDocument(MultipartFilefile){// 1. 解析文档内容StringdocumentContent=documentParser.parse(file);// 2. AI 分析文档Stringprompt=""" 请分析以下文档内容，提取以下信息： 1. 文档类型和主题 2. 关键条款和要点 3. 风险提示（如有） 4. 行动建议 文档内容： {content} 请以JSON格式返回分析结果： """;Stringanalysis=chatClient.prompt().user(prompt).param("content",documentContent).call().content();// 3. 解析并返回结果returnparseAnalysisResult(analysis);}privateDocumentAnalysisResultparseAnalysisResult(Stringanalysis){try{ObjectMappermapper=newObjectMapper();returnmapper.readValue(analysis,DocumentAnalysisResult.class);}catch(Exceptione){// 处理解析错误，返回默认结果returnDocumentAnalysisResult.builder().documentType("未知").keyPoints(List.of("解析失败，请手动检查")).build();}}}第二步：批量文档处理服务
这个服务提供了批量处理文档的能力，支持异步处理和进度跟踪。在实际的企业应用中，这对于处理大量文档非常重要。
@Service@RequiredArgsConstructorpublicclassBatchDocumentService{privatefinalDocumentAnalysisServiceanalysisService;privatefinalTaskExecutortaskExecutor;privatefinalMap<String,ProcessingStatus>processingTasks=newConcurrentHashMap<>();publicStringstartBatchProcessing(List<MultipartFile>documents){StringtaskId=UUID.randomUUID().toString();// 创建处理状态ProcessingStatusstatus=ProcessingStatus.builder().taskId(taskId).totalDocuments(documents.size()).processedDocuments(0).status("PROCESSING").startTime(LocalDateTime.now()).build();processingTasks.put(taskId,status);// 异步处理文档taskExecutor.execute(()->processBatch(taskId,documents));returntaskId;}privatevoidprocessBatch(StringtaskId,List<MultipartFile>documents){ProcessingStatusstatus=processingTasks.get(taskId);List<DocumentAnalysisResult>results=newArrayList<>();for(inti=0;i<documents.size();i++){try{DocumentAnalysisResultresult=analysisService.analyzeDocument(documents.get(i));results.add(result);// 更新进度status.setProcessedDocuments(i+1);status.setResults(results);}catch(Exceptione){log.error("处理文档失败: {}",documents.get(i).getOriginalFilename(),e);}}// 标记完成status.setStatus("COMPLETED");status.setEndTime(LocalDateTime.now());}publicProcessingStatusgetProcessingStatus(StringtaskId){returnprocessingTasks.get(taskId);}}四、最佳实践与注意事项
5.1 项目结构建议
src/main/java/com/company/ai/ ├── config/ # AI 相关配置 ├── service/ # AI 业务服务 ├── functions/ # 自定义函数实现 ├── vector/ # 向量处理相关 ├── prompt/ # 提示词模板 └── controller/ # REST 控制器5.2 配置管理
@ConfigurationpublicclassAIConfig{@Bean@ConditionalOnProperty(name="spring.ai.provider",havingValue="openai")publicChatClientopenAiChatClient(OpenAiChatModelchatModel){returnChatClient.builder(chatModel).build();}@Bean@ConditionalOnProperty(name="spring.ai.provider",havingValue="azure")publicChatClientazureChatClient(AzureOpenAiChatModelchatModel){returnChatClient.builder(chatModel).build();}}5.3 错误处理与监控
@ComponentpublicclassAIErrorHandler{@EventListenerpublicvoidhandleChatError(ChatErrorEventevent){// 记录错误日志log.error("AI 对话错误: {}",event.getMessage(),event.getException());// 发送告警alertService.sendAlert("AI 服务异常",event.getMessage());// 记录指标meterRegistry.counter("ai.chat.error","provider",event.getProvider()).increment();}}5.4 成本控制策略
在实际项目中，AI 调用成本控制非常重要：
- 智能路由：根据请求复杂度选择不同的模型
- 请求合并：将多个小请求合并处理
- 结果缓存：缓存相似问题的答案
- 使用限制：为不同用户设置调用频率限制
五、总结
Spring AI 作为 Spring 生态系统中的 AI 开发框架，为企业级 AI 应用提供了强大而灵活的解决方案。通过掌握其核心概念和实战技巧，开发者能够构建出高效、可维护的智能应用。
关键要点：
- 抽象设计：Spring AI 的核心是提供跨供应商的统一抽象
- 企业集成：与 Spring 生态系统的深度集成是其最大优势
- 实战导向：丰富的功能支持实际业务场景的实现
- 持续演进：项目活跃，不断跟进 AI 技术发展趋势
在实际开发中，建议从简单的应用场景开始，逐步深入到复杂的业务逻辑实现，同时注重性能优化和成本控制，这样才能在企业环境中成功落地 AI 应用。点赞点赞点赞！！！！！！！！！！！！！！
