spring-ai-alibaba

Spring AI Alibaba Development Guide

Overview

Spring AI Alibaba provides integration with Alibaba Cloud DashScope (Tongyi Qianwen), supporting the use of Alibaba Cloud's large language model services.

Core Features

1. Project Creation

Dependencies：

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-starter-model-aliyun-dashscope</artifactId>
</dependency>

Or use Gradle：

dependencies {
    implementation 'com.alibaba.cloud.ai:spring-ai-starter-model-aliyun-dashscope'
}

2. Configuration

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

Using 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();
    }
}

Streaming Responses：

@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. Model Selection

Supported Models：

• qwen-turbo - Tongyi Qianwen Turbo model (fast response)
• qwen-plus - Tongyi Qianwen Plus model (balanced performance)
• qwen-max - Tongyi Qianwen Max model (strongest performance)

Configuring Different Models：

spring:
  ai:
    alibaba:
      dashscope:
        chat:
          options:
            model: qwen-max  # 使用最强模型
            temperature: 0.7
            max-tokens: 2000

5. Prompt Template

Defining Templates：

@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);
    }
}

Using 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

Configuration：

spring:
  ai:
    alibaba:
      dashscope:
        embedding:
          options:
            model: text-embedding-V1

Using 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. Multi-turn Conversations

Maintaining Conversation Context：

@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();
    }
}

Best Practices

1. Configuration Management

• Use environment variables to store the API Key
• Distinguish between development and production environment configurations
• Configure reasonable timeout and retry policies

2. Error Handling

@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. Performance Optimization

• Choose the appropriate model based on the scenario (turbo/plus/max)
• Use streaming responses to improve user experience
• Use caching reasonably to reduce API calls

4. Cost Control

• Choose the appropriate model (qwen-turbo has lower cost)
• Limit Token usage
• Monitor API call usage

5. Chinese Language Optimization

Tongyi Qianwen has good support for Chinese, and you can:

• Use Chinese Prompt templates
• Optimize Chinese prompts
• Leverage multi-turn conversation capabilities

Common Dependencies

<!-- 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>

Configuration Example

Complete Configuration：

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

Example Prompt

• "How to integrate Tongyi Qianwen using Spring AI Alibaba?"
• "How to configure different models in Spring AI Alibaba?"
• "How to implement streaming responses in Spring AI Alibaba?"
• "How to implement multi-turn conversations in Spring AI Alibaba?"
• "How to optimize the Chinese language processing capability of Spring AI Alibaba?"