Azure OpenAI 嵌入模型

本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。 商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

Azure 的 OpenAI 扩展了 OpenAI 的功能，提供安全的文本生成和嵌入（Embedding）计算模型，适用于多种任务：

  • 相似性嵌入擅长捕捉两段或多段文本之间的语义相似性。

  • 文本搜索嵌入有助于衡量长文档是否与简短查询相关。

  • 代码搜索嵌入适用于嵌入代码片段和自然语言搜索查询。

Azure OpenAI 嵌入依靠 cosine similarity （余弦相似度）来计算文档与查询之间的相似性。

先决条件

Azure OpenAI 客户端提供三种连接方式：使用 Azure API Key、使用OpenAI API Key 或使用 Microsoft Entra ID。

Azure API Key 和 Endpoint

从 Azure 门户 的 Azure OpenAI 服务部分获取你的 Azure OpenAI endpoint 和 api-key。

Spring AI 定义了两个配置属性：

  1. spring.ai.azure.openai.api-key：设置为从 Azure 获取的 API Key 值。

  2. spring.ai.azure.openai.endpoint：设置为在 Azure 中配置模型时获取的 endpoint URL。

你可以在 application.properties 或 application.yml 文件中设置这些配置属性：

spring.ai.azure.openai.api-key=<your-azure-api-key>
spring.ai.azure.openai.endpoint=<your-azure-endpoint-url>

若你倾向对 API Key 等敏感信息使用环境变量，可在配置中使用 Spring 表达式语言（SpEL）：

# In application.yml
spring:
  ai:
    azure:
      openai:
        api-key: ${AZURE_OPENAI_API_KEY}
        endpoint: ${AZURE_OPENAI_ENDPOINT}
# In your environment or .env file
export AZURE_OPENAI_API_KEY=<your-azure-openai-api-key>
export AZURE_OPENAI_ENDPOINT=<your-azure-endpoint-url>

OpenAI Key

如需通过 OpenAI 服务（非 Azure）认证，请提供 OpenAI API Key。这将自动将端点设为 api.openai.com/v1。

采用此方式时，请将 spring.ai.azure.openai.chat.options.deployment-name 属性设置为要使用的 OpenAI 模型 名称。

应用配置：

spring.ai.azure.openai.openai-api-key=<your-azure-openai-key>
spring.ai.azure.openai.chat.options.deployment-name=<openai-model-name>

使用 SpEL 读取环境变量：

# In application.yml
spring:
  ai:
    azure:
      openai:
        openai-api-key: ${AZURE_OPENAI_API_KEY}
        chat:
          options:
            deployment-name: ${OPENAI_MODEL_NAME}
# In your environment or .env file
export AZURE_OPENAI_API_KEY=<your-openai-key>
export OPENAI_MODEL_NAME=<openai-model-name>

Microsoft Entra ID

对于使用 Microsoft Entra ID（原 Azure Active Directory）的无密钥认证，仅需设置 spring.ai.azure.openai.endpoint 配置属性，无需设置上述 api-key 属性。

仅提供 endpoint 属性时，应用将评估多种不同的选项来检索凭据，并将使用令牌凭据创建一个 OpenAIClient 实例。

不再需要手动创建 TokenCredential Bean，系统会自动完成其配置。

添加仓库和 BOM

Spring AI 构件已发布至 Maven 中央仓库和 Spring 快照仓库。请参阅 构件仓库 章节将这些仓库添加到你的构建系统中。

为简化依赖管理，Spring AI 提供 BOM 以确保项目统一使用相同版本。请参考 依赖管理 章节将 Spring AI 添加到你的构建系统中。

自动配置

Spring AI 自动配置及 Starter 模块的构件命名已发生重大变更，详情请参阅 升级说明文档。

Spring AI 为 Azure OpenAI 嵌入模型提供 Spring Boot 自动配置。启用该功能需在项目的 Maven pom.xml 文件中添加以下依赖：

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

或添加到你的 Gradle build.gradle 构建文件中。

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-azure-openai'
}
请参阅 依赖管理 章节将 Spring AI BOM 添加到你的构建文件。

