OpenAI SDK 图像生成（官方）
Spring AI 通过 OpenAI Java SDK 支持 OpenAI 的 DALL-E 图像生成模型，提供了与 OpenAI 服务（包括 Microsoft Foundry 和 GitHub Models）的稳健且官方维护的集成。
此实现使用了 OpenAI 官方的 OpenAI Java SDK。关于 Spring AI 的替代实现，请参阅 OpenAI 图像生成。
DALL-E是OpenAI开发的一款前沿图像生成模型，能够根据自然语言描述生成逼真的图像和艺术作品。
OpenAI SDK模块会根据您提供的基础URL自动检测服务提供商（OpenAI、Microsoft Foundry或GitHub Models）。
认证
身份验证通过基础URL和API密钥完成。该实现通过Spring Boot属性或环境变量提供了灵活的配置选项。
使用 OpenAI
如果您直接使用OpenAI，请在OpenAI注册页面创建账户，并在API密钥页面生成API密钥。
基础 URL 无需设置，因为其默认值为 [api.openai.com/v1](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
使用 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>
无密码身份验证（Azure 推荐使用）：
Microsoft Foundry 支持无密码身份验证，无需提供 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>
# No api-key needed - will use Azure credentials from environment
使用 GitHub 模型
GitHub Models 在使用 GitHub Models 基础 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 Expression Language (SpEL):
spring.ai.openai-sdk.api-key=${OPENAI_API_KEY}
添加存储库和物料清单（BOM）
Spring AI 项目构件已发布至 Maven Central 与 Spring Snapshot 仓库。请参阅构件仓库章节，将这些仓库添加至您的构建系统中。
为辅助依赖管理，Spring AI 提供了物料清单（BOM），以确保在整个项目中使用的 Spring AI 版本一致。请参阅依赖管理部分，将 Spring AI BOM 添加至您的构建系统。
自动配置
Spring AI 为 OpenAI SDK 的图像模型提供了 Spring Boot 自动配置。要启用此功能，请将以下依赖项添加到项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中：
- Maven
- Gradle
<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.ai.openai-sdk.base-url | 连接到的 URL。如果未设置，将从 OPENAI_BASE_URL 环境变量自动检测。 | api.openai.com/v1 |
| spring.ai.openai-sdk.api-key | API 密钥。如果未设置，将从 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.proxy | OpenAI 客户端的代理设置 (Java Proxy 对象)。 | - |
| spring.ai.openai-sdk.custom-headers | 请求中包含的自定义 HTTP 头。头名称到头值的映射。 | - |
Microsoft Foundry 属性
OpenAI SDK 实现为 Microsoft Foundry 提供了原生支持，并具备自动配置功能：
| 属性 | 说明 | 默认值 |
|---|---|---|
| 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-name | Microsoft Foundry 部署名称。若未指定，将使用模型名称。也可通过别名 deployment-name 访问。 | - |
| spring.ai.openai-sdk.microsoft-foundry-service-version | Microsoft Foundry API 服务版本。 | - |
| spring.ai.openai-sdk.credential | 用于无密码身份验证的凭据对象（需要 com.azure:azure-identity 依赖）。 | - |
Microsoft Foundry 支持无密码身份验证。添加 com.azure:azure-identity 依赖项后，当未提供 API 密钥时，实现将自动尝试使用环境中的 Azure 凭据。
GitHub 模型属性
原生支持 GitHub Models 现已可用：
| 属性 | 描述 | 默认值 |
|---|---|---|
| spring.ai.openai-sdk.github-models | 启用 GitHub Models 模式。如果基础 URL 包含 models.github.ai 或 models.inference.ai.azure.com 则自动检测启用。 | false |
:::提示
GitHub Models 需要一个具有 models:read 范围的个人访问令牌。通过 OPENAI_API_KEY 环境变量或 spring.ai.openai-sdk.api-key 属性进行设置。
:::
图像模型属性
前缀 spring.ai.openai-sdk.image 是用于配置图像模型实现的属性前缀：
| 属性 | 描述 | 默认值 |
|---|---|---|
| spring.ai.openai-sdk.image.options.model | 用于图像生成的模型。可用模型：dall-e-2、dall-e-3。更多信息请参阅模型页面。 | 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 监控和检测滥用行为。 | - |
:::提示
所有以 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 之外，你也可以使用可移植的 ImageOptions 实例，该实例可以通过 ImageOptionsBuilder#builder() 创建。
示例控制器
创建一个新的Spring Boot项目，并在你的pom（或gradle）依赖中添加 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 来连接 OpenAI 服务。
如果你不使用 Spring Boot 自动配置，可以手动配置 OpenAI SDK 图像模型。为此，请将 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'
}
请参考 依赖管理 部分，将 Spring AI BOM 添加到你的构建文件中。
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 配置
针对 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);
:::提示
Microsoft Foundry 支持无密码身份验证。请将 com.azure:azure-identity 依赖项添加到你的项目中。如果不提供 API 密钥，实现将自动尝试使用你环境中的 Azure 凭据。
:::
GitHub 模型配置
对于 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的可观测性功能。所有图像模型操作均经过插装，以便进行监控和追踪。