OpenAI 图像生成
Spring AI 支持 DALL-E，即 OpenAI 的图像生成模型。
从 2.0.0-M5 版本开始，Spring AI 在底层使用官方的 openai-java SDK 来支持所有 OpenAI 模型。这一过渡过程预计是无感的，对于现有 OpenAI API 属性和构建器的用户没有破坏性变更。如果您发现任何问题，请通过 Spring AI GitHub Issues 向我们报告。
先决条件
你需要在 OpenAI 创建一个 API 密钥才能访问 ChatGPT 模型。
在 OpenAI 注册页面 创建账户，并在 API Keys 页面 生成 token。
Spring AI 项目定义了一个名为 spring.ai.openai.api-key 的配置属性，您应将其设置为从 openai.com 获取的 API Key 值。
您可以在 application.properties 文件中设置此配置属性：
spring.ai.openai.api-key=<your-openai-api-key>
在处理 API 密钥等敏感信息时，为了增强安全性，可以使用 Spring Expression Language (SpEL) 来引用自定义环境变量：
# In application.yml
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}
# In your environment or .env file
export OPENAI_API_KEY=<your-openai-api-key>
你也可以在应用程序代码中以编程方式设置此配置：
// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("OPENAI_API_KEY");
自动配置
Spring AI 的自动配置、starter 模块的构件名称已发生重大变更。更多信息请参阅升级说明。
Spring AI 为 OpenAI 图像生成客户端提供了 Spring Boot 自动配置。要启用该功能，请在项目的 Maven pom.xml 文件中添加以下依赖项：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
或添加到您的 Gradle build.gradle 构建文件中。
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}
请参见依赖管理部分，以将 Spring AI BOM 添加到您的构建文件中。
图像生成属性
连接属性
前缀 spring.ai.openai 用作属性前缀，用于连接到 OpenAI。
| 属性 | 描述 | 默认值 |
|---|---|---|
| spring.ai.openai.base-url | 要连接的 URL | api.openai.com |
| spring.ai.openai.api-key | API Key | - |
| spring.ai.openai.organization-id | 可选，可以指定用于 API 请求的组织。 | - |
| spring.ai.openai.project-id | 可选，可以指定用于 API 请求的项目。 | - |
| spring.ai.openai.timeout | OpenAI 客户端的请求超时时间。 | 60 秒 |
| spring.ai.openai.max-retries | OpenAI 客户端的最大重试次数。 | 3 |
| spring.ai.openai.proxy | OpenAI 客户端的代理设置。 | - |
| spring.ai.openai.custom-headers | 添加到 OpenAI 客户端请求的自定义 HTTP 头。 | 空 |
| spring.ai.openai.connection-pool-metrics-enabled | 是否启用底层 OkHttp 客户端的连接池指标。 | false |
对于属于多个组织（或通过其旧版用户 API 密钥访问其项目）的用户，可以选择性地指定用于 API 请求的组织及项目。来自这些 API 请求的使用量将被计入指定组织和项目的使用量。
重试属性
前缀 spring.ai.retry 用作属性前缀，用于配置 OpenAI Image 客户端的重试机制。
| 属性 | 描述 | 默认值 |
|---|---|---|
| spring.ai.retry.max-attempts | 最大重试次数。 | 10 |
| spring.ai.retry.backoff.initial-interval | 指数退避策略的初始休眠时长。 | 2 sec. |
| spring.ai.retry.backoff.multiplier | 退避间隔倍数。 | 5 |
| spring.ai.retry.backoff.max-interval | 最大退避时长。 | 3 min. |
| spring.ai.retry.on-client-errors | 如果为 false，则抛出 NonTransientAiException，并且不会针对 4xx 客户端错误码尝试重试。 | false |
| spring.ai.retry.exclude-on-http-codes | 不应触发重试的 HTTP 状态码列表（例如，以抛出 NonTransientAiException）。 | empty |
| spring.ai.retry.on-http-codes | 应触发重试的 HTTP 状态码列表（例如，以抛出 TransientAiException）。 | empty |
配置属性
图像自动配置的启用和禁用现在通过前缀为 spring.ai.model.image 的顶级属性进行配置。
要启用，设置 spring.ai.model.image=openai（默认情况下已启用）
要禁用，设置 spring.ai.model.image=none（或任何不匹配 openai 的值）
此更改是为了允许多个模型的配置。
前缀 spring.ai.openai.image 是用于配置 OpenAI 的 ImageModel 实现的属性前缀。
| 属性 | 描述 | 默认值 |
|---|---|---|
| spring.ai.openai.image.enabled (已移除且不再有效) | 启用 OpenAI 图像模型。 | true |
| spring.ai.model.image | 启用 OpenAI 图像模型。 | openai |
| spring.ai.openai.image.base-url | 可选，覆盖 spring.ai.openai.base-url 以提供专用的聊天 URL | - |
| spring.ai.openai.image.api-key | 可选，覆盖 spring.ai.openai.api-key 以提供专用的 API 密钥 | - |
| spring.ai.openai.image.organization-id | 可选，指定用于 API 请求的组织。 | - |
| spring.ai.openai.image.project-id | 可选，指定用于 API 请求的项目。 | - |
| spring.ai.openai.image.n | 要生成的图像数量。必须在 1 到 10 之间。对于 dall-e-3，仅支持 n=1。 | - |
| spring.ai.openai.image.model | 用于图像生成的模型。 | ImageModel.GPT_IMAGE_1_MINI.toString() |
| spring.ai.openai.image.quality | 将生成的图像的质量。HD 会创建具有更精细细节和更高整体一致性的图像。此参数仅支持 dall-e-3。 | - |
| spring.ai.openai.image.response_format | 生成图像的返回格式。必须是 URL 或 b64_json 之一。 | - |
spring.ai.openai.image.size | 生成图像的尺寸。对于 dall-e-2，必须是 256x256、512x512 或 1024x1024 之一。对于 dall-e-3 模型，必须是 1024x1024、1792x1024 或 1024x1792 之一。 | - |
spring.ai.openai.image.size_width | 生成图像的宽度。对于 dall-e-2，必须是 256、512 或 1024 之一。 | - |
spring.ai.openai.image.size_height | 生成图像的高度。对于 dall-e-2，必须是 256、512 或 1024 之一。 | - |
spring.ai.openai.image.style | 生成图像的风格。必须是 vivid 或 natural 之一。Vivid 使模型倾向于生成超真实和戏剧化的图像。Natural 使模型生成更自然、不太超真实的外观图像。此参数仅支持 dall-e-3。 | - |
spring.ai.openai.image.user | 代表您的最终用户的唯一标识符，这有助于 OpenAI 监控和检测滥用行为。 | - |
您可以覆盖通用的 spring.ai.openai.base-url、spring.ai.openai.api-key、spring.ai.openai.organization-id 和 spring.ai.openai.project-id 属性。如果设置了 spring.ai.openai.image.base-url、spring.ai.openai.image.api-key、spring.ai.openai.image.organization-id 和 spring.ai.openai.image.project-id 属性，它们将优先于通用属性生效。这对于希望针对不同模型和不同的模型端点使用不同的 OpenAI 账户的情况非常有用。
所有以 spring.ai.openai.image.options 为前缀的属性都可以在运行时被覆盖。
运行时选项
OpenAiImageOptions.java 提供模型配置，例如要使用的模型、质量、大小等。
在启动时，可以通过向 OpenAiImageModel 构造函数传递 OpenAiImageOptions 来配置默认选项。或者，使用前面描述的 spring.ai.openai.image.* 属性。
在运行时，您可以通过向 ImagePrompt 调用中添加新的、特定于请求的选项来覆盖默认选项。例如，若要覆盖 OpenAI 特定选项，如质量和要生成的图像数量，请使用以下代码示例：
ImageResponse response = openaiImageModel.call(
new ImagePrompt("A light cream colored mini golden doodle",
OpenAiImageOptions.builder()
.quality("hd")
.n(4)
.height(1024)
.width(1024).build())
);
除了模型特定的 OpenAiImageOptions 之外，你还可以使用由 ImageOptionsBuilder#builder() 创建的便携式 ImageOptions 实例。
自定义 HTTP 客户端
Spring AI 在底层使用官方的 openai-java SDK，并通过 SpringAiOpenAiHttpClient.Builder 构建的自定义 OkHttp 客户端配置其 HTTP 传输层。你可以通过暴露一个或多个 OpenAiHttpClientBuilderCustomizer Bean 来在底层 OkHttpClient 创建之前拦截该构建器。每个自定义器都会接收所有 OpenAI 模型（聊天、嵌入、图像、音频、审核）共用的同一个构建器，因此自定义配置会统一生效。
@FunctionalInterface
public interface OpenAiHttpClientBuilderCustomizer {
void customize(SpringAiOpenAiHttpClient.Builder builder);
}
常见的使用场景包括：
-
注册 OkHttp
Interceptor实例（如认证、传播头、自定义日志记录）； -
替换调度器
ExecutorService（例如，将异步 I/O 路由到虚拟线程）； -
通过 builder 配置代理、SSL、主机名验证或连接池大小。
当存在多个自定义器时，它们在 Spring AI 自身的默认设置之后，按照 @Order / Ordered 的顺序应用，因此用户代码具有更高的优先级。
在使用 OpenAi*Model.Builder 手动配置模型时，也可使用相同的钩子：
var chatModel = OpenAiChatModel.builder()
.options(OpenAiChatOptions.builder().model("gpt-4o").build())
.httpClientBuilderCustomizer(myCustomizer)
.build();