full-stack-skills Spring AI Alibaba 开发指南
概述
Spring AI Alibaba 提供了与阿里云 DashScope（通义千问）的集成，支持使用阿里云的大语言模型服务。
核心功能
1. 项目创建
依赖：
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-starter-model-aliyun-dashscope</artifactId>
</dependency>
或使用 Gradle：
dependencies {
implementation 'com.alibaba.cloud.ai:spring-ai-starter-model-aliyun-dashscope'
}
2. 配置
application.yml：
spring:
ai:
alibaba:
dashscope:
api-key: ${DASHSCOPE_API_KEY}
chat:
options:
model: qwen-turbo
temperature: 0.7
max-tokens: 2000
application.properties：
spring.ai.alibaba.dashscope.api-key=${DASHSCOPE_API_KEY}
spring.ai.alibaba.dashscope.chat.options.model=qwen-turbo
spring.ai.alibaba.dashscope.chat.options.temperature=0.7
spring.ai.alibaba.dashscope.chat.options.max-tokens=2000
3. Chat Client
使用 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());
}
}
4. 模型选择
支持的模型：
qwen-turbo- 通义千问 Turbo 模型（快速响应）qwen-plus- 通义千问 Plus 模型（平衡性能）qwen-max- 通义千问 Max 模型（最强性能）
配置不同模型：
spring:
ai:
alibaba:
dashscope:
chat:
options:
model: qwen-max # 使用最强模型
temperature: 0.7
max-tokens: 2000
5. 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();
}
}
6. Embedding
配置：
spring:
ai:
alibaba:
dashscope:
embedding:
options:
model: text-embedding-V1
使用 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();
}
}
7. 多轮对话
维护对话上下文：
@Service
public class ConversationService {
private final ChatClient chatClient;
private final List<Message> conversationHistory = new ArrayList<>();
public ConversationService(ChatClient chatClient) {
this.chatClient = chatClient;
}
public String chat(String userMessage) {
conversationHistory.add(new UserMessage(userMessage));
Prompt prompt = new Prompt(conversationHistory);
ChatResponse response = chatClient.call(prompt);
String assistantMessage = response.getResult().getOutput().getContent();
conversationHistory.add(new AssistantMessage(assistantMessage));
return assistantMessage;
}
public void clearHistory() {
conversationHistory.clear();
}
}
最佳实践
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. 性能优化
- 根据场景选择合适的模型（turbo/plus/max）
- 使用流式响应提升用户体验
- 合理使用缓存减少 API 调用
4. 成本控制
- 选择合适的模型（qwen-turbo 成本更低）
- 限制 Token 使用量
- 监控 API 调用情况
5. 中文优化
通义千问对中文支持较好，可以：
- 使用中文 Prompt 模板
- 优化中文提示词
- 利用多轮对话能力
常用依赖
<!-- Spring AI Alibaba DashScope -->
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-starter-model-aliyun-dashscope</artifactId>
</dependency>
<!-- Spring Boot Web (可选，用于 REST API) -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
配置示例
完整配置：
spring:
ai:
alibaba:
dashscope:
api-key: ${DASHSCOPE_API_KEY}
chat:
options:
model: qwen-turbo
temperature: 0.7
max-tokens: 2000
top-p: 0.9
embedding:
options:
model: text-embedding-V1
示例 Prompt
- "如何使用 Spring AI Alibaba 集成通义千问？"
- "Spring AI Alibaba 中如何配置不同的模型？"
- "如何在 Spring AI Alibaba 中实现流式响应？"
- "Spring AI Alibaba 中如何实现多轮对话？"
- "如何优化 Spring AI Alibaba 的中文处理能力？"
能力边界
✅ 适用场景
- 当你需要使用此技能对应的技术栈时
- 当项目需要遵循最佳实践时
- 当需要快速上手或深入理解核心概念时
⚠️ 需要注意
- 复杂业务逻辑需要结合具体场景调整
- 性能优化需要根据实际数据量评估
❌ 不适用场景
- 不相关的技术栈或框架
- 需要完全自定义的特殊场景
常见陷阱 (Gotchas)
- 版本兼容性：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异
- 配置文件格式：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查
- 环境变量：确保所有必要的环境变量已正确设置，敏感信息不要硬编码
- 依赖冲突：多版本共存时注意依赖冲突，使用 lock 文件锁定版本
- 性能陷阱：大数据量场景下注意性能优化，避免 N+1 查询等常见问题
使用流程
Step 1: 环境准备
确保开发环境已安装必要的依赖和工具。
Step 2: 配置初始化
根据项目需求进行基础配置。
Step 3: 核心功能使用
按照示例代码实现核心功能。
Step 4: 测试验证
运行测试确保功能正常。
Step 5: 部署上线
完成开发后进行部署和监控。