SpringAI-接入OpenAI

Spring AI 支持来自OpenAI（ChatGPT背后的公司）的各种人工智能语言模型。OpenAI通过创建行业领先的文本生成模型和嵌入技术，极大地推动了对AI驱动文本生成的兴趣。

先决条件

您需要在OpenAI创建API以访问ChatGPT模型。
在OpenAI注册页面创建账户，并在API密钥页面生成令牌。
Spring AI项目定义了一个名为spring.ai.openai.api-key的配置属性，您应将其设置为从openai.com获取的API密钥值。

可在application.properties文件中设置此配置属性：

spring.ai.openai.api-key=<您的OpenAI-API密钥>

为增强API密钥等敏感信息的安全性，可使用Spring表达式语言(SpEL)引用自定义环境变量：

# application.yml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}

# 环境变量或.env文件
export OPENAI_API_KEY=<您的OpenAI-API密钥>

也可在应用代码中编程设置：

// 从安全源或环境变量获取API密钥
String apiKey = System.getenv("OPENAI_API_KEY");

添加仓库与BOM
Spring AI工件发布在Maven中央仓库和Spring快照仓库。请参考"工件仓库"章节将其添加到构建系统。
为统一依赖管理，Spring AI提供BOM（材料清单）确保项目使用一致版本。请参考"依赖管理"章节将Spring AI BOM加入构建系统。

自动配置

Spring AI自动配置和starter模块的工件名称有重大变更，详情请查阅升级说明。
Spring AI为OpenAI聊天客户端提供Spring Boot自动配置。启用需添加以下依赖：

Maven

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

Gradle

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}

请参考"依赖管理"章节将Spring AI BOM加入构建文件。

聊天属性

重试属性
前缀spring.ai.retry用于配置OpenAI聊天模型的重试机制：

连接属性
前缀spring.ai.openai用于连接OpenAI：

多组织用户可通过指定组织ID和项目ID将API请求计入特定组织/项目。

配置属性
聊天自动配置的启用/禁用现通过顶级属性spring.ai.model.chat配置：

• 启用：spring.ai.model.chat=openai（默认启用）

• 禁用：spring.ai.model.chat=none（或非openai值）

此项变更为支持多模型配置。

前缀spring.ai.openai.chat用于配置OpenAI聊天模型：

所有spring.ai.openai.chat.options前缀属性可通过运行时选项在Prompt调用中覆盖。

运行时选项

OpenAiChatOptions类提供模型配置（如模型选择、温度值等）。启动时默认选项可通过构造函数或属性配置。运行时可通过Prompt调用覆盖：

ChatResponse response = chatModel.call(
    new Prompt(
        "生成5个著名海盗的名字",
        OpenAiChatOptions.builder()
            .model("gpt-4o")
            .temperature(0.4)
        .build()
    ));

除模型特定选项外，也可使用ChatOptionsBuilder#builder()创建便携式配置。

函数调用

可向OpenAiChatModel注册Java函数，使模型智能输出JSON参数调用函数。这是连接LLM与外部工具的强大技术，详见[工具调用文档]。

多模态

多模态指模型同时处理文本、图像、音频等多种信息的能力。OpenAI支持文本、视觉和音频输入模态。

视觉支持
支持视觉的模型包括gpt-4, gpt-4o, gpt-4o-mini，详见[视觉指南]。

OpenAI用户消息API可包含Base64编码图像或URL。Spring AI的Message接口通过Media类型支持多模态，示例：

// 使用本地图片
var imageResource = new ClassPathResource("/multimodal.test.png");
var userMessage = new UserMessage("解释图片内容", 
        new Media(MimeTypeUtils.IMAGE_PNG, imageResource));

// 使用图片URL
var userMessage = new UserMessage("解释图片内容",
        new Media(MimeTypeUtils.IMAGE_PNG, 
        URI.create("https://example.com/image.png")));

ChatResponse response = chatModel.call(new Prompt(userMessage,
        OpenAiChatOptions.builder().model("gpt-4o").build()));

可传递多张图片。GPT_4_VISION_PREVIEW自2024年6月17日起仅限现有用户使用。

音频输入
支持音频输入的模型如gpt-4o-audio-preview，详见[音频指南]。

var audioResource = new ClassPathResource("audio.mp3");
var userMessage = new UserMessage("解析录音内容",
        List.of(new Media(MimeTypeUtils.parseMimeType("audio/mp3"), audioResource)));

