OpenAI Embeddings

Spring AI 支持 OpenAI 的文本嵌入模型。OpenAI 的文本嵌入衡量了文本字符串之间的相关性。嵌入是一个浮点数向量（列表）。两个向量之间的距离衡量了它们的相关性。距离小表明相关性高，距离大表明相关性低。

Prerequisites

你需要使用 OpenAI 创建一个 API，以访问 OpenAI 词嵌入模型。

在 ` OpenAI signup page` 创建一个帐户并在 ` API Keys page` 上生成令牌。Spring AI 项目定义了一个名为 spring.ai.openai.api-key 的配置属性，您应该将其设置为从 openai.com 获得的 API Key 的值。导出环境变量是设置该配置属性的一种方法：

export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>

Add Repositories and BOM

Spring AI 工件发布在 Spring Milestone 和 Snapshot 存储库中。有关将这些存储库添加到你的构建系统的说明，请参阅 Repositories 部分。

为了帮助进行依赖项管理，Spring AI 提供了一个 BOM（物料清单）以确保在整个项目中使用一致版本的 Spring AI。有关将 Spring AI BOM 添加到你的构建系统的说明，请参阅 Dependency Management 部分。

Auto-configuration

Spring AI 为 Azure OpenAI 嵌入客户端提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到项目的 Maven pom.xml 文件：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>

或添加到 Gradle build.gradle 构建文件中。

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
}

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

Embedding Properties

Retry Properties

spring.ai.retry 前缀用作允许你为 OpenAI 词嵌入客户端配置重试机制的属性前缀。

Property Description Default

spring.ai.retry.max-attempts

最大重试次数。

10

spring.ai.retry.backoff.initial-interval

指数退避策略的初始休眠持续时间。

2 sec.

spring.ai.retry.backoff.multiplier

Backoff interval multiplier.

5

spring.ai.retry.backoff.max-interval

Maximum backoff duration.

3 min.

spring.ai.retry.on-client-errors

如果为 false，则抛出 NonTransientAiException，并且不尝试针对 4xx 客户端错误代码重试

false

spring.ai.retry.exclude-on-http-codes

不应触发重试的 HTTP 状态代码列表（例如，抛出 NonTransientAiException）。

empty

Connection Properties

spring.ai.openai 前缀用作可让你连接到 Open AI 的属性前缀。

Property Description Default

spring.ai.openai.base-url

连接到的 URL

[role="bare"]https://api.openai.com

spring.ai.openai.api-key

The API Key

-

Configuration Properties

spring.ai.openai.embedding 前缀是为 OpenAI 配置 EmbeddingClient 实现的属性前缀。

Property Description Default

spring.ai.openai.embedding.enabled

Enable OpenAI embedding client.

true

spring.ai.openai.embedding.base-url

可选地覆盖 spring.ai.openai.base-url 来提供特定于嵌入的 URL

-

spring.ai.openai.embedding.api-key

可选地覆盖 spring.ai.openai.api-key 来提供特定于嵌入的 API 密钥

-

spring.ai.openai.embedding.metadata-mode

Document content extraction mode.

EMBED

spring.ai.openai.embedding.options.model

The model to use

text-embedding-ada-002（其他选项：text-embedding-3-large、text-embedding-3-small）

spring.ai.openai.embedding.options.encodingFormat

返回嵌入的格式。可以是浮点或 base64。

-

spring.ai.openai.embedding.options.user

一个表示最终用户的独特标识符，可帮助 OpenAI 监控和检测滥用。

-

您可以覆盖 ChatClient 和 EmbeddingClient 实现的 spring.ai.openai.base-url 和 spring.ai.openai.api-key。如果设置了 spring.ai.openai.embedding.base-url 和 spring.ai.openai.embedding.api-key 属性，优先于通用属性。同样，如果设置了 spring.ai.openai.embedding.base-url 和 spring.ai.openai.embedding.api-key 属性，优先于通用属性。如果您希望为不同的模型和不同的模型端点使用不同的 OpenAI 帐户，这将很有用。

所有前缀为 spring.ai.openai.embedding.options 的属性可以通过在 EmbeddingRequest 调用中添加一个请求特定的 Embedding Options 来在运行时覆盖。

Embedding Options

OpenAiEmbeddingOptions.java 提供 OpenAI 配置，例如使用该模型等。

还可以使用 spring.ai.openai.embedding.options 属性配置默认选项。

在启动时使用 OpenAiEmbeddingClient 构造函数来设置所有词嵌入请求使用的默认选项。在运行时，你可以使用 OpenAiEmbeddingOptions 实例作为 EmbeddingRequest 的一部分来覆盖默认选项。

例如，要覆盖特定请求的默认模型名称：

EmbeddingResponse embeddingResponse = embeddingClient.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OpenAiEmbeddingOptions.builder()
            .withModel("Different-Embedding-Model-Deployment-Name")
        .build()));

Sample Controller (Auto-configuration)

这将创建一个 EmbeddingClient 实现，你可以将其注入到你的类中。这里有一个简单的 @Controller 类的示例，它使用 EmbeddingClient 实现。

spring.ai.openai.api-key=YOUR_API_KEY
spring.ai.openai.embedding.options.model=text-embedding-ada-002
@RestController
public class EmbeddingController {

    private final EmbeddingClient embeddingClient;

    @Autowired
    public EmbeddingController(EmbeddingClient embeddingClient) {
        this.embeddingClient = embeddingClient;
    }

    @GetMapping("/ai/embedding")
    public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        EmbeddingResponse embeddingResponse = this.embeddingClient.embedForResponse(List.of(message));
        return Map.of("embedding", embeddingResponse);
    }
}

Manual Configuration

如果你不使用 Spring Boot，则可以手动配置 OpenAI 词嵌入客户端。为此，将 spring-ai-openai 依赖项添加到项目的 Maven pom.xml 文件：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai</artifactId>
</dependency>

或添加到 Gradle build.gradle 构建文件中。

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai'
}

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

spring-ai-openai 依赖项还提供对 OpenAiChatClient 的访问。有关 OpenAiChatClient 的更多信息，请参阅 OpenAI Chat Client 部分。

接下来，创建一个 OpenAiEmbeddingClient 实例，并使用它来计算两个输入文本之间的相似性：

var openAiApi = new OpenAiApi(System.getenv("OPENAI_API_KEY"));

var embeddingClient = new OpenAiEmbeddingClient(openAiApi)
    .withDefaultOptions(OpenAiChatOptions.build()
        .withModel("text-embedding-ada-002")
        .withUser("user-6")
        .build());

EmbeddingResponse embeddingResponse = embeddingClient
	.embedForResponse(List.of("Hello World", "World is big and salvation is near"));

OpenAiEmbeddingOptions 为词嵌入请求提供配置信息。选项类提供一个 builder() 以便轻松创建选项。