partme-ai/spring-ai

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 支持多个模型？"