此版本仍在开发中，尚未被视为稳定版。如需最新的快照版本，请使用 Spring AI 1.1.3！spring-doc.cadn.net.cn

OpenAI SDK 图像生成（官方）

Spring AI 通过 OpenAI Java SDK 支持 OpenAI 的 DALL-E 图像生成模型，提供了与 OpenAI 服务（包括 Microsoft Foundry 和 GitHub Models）的稳健且官方维护的集成。spring-doc.cadn.net.cn

此实现使用官方的

DALL-E 是 OpenAI 推出的一款最先进的图像生成模型，能够根据自然语言描述创建逼真的图像和艺术作品。spring-doc.cadn.net.cn

The OpenAI SDK模块会根据您提供的基础URL自动检测服务提供商（OpenAI、Microsoft Foundry或GitHub Models）。spring-doc.cadn.net.cn

身份验证

使用基础URL和API密钥进行身份验证。实现通过Spring Boot属性或环境变量提供灵活的配置选项。spring-doc.cadn.net.cn

使用 OpenAI

如果您直接使用 OpenAI，请在 OpenAI 注册页面 创建账户，并在 API 密钥页面 生成 API 密钥。spring-doc.cadn.net.cn

基URL不需要设置，因为它默认为api.openai.com/v1:spring-doc.cadn.net.cn

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

使用环境变量:spring-doc.cadn.net.cn

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

使用 Microsoft Foundry

当使用微软Foundry网址时，会自动检测到它。您可以使用属性进行配置：spring-doc.cadn.net.cn

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>

使用环境变量:spring-doc.cadn.net.cn

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

无密码身份验证（推荐用于Azure）:spring-doc.cadn.net.cn

Microsoft Foundry 支持无需提供 API 密钥的密码less身份验证，这在运行于 Azure 时更加安全。spring-doc.cadn.net.cn

要启用无密码认证，请添加以下依赖：
com.azure:azure-identityspring-doc.cadn.net.cn

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

然后无需 API 密钥进行配置：spring-doc.cadn.net.cn

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

使用 GitHub 模型

当使用 GitHub Models 基础 URL 时，GitHub Models 会自动检测。您需要创建一个具有 models:read 权限范围的 GitHub Personal Access Token (PAT)。spring-doc.cadn.net.cn

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

使用环境变量:spring-doc.cadn.net.cn

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 Snapshot 仓库中。 请参阅 构件仓库 部分，将这些仓库添加到您的构建系统中。spring-doc.cadn.net.cn

为了帮助进行依赖管理，Spring AI 提供了一个 BOM（物料清单），以确保整个项目中使用的是相同的 Spring AI 版本。请参阅 依赖管理 部分，将 Spring AI BOM 添加到您的构建系统中。spring-doc.cadn.net.cn

Auto-configuration

Spring AI 为 OpenAI SDK 图像模型提供了 Spring Boot 自动配置。 要启用它，请将以下依赖项添加到项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中：spring-doc.cadn.net.cn

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai-sdk</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-openai-sdk'
}
请参阅依赖管理部分，将Spring AI BOM添加到您的构建文件中。

配置属性

连接属性

使用前缀spring.ai.openai-sdk作为属性前缀，以便配置OpenAI SDK客户端。spring-doc.cadn.net.cn

<property> </property> <description> </description> 默认

spring.ai.openai-sdk.base-urlspring-doc.cadn.net.cn

连接的URL。如果没有设置，则自动检测从OPENAI_BASE_URL环境变量。spring-doc.cadn.net.cn

api.openai.com/v1spring-doc.cadn.net.cn

spring.ai.openai-sdk.api-keyspring-doc.cadn.net.cn

The API密钥。如果未设置，则从OPENAI_API_KEY环境变量中自动检测。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.organization-idspring-doc.cadn.net.cn

可选地指定用于API请求的组织。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.timeoutspring-doc.cadn.net.cn

请求超时时间。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.max-retriesspring-doc.cadn.net.cn

失败请求的最大重试次数。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.proxyspring-doc.cadn.net.cn

OpenAI客户端（Java Proxy对象）的代理设置。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.custom-headersspring-doc.cadn.net.cn

包含在请求中的自定义HTTP标头。键值对映射，键为标头名称，值为标头值。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

微软 Foundry 属性

OpenAI SDK 实现提供对 Microsoft Foundry 的原生支持，并具备自动配置功能：spring-doc.cadn.net.cn

<property> </property> <description> </description> 默认

spring.ai.openai-sdk.microsoft-foundryspring-doc.cadn.net.cn

启用Microsoft Foundry模式。如果基础URL包含openai.azure.com、cognitiveservices.azure.com或.openai.microsoftFoundry.com，则自动检测。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.openai-sdk.microsoft-deployment-namespring-doc.cadn.net.cn

Microsoft Foundry 部署名称。如果没有指定，将使用模型名称。也可通过别名 deployment-name 访问。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.microsoft-foundry-service-versionspring-doc.cadn.net.cn

Microsoft Foundry API 服务版本。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.credentialspring-doc.cadn.net.cn

Credential对象用于无密码认证（需要com.azure:azure-identity依赖）。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn
Microsoft Foundry 支持密码less认证。添加 com.azure:azure-identity 依赖后，当未提供API密钥时，实现将自动尝试使用环境中的 Azure凭据。

