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.yml
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY:your–api–key–here}
chat:
options:
model: gpt–3.5–turbo
temperature: 0.7
vectorstore:
pgvector:
dimension: 1536
distance-type: cosine
index-type: ivfflat
datasource:
url: jdbc:postgresql://localhost:5432/customer_service
username: ${DB_USERNAME:postgres}
password: ${DB_PASSWORD:password}
第三步：创建客服服务类
这个服务类是智能客服系统的核心，它整合了文档检索和 AI 对话能力。通过 VectorStore 查询相关文档，然后让 ChatModel 基于检索到的内容生成回答。
@Service
@RequiredArgsConstructor
public class CustomerServiceAI {
private final ChatClient chatClient;
private final VectorStore vectorStore;
public String handleCustomerQuery(String customerQuery) {
// 1. 将用户查询向量化并搜索相关文档
List<Document> relevantDocs = vectorStore.similaritySearch(
SearchRequest.query(customerQuery).withTopK(5)
);
// 2. 构建上下文信息
String context = relevantDocs.stream()
.map(Document::getContent)
.collect(Collectors.joining("\\n"));
// 3. 生成回答
String prompt = """
作为专业的客服人员，请根据以下知识库内容回答用户问题。
如果知识库中没有相关信息，请礼貌地说明并提供合理的建议。
知识库内容：
{context}
用户问题：{query}
请提供准确、友好的回答：
""";
return chatClient.prompt()
.user(prompt)
.param("context", context)
.param("query", customerQuery)
.call()
.content();
}
}
第四步：实现文档向量化服务
这个服务负责将企业文档（如产品手册、FAQ、政策说明等）转换为向量并存储到数据库中。在实际项目中，这通常是一个批处理任务，定期更新知识库。
@Service
@RequiredArgsConstructor
public class DocumentIndexingService {
private final VectorStore vectorStore;
private final EmbeddingModel embeddingModel;
@Scheduled(cron = "0 0 2 * * ?") // 每天凌晨2点更新
public void indexDocuments() {
// 1. 读取需要索引的文档
List<Document> documents = loadDocumentsFromSources();
// 2. 向量化并存储
vectorStore.add(documents);
log.info("成功索引 {} 个文档", documents.size());
}
private List<Document> loadDocumentsFromSources() {
List<Document> documents = new ArrayList<>();
// 从数据库加载FAQ
documents.addAll(loadFAQs());
// 从文件系统加载产品手册
documents.addAll(loadProductManuals());
// 从CMS加载政策文档
documents.addAll(loadPolicyDocuments());
return documents;
}
}
第五步：创建 REST 控制器
这个控制器提供 HTTP API 接口，允许前端应用调用智能客服功能。在实际项目中，还需要添加用户认证、请求限流、日志记录等功能。
@RestController
@RequestMapping("/api/customer-service")
@RequiredArgsConstructor
public class CustomerServiceController {
private final CustomerServiceAI customerServiceAI;
@PostMapping("/query")
public ResponseEntity<QueryResponse> handleQuery(@RequestBody QueryRequest request) {
String answer = customerServiceAI.handleCustomerQuery(request.getQuery());
QueryResponse response = QueryResponse.builder()
.query(request.getQuery())
.answer(answer)
.timestamp(LocalDateTime.now())
.build();
return ResponseEntity.ok(response);
}
}
3.2 电商商品推荐系统
场景描述
在电商系统中，基于用户的浏览历史和行为数据，通过 AI 模型生成个性化的商品推荐。这个场景展示了 Spring AI 函数调用功能的实际应用。
实现代码
第一步：定义推荐服务函数
这个 Java 函数将被注册为 AI 可调用的函数，用于获取用户推荐商品。在实际的电商系统中，这个函数会访问用户行为数据库和商品库存系统。
@Component
public class ProductRecommendationFunctions {
private final UserRepository userRepository;
private final ProductRepository productRepository;
@Bean
@Description("根据用户ID获取个性化商品推荐")
public Function<ProductRecommendationRequest, List<Product>> getRecommendations() {
return request -> {
// 1. 获取用户历史行为数据
User user = userRepository.findById(request.getUserId())
.orElseThrow(() -> new UserNotFoundException("用户不存在"));
// 2. 基于用户偏好生成推荐
List<Product> recommendations = generateRecommendations(user);
return recommendations;
};
}
private List<Product> generateRecommendations(User user) {
// 实际项目中这里会有复杂的推荐算法
// 这里简化为基于用户标签的商品过滤
return productRepository.findByCategoryIn(user.getPreferredCategories())
.stream()
.filter(Product::isInStock)
.limit(10)
.collect(Collectors.toList());
}
}
第二步：推荐对话服务
这个服务整合了商品推荐功能与 AI 对话能力，能够理解用户的自然语言查询并提供相应的商品推荐。
@Service
@RequiredArgsConstructor
public class ShoppingAssistantService {
private final ChatClient chatClient;
public String getShoppingAdvice(String userId, String userQuery) {
String prompt = """
你是一个专业的购物助手，能够根据用户的需求和偏好提供个性化的商品推荐。
请使用 getRecommendations 函数获取推荐商品，然后基于这些推荐给用户提供建议。
用户查询：{query}
用户ID：{userId}
请提供友好的购物建议：
""";
return chatClient.prompt()
.user(prompt)
.param("query", userQuery)
.param("userId", userId)
.functions("getRecommendations")
.call()
.content();
}
}
3.3 文档分析工具
场景描述
企业文档管理系统需要自动分析和提取文档中的关键信息，如合同条款、财务数据等。这个案例展示了 Spring AI 在文档处理方面的应用。
实现代码
第一步：文档分析服务
这个服务能够处理各种格式的文档，提取关键信息并生成摘要。在实际项目中，这通常集成到企业的文档管理系统中。
@Service
@RequiredArgsConstructor
public class DocumentAnalysisService {
private final ChatClient chatClient;
private final DocumentParser documentParser;
public DocumentAnalysisResult analyzeDocument(MultipartFile file) {
// 1. 解析文档内容
String documentContent = documentParser.parse(file);
// 2. AI 分析文档
String prompt = """
请分析以下文档内容，提取以下信息：
1. 文档类型和主题
2. 关键条款和要点
3. 风险提示（如有）
4. 行动建议
文档内容：
{content}
请以JSON格式返回分析结果：
""";
String analysis = chatClient.prompt()
.user(prompt)
.param("content", documentContent)
.call()
.content();
// 3. 解析并返回结果
return parseAnalysisResult(analysis);
}
private DocumentAnalysisResult parseAnalysisResult(String analysis) {
try {
ObjectMapper mapper = new ObjectMapper();
return mapper.readValue(analysis, DocumentAnalysisResult.class);
} catch (Exception e) {
// 处理解析错误，返回默认结果
return DocumentAnalysisResult.builder()
.documentType("未知")
.keyPoints(List.of("解析失败，请手动检查"))
.build();
}
}
}
第二步：批量文档处理服务
这个服务提供了批量处理文档的能力，支持异步处理和进度跟踪。在实际的企业应用中，这对于处理大量文档非常重要。
@Service
@RequiredArgsConstructor
public class BatchDocumentService {
private final DocumentAnalysisService analysisService;
private final TaskExecutor taskExecutor;
private final Map<String, ProcessingStatus> processingTasks =
new ConcurrentHashMap<>();
public String startBatchProcessing(List<MultipartFile> documents) {
String taskId = UUID.randomUUID().toString();
// 创建处理状态
ProcessingStatus status = ProcessingStatus.builder()
.taskId(taskId)
.totalDocuments(documents.size())
.processedDocuments(0)
.status("PROCESSING")
.startTime(LocalDateTime.now())
.build();
processingTasks.put(taskId, status);
// 异步处理文档
taskExecutor.execute(() -> processBatch(taskId, documents));
return taskId;
}
private void processBatch(String taskId, List<MultipartFile> documents) {
ProcessingStatus status = processingTasks.get(taskId);
List<DocumentAnalysisResult> results = new ArrayList<>();
for (int i = 0; i < documents.size(); i++) {
try {
DocumentAnalysisResult result = analysisService.analyzeDocument(documents.get(i));
results.add(result);
// 更新进度
status.setProcessedDocuments(i + 1);
status.setResults(results);
} catch (Exception e) {
log.error("处理文档失败: {}", documents.get(i).getOriginalFilename(), e);
}
}
// 标记完成
status.setStatus("COMPLETED");
status.setEndTime(LocalDateTime.now());
}
public ProcessingStatus getProcessingStatus(String taskId) {
return processingTasks.get(taskId);
}
}
四、最佳实践与注意事项
5.1 项目结构建议
src/main/java/com/company/ai/
├── config/ # AI 相关配置
├── service/ # AI 业务服务
├── functions/ # 自定义函数实现
├── vector/ # 向量处理相关
├── prompt/ # 提示词模板
└── controller/ # REST 控制器
5.2 配置管理
@Configuration
public class AIConfig {
@Bean
@ConditionalOnProperty(name = "spring.ai.provider", havingValue = "openai")
public ChatClient openAiChatClient(OpenAiChatModel chatModel) {
return ChatClient.builder(chatModel).build();
}
@Bean
@ConditionalOnProperty(name = "spring.ai.provider", havingValue = "azure")
public ChatClient azureChatClient(AzureOpenAiChatModel chatModel) {
return ChatClient.builder(chatModel).build();
}
}
5.3 错误处理与监控
@Component
public class AIErrorHandler {
@EventListener
public void handleChatError(ChatErrorEvent event) {
// 记录错误日志
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 应用。点赞点赞点赞！！！！！！！！！！！！！！
