OpenAI SDK Embeddings（官方）
Spring AI 通过 OpenAI Java SDK 支持 OpenAI 的文本嵌入模型，提供了与 OpenAI 服务（包括 Microsoft Foundry 和 GitHub Models）的稳健且官方维护的集成。
此实现使用了 OpenAI 官方的 OpenAI Java SDK。如需查看 Spring AI 的替代实现，请参阅 OpenAI Embeddings。
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 表达式语言（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 Models Properties
原生支持 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.embedding 前缀是用于配置嵌入模型实现的属性前缀：
| 属性 | 描述 | 默认值 |
|---|---|---|
| spring.ai.openai-sdk.embedding.metadata-mode | 文档内容提取模式。 | EMBED |
| spring.ai.openai-sdk.embedding.options.model | 要使用的模型。您可以在以下模型之间选择：text-embedding-ada-002, text-embedding-3-small, text-embedding-3-large。更多信息请参见 models 页面。 | text-embedding-ada-002 |
| spring.ai.openai-sdk.embedding.options.user | 代表您最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。 | - |
| spring.ai.openai-sdk.embedding.options.dimensions | 结果输出嵌入向量的维度数量。仅在 text-embedding-3 及更高版本的模型中受支持。 | - |
:::提示
所有以 spring.ai.openai-sdk.embedding.options 为前缀的属性，都可以在运行时通过在 EmbeddingRequest 调用中添加特定请求的运行时选项来覆盖。
:::
Runtime Options
OpenAiSdkEmbeddingOptions.java 提供了 OpenAI 的配置选项，例如使用的模型、维度和用户标识符。
默认选项也可以通过 spring.ai.openai-sdk.embedding.options 属性进行配置。
在启动时，使用 OpenAiSdkEmbeddingModel 构造函数来设置所有嵌入请求的默认选项。在运行时，你可以通过将 OpenAiSdkEmbeddingOptions 实例作为 EmbeddingRequest 的一部分来覆盖这些默认选项。
例如，为特定请求覆盖默认模型名称：
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
OpenAiSdkEmbeddingOptions.builder()
.model("text-embedding-3-large")
.dimensions(1024)
.build()));
除了模型特定的 OpenAiSdkEmbeddingOptions 之外，你也可以使用可移植的 EmbeddingOptions 实例，该实例可通过构建器创建。
示例控制器
创建一个新的 Spring Boot 项目，并将 spring-ai-openai-sdk 添加到你的 pom（或 gradle）依赖中。
在 src/main/resources 目录下添加 application.properties 文件以配置 OpenAI SDK 嵌入模型：
spring.ai.openai-sdk.api-key=YOUR_API_KEY
spring.ai.openai-sdk.embedding.options.model=text-embedding-ada-002
:::提示
将 api-key 替换为你的 OpenAI 凭据。
:::
这将创建一个 OpenAiSdkEmbeddingModel 实现，你可以将其注入到你的类中。以下是一个使用该嵌入模型的简单 @RestController 类示例。
@RestController
public class EmbeddingController {
private final EmbeddingModel embeddingModel;
@Autowired
public EmbeddingController(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
@GetMapping("/ai/embedding")
public Map<String, Object> embed(
@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
return Map.of("embedding", embeddingResponse);
}
}
手动配置
OpenAiSdkEmbeddingModel 实现了 EmbeddingModel 接口，并使用官方的 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 和 OpenAiSdkImageModel 的访问。有关 OpenAiSdkChatModel 的更多信息，请参阅 OpenAI SDK 聊天 部分。
接下来，创建一个 OpenAiSdkEmbeddingModel 实例，并使用它计算两个输入文本之间的相似度：
var embeddingOptions = OpenAiSdkEmbeddingOptions.builder()
.model("text-embedding-ada-002")
.apiKey(System.getenv("OPENAI_API_KEY"))
.build();
var embeddingModel = new OpenAiSdkEmbeddingModel(embeddingOptions);
EmbeddingResponse embeddingResponse = embeddingModel
.embedForResponse(List.of("Hello World", "World is big and salvation is near"));
OpenAiSdkEmbeddingOptions 提供了嵌入请求的配置信息。该选项类提供了一个 builder() 方法，以便轻松创建选项。
Microsoft Foundry 配置
对于Microsoft Foundry：
var embeddingOptions = OpenAiSdkEmbeddingOptions.builder()
.baseUrl("https://your-resource.openai.azure.com")
.apiKey(System.getenv("OPENAI_API_KEY"))
.deploymentName("text-embedding-ada-002")
.azureOpenAIServiceVersion(AzureOpenAIServiceVersion.V2024_10_01_PREVIEW)
.azure(true) // Enables Microsoft Foundry mode
.build();
var embeddingModel = new OpenAiSdkEmbeddingModel(embeddingOptions);
Microsoft Foundry 支持无密码身份验证。将 com.azure:azure-identity 依赖项添加到您的项目中。如果您不提供 API 密钥，该实现将自动尝试使用您环境中的 Azure 凭据。
GitHub 模型配置
对于 GitHub 模型：
var embeddingOptions = OpenAiSdkEmbeddingOptions.builder()
.baseUrl("https://models.inference.ai.azure.com")
.apiKey(System.getenv("GITHUB_TOKEN"))
.model("text-embedding-3-large")
.githubModels(true)
.build();
var embeddingModel = new OpenAiSdkEmbeddingModel(embeddingOptions);
可观测性
OpenAI SDK实现通过Micrometer支持Spring AI的可观测性功能。所有嵌入模型操作都已进行监控和跟踪的仪表化处理。