Azure OpenAI 嵌入

Azure 的 OpenAI 擴充套件了 OpenAI 的能力，為各種任務提供了安全的文字生成和嵌入計算模型。

  • 相似度嵌入擅長捕獲兩段或多段文字之間的語義相似性。

  • 文字搜尋嵌入有助於衡量長文件與短查詢的相關性。

  • 程式碼搜尋嵌入可用於嵌入程式碼片段和自然語言搜尋查詢。

Azure OpenAI 嵌入依賴於 餘弦相似度 來計算文件與查詢之間的相似性。

先決條件

Azure OpenAI 客戶端提供三種連線選項：使用 Azure API 金鑰、使用 OpenAI API 金鑰或使用 Microsoft Entra ID。

Azure API 金鑰和端點

從 Azure Portal 上的 Azure OpenAI Service 部分獲取你的 Azure OpenAI endpoint（端點）和 api-key（API 金鑰）。

Spring AI 定義了兩個配置屬性

  1. spring.ai.azure.openai.api-key：將其設定為從 Azure 獲取的 API Key 的值。

  2. spring.ai.azure.openai.endpoint：將其設定為在 Azure 中預配模型時獲得的端點 URL。

你可以透過匯出環境變數來設定這些配置屬性

export SPRING_AI_AZURE_OPENAI_API_KEY=<INSERT AZURE KEY HERE>
export SPRING_AI_AZURE_OPENAI_ENDPOINT=<INSERT ENDPOINT URL HERE>

OpenAI 金鑰

要使用 OpenAI 服務（非 Azure）進行身份驗證，請提供 OpenAI API 金鑰。這將自動把端點設定為 api.openai.com/v1。

使用此方法時，將 spring.ai.azure.openai.chat.options.deployment-name 屬性設定為你希望使用的 OpenAI 模型 的名稱。

export SPRING_AI_AZURE_OPENAI_OPENAI_API_KEY=<INSERT OPENAI KEY HERE>

Microsoft Entra ID

要使用 Microsoft Entra ID（以前稱為 Azure Active Directory）進行身份驗證，請在你的配置中建立一個 TokenCredential bean。如果此 bean 可用，則將使用令牌憑據建立一個 OpenAIClient 例項。

新增倉庫和 BOM

Spring AI 的構建產物釋出在 Maven Central 和 Spring Snapshot 倉庫中。請參閱倉庫部分，瞭解如何將這些倉庫新增到你的構建系統中。

為了幫助管理依賴項，Spring AI 提供了一個 BOM（物料清單），以確保在整個專案中使用的 Spring AI 版本一致。請參閱依賴管理部分，瞭解如何將 Spring AI BOM 新增到你的構建系統中。

自動配置

Spring AI 自動配置、Starter 模組的構建產物名稱發生了重大變化。更多資訊請參閱升級說明。

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。這會自動將端點設定為 api.openai.com/v1。請使用 api-key 或 openai-api-key 屬性中的一個。在此配置下，spring.ai.azure.openai.embedding.options.deployment-name 被視為 OpenAI 模型 名稱。

-

Embedding 自動配置的啟用和停用現在透過以 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 embedding 模型。

true

spring.ai.model.embedding

啟用 Azure OpenAI embedding 模型。

azure-openai

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

文件內容提取模式

EMBED

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

這是 Azure AI Portal 中顯示的“部署名稱”的值。

text-embedding-ada-002

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

操作呼叫方或終端使用者的識別符號。可用於跟蹤或速率限制目的。

-
所有以 spring.ai.azure.openai.embedding.options 為字首的屬性都可以在執行時透過向 EmbeddingRequest 呼叫新增特定於請求的執行時選項來覆蓋。

執行時選項

AzureOpenAiEmbeddingOptions 提供 embedding 請求的配置資訊。AzureOpenAiEmbeddingOptions 提供一個構建器來建立選項。

啟動時使用 AzureOpenAiEmbeddingModel 建構函式設定所有 embedding 請求使用的預設選項。執行時，你可以透過將包含你的 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 實現，你可以將其注入到你的類中。這是一個使用 EmbeddingModel 實現的簡單 @Controller 類的示例。

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。為此，請將 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 Portal 中顯示的 部署名稱。