OpenAI Embeddings
Spring AI 支持 OpenAI 的文本嵌入模型。OpenAI 的文本嵌入模型用于衡量文本字符串之间的相关性。嵌入向量是一组浮点数的向量。两个向量之间的距离表示它们的相关性。较小的距离表示高相关性,较大的距离表示低相关性。
先决条件
您需要创建一个与 OpenAI 交互的 API KEY,以访问 OpenAI 的嵌入向量模型。
在 OpenAI 注册页面 创建帐户并在 API 密钥页面 生成令牌。Spring AI 项目定义了一个名为 spring.ai.openai.api-key 的配置属性,您应该将其设置为从 openai.com 获得的 API Key 的值。配置环境变量是设置该配置属性的一种方法:
export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>
添加仓库和 BOM
Spring AI 组件发布在 Spring Milestone 和 Snapshot 仓库 中。请参考03. 开始章节中的添加 Milestone 和 Snapshot Repositories,将这些存储库添加到您的构建系统中。
为了帮助依赖管理,Spring AI 提供了 BOM,以确保整个项目中使用一致的 Spring AI 版本。请参考 3. 开始章节 中的 依赖管理 部分,将 Spring AI BOM 添加到您的系统中。
自动装配
Spring AI 为 Azure OpenAI Embedding 客户端提供了 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'
}
参考 3. 开始章节 中的 依赖管理 部分,将 Spring AI BOM 添加到您的构建文件中。
嵌入向量属性
重试属性
OpenAI Embedding 客户端重试机制属性前缀是spring.ai.retry
属性 | 描述 | 默认值 |
---|---|---|
spring.ai.retry.max-attempts | 最大重试次数。 | 10 |
spring.ai.retry.backoff.initial-interval | 指数退避策略的初始睡眠持续时间。 | 2 sec. |
spring.ai.retry.backoff.multiplier | 退避间隔倍数。 | 5 |
spring.ai.retry.backoff.max-interval | 最大退避持续时间。 | 3 min. |
spring.ai.retry.on-client-errors | 如果为 false,则抛出 NonTransientAiException,并且对4xx客户端错误代码不尝试重试 | false |
spring.ai.retry.exclude-on-http-codes | 不应触发重试的 HTTP 状态代码列表(例如,抛出 NonTransientAiException)。 | empty |
连接属性
属性前缀是spring.ai.openai
属性 | 描述 | 默认值 |
---|---|---|
spring.ai.openai.base-url | 连接到的 URL | api.openai.com |
spring.ai.openai.api-key | The API Key | - |
配置属性
OpenAI 的EmbeddingClient实现的属性前缀是spring.ai.openai.embedding
属性 | 描述 | 默认值 |
---|---|---|
spring.ai.openai.embedding.enabled | 启用OpenAI嵌入向量客户端。 | true |
spring.ai.openai.embedding.base-url | 可选属性,用于提供特定于嵌入向量的 URL,配置会覆盖 spring.ai.openai.base-url | - |
spring.ai.openai.embedding.api-key | 可选属性,用于提供特定于嵌入向量的 API 密钥,配置会覆盖 spring.ai.openai.api-key | - |
spring.ai.openai.embedding.metadata-mode | 文档内容提取模式 | EMBED |
spring.ai.openai.embedding.options.model | 要使用的模型 | text-embedding-ada-002 (other options: text-embedding-3-large, text-embedding-3-small) |
spring.ai.openai.embedding.options.encodingFormat | 返回嵌入向量的格式。可以是浮点数或 base64。 | - |
spring.ai.openai.embedding.options.user | 代表您的终端用户的唯一标识符,可以帮助 OpenAI 监控和检测滥用行为。 |
spring.ai.openai.base-url 和 spring.ai.openai.api-key 是用于 ChatClient 和 EmbeddingClient 实现的基础属性,您可以自己手动覆盖。同样,如果设置了 spring.ai.openai.embedding.base-url 和 spring.ai.openai.embedding.api-key 属性,则优先于基础属性。如果您希望为不同的模型和不同的模型端点使用不同的 OpenAI 帐户,这将非常有用。
所有可以通过向 EmbeddingRequest 参数中自定义设置 Embedding Options 参数来在运行时进行覆盖以 spring.ai.openai.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()));
示例接口(自动配置)
将创建一个 EmbeddingClient 实现,您可以将其注入到您的类中。这里是一个使用 EmbeddingClient 实现的简单 @Controller 类的示例。
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);
}
}
手动配置
如果您没有使用 Spring Boot,您可以手动配置 OpenAI Embedding Client。为此,请将 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'
}
参考 3. 开始章节 中的 依赖管理 部分,将 Spring AI BOM 添加到您的构建文件中。
spring-ai-openai 依赖包还提供了访问 OpenAiChatClient 的功能。有关 OpenAiChatClient 的更多信息,请参考 04.Spring AI API 下 01. 聊天API 下 01. OpenAI 章节 。
接下来,创建一个 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提供了嵌入向量请求的配置信息。Options 类提供了一个便于创建实例的builder()。