Azure OpenAI 嵌入

Azure 的 OpenAI 擴展了 OpenAI 的功能，為各種任務提供安全的文字生成和嵌入計算模型

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

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

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

Azure OpenAI 嵌入依賴 cosine similarity 來計算文件和查詢之間的相似度。

先決條件

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

Azure API 金鑰 & 端點

從 Azure 入口網站上的 Azure OpenAI 服務區段取得您的 Azure OpenAI endpoint 和 api-key。

Spring AI 定義了兩個組態屬性

  1. spring.ai.azure.openai.api-key：將此設定為從 Azure 取得的 API 金鑰 值。

  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 成品發佈在 Spring Milestone 和 Snapshot 儲存庫中。請參閱儲存庫章節，將這些儲存庫新增至您的建置系統。

為了協助進行依賴性管理，Spring AI 提供了 BOM（物料清單），以確保在整個專案中使用一致版本的 Spring AI。請參閱依賴性管理章節，將 Spring AI BOM 新增至您的建置系統。

自動配置

Spring AI 為 Azure OpenAI 嵌入模型提供 Spring Boot 自動配置。若要啟用它，請將下列依賴性新增至您專案的 Maven pom.xml 檔案

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

或新增至您的 Gradle build.gradle 建置檔案。

dependencies {
    implementation 'org.springframework.ai:spring-ai-azure-openai-spring-boot-starter'
}
請參閱依賴性管理章節，將 Spring AI BOM 新增至您的建置檔案。

嵌入屬性

前綴 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 模型 名稱。

-

前綴 spring.ai.azure.openai.embedding 是配置 Azure OpenAI 的 EmbeddingModel 實作的屬性前綴

屬性 描述 預設值

spring.ai.azure.openai.embedding.enabled

啟用 Azure OpenAI 嵌入模型。

true

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()
        .withModel("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。為此，請將 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 嵌入章節。

接下來，建立一個 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()
        .withModel("text-embedding-ada-002")
        .withUser("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 入口網站中顯示的 部署名稱。