使用 Spring AI OpenAI Starter 快速集成指南

使用 Spring AI OpenAI Starter 快速集成指南

Spring AI 的 spring-ai-openai-spring-boot-starter 提供了与 OpenAI 模型（如 GPT-3.5、GPT-4）开箱即用的集成能力。以下是完整的配置与实战步骤：

---

1. 添加依赖

如果找不到对应版本可以查看 对应ai版本，一定要认准groupId，版本比较多，另外一版本mvnrepository 我们用的是第一个
在 pom.xml 中添加 Spring AI OpenAI Starter：

<dependency>
    <groupId>io.springboot.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>1.0.0</version> <!-- 使用最新版本 -->
</dependency>

---

2. 配置 OpenAI API 密钥

在 application.yml 中配置 OpenAI 的 API 密钥和模型参数：

spring:
  ai:
    openai:
      api-key: "sk-your-openai-api-key-here"  # 替换为你的 OpenAI API 密钥
      base-url: "https://api.openai.com/v1"    # 默认值，通常无需修改
      chat:
        options:
          model: "deepseek-r1:671b"                # 默认模型
          temperature: 0.7                       # 生成文本的随机性控制
          max-tokens: 500

---

3. 核心代码实现

3.1 注入 ChatClient

Spring AI 会自动配置 ChatClient 实例，直接注入即可使用：

import org.springframework.ai.chat.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/ai")
public class AIController {

    private final ChatClient chatClient;

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

   @PostMapping("/chat")
    public String generateText(@RequestBody String prompt) {
        return chatClient.call(prompt);
    }
}

3.2 高级参数控制

通过 ChatOptions 动态调整请求参数：

import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.openai.OpenAiChatOptions;

@PostMapping("/chat/advanced")
public String advancedChat(@RequestBody String prompt) {
    // 自定义参数
    OpenAiChatOptions options = OpenAiChatOptions.builder()
        .withModel("gpt-4")
        .withTemperature(0.3)
        .withMaxTokens(1000)
        .build();

    // 构建 Prompt
    Prompt request = new Prompt(prompt, options);
    return chatClient.generate(request).getOutput().getContent();
}

---

4. 流式响应（Server-Sent Events）

实现实时流式输出：

import org.springframework.ai.chat.StreamingChatClient;
import reactor.core.publisher.Flux;

@Autowired
private StreamingChatClient streamingChatClient;

  public Flux<String> streamChat(@RequestParam String prompt) {
    return streamingChatClient.stream(prompt);
  }

---

5. 异常处理

全局捕获 OpenAI 相关异常：

import org.springframework.ai.openai.api.OpenAiApiException;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class AIExceptionHandler {

    @ExceptionHandler(OpenAiApiException.class)
    public ResponseEntity<String> handleOpenAiException(OpenAiApiException ex) {
        return ResponseEntity.status(ex.getStatusCode())
            .body("OpenAI 服务错误: " + ex.getMessage());
    }
}

---

6. 高级功能

6.1 多模态支持（图片生成）

import org.springframework.ai.openai.OpenAiImageClient;
import org.springframework.ai.openai.api.OpenAiImageApi;

@Autowired
private OpenAiImageClient imageClient;

  @PostMapping("/generate-image")
  public String generateImage(@RequestParam String prompt) {
    ImageResponse call = imageClient.call(
      new ImagePrompt(prompt)
    );
    return call.getResult().getOutput().getUrl();
  }

6.2 嵌入向量（Embeddings）

import org.springframework.ai.embedding.EmbeddingClient;

@Autowired
private EmbeddingClient embeddingClient;

@PostMapping("/embed")
public List<Double> getEmbedding(@RequestBody String text) {
    return embeddingClient.embed(text);
}

---

7. 配置项详解

配置项	说明
spring.ai.openai.api-key	OpenAI API 密钥（必填）
spring.ai.openai.base-url	API 端点地址（默认 https://api.openai.com/v1）
spring.ai.openai.chat.options.model	聊天模型（如 gpt-4-turbo、gpt-3.5-turbo）
spring.ai.openai.chat.options.temperature	生成文本的随机性控制）
spring.ai.openai.chat.options.portmax-tokens	最大token

---

8. 测试验证

8.1 使用 CURL 测试

curl -X POST -H "Content-Type: application/json" \
-d '"请写一首关于春天的诗"' \
http://localhost:8080/ai/chat

8.2 单元测试

@SpringBootTest
public class AIControllerTest {

    @Autowired
    private ChatClient chatClient;

    @Test
    void testChat() {
        String response = chatClient.generate("你好");
        assertNotNull(response);
        System.out.println("AI 回复: " + response);
    }
}

---

9. 安全与优化建议

1. 密钥管理：

   • 使用环境变量或 Vault 注入 api-key：

     spring:
       ai:
         openai:
           api-key: ${OPENAI_API_KEY}
     

   • 禁止在代码中硬编码密钥

2. 性能调优：

   spring:
     ai:
       openai:
         connect-timeout: 5000   # 连接超时（毫秒）
         read-timeout: 30000    # 读取超时（长文本生成场景）
   

3. 限流与熔断：

   // Resilience4j 熔断器配置
   @Bean
   public CircuitBreakerConfig circuitBreakerConfig() {
       return CircuitBreakerConfig.custom()
           .failureRateThreshold(50)  # 失败率阈值
           .waitDurationInOpenState(Duration.ofSeconds(30))
           .build();
   }
   

---

10. 常见问题

Q1：如何解决 401 Unauthorized 错误？

• 检查 api-key 是否正确
• 确认 API 密钥是否有访问目标模型的权限

Q2：如何处理 429 Too Many Requests？

• 降低请求频率
• 配置 Resilience4j 限流器：

  @RateLimiter(name = "openaiRateLimit", fallbackMethod = "rateLimitFallback")
  public String rateLimitedGenerate(String prompt) {
      return chatClient.generate(prompt);
  }
  

Q3：如何切换为 Azure OpenAI？
修改配置即可无缝切换：

spring:
  ai:
    openai:
      base-url: "https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-name}"
      api-key: "Azure API Key"
      headers:
        "api-key": "${spring.ai.openai.api-key}"  # Azure 需要 header 传参

---

通过以上步骤，您已快速实现 Spring Boot 与 OpenAI 的深度集成。如需扩展其他 AI 服务（如 DeepSeek），可参考 Spring AI 的 ChatClient 接口自定义实现。

附录

下篇文章介绍如何无缝接入DeepSeek