Skip to main content

OpenAI SDK Image Generation (Official)

Spring AI 通过 OpenAI Java SDK 支持 OpenAI 的 DALL-E 图像生成模型，提供与 OpenAI 服务（包括 Microsoft Foundry 和 GitHub Models）的强大且官方维护的集成。

NOTE: 此实现使用来自 OpenAI 的官方 OpenAI Java SDK。有关替代的 Spring AI 实现，请参阅 OpenAI Image Generation。

DALL-E 是来自 OpenAI 的最先进的图像生成模型，可以从自然语言描述创建逼真的图像和艺术作品。

OpenAI SDK 模块根据您提供的基础 URL 自动检测服务提供者（OpenAI、Microsoft Foundry 或 GitHub Models）。

Authentication​

使用基础 URL 和 API Key 进行身份验证。该实现通过 Spring Boot 属性或环境变量提供灵活的配置选项。

Using OpenAI​

如果您直接使用 OpenAI，请在 OpenAI signup page 创建账户，并在 API Keys page 生成 API key。

基础 URL 不需要设置，因为它默认为 https://api.openai.com/v1：

spring.ai.openai-sdk.api-key=<your-openai-api-key>
# base-url is optional, defaults to https://api.openai.com/v1

或使用环境变量：

export OPENAI_API_KEY=<your-openai-api-key>
# OPENAI_BASE_URL is optional, defaults to https://api.openai.com/v1

Using Microsoft Foundry​

当使用 Microsoft Foundry URL 时，Microsoft Foundry 会自动检测。您可以使用属性配置它：

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>

Passwordless Authentication (Recommended for Azure):

Microsoft Foundry 支持无密码身份验证，无需提供 API key，在 Azure 上运行时更安全。

要启用无密码身份验证，请添加 com.azure:azure-identity 依赖项：

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

然后配置时不使用 API key：

spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>
# No api-key needed - will use Azure credentials from environment

Using GitHub Models​

当使用 GitHub Models 基础 URL 时，GitHub Models 会自动检测。您需要创建一个具有 models:read 范围的 GitHub Personal Access Token (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

TIP: 为了在处理敏感信息（如 API keys）时增强安全性，您可以在属性中使用 Spring Expression Language (SpEL)：

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

Add Repositories and BOM​

Spring AI artifacts 发布在 Maven Central 和 Spring Snapshot 存储库中。 请参考 Artifact Repositories 部分，将这些存储库添加到您的构建系统。

为了帮助依赖管理，Spring AI 提供了一个 BOM（物料清单）以确保在整个项目中使用一致版本的 Spring AI。请参考 Dependency Management 部分，将 Spring AI BOM 添加到您的构建系统。

Auto-configuration​

Spring AI 为 OpenAI SDK Image Model 提供 Spring Boot 自动配置。 要启用它，请将以下依赖项添加到项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中：

Maven:

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

Gradle:

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

TIP: 请参考 Dependency Management 部分，将 Spring AI BOM 添加到您的构建文件中。

Configuration Properties​

Connection Properties​

前缀 spring.ai.openai-sdk 用作允许您配置 OpenAI SDK 客户端的属性前缀。

PropertyDescriptionDefault
spring.ai.openai-sdk.base-url连接的 URL。如果未设置，则从 OPENAI_BASE_URL 环境变量自动检测https://api.openai.com/v1
spring.ai.openai-sdk.api-keyAPI Key。如果未设置，则从 OPENAI_API_KEY 环境变量自动检测-
spring.ai.openai-sdk.organization-id可选，指定用于 API 请求的组织-
spring.ai.openai-sdk.timeout请求超时持续时间-
spring.ai.openai-sdk.max-retries失败请求的最大重试尝试次数-
spring.ai.openai-sdk.proxyOpenAI 客户端的代理设置（Java Proxy 对象）-
spring.ai.openai-sdk.custom-headers要在请求中包含的自定义 HTTP 标头。标头名称到标头值的映射-

Microsoft Foundry Properties​

OpenAI SDK 实现为 Microsoft Foundry 提供原生支持，具有自动配置：

PropertyDescriptionDefault
spring.ai.openai-sdk.microsoft-foundry启用 Microsoft Foundry 模式。如果基础 URL 包含 openai.azure.com、cognitiveservices.azure.com 或 .openai.microsoftFoundry.com，则自动检测false
spring.ai.openai-sdk.microsoft-deployment-nameMicrosoft Foundry 部署名称。如果未指定，将使用模型名称。也可通过别名 deployment-name 访问-
spring.ai.openai-sdk.microsoft-foundry-service-versionMicrosoft Foundry API 服务版本-
spring.ai.openai-sdk.credential用于无密码身份验证的凭据对象（需要 com.azure:azure-identity 依赖项）-

TIP: Microsoft Foundry 支持无密码身份验证。添加 com.azure:azure-identity 依赖项，当未提供 API key 时，实现将自动尝试使用环境中的 Azure 凭据。

GitHub Models Properties​

提供对 GitHub Models 的原生支持：

PropertyDescriptionDefault
spring.ai.openai-sdk.github-models启用 GitHub Models 模式。如果基础 URL 包含 models.github.ai 或 models.inference.ai.azure.com，则自动检测false

TIP: GitHub Models 需要具有 models:read 范围的 Personal Access Token。通过 OPENAI_API_KEY 环境变量或 spring.ai.openai-sdk.api-key 属性设置它。

Image Model Properties​

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

PropertyDescriptionDefault
spring.ai.openai-sdk.image.options.model用于图像生成的模型。可用模型：dall-e-2、dall-e-3。有关更多信息，请参阅 models 页面dall-e-3
spring.ai.openai-sdk.image.options.n要生成的图像数量。必须在 1 到 10 之间。对于 dall-e-3，仅支持 n=1-
spring.ai.openai-sdk.image.options.quality将生成的图像质量。hd 创建具有更精细细节和更大一致性的图像。此参数仅支持 dall-e-3。可用值：standard、hd-
spring.ai.openai-sdk.image.options.response-format返回生成的图像的格式。必须是 url 或 b64_json 之一-
spring.ai.openai-sdk.image.options.size生成的图像大小。对于 dall-e-2，必须是 256x256、512x512 或 1024x1024 之一。对于 dall-e-3 模型，必须是 1024x1024、1792x1024 或 1024x1792 之一-
spring.ai.openai-sdk.image.options.width生成的图像宽度。对于 dall-e-2，必须是 256、512 或 1024 之一-
spring.ai.openai-sdk.image.options.height生成的图像高度。对于 dall-e-2，必须是 256、512 或 1024 之一-
spring.ai.openai-sdk.image.options.style生成的图像样式。必须是 vivid 或 natural 之一。Vivid 使模型倾向于生成超真实和戏剧性的图像。Natural 使模型产生更自然、不那么超真实的图像。此参数仅支持 dall-e-3-
spring.ai.openai-sdk.image.options.user代表您的最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用-

TIP: 所有以 spring.ai.openai-sdk.image.options 为前缀的属性都可以通过在 ImagePrompt 调用中添加特定于请求的 image-options 在运行时覆盖。

Runtime Options​

OpenAiSdkImageOptions.java 提供 OpenAI 配置，例如要使用的模型、质量、大小、样式和要生成的图像数量。

也可以使用 spring.ai.openai-sdk.image.options 属性配置默认选项。

在启动时，使用 OpenAiSdkImageModel 构造函数设置用于所有图像生成请求的默认选项。 在运行时，您可以使用 OpenAiSdkImageOptions 实例作为 ImagePrompt 的一部分来覆盖默认选项。

例如，为特定请求覆盖默认模型和质量：

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()));

