Spring AI 使用 OpenAI SDK 图像生成（官方版）

Spring AI 通过 OpenAI Java SDK 支持 OpenAI 的 DALL-E 图像生成模型，提供了与 OpenAI 服务（包括微软云服务和 GitHub 模型）的健壮、官方维护的集成方案。

该实现使用 OpenAI 官方提供的 Java SDK。如需替代的 Spring AI 实现方案，请参考 OpenAI 图像生成文档。 DALL-E 是 OpenAI 推出的顶尖图像生成模型，能够根据自然语言描述创建逼真的图像和艺术作品。

OpenAI SDK 模块会根据你提供的基础 URL 自动检测服务提供商（OpenAI、微软云服务或 GitHub 模型）。

身份认证

身份认证通过基础 URL 和 API 密钥完成。该实现支持通过 Spring Boot 配置属性或环境变量进行灵活配置。

使用 OpenAI

如果直接使用 OpenAI，请在 OpenAI 注册页面创建账号，并在 API 密钥页面生成 API 密钥。

基础 URL 无需手动设置，默认值为 api.openai.com/v1：

spring.ai.openai-sdk.api-key=<your-openai-api-key>
# base-url 为可选配置，默认值：https://api.openai.com/v1

也可以使用环境变量：

export OPENAI_API_KEY=<your-openai-api-key>
# OPENAI_BASE_URL 为可选配置，默认值：https://api.openai.com/v1

使用微软云服务

当使用微软云服务 URL 时，系统会自动识别。你可以通过配置属性进行设置：

spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.api-key=<your-api-key>
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>

也可以使用环境变量：

export OPENAI_BASE_URL=https://<your-deployment-url>.openai.azure.com
export OPENAI_API_KEY=<your-api-key>

无密码认证（Azure 推荐）：

微软云服务支持无需提供 API 密钥的无密码认证，在 Azure 环境中运行时安全性更高。

启用无密码认证，需添加 com.azure:azure-identity 依赖：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

然后无需配置 API 密钥即可使用：

spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>
# 无需配置 api-key，系统会自动使用环境中的 Azure 凭证

使用 GitHub 模型

当使用 GitHub 模型基础 URL 时，系统会自动识别。你需要创建一个拥有 models:read 权限的 GitHub 个人访问令牌（PAT）。

spring.ai.openai-sdk.base-url=https://models.inference.ai.azure.com
spring.ai.openai-sdk.api-key=github_pat_XXXXXXXXXXX

也可以使用环境变量：

export OPENAI_BASE_URL=https://models.inference.ai.azure.com
export OPENAI_API_KEY=github_pat_XXXXXXXXXXX

为了安全处理 API 密钥等敏感信息，你可以在配置中使用 Spring 表达式语言（SpEL）：

spring.ai.openai-sdk.api-key=${OPENAI_API_KEY}

添加仓库和物料清单（BOM）

Spring AI 构件发布在 Maven 中央仓库和 Spring 快照仓库中。参考构件仓库章节，将这些仓库添加到你的构建系统中。

为了简化依赖管理，Spring AI 提供了物料清单（BOM），确保整个项目使用一致版本的 Spring AI。参考依赖管理章节，将 Spring AI BOM 添加到你的构建系统中。

自动配置

Spring AI 为 OpenAI SDK 图像模型提供了 Spring Boot 自动配置。启用该功能需要在项目的 Maven pom.xml 或 Gradle build.gradle 文件中添加以下依赖：

Maven

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

参考依赖管理章节，将 Spring AI BOM 添加到你的构建文件中。

配置属性

连接属性

以 spring.ai.openai-sdk 为前缀的属性用于配置 OpenAI SDK 客户端。

微软云服务属性

OpenAI SDK 实现原生支持微软云服务并支持自动配置：

微软云服务支持无密码认证。添加 azure-identity 依赖后，未提供 API 密钥时系统会自动使用环境中的 Azure 凭证。

GitHub 模型属性

原生支持 GitHub 模型：

GitHub 模型需要拥有 models:read 权限的个人访问令牌，通过 OPENAI_API_KEY 环境变量或 api-key 属性配置。

图像模型属性

以 spring.ai.openai-sdk.image 为前缀的属性用于配置图像模型实现：

所有以 spring.ai.openai-sdk.image.options 为前缀的属性，都可以在运行时通过 ImagePrompt 添加请求专属选项覆盖。

运行时选项

