元宿six1. Spring AI 框架概述
Spring AI 是 Spring 生态系统中面向 AI 工程的应用框架，其核心设计理念是将 Spring 的模块化、可移植性等优势引入 AI 领域。作为 Spring 家族的新成员，它解决了企业数据/API 与 AI 模型之间的连接难题。我在实际项目中使用 Spring AI 2.0 时发现，其 POJO 编程模型显著降低了 AI 集成的复杂度。
框架主要特性包括：
- 多模型支持：覆盖 OpenAI、Anthropic、Google 等主流厂商的聊天补全、嵌入、文生图等能力
- 向量数据库集成：支持 Chroma、PGVector 等 12 种向量存储方案
- 结构化输出：自动将 AI 响应映射为 Java 对象
- 函数调用：实现模型与客户端工具的动态交互
- 可观测性：提供 AI 操作的监控指标
注意：Spring AI 2.0 需要 JDK 17+ 和 Spring Boot 3.2+ 环境，与旧版本存在 API 不兼容问题
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境搭建与基础配置
2.1 项目初始化
使用 Spring Initializr 创建项目时，需添加对应模型 starter。例如接入 OpenAI 时选择：
xml复制<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>
实测发现不同模型 starter 的配置前缀有差异：
- OpenAI:
spring.ai.openai - Ollama:
spring.ai.ollama - Azure:
spring.ai.azure
2.2 关键配置项
在 application.yml 中必须配置：
yaml复制spring:
ai:
openai:
api-key: sk-xxx
chat:
model: gpt-4-turbo # 默认gpt-3.5-turbo
temperature: 0.7
常见问题排查：
- 连接超时：检查代理设置或尝试增加
spring.ai.openai.connect-timeout=60s - 429错误：配置重试策略
spring.ai.openai.retry.max-attempts=3
3. 核心 API 实战
3.1 ChatClient 基础用法
同步调用示例：
java复制@Autowired
private ChatClient chatClient;
public String getJoke() {
return chatClient.prompt()
.user(u -> u.text("讲个程序员笑话"))
.call()
.content();
}
流式响应处理（SSE）：
java复制Flux<String> streamResponse = chatClient.prompt()
.user("解释RESTful架构")
.stream()
.map(ChatResponse::getContent);
3.2 结构化输出
定义返回类型：
java复制record ProgrammingLanguage(String name, int popularityRank) {}
ProgrammingLanguage result = chatClient.prompt()
.user("生成Java语言信息")
.call()
.entity(ProgrammingLanguage.class);
技巧：对于复杂结构，建议先用 @Description 注解添加字段说明
4. 高级功能实现
4.1 函数调用实战
定义工具函数：
java复制@Bean
public Function<WeatherRequest, WeatherResponse> weatherFunction() {
return request -> {
// 调用真实天气API
return new WeatherResponse(...);
};
}
在提示中声明工具：
java复制ChatResponse response = chatClient.prompt()
.user("北京现在天气如何？")
.functions("weatherFunction")
.call();
4.2 RAG 实现方案
文档处理流程：
- 文档加载：使用 DocumentReader 读取 PDF/HTML
- 文本分割：TokenTextSplitter 按语义分块
- 向量化：通过 EmbeddingClient 生成向量
- 存储：持久化到 VectorStore
检索增强代码示例：
java复制Retriever retriever = content ->
vectorStore.similaritySearch(content, 3);
String answer = chatClient.prompt()
.user("Spring AI如何实现文档问答？")
.advisors(new RetrievalAugmentor(retriever))
.call()
.content();
5. 生产环境最佳实践
5.1 性能优化方案
- 批处理：对多个查询使用
ChatClient.batch() - 缓存：对稳定知识类问答实现 Embedding 缓存
- 超时设置：
yaml复制spring:
ai:
openai:
connect-timeout: 10s
read-timeout: 30s
5.2 可观测性配置
添加监控依赖：
xml复制<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-core</artifactId>
</dependency>
关键监控指标：
spring.ai.requests.count请求总数spring.ai.tokens.prompt提示词消耗spring.ai.duration请求耗时
6. 常见问题排错指南
问题现象：流式响应中断
- 检查点：SSE 客户端是否保持连接
- 解决方案：配置心跳机制
java复制SseEmitter emitter = new SseEmitter(180_000L);
emitter.send(SseEmitter.event().comment("keep-alive"));
问题现象：中文响应乱码
- 修复方案：
yaml复制spring:
mvc:
async:
request-timeout: 60s
servlet:
encoding:
force-response: true
我在实际项目中总结的黄金法则：始终对 AI 响应做内容验证，特别是涉及数据库操作时。曾遇到模型将 "SELECT * FROM users" 解释为删除语句的情况，建议添加输出校验层