OpenAI 嵌入模型
Spring AI 支持 OpenAI 的文本嵌入模型。 OpenAI 的文本嵌入用于测量文本字符串之间的相关性。 嵌入是一个浮点数的向量（列表）。两个向量之间的距离衡量它们的相关性。距离小表示高度相关，距离大表示低相关性。
前提条件
你需要创建一个 OpenAI API 来访问 OpenAI 嵌入模型。
在 OpenAI 注册页面 创建账户，并在 API Keys 页面 生成令牌。
Spring AI 项目定义了一个名为 spring.ai.openai.api-key 的配置属性，你应该将其设置为从 openai.com 获取的 API Key 值。
你可以在 application.properties 文件中设置此配置属性：
spring.ai.openai.api-key=<your-openai-api-key>为了增强处理敏感信息（如 API 密钥）的安全性，你可以使用 Spring 表达式语言（SpEL）来引用环境变量：
# 在 application.yml 中
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}# 在你的环境或 .env 文件中
export OPENAI_API_KEY=<your-openai-api-key>你也可以在应用程序代码中以编程方式设置此配置：
// 从安全源或环境变量中获取 API 密钥
String apiKey = System.getenv("OPENAI_API_KEY");自动配置
|
Spring AI 自动配置、starter 模块的构件名称发生了重大变化。 请参阅 升级说明 了解更多信息。 |
Spring AI 为 OpenAI 嵌入模型提供了 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven pom.xml 文件中：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>或添加到 Gradle build.gradle 构建文件中。
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}提示：请参阅 依赖管理 部分，将 Spring AI BOM 添加到你的构建文件中。
嵌入属性
重试属性
前缀 spring.ai.retry 用作属性前缀，让你可以为 OpenAI 嵌入模型配置重试机制。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.retry.max-attempts |
最大重试尝试次数。 |
10 |
spring.ai.retry.backoff.initial-interval |
指数退避策略的初始睡眠持续时间。 |
2 秒 |
spring.ai.retry.backoff.multiplier |
退避间隔乘数。 |
5 |
spring.ai.retry.backoff.max-interval |
最大退避持续时间。 |
3 分钟 |
spring.ai.retry.on-client-errors |
如果为 false，则抛出 NonTransientAiException，并且不对 |
false |
spring.ai.retry.exclude-on-http-codes |
不应触发重试的 HTTP 状态代码列表（例如抛出 NonTransientAiException）。 |
empty |
spring.ai.retry.on-http-codes |
应触发重试的 HTTP 状态代码列表（例如抛出 TransientAiException）。 |
empty |
连接属性
前缀 spring.ai.openai 用作属性前缀，让你可以连接到 OpenAI。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.openai.base-url |
连接 URL |
https://api.openai.com |
spring.ai.openai.api-key |
API 密钥 |
- |
spring.ai.openai.organization-id |
可选，你可以指定用于 API 请求的组织。 |
- |
spring.ai.openai.project-id |
可选，你可以指定用于 API 请求的项目。 |
- |
提示：对于属于多个组织的用户（或通过其旧版用户 API 密钥访问其项目），你可以选择指定用于 API 请求的组织和项目。 这些 API 请求的使用将计入指定组织和项目的使用量。
配置属性
|
嵌入自动配置的启用和禁用现在通过前缀为 要启用，spring.ai.model.embedding=openai（默认启用） 要禁用，spring.ai.model.embedding=none（或任何不匹配 openai 的值） 此更改是为了允许多个模型的配置。 |
前缀 spring.ai.openai.embedding 是配置 OpenAI 的 EmbeddingModel 实现的属性前缀。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.openai.embedding.enabled（必需且不再有效） |
启用 OpenAI 嵌入模型。 |
true |
spring.ai.model.embedding |
启用 OpenAI 嵌入模型。 |
openai |
spring.ai.openai.embedding.base-url |
可选覆盖 spring.ai.openai.base-url 以提供特定于嵌入的 url |
- |
spring.ai.openai.embedding.embeddings-path |
附加到 base-url 的路径 |
|
spring.ai.openai.embedding.api-key |
可选覆盖 spring.ai.openai.api-key 以提供特定于嵌入的 api-key |
- |
spring.ai.openai.embedding.organization-id |
可选，你可以指定用于 API 请求的组织。 |
- |
spring.ai.openai.embedding.project-id |
可选，你可以指定用于 API 请求的项目。 |
- |
spring.ai.openai.embedding.metadata-mode |
文档内容提取模式。 |
EMBED |
spring.ai.openai.embedding.options.model |
要使用的模型 |
text-embedding-ada-002（其他选项：text-embedding-3-large、text-embedding-3-small） |
spring.ai.openai.embedding.options.encodingFormat |
返回嵌入的格式。可以是 float 或 base64。 |
- |
spring.ai.openai.embedding.options.user |
代表你的最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用。 |
- |
spring.ai.openai.embedding.options.dimensions |
结果输出嵌入应具有的维度数。仅在 |
- |
注意：你可以覆盖 ChatModel 和 EmbeddingModel 实现的通用 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.chat.base-url 和 spring.ai.openai.chat.api-key 属性，它们将优先于通用属性。
如果你想为不同的模型和不同的模型端点使用不同的 OpenAI 账户，这很有用。
提示：所有以 spring.ai.openai.embedding.options 为前缀的属性都可以通过在 EmbeddingRequest 调用中添加请求特定的 运行时选项 在运行时被覆盖。
运行时选项
OpenAiEmbeddingOptions.java 提供了 OpenAI 配置，例如要使用的模型等。
默认选项也可以使用 spring.ai.openai.embedding.options 属性进行配置。
在启动时使用 OpenAiEmbeddingModel 构造函数设置用于所有嵌入请求的默认选项。
在运行时，你可以通过在 EmbeddingRequest 中使用 OpenAiEmbeddingOptions 实例来覆盖默认选项。
例如，为特定请求覆盖默认模型名称：
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
OpenAiEmbeddingOptions.builder()
.model("Different-Embedding-Model-Deployment-Name")
.build()));示例控制器
这将创建一个 EmbeddingModel 实现，你可以将其注入到你的类中。
以下是一个使用 EmbeddingModel 实现的简单 @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 EmbeddingModel embeddingModel;
@Autowired
public EmbeddingController(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
@GetMapping("/ai/embedding")
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
return Map.of("embedding", embeddingResponse);
}
}手动配置
如果你不使用 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'
}提示：请参阅 依赖管理 部分，将 Spring AI BOM 添加到你的构建文件中。
注意：spring-ai-openai 依赖项还提供对 OpenAiChatModel 的访问。
有关 OpenAiChatModel 的更多信息，请参阅 OpenAI Chat Client 部分。
接下来，创建一个 OpenAiEmbeddingModel 实例并使用它来计算两个输入文本之间的相似度：
var openAiApi = OpenAiApi.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.build();
var embeddingModel = new OpenAiEmbeddingModel(
this.openAiApi,
MetadataMode.EMBED,
OpenAiEmbeddingOptions.builder()
.model("text-embedding-ada-002")
.user("user-6")
.build(),
RetryUtils.DEFAULT_RETRY_TEMPLATE);
EmbeddingResponse embeddingResponse = this.embeddingModel
.embedForResponse(List.of("Hello World", "World is big and salvation is near"));OpenAiEmbeddingOptions 提供嵌入请求的配置信息。
api 和 options 类提供了 builder() 用于轻松创建选项。