OpenAiSdkImageOptions.java 提供了 OpenAI 配置项，包括使用的模型、质量、尺寸、风格和生成数量等。

默认选项可以通过 spring.ai.openai-sdk.image.options 配置属性设置。

启动时可以通过 OpenAiSdkImageModel 构造方法设置全局默认选项；运行时可以在 ImagePrompt 中使用 OpenAiSdkImageOptions 实例覆盖默认配置。

示例：为单个请求覆盖默认模型和质量：

ImageResponse response = imageModel.call(
    new ImagePrompt("A light cream colored mini golden doodle",
        OpenAiSdkImageOptions.builder()
            .model("dall-e-3")
            .quality("hd")
            .N(1)
            .width(1024)
            .height(1024)
            .style("vivid")
        .build()));

除了模型专属的 OpenAiSdkImageOptions，你还可以使用 ImageOptionsBuilder 创建的通用 ImageOptions 实例。

示例控制器

创建新的 Spring Boot 项目，并将 spring-ai-openai-sdk 添加到依赖中。

在 src/main/resources 目录下添加 application.properties 文件配置 OpenAI SDK 图像模型：

spring.ai.openai-sdk.api-key=YOUR_API_KEY
spring.ai.openai-sdk.image.options.model=dall-e-3

将 api-key 替换为你的 OpenAI 凭证。

配置完成后会创建 OpenAiSdkImageModel 实例并可注入使用。以下是简单的 @RestController 示例：

@RestController
public class ImageController {

    private final ImageModel imageModel;

    @Autowired
    public ImageController(ImageModel imageModel) {
        this.imageModel = imageModel;
    }

    @GetMapping("/ai/image")
    public Map<String, Object> generateImage(
            @RequestParam(value = "prompt", defaultValue = "A light cream colored mini golden doodle") String prompt) {
        ImageResponse response = this.imageModel.call(
            new ImagePrompt(prompt,
                OpenAiSdkImageOptions.builder()
                    .quality("hd")
                    .N(1)
                    .width(1024)
                    .height(1024)
                .build()));

        String imageUrl = response.getResult().getOutput().getUrl();
        return Map.of("url", imageUrl);
    }
}

手动配置

OpenAiSdkImageModel 实现了 ImageModel 接口，并使用官方 OpenAI Java SDK 连接服务。

如果不使用 Spring Boot 自动配置，可以手动配置。添加依赖：

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

Gradle：

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

spring-ai-openai-sdk 依赖同时提供 OpenAiSdkChatModel 和 OpenAiSdkEmbeddingModel。更多聊天模型信息参考 OpenAI SDK 聊天章节。

创建 OpenAiSdkImageModel 实例生成图像：

var imageOptions = OpenAiSdkImageOptions.builder()
    .model("dall-e-3")
    .quality("hd")
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();

var imageModel = new OpenAiSdkImageModel(imageOptions);

ImageResponse response = imageModel.call(
    new ImagePrompt("A light cream colored mini golden doodle",
        OpenAiSdkImageOptions.builder()
            .N(1)
            .width(1024)
            .height(1024)
        .build()));

OpenAiSdkImageOptions 提供图像生成请求的配置，支持建造者模式便捷创建。

微软云服务配置

var imageOptions = OpenAiSdkImageOptions.builder()
    .baseUrl("https://your-resource.openai.azure.com")
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .deploymentName("dall-e-3")
    .azureOpenAIServiceVersion(AzureOpenAIServiceVersion.V2024_10_01_PREVIEW)
    .azure(true)  // 启用微软云服务模式
    .build();

var imageModel = new OpenAiSdkImageModel(imageOptions);

微软云服务支持无密码认证，添加 azure-identity 依赖后，不提供 API 密钥会自动使用环境凭证。

GitHub 模型配置

var imageOptions = OpenAiSdkImageOptions.builder()
    .baseUrl("https://models.inference.ai.azure.com")
    .apiKey(System.getenv("GITHUB_TOKEN"))
    .model("dall-e-3")
    .githubModels(true)
    .build();

var imageModel = new OpenAiSdkImageModel(imageOptions);

可观测性

OpenAI SDK 实现通过 Micrometer 支持 Spring AI 的可观测性特性，所有图像模型操作都支持监控和追踪。

附加资源

OpenAI 官方 Java SDK
OpenAI 图像 API 文档
OpenAI 图像生成指南
OpenAI 模型列表
微软云服务文档
GitHub 模型