41_Spring AI 干货笔记之 OpenAI SDK 嵌入（官方支持）

一、OpenAI SDK 嵌入（官方支持）

Spring AI 通过 OpenAI Java SDK 提供对 OpenAI 文本嵌入模型的支持，为 OpenAI 服务（包括 Microsoft Foundry 和 GitHub Models）提供了稳健且官方维护的集成方案。

此实现使用来自 OpenAI 的官方 Java SDK。如需了解 Spring AI 的替代实现，请参阅 OpenAI 嵌入。

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

OpenAI SDK 模块会根据您提供的基础 URL 自动检测服务提供商（OpenAI、Microsoft Foundry 或 GitHub Models）。

二、认证

认证通过基础 URL 和 API 密钥完成。该实现通过 Spring Boot 属性或环境变量提供了灵活的配置选项。

2.1 使用 OpenAI

如果您直接使用 OpenAI，请在 OpenAI 注册页面创建账户，并在 API 密钥页面生成 API 密钥。

基础 URL 无需设置，因为它默认指向 api.openai.com/v1：

yaml 复制代码

spring.ai.openai-sdk.api-key=<your-openai-api-key>
# base-url 是可选的，默认为 https://api.openai.com/v1

或使用环境变量：

bash 复制代码

export OPENAI_API_KEY=<your-openai-api-key>
# OPENAI_BASE_URL 是可选的，默认为 https://api.openai.com/v1

2.2 使用 Microsoft Foundry

当使用 Microsoft Foundry 的 URL 时，系统会自动检测到它。您可以使用属性进行配置：

yaml 复制代码

spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.api-key=<your-api-key>
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>

或使用环境变量：

bash 复制代码

export OPENAI_BASE_URL=https://<your-deployment-url>.openai.azure.com
export OPENAI_API_KEY=<your-api-key>

2.3 无密码认证（Azure 推荐）：

Microsoft Foundry 支持不提供 API 密钥的无密码认证，这在 Azure 上运行时更加安全。

要启用无密码认证，请添加 com.azure:azure-identity 依赖项：

xml 复制代码

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

然后，无需 API 密钥即可配置：

yaml 复制代码

spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>
# 无需 api-key - 将使用环境中的 Azure 凭据

2.4 使用 GitHub Models

当使用 GitHub Models 的基础 URL 时，系统会自动检测到它。您需要创建一个具有 models:read 范围的 GitHub 个人访问令牌（PAT）。

yaml 复制代码

spring.ai.openai-sdk.base-url=https://models.inference.ai.azure.com
spring.ai.openai-sdk.api-key=github_pat_XXXXXXXXXXX

或使用环境变量：

bash 复制代码

export OPENAI_BASE_URL=https://models.inference.ai.azure.com
export OPENAI_API_KEY=github_pat_XXXXXXXXXXX

为了在处理敏感信息（如 API 密钥）时增强安全性，您可以在属性中使用 Spring 表达式语言（SpEL）：

yaml 复制代码

spring.ai.openai-sdk.api-key=${OPENAI_API_KEY}

2.5 添加仓库和 BOM

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

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

三、自动配置

Spring AI 为 OpenAI SDK 嵌入模型提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中：

Maven

xml 复制代码

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

Gradle

groovy 复制代码

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

请参阅依赖管理部分，将 Spring AI BOM 添加到您的构建文件中。

四、配置属性

4.1 连接属性

前缀 spring.ai.openai-sdk 用作属性前缀，用于配置 OpenAI SDK 客户端。

4.2 Microsoft Foundry 属性

OpenAI SDK 实现提供了对 Microsoft Foundry 的原生支持，并支持自动配置：

Microsoft Foundry 支持无密码认证。添加 com.azure:azure-identity 依赖项，当不提供 API 密钥时，实现将自动尝试使用环境中的 Azure 凭据。

4.3 GitHub Models 属性

提供对 GitHub Models 的原生支持：

GitHub Models 需要一个具有 models:read 范围的个人访问令牌。通过 OPENAI_API_KEY 环境变量或 spring.ai.openai-sdk.api-key 属性进行设置。

4.4 嵌入模型属性

前缀 spring.ai.openai-sdk.embedding 是用于配置嵌入模型实现的属性前缀：

所有以 spring.ai.openai-sdk.embedding.options 为前缀的属性都可以在运行时通过向 EmbeddingRequest 调用添加请求特定的运行时选项来覆盖。

五、运行时选项

OpenAiSdkEmbeddingOptions.java 提供了 OpenAI 的配置，例如要使用的模型、维度和用户标识符。

