OpenAI 嵌入模型
| 本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。 商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。 |
Spring AI 支持 OpenAI 的文本嵌入模型。OpenAI 的文本嵌入用于衡量文本字符串之间的相关性。嵌入是由浮点数组成的向量（列表），两个向量之间的距离反映它们的相关性：距离越小表示相关性越高，距离越大表示相关性越低。
先决条件
你需要创建 OpenAI API 以访问其嵌入模型。
前往 OpenAI 注册页面 创建账户，并在 API Key 页面 生成访问令牌。
Spring AI 项目定义了名为 spring.ai.openai.api-key 的配置属性，需设置为从 openai.com 获取的 API 密钥值。
你可以在 application.properties 文件中配置此属性：
spring.ai.openai.api-key=<your-openai-api-key>为提升 API 密钥等敏感信息的安全性，可使用 Spring 表达式语言 （SpEL）引用环境变量：
# In application.yml
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}# In your environment or .env file
export OPENAI_API_KEY=<your-openai-api-key>你也可以在应用代码中以编程方式配置：
// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("OPENAI_API_KEY");添加仓库和 BOM
Spring AI 构件已发布至 Maven 中央仓库和 Spring 快照仓库。请参阅 “Artifact 仓库” 章节将这些仓库添加到你的构建系统中。
为简化依赖管理，Spring AI 提供 BOM 以确保项目统一使用相同版本。请参考 “依赖管理” 章节将 Spring AI BOM 添加到你的构建系统。
自动配置
|
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 添加到你的构建文件。 |
嵌入配置
重试配置
前缀 ring.ai.retrysp 是用于配置 OpenAI 嵌入模型重试机制的属性前缀。
| 属性 | 说明 | 默认值 |
|---|---|---|
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，则抛出 |
false |
spring.ai.retry.exclude-on-http-codes |
不应触发重试的 HTTP 状态代码列表（例如抛出 |
empty |
spring.ai.retry.on-http-codes |
应触发重试的 HTTP 状态代码列表（例如抛出 |
empty |
连接配置
前缀 spring.ai.openai 是用于连接 OpenAI 的属性前缀。
| 属性 | 说明 | 默认值 |
|---|---|---|
spring.ai.openai.base-url |
要连接到的 URL |
https://api.openai.com |
spring.ai.openai.api-key |
API Key |
- |
spring.ai.openai.organization-id |
可选，指定用于 API 请求的组织。 |
- |
spring.ai.openai.project-id |
可选指定用于 API 请求的项目。 |
- |
| 对于属于多个组织（或通过旧版用户 API Key 访问项目）的用户，可选指定用于 API 请求的组织和项目。相关 API 请求的使用量将计入指定组织和项目。 |
配置属性
|
嵌入自动配置的启用与禁用现在通过顶级属性配置，前缀为
此变更是为了支持多模型配置。 |
前缀 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.embedding.embeddings-path |
附加到 base-url 的路径。 |
|
spring.ai.openai.embedding.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 (other options: text-embedding-3-large, text-embedding-3-small) |
spring.ai.openai.embedding.options.encodingFormat |
返回嵌入向量的格式，可选 |
- |
spring.ai.openai.embedding.options.user |
用于标识终端用户的唯一 ID，可协助 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()));示例 Controller
这将创建一个可注入到类中的 EmbeddingModel 实现。以下是一个简单的 @Controller 类示例，该类使 EmbeddingModel 实现：
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 嵌入模型。为此需在项目的 Maven pom.xml 文件中添加 spring-ai-openai 依赖：
<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 聊天客户端” 章节。
|
接下来，创建 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 为嵌入请求提供配置信息，其内置的 builder() 方法可便捷创建配置选项。