GitHub 模型属性

GitHub 模型的本地支持现已可用：spring-doc.cadn.net.cn

<property> </property> <description> </description> 默认

spring.ai.openai-sdk.github-modelsspring-doc.cadn.net.cn

启用GitHub模型模式。如果基础URL包含models.github.ai或models.inference.ai.azure.com，将自动检测。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn
GitHub Models 需要一个带有 models:read 范围的个人访问Tokens。请通过 OPENAI_API_KEY 环境变量或 spring.ai.openai-sdk.api-key 属性设置它。

图像模型属性

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

<property> </property> <description> </description> 默认

spring.ai.openai-sdk.image.options.modelspring-doc.cadn.net.cn

用于图像生成的模型。可用模型：dall-e-2、dall-e-3。更多信息请参阅 模型 页面。spring-doc.cadn.net.cn

dall-e-3spring-doc.cadn.net.cn

spring.ai.openai-sdk.image.options.nspring-doc.cadn.net.cn

要生成的图像数量。必须在 1 到 10 之间。对于 dall-e-3，仅支持 n=1。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.image.options.qualityspring-doc.cadn.net.cn

将生成的图像质量。hd 会创建细节更丰富、整体一致性更高的图像。此参数仅支持 dall-e-3。可用值：standard、hd。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.image.options.response-formatspring-doc.cadn.net.cn

生成图像的返回格式。必须是 url 或 b64_json 之一。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.image.options.sizespring-doc.cadn.net.cn

生成图像的尺寸。对于 dall-e-2 模型，必须为 256x256、512x512 或 1024x1024；对于 dall-e-3 模型，必须为 1024x1024、1792x1024 或 1024x1792。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.image.options.widthspring-doc.cadn.net.cn

生成图像的宽度。对于 dall-e-2，必须为 256、512 或 1024 之一。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.image.options.heightspring-doc.cadn.net.cn

生成图像的高度。对于 dall-e-2，必须为 256、512 或 1024 之一。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.image.options.stylespring-doc.cadn.net.cn

生成图像的风格。必须是 vivid 或 natural 之一。Vivid（生动）会使模型倾向于生成超现实和戏剧性的图像。Natural（自然）会使模型生成更自然、较少超现实感的图像。此参数仅支持 dall-e-3。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai-sdk.image.options.userspring-doc.cadn.net.cn

代表您最终用户的唯一标识符，这有助于OpenAI监控和检测滥用行为。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn
所有以spring.ai.openai-sdk.image.options开头的属性可以在运行时通过向ImagePrompt调用添加请求特定的运行时选项来覆盖。

运行时选项

OpenAiSdkImageOptions.java 提供了 OpenAI 配置，例如要使用的模型、质量、尺寸、风格以及要生成的图像数量。spring-doc.cadn.net.cn

默认选项也可以使用 spring.ai.openai-sdk.image.options 属性进行配置。spring-doc.cadn.net.cn

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

例如，要为特定请求覆盖默认模型和质量：spring-doc.cadn.net.cn

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#builder() 创建的可移植 ImageOptions 实例。

样本控制器

创建一个新的Spring Boot项目，并在pom（或gradle）依赖中添加spring-ai-openai-sdk。spring-doc.cadn.net.cn

在 src/main/resources 目录下添加一个 application.properties 文件，以配置 OpenAI SDK 图像模型：spring-doc.cadn.net.cn

spring.ai.openai-sdk.api-key=YOUR_API_KEY
spring.ai.openai-sdk.image.options.model=dall-e-3
替换api-key为您自己的OpenAI凭据。

这将创建一个您可以注入到类中的 OpenAiSdkImageModel 实现。 以下是一个使用图像模型的简单 @RestController 类的示例。spring-doc.cadn.net.cn

@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 连接到 OpenAI 服务。spring-doc.cadn.net.cn

如果您未使用 Spring Boot 自动配置，可以手动配置 OpenAI SDK 图像模型。 为此，请将 spring-ai-openai-sdk 依赖项添加到项目的 Maven pom.xml 文件中：spring-doc.cadn.net.cn

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

或添加到您的 Gradle build.gradle 构建文件中：spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai-sdk'
}
请参阅依赖管理部分，将Spring AI BOM添加到您的构建文件中。
spring-ai-openai-sdk 依赖项还提供了对 OpenAiSdkChatModel 和 OpenAiSdkEmbeddingModel 的访问权限。 有关 OpenAiSdkChatModel 的更多信息，请参阅 OpenAI SDK Chat 部分。

接下来，创建一个 OpenAiSdkImageModel 实例并使用它生成图像：spring-doc.cadn.net.cn

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()，以便轻松创建选项。spring-doc.cadn.net.cn

Microsoft Foundry 配置

对于 Microsoft Foundry：spring-doc.cadn.net.cn

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);
Microsoft Foundry 支持无密码认证。请将 com.azure:azure-identity 依赖项添加到您的项目中。如果您未提供 API 密钥，实现将自动尝试使用您环境中的 Azure 凭证。

GitHub 模型配置

对于 GitHub 模型：spring-doc.cadn.net.cn

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 的可观测性功能。 所有图像模型操作均已纳入监控和追踪。spring-doc.cadn.net.cn

附加资源