Azure OpenAI Image Generation

Spring AI 支持 DALL-E，即 Azure OpenAI 的图像生成模型。

Spring AI supports DALL-E, the Image generation model from Azure OpenAI.

Prerequisites

从 Azure Portal 上的 Azure OpenAI 服务部分中获取 Azure OpenAI endpoint 和 api-key。

Obtain your Azure OpenAI endpoint and api-key from the Azure OpenAI Service section on the Azure Portal.

Spring AI定义了两个配置属性：

Spring AI defines two configuration properties:

* spring.ai.azure.openai.api-key：将其设置为从Azure获取的API密钥的值。
spring.ai.azure.openai.api-key: Set this to the value of the API Key obtained from Azure.
* spring.ai.azure.openai.endpoint：将其设置为在Azure中配置模型时获取的端点URL。
spring.ai.azure.openai.endpoint: Set this to the endpoint URL obtained when provisioning your model in Azure.

您可以在 application.properties 文件中设置这些配置属性：

You can set these configuration properties in your application.properties file:

spring.ai.azure.openai.api-key=<your-azure-openai-api-key>
spring.ai.azure.openai.endpoint=<your-azure-openai-endpoint>

为了在处理敏感信息（如 API 密钥）时增强安全性，您可以使用 Spring 表达式语言 (SpEL) 来引用自定义环境变量：

For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference custom environment variables:

# In application.yml
spring:
  ai:
    azure:
      openai:
        api-key: ${AZURE_OPENAI_API_KEY}
        endpoint: ${AZURE_OPENAI_ENDPOINT}

# In your environment or .env file
export AZURE_OPENAI_API_KEY=<your-azure-openai-api-key>
export AZURE_OPENAI_ENDPOINT=<your-azure-openai-endpoint>

您还可以在应用程序代码中以编程方式设置这些配置：

You can also set these configurations programmatically in your application code:

// Retrieve API key and endpoint from secure sources or environment variables
String apiKey = System.getenv("AZURE_OPENAI_API_KEY");
String endpoint = System.getenv("AZURE_OPENAI_ENDPOINT");

Deployment Name

