42_Spring AI 干货笔记之 OpenAI 嵌入-编程实验室

一、OpenAI 嵌入

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

二、先决条件

您需要创建 OpenAI 的 API 来访问其嵌入模型。

在 OpenAI 注册页面创建账户。
在 API 密钥页面生成令牌。

Spring AI 项目定义了一个名为 spring.ai.openai.api-key 的配置属性，您应将其设置为从 openai.com 获取的 API 密钥值。

您可以在 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 文件中exportOPENAI_API_KEY=<your-openai-api-key>

您也可以在应用程序代码中以编程方式设置此配置：

// 从安全源或环境变量检索 API 密钥StringapiKey=System.getenv("OPENAI_API_KEY");

2.1 添加仓库和 BOM

Spring AI 工件发布在 Maven Central 和 Spring Snapshot 仓库中。请参阅工件仓库部分，将这些仓库添加到您的构建系统中。

为了帮助管理依赖项，Spring AI 提供了一个 BOM（物料清单）来确保在整个项目中使用一致的 Spring AI 版本。请参阅依赖管理部分，将 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 添加到您的构建文件中。

四、嵌入属性

4.1 重试属性

前缀 spring.ai.retry 用作属性前缀，用于配置 OpenAI 嵌入模型的重试机制。

4.2 连接属性

前缀 spring.ai.openai 用作属性前缀，用于连接到 OpenAI。

对于属于多个组织的用户（或通过其旧版用户 API 密钥访问其项目），您可以选择指定哪个组织和项目用于 API 请求。来自这些 API 请求的使用量将计入指定组织和项目的使用量。

4.3 配置属性

嵌入自动配置的启用和禁用现在通过顶级属性 spring.ai.model.embedding 前缀进行配置。
要启用：spring.ai.model.embedding=openai（默认启用）
要禁用：spring.ai.model.embedding=none（或任何与 openai 不匹配的值）
进行此更改是为了允许配置多个模型。

前缀 spring.ai.openai.embedding 是用于配置 OpenAI 的 EmbeddingModel 实现的属性前缀。

您可以为 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 构造函数来设置用于所有嵌入请求的默认选项。在运行时，您可以使用 OpenAiEmbeddingOptions 实例作为 EmbeddingRequest 的一部分来覆盖默认选项。

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

EmbeddingResponseembeddingResponse=embeddingModel.call(newEmbeddingRequest(List.of("Hello World","World is big and salvation is near"),OpenAiEmbeddingOptions.builder().model("Different-Embedding-Model-Deployment-Name").build()));

六、示例控制器

这将创建一个 EmbeddingModel 实现，您可以将其注入到您的类中。下面是一个简单的 @Controller 类示例，它使用 EmbeddingModel 实现。

spring.ai.openai.api-key=YOUR_API_KEY spring.ai.openai.embedding.options.model=text-embedding-ada-002

@RestControllerpublicclassEmbeddingController{privatefinalEmbeddingModelembeddingModel;@AutowiredpublicEmbeddingController(EmbeddingModelembeddingModel){this.embeddingModel=embeddingModel;}@GetMapping("/ai/embedding")publicMapembed(@RequestParam(value="message",defaultValue="给我讲个笑话")Stringmessage){EmbeddingResponseembeddingResponse=this.embeddingModel.embedForResponse(List.of(message));returnMap.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 聊天客户端部分。

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

varopenAiApi=OpenAiApi.builder().apiKey(System.getenv("OPENAI_API_KEY")).build();varembeddingModel=newOpenAiEmbeddingModel(this.openAiApi,MetadataMode.EMBED,OpenAiEmbeddingOptions.builder().model("text-embedding-ada-002").user("user-6").build(),RetryUtils.DEFAULT_RETRY_TEMPLATE);EmbeddingResponseembeddingResponse=this.embeddingModel.embedForResponse(List.of("Hello World","World is big and salvation is near"));