嵌入配置

前缀 spring.ai.azure.openai 是用于配置 Azure OpenAI 连接的属性前缀。

属性 说明 默认值

spring.ai.azure.openai.api-key

Key 来自 Azure AI OpenAI Resource Management 下的 Keys and Endpoint 部分

-

spring.ai.azure.openai.endpoint

Endpoint 来自 Azure AI OpenAI Resource Management 下的 Keys and Endpoint 部分

-

spring.ai.azure.openai.openai-api-key

（非 Azure）OpenAI API Key。用于直接认证 OpenAI 服务（而非 Azure OpenAI），该配置会自动将终端点设为 api.openai.com/v1。可选择配置 api-key 或 openai-api-key 属性。在此配置下，spring.ai.azure.openai.embedding.options.deployment-name 将被视为 OpenAi Model 名称。

-

嵌入自动配置的启用与禁用现在通过顶级属性配置，前缀为 spring.ai.model.embedding。

启用方式：spring.ai.model.embedding=azure-openai（默认启用）

禁用方式：spring.ai.model.embedding=none（或任何不匹配 azure-openai 的值）

此变更是为了支持多模型配置。

前缀 spring.ai.azure.openai.embedding 是用于配置 Azure OpenAI 嵌入模型（EmbeddingModel）实现的属性前缀：

属性 说明 默认值

spring.ai.azure.openai.embedding.enabled （已移除，不再有效）

启用 Azure OpenAI 嵌入模型。

true

spring.ai.model.embedding

启用 Azure OpenAI 嵌入模型。

azure-openai

spring.ai.azure.openai.embedding.metadata-mode

文档内容提取模式

EMBED

spring.ai.azure.openai.embedding.options.deployment-name

该值为 Azure AI 门户中显示的 “部署名称”(Deployment Name)

text-embedding-ada-002

spring.ai.azure.openai.embedding.options.user

操作调用者或终端用户的标识符，可用于追踪或限流目的。

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

运行时选项

AzureOpenAiEmbeddingOptions 为嵌入请求提供配置信息，其内置的构建器（Builder）可用于创建配置选项。

初始化时通过 AzureOpenAiEmbeddingModel 构造函数设置所有嵌入请求的默认选项。运行时可通过向 EmbeddingRequest 传递 AzureOpenAiEmbeddingOptions 实例来覆盖默认配置。

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

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        AzureOpenAiEmbeddingOptions.builder()
        .model("Different-Embedding-Model-Deployment-Name")
        .build()));

示例代码

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

spring.ai.azure.openai.api-key=YOUR_API_KEY
spring.ai.azure.openai.endpoint=YOUR_ENDPOINT
spring.ai.azure.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 自动配置，你可以在应用中手动配置 AzureOpenAiEmbeddingModel。为此，需在项目的 Maven pom.xml 文件中添加 spring-ai-azure-openai 依赖：

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

或添加到你的 Gradle build.gradle 构建文件中。

dependencies {
    implementation 'org.springframework.ai:spring-ai-azure-openai'
}
请参阅 依赖管理 章节将 Spring AI BOM 添加到你的构建文件。
spring-ai-azure-openai 依赖项同时提供对 AzureOpenAiEmbeddingModel 的访问。有关 AzureOpenAiChatModel 的更多信息，请参阅 Azure OpenAI 嵌入 章节。

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

var openAIClient = OpenAIClientBuilder()
        .credential(new AzureKeyCredential(System.getenv("AZURE_OPENAI_API_KEY")))
		.endpoint(System.getenv("AZURE_OPENAI_ENDPOINT"))
		.buildClient();

var embeddingModel = new AzureOpenAiEmbeddingModel(this.openAIClient)
    .withDefaultOptions(AzureOpenAiEmbeddingOptions.builder()
        .model("text-embedding-ada-002")
        .user("user-6")
        .build());

EmbeddingResponse embeddingResponse = this.embeddingModel
	.embedForResponse(List.of("Hello World", "World is big and salvation is near"));
text-embedding-ada-002 实际对应的是 Azure AI 门户中显示的部署名称（Deployment Name）。