TIP: 除了模型特定的 OpenAiSdkImageOptions，您可以使用可移植的 ImageOptions 实例，使用 ImageOptionsBuilder#builder() 创建。

Sample Controller​

Create 一个新的 Spring Boot 项目，并将 spring-ai-openai-sdk 添加到您的 pom（或 gradle）依赖项中。

在 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

TIP: 将 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);
    }
}

Manual Configuration​

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

如果您不使用 Spring Boot 自动配置，可以手动配置 OpenAI SDK Image Model。 为此，请将 spring-ai-openai-sdk 依赖项添加到项目的 Maven pom.xml 文件中：

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

或添加到 Gradle build.gradle 构建文件中：

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

TIP: 请参考 Dependency Management 部分，将 Spring AI BOM 添加到您的构建文件中。

NOTE: spring-ai-openai-sdk 依赖项还提供对 OpenAiSdkChatModel 和 OpenAiSdkEmbeddingModel 的访问。 有关 OpenAiSdkChatModel 的更多信息，请参阅 OpenAI SDK Chat 部分。

接下来，创建一个 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 提供图像生成请求的配置信息。 选项类提供了一个 builder() 用于轻松创建选项。

Microsoft Foundry Configuration​

对于 Microsoft Foundry：

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)  // Enables Microsoft Foundry mode
    .build();

var imageModel = new OpenAiSdkImageModel(imageOptions);

TIP: Microsoft Foundry 支持无密码身份验证。将 com.azure:azure-identity 依赖项添加到您的项目。如果您不提供 API key，实现将自动尝试使用环境中的 Azure 凭据。

GitHub Models Configuration​

对于 GitHub Models：

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);

Observability​

OpenAI SDK 实现通过 Micrometer 支持 Spring AI 的可观测性功能。 所有图像模型操作都经过检测以进行监控和跟踪。

Additional Resources​

Spring AI Alibaba 开源项目基于 Spring AI 构建，是阿里云通义系列模型及服务在 Java AI 应用开发领域的最佳实践，提供高层次的 AI API 抽象与云原生基础设施集成方案，帮助开发者快速构建 AI 应用。