Spring AI实战：快速集成OpenAI智能对话服务

1. Spring AI 入门实战：从零搭建智能对话服务

最近在尝试将AI能力集成到Spring Boot应用中，发现Spring社区推出的Spring AI项目确实能大幅简化开发流程。不过在实际配置过程中，遇到了不少依赖管理和环境配置的问题，这里把我的踩坑经历和最终解决方案完整记录下来，希望能帮到同样想快速上手Spring AI的开发者。

Spring AI是Spring官方推出的AI应用开发框架，它抽象了不同AI提供商（如OpenAI、Azure OpenAI等）的接口，让开发者可以用统一的Spring风格API调用各种AI能力。目前最新版本是0.8.0，需要Spring Boot 3.2+作为基础环境。下面我会从项目搭建、配置调试到实际应用，一步步展示如何构建一个基于OpenAI的智能对话服务。

2. 环境准备与依赖配置

2.1 项目基础框架搭建

首先需要确保使用正确版本的Spring Boot。由于Spring AI 0.8.0采用了Spring Boot 3.2的新特性，我们必须使用3.2.5或更高版本作为父项目：

xml复制<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.5</version>
    <relativePath/> <!-- 优先从本地仓库查找 -->
</parent>

这里有个关键细节：Spring AI目前还没有纳入Spring Boot的BOM（Bill of Materials）依赖管理，所以相关依赖需要显式指定版本号。这在实际开发中要注意，因为大多数Spring生态的starter都已经包含在BOM里了。

2.2 核心依赖配置

接下来添加必要的依赖项。除了常规的web starter，关键是要引入spring-ai-openai-spring-boot-starter：

xml复制<dependencies>
    <!-- 基础Spring Boot依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>

    <!-- Web支持 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring AI OpenAI集成 -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
        <version>0.8.0</version>
    </dependency>
</dependencies>

注意：目前Spring AI还处于快速迭代阶段，不同版本间可能存在API变化。建议锁定特定版本号，避免自动升级导致兼容性问题。

2.3 仓库配置技巧

由于Spring AI尚未发布到Maven中央仓库，我们需要在settings.xml中添加Spring的里程碑仓库：

xml复制<repository>
    <id>spring-milestones</id>
    <name>Spring Milestones</name>
    <url>https://repo.spring.io/milestone</url>
    <snapshots>
        <enabled>false</enabled>
    </snapshots>
</repository>

这个配置可以放在settings.xml的部分，或者直接在项目的pom.xml中声明。我推荐前者，因为这样所有项目都能共享这个配置。

3. 应用配置详解

3.1 基础配置参数

在application.yml中，我们需要配置OpenAI的访问参数：

yaml复制spring:
  ai:
    openai:
      api-key: sk-your-api-key-here
      chat:
        options:
          model: gpt-3.5-turbo

关键参数说明：

• api-key：从OpenAI平台获取的API密钥
• model：指定使用的模型版本，gpt-3.5-turbo是性价比较高的选择

3.2 高级配置选项

Spring AI还支持更多细粒度配置：

yaml复制spring:
  ai:
    openai:
      base-url: https://api.openai.com/v1  # 可自定义API端点
      chat:
        options:
          temperature: 0.7  # 控制生成文本的随机性
          max-tokens: 500   # 限制响应长度
          top-p: 1.0        # 核采样参数

这些参数可以根据实际需求调整。例如，在需要创造性输出的场景，可以适当提高temperature值；在需要精确回答的场景，则应该降低这个值。

4. 核心功能实现

4.1 创建对话服务

Spring AI最强大的地方在于它提供了现成的ChatClient接口，我们只需要简单注入就能使用：

java复制import org.springframework.ai.chat.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AIController {

    private final ChatClient chatClient;

    @Autowired
    public AIController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @GetMapping("/chat")
    public String generate(@RequestParam String message) {
        return chatClient.call(message);
    }
}

这个简单的REST接口已经可以处理基本的对话请求。Spring AI会自动处理与OpenAI API的所有底层通信细节。

4.2 进阶使用：结构化提示

实际应用中，我们往往需要更结构化的提示词设计。Spring AI提供了PromptTemplate支持：

java复制@GetMapping("/recommend")
public String recommendBook(@RequestParam String genre) {
    String template = """
        请为我推荐3本{genre}类型的书籍。
        每本书需要包含：
        - 书名
        - 作者
        - 简短推荐理由(不超过50字)
        请用JSON格式返回结果""";
    
    PromptTemplate promptTemplate = new PromptTemplate(template);
    Prompt prompt = promptTemplate.create(Map.of("genre", genre));
    
    return chatClient.call(prompt.getContents());
}

这种方式可以确保AI返回符合我们需求的结构化数据，便于后续处理。

5. 实战问题排查

5.1 常见错误与解决方案

在实际开发中，我遇到了几个典型问题：

1. 依赖下载失败

   • 现象：无法解析spring-ai-openai-spring-boot-starter
   • 原因：没有正确配置Spring里程碑仓库
   • 解决：确保settings.xml或pom.xml中有正确的repository配置

2. 版本冲突

   • 现象：启动时报MethodNotFound或ClassNotFound异常
   • 原因：Spring Boot版本不兼容
   • 解决：必须使用Spring Boot 3.2.5或更高版本

3. API密钥无效

   • 现象：401 Unauthorized错误
   • 解决：检查api-key配置，确保没有多余空格或错误字符

5.2 性能优化建议

1. 连接池配置

   yaml复制spring:
     ai:
       openai:
         client:
           connect-timeout: 10s
           read-timeout: 30s
   

   适当调整超时设置可以避免长时间等待

2. 异步处理
   对于耗时较长的AI请求，建议使用异步处理：

   java复制@GetMapping("/async-chat")
   public CompletableFuture<String> asyncGenerate(@RequestParam String message) {
       return CompletableFuture.supplyAsync(() -> chatClient.call(message));
   }
   

3. 缓存策略
   对相似请求的结果进行缓存，可以显著减少API调用次数和响应时间。

6. 扩展应用场景

Spring AI的能力不仅限于简单对话。在实际项目中，我们可以利用它实现更多复杂功能：

6.1 文档摘要生成

java复制public String generateSummary(String document) {
    String prompt = """
        请为以下文档生成一个简洁的摘要：
        {document}
        
        摘要要求：
        - 不超过200字
        - 包含主要观点
        - 使用中文输出""";
    
    return chatClient.call(prompt.replace("{document}", document));
}

6.2 数据格式化转换

java复制public String formatData(String rawData) {
    String template = """
        将以下数据转换为标准的JSON格式：
        {rawData}
        
        要求：
        - 识别键值对
        - 处理嵌套结构
        - 确保JSON有效性""";
    
    return chatClient.call(template.replace("{rawData}", rawData));
}

6.3 代码辅助生成

java复制public String generateCode(String requirement) {
    String prompt = """
        根据以下需求生成Java代码：
        {requirement}
        
        要求：
        - 使用Java 17语法
        - 包含必要的注释
        - 遵循Spring最佳实践""";
    
    return chatClient.call(prompt.replace("{requirement}", requirement));
}

我在实际使用中发现，Spring AI虽然还在早期阶段，但已经能显著提升开发效率。特别是在快速原型开发阶段，可以省去大量样板代码的编写时间。不过要注意，生产环境使用需要考虑API成本、速率限制和错误处理等更多因素。建议从简单功能开始，逐步扩展到核心业务场景。