|
此版本仍在开发中，尚未被视为稳定版。如需最新的快照版本，请使用 Spring AI 1.1.3！ |
OpenAI SDK 嵌入（官方）
Spring AI 通过 OpenAI Java SDK 支持 OpenAI 的文本嵌入模型，提供了与 OpenAI 服务（包括 Microsoft Foundry 和 GitHub Models）的稳健且官方维护的集成。
| 此实现使用了 OpenAI 官方的 OpenAI Java SDK。对于替代的 Spring AI 实现，请参阅 OpenAI 嵌入。 |
OpenAI 的文本嵌入用于衡量文本字符串之间的相关性。 嵌入是一个由浮点数组成的向量（列表）。两个向量之间的距离衡量它们的相关性。较小的距离表示较高的相关性，较大的距离表示较低的相关性。
The OpenAI SDK模块会根据您提供的基础URL自动检测服务提供商（OpenAI、Microsoft Foundry或GitHub Models）。
身份验证
使用基础URL和API密钥进行身份验证。实现通过Spring Boot属性或环境变量提供灵活的配置选项。
使用 OpenAI
如果您直接使用 OpenAI，请在 OpenAI 注册页面 创建账户，并在 API 密钥页面 生成 API 密钥。
基URL不需要设置，因为它默认为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
当使用微软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 密钥的密码less身份验证，这在运行于 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 基础 URL 时，GitHub Models 会自动检测。您需要创建一个具有 models:read 权限范围的 GitHub Personal Access Token (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}Auto-configuration
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客户端。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.openai-sdk.base-url |
连接的URL。如果没有设置，则自动检测从 |
|
spring.ai.openai-sdk.api-key |
The API密钥。如果未设置，则从 |
- |
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 |
- |
spring.ai.openai-sdk.custom-headers |
包含在请求中的自定义HTTP标头。键值对映射，键为标头名称，值为标头值。 |
- |
微软 Foundry 属性
OpenAI SDK 实现提供对 Microsoft Foundry 的原生支持，并具备自动配置功能：
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.openai-sdk.microsoft-foundry |
启用Microsoft Foundry模式。如果基础URL包含 |
false |
spring.ai.openai-sdk.microsoft-deployment-name |
Microsoft Foundry 部署名称。如果没有指定，将使用模型名称。也可通过别名 |
- |
spring.ai.openai-sdk.microsoft-foundry-service-version |
Microsoft Foundry API 服务版本。 |
- |
spring.ai.openai-sdk.credential |
Credential对象用于无密码认证（需要 |
- |
Microsoft Foundry 支持密码less认证。添加 com.azure:azure-identity 依赖后，当未提供API密钥时，实现将自动尝试使用环境中的 Azure凭据。 |
GitHub 模型属性
GitHub 模型的本地支持现已可用：
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.openai-sdk.github-models |
启用GitHub模型模式。如果基础URL包含 |
false |
GitHub Models 需要一个带有 models:read 范围的个人访问Tokens。请通过 OPENAI_API_KEY 环境变量或 spring.ai.openai-sdk.api-key 属性设置它。 |
嵌入模型属性
前缀 spring.ai.openai-sdk.embedding 是用于配置嵌入模型实现的属性前缀：
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.openai-sdk.embedding.metadata-mode |
文档内容提取模式。 |
嵌入 |
spring.ai.openai-sdk.embedding.options.model |
要使用的模型。您可以在以下模型之间进行选择： |
|
spring.ai.openai-sdk.embedding.options.user |
代表您最终用户的唯一标识符，这有助于OpenAI监控和检测滥用行为。 |
- |
spring.ai.openai-sdk.embedding.options.dimensions |
结果输出嵌入应具备的维度数量。仅在 |
- |
所有以spring.ai.openai-sdk.embedding.options开头的属性可以在运行时通过向EmbeddingRequest调用添加请求特定的运行时选项来覆盖。 |
运行时选项
OpenAiSdkEmbeddingOptions.java 提供了 OpenAI 配置，例如要使用的模型、维度和用户标识符。
默认选项也可以使用 spring.ai.openai-sdk.embedding.options 属性进行配置。
在启动时，使用 OpenAiSdkEmbeddingModel 构造函数来设置所有嵌入请求的默认选项。
在运行时，您可以使用作为 EmbeddingRequest 一部分的 OpenAiSdkEmbeddingOptions 实例来覆盖默认选项。
例如，要为特定请求覆盖默认模型名称：
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项目，并在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.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 Chat 部分。 |
接下来，创建一个 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);