若要使用运行 Azure AI 应用程序，请通过 [Azure AI 门户]([role="bare"][role="bare"]https://oai.azure.com/portal) 创建一个 Azure AI 部署。

To use run Azure AI applications, create an Azure AI Deployment through the [Azure AI Portal]([role="bare"]https://oai.azure.com/portal).

在 Azure 中，每个客户端必须指定一个 Deployment Name 才能连接到 Azure OpenAI 服务。

In Azure, each client must specify a Deployment Name to connect to the Azure OpenAI service.

了解 Deployment Name 与您选择部署的模型不同非常重要。

It’s essential to understand that the Deployment Name is different from the model you choose to deploy

例如，名为“MyImgAiDeployment”的部署可以配置为使用 Dalle3 模型或 Dalle2 模型。

For instance, a deployment named 'MyImgAiDeployment' could be configured to use either the Dalle3 model or the Dalle2 model.

现在，为了简化起见，您可以使用以下设置创建部署：

For now, to keep things simple, you can create a deployment using the following settings:

部署名称： MyImgAiDeployment 模型名称： Dalle3

Deployment Name: MyImgAiDeployment Model Name: Dalle3

此 Azure 配置将与 Spring Boot Azure AI Starter 及其自动配置功能的默认配置保持一致。

This Azure configuration will align with the default configurations of the Spring Boot Azure AI Starter and its Autoconfiguration feature.

如果您使用不同的部署名称，请相应地更新配置属性：

If you use a different Deployment Name, update the configuration property accordingly:

spring.ai.azure.openai.image.options.deployment-name=<my deployment name>

Azure OpenAI 和 OpenAI 不同的部署结构导致 Azure OpenAI 客户端库中的一个属性名为 deploymentOrModelName。这是因为在 OpenAI 中没有“部署名称”，只有“模型名称”。

The different deployment structures of Azure OpenAI and OpenAI leads to a property in the Azure OpenAI client library named deploymentOrModelName. This is because in OpenAI there is no Deployment Name, only a Model Name.

Add Repositories and BOM

Spring AI 工件发布在 Maven Central 和 Spring Snapshot 存储库中。请参阅“添加 Spring AI 仓库”部分，将这些仓库添加到您的构建系统。

Spring AI artifacts are published in Maven Central and Spring Snapshot repositories. Refer to the Artifact Repositories section to add these repositories to your build system.

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

To help with dependency management, Spring AI provides a BOM (bill of materials) to ensure that a consistent version of Spring AI is used throughout the entire project. Refer to the Dependency Management section to add the Spring AI BOM to your build system.

Auto-configuration

Spring AI 自动配置、启动器模块的工件名称发生了重大变化。请参阅 upgrade notes 以获取更多信息。

There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the upgrade notes for more information.

Spring AI 为 Azure OpenAI Chat 客户端提供 Spring Boot 自动配置。若要启用它，请将以下依赖项添加到项目的 Maven pom.xml 文件中：

Spring AI provides Spring Boot auto-configuration for the Azure OpenAI Chat Client. To enable it add the following dependency to your project’s Maven pom.xml file:

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

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

or to your Gradle build.gradle build file.

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

参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

Refer to the Dependency Management section to add the Spring AI BOM to your build file.

Image Generation Properties

图像自动配置的启用和禁用现在通过带有前缀 spring.ai.model.image 的顶级属性进行配置。

Enabling and disabling of the image auto-configurations are now configured via top level properties with the prefix spring.ai.model.image.

要启用，spring.ai.model.image=azure-openai（默认启用）

To enable, spring.ai.model.image=azure-openai (It is enabled by default)

要禁用，spring.ai.model.image=none（或任何不匹配 azure-openai 的值）

To disable, spring.ai.model.image=none (or any value which doesn’t match azure-openai)

此更改旨在允许配置多个模型。

This change is done to allow configuration of multiple models.

前缀 spring.ai.openai.image 是属性前缀，可用于配置 OpenAI 的 ImageModel 实现。

The prefix spring.ai.openai.image is the property prefix that lets you configure the ImageModel implementation for OpenAI.

Property

Description

Default

spring.ai.azure.openai.image.enabled (Removed and no longer valid)

Enable OpenAI image model.

true

spring.ai.model.image

Enable OpenAI image model.

azure-openai

spring.ai.azure.openai.image.options.n

The number of images to generate. Must be between 1 and 10. For dall-e-3, only n=1 is supported.

spring.ai.azure.openai.image.options.model

The model to use for image generation.

AzureOpenAiImageOptions.DEFAULT_IMAGE_MODEL

spring.ai.azure.openai.image.options.quality

The quality of the image that will be generated. HD creates images with finer details and greater consistency across the image. This parameter is only supported for dall-e-3.

spring.ai.azure.openai.image.options.response_format

The format in which the generated images are returned. Must be one of URL or b64_json.

spring.ai.openai.image.options.size

The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024 for dall-e-2. Must be one of 1024x1024, 1792x1024, or 1024x1792 for dall-e-3 models.

spring.ai.openai.image.options.size_width

The width of the generated images. Must be one of 256, 512, or 1024 for dall-e-2.

spring.ai.openai.image.options.size_height

The height of the generated images. Must be one of 256, 512, or 1024 for dall-e-2.

spring.ai.openai.image.options.style

The style of the generated images. Must be one of vivid or natural. Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images. This parameter is only supported for dall-e-3.

spring.ai.openai.image.options.user

A unique identifier representing your end-user, which can help Azure OpenAI to monitor and detect abuse.

Connection Properties

前缀 spring.ai.openai 用作属性前缀，允许您连接到 Azure OpenAI。

The prefix spring.ai.openai is used as the property prefix that lets you connect to Azure OpenAI.

Property

Description

Default

spring.ai.azure.openai.endpoint

The URL to connect to

[role="bare"]https://my-dalle3.openai.azure.com/

spring.ai.azure.openai.apiKey

The API Key

Runtime Options

OpenAiImageOptions.java提供模型配置，例如使用的模型、质量、大小等。

The OpenAiImageOptions.java provides model configurations, such as the model to use, the quality, the size, etc.

在启动时，可以使用 AzureOpenAiImageModel(OpenAiImageApi openAiImageApi) 构造函数和 withDefaultOptions(OpenAiImageOptions defaultOptions) 方法配置默认选项。或者，使用前面描述的 spring.ai.azure.openai.image.options.* 属性。

On start-up, the default options can be configured with the AzureOpenAiImageModel(OpenAiImageApi openAiImageApi) constructor and the withDefaultOptions(OpenAiImageOptions defaultOptions) method. Alternatively, use the spring.ai.azure.openai.image.options.* properties described previously.

在运行时，你可以通过将新的请求特定选项添加到 ImagePrompt 调用来覆盖默认选项。例如，要覆盖 OpenAI 特定的选项（例如质量和创建的图像数量），请使用以下代码示例：

At runtime you can override the default options by adding new, request specific, options to the ImagePrompt call. For example to override the OpenAI specific options such as quality and the number of images to create, use the following code example:

ImageResponse response = azureOpenaiImageModel.call(
        new ImagePrompt("A light cream colored mini golden doodle",
        OpenAiImageOptions.builder()
                .quality("hd")
                .N(4)
                .height(1024)
                .width(1024).build())

);

除了模型特定的 AzureOpenAiImageOptions 之外，您还可以使用通过 ImageOptions 创建的可移植 ImageOptionsBuilder#builder() 实例。

In addition to the model specific AzureOpenAiImageOptions you can use a portable ImageOptions instance, created with the ImageOptionsBuilder#builder().