Azure OpenAI 向量模型 - 零基础入门Java AI

Azure OpenAI 扩展了 OpenAI 的功能，为各种任务提供安全的文本生成和 Embeddings 计算模型：

相似性嵌入擅长捕捉两个或多个文本片段之间的语义相似性。
文本搜索嵌入有助于衡量长文档是否与短查询相关。
代码搜索嵌入可用于嵌入代码片段和嵌入自然语言搜索查询。

Azure OpenAI 嵌入依赖于余弦相似度来计算文档和查询之间的相似度。

先决条件

Azure OpenAI 客户端提供三种连接选项：使用 Azure API 密钥、使用 OpenAI API 密钥或使用 Microsoft Entra ID。

Azure API 密钥和终结点

从 Azure 门户上的 Azure OpenAI 服务部分获取您的 Azure OpenAI endpoint 和 api-key。 Spring AI 定义了两个配置属性：

spring.ai.azure.openai.api-key：将其设置为从 Azure 获取的 API Key 的值。
spring.ai.azure.openai.endpoint：将其设置为在 Azure 中预配模型时获取的终结点 URL。

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

spring.ai.azure.openai.api-key=<您的 Azure API 密钥>
spring.ai.azure.openai.endpoint=<您的 Azure 终结点 URL>

如果您希望对 API 密钥等敏感信息使用环境变量，可以在配置中使用 Spring 表达式语言 (SpEL)：

# 在 application.yml 中
spring:
  ai:
    azure:
      openai:
        api-key: ${AZURE_OPENAI_API_KEY}
        endpoint: ${AZURE_OPENAI_ENDPOINT}

# 在您的环境或 .env 文件中
export AZURE_OPENAI_API_KEY=<您的 Azure OpenAI API 密钥>
export AZURE_OPENAI_ENDPOINT=<您的 Azure 终结点 URL>

OpenAI 密钥

要使用 OpenAI 服务（而非 Azure）进行身份验证，请提供 OpenAI API 密钥。

自动配置

注意：Spring AI 自动配置和启动器模块的工件名称已发生重大更改。有关更多信息，请参阅升级说明。

Spring AI 为 Azure OpenAI Embedding 模型提供 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 添加到您的构建文件中。

Embedding 属性

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

属性	描述	默认值
spring.ai.azure.openai.api-key	Azure AI OpenAI `资源管理`下`密钥和终结点`部分的密钥。	-
spring.ai.azure.openai.endpoint	Azure AI OpenAI `资源管理`下`密钥和终结点`部分的终结点。	-
spring.ai.azure.openai.openai-api-key	(非 Azure) OpenAI API 密钥。用于向 OpenAI 服务（而非 Azure OpenAI）进行身份验证。这会自动将终结点设置为 https://api.openai.com/v1。使用 `api-key` 或 `openai-api-key` 属性。使用此配置时，`spring.ai.azure.openai.embedding.options.deployment-name` 将被视为 OpenAI 模型名称。	-

注意：嵌入自动配置的启用和禁用现在通过前缀为 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 门户中显示的”部署名称”的值。	text-embedding-ada-002
spring.ai.azure.openai.embedding.options.user	操作的调用方或最终用户的标识符。这可用于跟踪或速率限制目的。	-

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

运行时选项

AzureOpenAiEmbeddingOptions 提供嵌入请求的配置信息。 AzureOpenAiEmbeddingOptions 提供了一个构建器来创建选项。在启动时，使用 AzureOpenAiEmbeddingModel 构造函数设置用于所有嵌入请求的默认选项。在运行时，您可以通过将 AzureOpenAiEmbeddingOptions 实例传递给 EmbeddingRequest 请求来覆盖默认选项。例如，要覆盖特定请求的默认模型名称：

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=您的 API 密钥
spring.ai.azure.openai.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。为此，请将 spring-ai-azure-openai 依赖项添加到项目的 Maven pom.xml 文件中：

<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 Embeddings 部分。

接下来，创建一个 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 门户中显示的部署名称。

文档有误？请协助编辑

发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！

​先决条件

​Azure API 密钥和终结点

​OpenAI 密钥

​自动配置

​Embedding 属性

​运行时选项

​示例代码

​手动配置