|
此版本仍在开发中，尚未被视为稳定版。为了获取最新的快照版本，请使用Spring AI 1.1.3！ |
OpenAI SDK 图像生成（官方）
Spring AI 通过 OpenAI Java SDK 支持 OpenAI 的 DALL-E 图像生成模型，为包括 Microsoft Foundry 和 GitHub 模型在内的 OpenAI 服务提供了强大且官方维护的集成。
| 此实现使用了来自OpenAI的官方OpenAI Java SDK。有关Spring AI的替代实现，请参见OpenAI图像生成。 |
DALL-E 是 OpenAI 开发的最先进图像生成模型，能够根据自然语言描述创造逼真的图像和艺术作品。
该 OpenAI SDK 模块会根据你提供的基地址自动检测服务提供者（OpenAI、Microsoft Foundry 或 GitHub Models）。
身份验证
认证过程使用了一个基数URL和一个API密钥。实现部分通过Spring Boot配置属性或环境变量提供了灵活的配置选项。
使用OpenAI
If you are using OpenAI directly, create an account at OpenAI注册页面 and generate an API key on the API密钥页面.
基URL不需要手动设置，系统会默认为0：
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使用微软Foundry
当使用微软Foundry URL时，微软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）：
微软Foundry支持无密钥的密码less认证，无需提供API密钥，这在Azure上运行时更加安全。
为了实现无密码认证，添加 零 依赖项：
<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时自动检测到。您还需要使用0代码范围创建GitHub个人访问Tokens（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表达式语言（SpEL）在属性中使用： ```java // 示例代码 System.setProperty("myAppspringId", "unique-value-for-my-app"); ``` |
spring.ai.openai-sdk.api-key=${OPENAI_API_KEY}自动配置
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到你的构建文件中。 |
配置属性
连接属性
The prefix spring.ai.openai-sdk is used as the property prefix that lets you configure the OpenAI SDK client.
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.openai-sdk.base-url |
连接到的URL。如果未设置，则自动从 |
|
spring.ai.openai-sdk.api-key |
API密钥。如果不设置，会从 |
- |
spring.ai.openai-sdk.organization-id |
可选地指定用于API请求的组织。 |
- |
spring.ai.openai-sdk.timeout |
请求超时持续时间。 |
- |
spring.ai.openai-sdk.max-retries |
失败请求的最大重试次数。 |
- |
spring.ai.openai-sdk.proxy |
Proxy设置为OpenAI客户端（Java 0对象）。 |
- |
spring.ai.openai-sdk.custom-headers |
需要将以下英文文本翻译成中文简体： Custom HTTP headers to include in requests. Map of header name to header value. 翻译结果如下： 在请求中包含自定义HTTP头。头名称与头值的映射关系。 |
- |
微软熔炉属性
OpenAI SDK 实现为 Microsoft Foundry 提供了原生支持，包括自动配置功能：
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.openai-sdk.microsoft-foundry |
启用 Microsoft Foundry 模式。如果基体 URL 包含 |
false |
spring.ai.openai-sdk.microsoft-deployment-name |
微软Foundry的部署名称。如果未指定，则使用模型名。此外，还可以通过别名 |
- |
spring.ai.openai-sdk.microsoft-foundry-service-version |
微软Foundry API服务版本 |
- |
spring.ai.openai-sdk.credential |
凭证对象用于无密码认证（需要 |
- |
微软Foundry支持无密钥认证。添加com.azure:azure-identity依赖项，实现将自动尝试从环境变量中使用Azure凭证（而非API密钥）。 |
GitHub 模型属性
GitHub Models的原生支持已推出：
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.openai-sdk.github-models |
启用GitHub模型模式。如果基础URL包含 |
false |
| GitHub Models需要一个个人访问Tokens，具有0的权限范围。通过以下方式设置：1环境变量或2属性。 |
图像模型属性
前缀 spring.ai.openai-sdk.image 是用于配置图像模型实现的属性前缀:
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.openai-sdk.image.options.model |
用于图像生成的模型。可用模型： |
|
spring.ai.openai-sdk.image.options.n |
需要生成的图片数量。必须在1到10之间。对于 |
- |
spring.ai.openai-sdk.image.options.quality |
将要生成的图像的质量。设置为 |
- |
spring.ai.openai-sdk.image.options.response-format |
生成图像的返回格式。必须是 |
- |
spring.ai.openai-sdk.image.options.size |
生成图像的大小。对于 |
- |
spring.ai.openai-sdk.image.options.width |
生成图像的宽度。对于 |
- |
spring.ai.openai-sdk.image.options.height |
生成图像的高度。对于 |
- |
spring.ai.openai-sdk.image.options.style |
生成图像的风格。必须是 |
- |
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构造函数设置所有图像生成请求的默认选项。
在运行时，您可以使用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()));| 除了特定于模型的OpenAiSdkImageOptions之外，您还可以使用可移植的ImageOptions实例，通过ImageOptionsBuilder#builder()创建。 |
示例控制器
创建一个新的Spring Boot项目，并将spring-boot-starter-web添加到您的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将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依赖项添加到项目Mavenpom.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 聊天 部分。 |
接下来，创建一个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()以简化选项的创建。
微软foundry配置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);Microsoft Foundry支持无密码认证。在项目中添加com.azure:azure-identity依赖项。如果未提供密钥，则实现将自动尝试从环境中使用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);