默认选项也可以使用 spring.ai.openai-sdk.embedding.options 属性进行配置。

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

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

java 复制代码

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OpenAiSdkEmbeddingOptions.builder()
            .model("text-embedding-3-large")
            .dimensions(1024)
        .build()));

除了特定于模型的 OpenAiSdkEmbeddingOptions，您还可以使用可移植的 EmbeddingOptions 实例，通过构建器创建。

六、示例控制器

创建一个新的 Spring Boot 项目，并将 spring-ai-openai-sdk 添加到您的 pom（或 gradle）依赖项中。

在 src/main/resources 目录下添加一个 application.properties 文件来配置 OpenAI SDK 嵌入模型：

yaml 复制代码

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

将 api-key 替换为您的 OpenAI 凭据。

这将创建一个 OpenAiSdkEmbeddingModel 实现，您可以将其注入到您的类中。下面是一个简单的 @RestController 类示例，它使用嵌入模型：

java 复制代码

@RestController
public class EmbeddingController {

    private final EmbeddingModel embeddingModel;

    @Autowired
    public EmbeddingController(EmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }

    @GetMapping("/ai/embedding")
    public Map<String, Object> embed(
            @RequestParam(value = "message", defaultValue = "给我讲个笑话") String message) {
        EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
        return Map.of("embedding", embeddingResponse);
    }
}

七、手动配置

OpenAiSdkEmbeddingModel 实现了 EmbeddingModel，并使用官方的 OpenAI Java SDK 连接到 OpenAI 服务。

如果不使用 Spring Boot 自动配置，您可以手动配置 OpenAI SDK 嵌入模型。为此，请将 spring-ai-openai-sdk 依赖项添加到项目的 Maven pom.xml 文件中：

xml 复制代码

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

或添加到您的 Gradle build.gradle 构建文件中：

groovy 复制代码

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

请参阅依赖管理部分，将 Spring AI BOM 添加到您的构建文件中。

spring-ai-openai-sdk 依赖项还提供了对 OpenAiSdkChatModel 和 OpenAiSdkImageModel 的访问权限。有关 OpenAiSdkChatModel 的更多信息，请参阅 OpenAI SDK 聊天部分。

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

java 复制代码

var embeddingOptions = OpenAiSdkEmbeddingOptions.builder()
    .model("text-embedding-ada-002")
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();

var embeddingModel = new OpenAiSdkEmbeddingModel(embeddingOptions);

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

OpenAiSdkEmbeddingOptions 提供嵌入请求的配置信息。选项类提供了一个 builder() 用于轻松创建选项。

7.1 Microsoft Foundry 配置

对于 Microsoft Foundry：

java 复制代码

var embeddingOptions = OpenAiSdkEmbeddingOptions.builder()
    .baseUrl("https://your-resource.openai.azure.com")
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .deploymentName("text-embedding-ada-002")
    .azureOpenAIServiceVersion(AzureOpenAIServiceVersion.V2024_10_01_PREVIEW)
    .azure(true)  // 启用 Microsoft Foundry 模式
    .build();

var embeddingModel = new OpenAiSdkEmbeddingModel(embeddingOptions);

Microsoft Foundry 支持无密码认证。将 com.azure:azure-identity 依赖项添加到您的项目中。如果不提供 API 密钥，实现将自动尝试使用您环境中的 Azure 凭据。

7.2 GitHub Models 配置

对于 GitHub Models：

java 复制代码

var embeddingOptions = OpenAiSdkEmbeddingOptions.builder()
    .baseUrl("https://models.inference.ai.azure.com")
    .apiKey(System.getenv("GITHUB_TOKEN"))
    .model("text-embedding-3-large")
    .githubModels(true)
    .build();

var embeddingModel = new OpenAiSdkEmbeddingModel(embeddingOptions);

八、可观测性

OpenAI SDK 实现通过 Micrometer 支持 Spring AI 的可观测性功能。所有嵌入模型操作都经过检测，用于监控和追踪。

41_Spring AI 干货笔记之 OpenAI SDK 嵌入（官方支持）

一、OpenAI SDK 嵌入（官方支持）

二、认证

2.1 使用 OpenAI

2.2 使用 Microsoft Foundry

2.3 无密码认证（Azure 推荐）：

2.4 使用 GitHub Models

2.5 添加仓库和 BOM

三、自动配置

四、配置属性

4.1 连接属性

4.2 Microsoft Foundry 属性

4.3 GitHub Models 属性

4.4 嵌入模型属性

五、运行时选项

六、示例控制器

七、手动配置

7.1 Microsoft Foundry 配置

7.2 GitHub Models 配置

八、可观测性

九、其他资源