ChatResponse response = chatModel.call(new Prompt(List.of(userMessage),
        OpenAiChatOptions.builder().model("gpt-4o-audio-preview").build()));

支持多音频文件，目前仅支持audio/mp3和audio/wav格式。

音频输出

var userMessage = new UserMessage("讲个关于Spring的笑话");
ChatResponse response = chatModel.call(new Prompt(List.of(userMessage),
        OpenAiChatOptions.builder()
            .model("gpt-4o-audio-preview")
            .outputModalities(List.of("text", "audio"))
            .outputAudio(new AudioParameters(Voice.ALLOY, AudioResponseFormat.WAV))
            .build()));

String text = response.getResult().getOutput().getContent(); // 文本转录
byte[] audioData = response.getResult().getOutput().getMedia().get(0).getDataAsByteArray(); // 音频数据

需在选项中指定音频模态和声音参数。

结构化输出

OpenAI提供结构化输出API，确保响应严格符合JSON模式。除通用转换器外，Spring AI支持专属配置。

配置方式
可通过编程或属性配置响应格式：

// 编程配置示例
String jsonSchema = "..."; // JSON模式字符串
Prompt prompt = new Prompt("解方程: 8x + 7 = -23",
        OpenAiChatOptions.builder()
            .model("gpt-4o-mini")
            .responseFormat(new ResponseFormat(ResponseFormat.Type.JSON_SCHEMA, jsonSchema))
            .build());

# 属性配置
spring.ai.openai.chat.options.response-format.type=JSON_SCHEMA
spring.ai.openai.chat.options.response-format.schema={"type":"object", ...}

整合BeanOutputConverter
可利用工具自动生成模式并转换响应：

record Solution(...) { /* 字段定义 */ }

var outputConverter = new BeanOutputConverter<>(Solution.class);
var jsonSchema = outputConverter.getJsonSchema();

// 创建Prompt（同上）
ChatResponse response = chatModel.call(prompt);
Solution result = outputConverter.convert(response.getResult().getOutput().getContent());

示例控制器

创建Spring Boot项目并添加依赖后，配置application.properties：

spring.ai.openai.api-key=您的密钥
spring.ai.openai.chat.options.model=gpt-4o
spring.ai.openai.chat.options.temperature=0.7

控制器实现：

@RestController
public class ChatController {
    private final OpenAiChatModel chatModel;

    @Autowired
    public ChatController(OpenAiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public Map<String,String> generate(@RequestParam String message) {
        return Map.of("generation", chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
    public Flux<ChatResponse> generateStream(@RequestParam String message) {
        return chatModel.stream(new Prompt(new UserMessage(message)));
    }
}

手动配置
添加spring-ai-openai依赖后：

// 创建API客户端
var openAiApi = OpenAiApi.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .build();

// 构建配置选项
var options = OpenAiChatOptions.builder()
        .model("gpt-3.5-turbo")
        .temperature(0.4)
        .build();

// 实例化聊天模型
var chatModel = new OpenAiChatModel(openAiApi, options);

// 同步调用
ChatResponse response = chatModel.call(new Prompt("生成5个海盗名"));

// 流式调用
Flux<ChatResponse> stream = chatModel.stream(new Prompt("生成5个海盗名"));

底层OpenAiApi客户端

OpenAiApi是轻量级OpenAI API客户端：

OpenAiApi api = OpenAiApi.builder().apiKey("key").build();

// 同步请求
ResponseEntity<ChatCompletion> response = api.chatCompletionEntity(
    new ChatCompletionRequest(messages, "gpt-3.5-turbo", 0.8, false));

// 流式请求
Flux<ChatCompletionChunk> stream = api.chatCompletionStream(
    new ChatCompletionRequest(messages, "gpt-3.5-turbo", 0.8, true));

API密钥管理
Spring AI通过ApiKey接口提供灵活管理：

默认配置

spring.ai.openai.api-key=您的密钥

自定义实现

ApiKey customKey = new ApiKey() {
    @Override
    public String getValue() {
        // 自定义获取逻辑
        return "动态密钥";
    }
};

OpenAiApi api = OpenAiApi.builder().apiKey(customKey).build();
OpenAiChatClient client = new OpenAiChatClient(api);

适用于从密钥库获取、动态轮换或复杂选择逻辑的场景。