full-stack-skills Spring AI 开发指南
概述
Spring AI 是 Spring 官方提供的 AI 应用开发框架，简化了与各种大语言模型（LLM）的集成，包括 OpenAI、Anthropic、Azure OpenAI 等。
核心功能
1. 项目创建
依赖：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>
或使用 Gradle：
dependencies {
implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
}
2. Chat Client
配置：
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}
chat:
options:
model: gpt-4
temperature: 0.7
使用 ChatClient：
@Service
public class ChatService {
private final ChatClient chatClient;
public ChatService(ChatClient chatClient) {
this.chatClient = chatClient;
}
public String chat(String message) {
return chatClient.call(message);
}
public String chatWithPrompt(String userMessage) {
Prompt prompt = new Prompt(new UserMessage(userMessage));
ChatResponse response = chatClient.call(prompt);
return response.getResult().getOutput().getContent();
}
}
流式响应：
@Service
public class ChatService {
private final StreamingChatClient streamingChatClient;
public ChatService(StreamingChatClient streamingChatClient) {
this.streamingChatClient = streamingChatClient;
}
public Flux<String> streamChat(String message) {
return streamingChatClient.stream(message)
.map(response -> response.getResult().getOutput().getContent());
}
}
3. Prompt Template
定义模板：
@Service
public class PromptService {
private final PromptTemplate promptTemplate;
public PromptService() {
this.promptTemplate = new PromptTemplate(
"请用{style}风格回答以下问题：{question}"
);
}
public String generatePrompt(String style, String question) {
Map<String, Object> variables = Map.of(
"style", style,
"question", question
);
return promptTemplate.render(variables);
}
}
使用 ChatClient：
@Service
public class ChatService {
private final ChatClient chatClient;
private final PromptTemplate promptTemplate;
public ChatService(ChatClient chatClient) {
this.chatClient = chatClient;
this.promptTemplate = new PromptTemplate(
"请用{style}风格回答以下问题：{question}"
);
}
public String chatWithStyle(String style, String question) {
Prompt prompt = promptTemplate.create(Map.of(
"style", style,
"question", question
));
ChatResponse response = chatClient.call(prompt);
return response.getResult().getOutput().getContent();
}
}
4. Embedding
配置：
spring:
ai:
openai:
embedding:
options:
model: text-embedding-ada-002
使用 EmbeddingClient：
@Service
public class EmbeddingService {
private final EmbeddingClient embeddingClient;
public EmbeddingService(EmbeddingClient embeddingClient) {
this.embeddingClient = embeddingClient;
}
public List<Double> embed(String text) {
EmbeddingResponse response = embeddingClient.embedForResponse(
List.of(text)
);
return response.getResult().getOutput();
}
public List<List<Double>> embedBatch(List<String> texts) {
EmbeddingResponse response = embeddingClient.embedForResponse(texts);
return response.getResult().getOutput();
}
}
5. Vector Store
配置：
spring:
ai:
vectorstore:
pgvector:
index-type: HNSW
distance-type: COSINE_DISTANCE
使用 VectorStore：
@Service
public class VectorStoreService {
private final VectorStore vectorStore;
private final EmbeddingClient embeddingClient;
public VectorStoreService(
VectorStore vectorStore,
EmbeddingClient embeddingClient
) {
this.vectorStore = vectorStore;
this.embeddingClient = embeddingClient;
}
public void addDocument(String id, String content) {
List<Double> embedding = embeddingClient.embed(content);
Document document = new Document(id, content, Map.of());
vectorStore.add(List.of(document));
}
public List<Document> searchSimilar(String query, int topK) {
List<Double> queryEmbedding = embeddingClient.embed(query);
return vectorStore.similaritySearch(
SearchRequest.query(query)
.withTopK(topK)
);
}
}
6. Function Calling
定义函数：
@Bean
public Function<WeatherRequest, WeatherResponse> weatherFunction() {
return request -> {
// 调用天气 API
WeatherResponse response = weatherService.getWeather(
request.getLocation()
);
return response;
};
}
配置 Function Calling：
@Configuration
public class FunctionCallingConfig {
@Bean
public Function<WeatherRequest, WeatherResponse> weatherFunction() {
return request -> {
// 实现天气查询逻辑
return new WeatherResponse(/* ... */);
};
}
}
使用 Function Calling：
@Service
public class ChatService {
private final ChatClient chatClient;
private final FunctionCallbackRegistry functionCallbackRegistry;
public ChatService(
ChatClient chatClient,
FunctionCallbackRegistry functionCallbackRegistry
) {
this.chatClient = chatClient;
this.functionCallbackRegistry = functionCallbackRegistry;
}
public String chatWithFunction(String message) {
Prompt prompt = new Prompt(
new UserMessage(message),
functionCallbackRegistry.getFunctionCallbacks()
);
ChatResponse response = chatClient.call(prompt);
return response.getResult().getOutput().getContent();
}
}
7. 多模型支持
配置多个模型：
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}
anthropic:
api-key: ${ANTHROPIC_API_KEY}
azure:
openai:
api-key: ${AZURE_OPENAI_API_KEY}
endpoint: ${AZURE_OPENAI_ENDPOINT}
使用特定模型：
@Service
public class MultiModelService {
private final ChatClient openAiChatClient;
private final ChatClient anthropicChatClient;
public MultiModelService(
@Qualifier("openAiChatClient") ChatClient openAiChatClient,
@Qualifier("anthropicChatClient") ChatClient anthropicChatClient
) {
this.openAiChatClient = openAiChatClient;
this.anthropicChatClient = anthropicChatClient;
}
public String chatWithOpenAI(String message) {
return openAiChatClient.call(message);
}
public String chatWithAnthropic(String message) {
return anthropicChatClient.call(message);
}
}
最佳实践
1. 配置管理
- 使用环境变量存储 API Key
- 区分开发和生产环境配置
- 配置合理的超时和重试策略
2. 错误处理
@Service
public class ChatService {
private final ChatClient chatClient;
public String chat(String message) {
try {
return chatClient.call(message);
} catch (Exception e) {
// 处理错误
log.error("Chat error", e);
return "抱歉，处理请求时出现错误";
}
}
}
3. 性能优化
- 使用流式响应提升用户体验
- 合理使用缓存减少 API 调用
- 批量处理 Embedding 请求
4. 成本控制
- 选择合适的模型（GPT-3.5 vs GPT-4）
- 限制 Token 使用量
- 监控 API 调用情况
常用依赖
<!-- OpenAI -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>
<!-- Anthropic -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-anthropic-spring-boot-starter</artifactId>
</dependency>
<!-- Azure OpenAI -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-azure-openai-spring-boot-starter</artifactId>
</dependency>
<!-- Vector Store (PGVector) -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-pgvector-store-spring-boot-starter</artifactId>
</dependency>
示例 Prompt
- "如何使用 Spring AI 集成 OpenAI？"
- "Spring AI 中如何实现流式响应？"
- "如何在 Spring AI 中使用 Embedding 和 Vector Store？"
- "Spring AI 中如何实现 Function Calling？"
- "如何配置 Spring AI 支持多个模型？"
能力边界
✅ 适用场景
- 当你需要使用此技能对应的技术栈时
- 当项目需要遵循最佳实践时
- 当需要快速上手或深入理解核心概念时
⚠️ 需要注意
- 复杂业务逻辑需要结合具体场景调整
- 性能优化需要根据实际数据量评估
❌ 不适用场景
- 不相关的技术栈或框架
- 需要完全自定义的特殊场景
常见陷阱 (Gotchas)
- 版本兼容性：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异
- 配置文件格式：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查
- 环境变量：确保所有必要的环境变量已正确设置，敏感信息不要硬编码
- 依赖冲突：多版本共存时注意依赖冲突，使用 lock 文件锁定版本
- 性能陷阱：大数据量场景下注意性能优化，避免 N+1 查询等常见问题
使用流程
Step 1: 环境准备
确保开发环境已安装必要的依赖和工具。
Step 2: 配置初始化
根据项目需求进行基础配置。
Step 3: 核心功能使用
按照示例代码实现核心功能。
Step 4: 测试验证
运行测试确保功能正常。
Step 5: 部署上线
完成开发后进行部署和监控。