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 的中文处理能力？”