Azure Cosmos DB

本節將引導您設定 CosmosDBVectorStore,以便儲存文件嵌入並執行相似性搜尋。

什麼是 Azure Cosmos DB?

Azure Cosmos DB 是微軟的全球分散式雲原生資料庫服務,專為關鍵任務應用程式而設計。它提供高可用性、低延遲以及水平擴充套件能力,以滿足現代應用程式的需求。它從頭開始構建,其核心具備全球分散式、細粒度多租戶和水平可擴充套件性。它是 Azure 中的基礎服務,被微軟大多數全球範圍內的關鍵任務應用程式使用,包括 Teams、Skype、Xbox Live、Office 365、Bing、Azure Active Directory、Azure Portal、Microsoft Store 等等。它也被數千家外部客戶使用,包括 OpenAI 用於 ChatGPT 和其他需要彈性擴充套件、開箱即用的全球分散式以及遍佈全球的低延遲和高可用性的關鍵任務 AI 應用程式。

什麼是 DiskANN?

DiskANN(基於磁碟的近似最近鄰搜尋)是 Azure Cosmos DB 中用於增強向量搜尋效能的一項創新技術。透過索引儲存在 Cosmos DB 中的嵌入,它可以在高維資料上實現高效且可擴充套件的相似性搜尋。

DiskANN 提供以下優勢:

  • 效率:透過利用基於磁碟的結構,DiskANN 顯著減少了查詢最近鄰所需的時間,優於傳統方法。

  • 可擴充套件性:它可以處理超出記憶體容量的大型資料集,適用於各種應用程式,包括機器學習和 AI 驅動的解決方案。

  • 低延遲:DiskANN 最大限度地減少搜尋操作期間的延遲,確保應用程式即使在資料量巨大時也能快速檢索結果。

在適用於 Azure Cosmos DB 的 Spring AI 環境中,向量搜尋將建立並利用 DiskANN 索引,以確保相似性查詢的最佳效能。

使用自動配置設定 Azure Cosmos DB 向量儲存

以下程式碼演示瞭如何使用自動配置設定 CosmosDBVectorStore

package com.example.demo;

import io.micrometer.observation.ObservationRegistry;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.document.Document;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Lazy;

import java.util.List;
import java.util.Map;
import java.util.UUID;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootApplication
@EnableAutoConfiguration
public class DemoApplication implements CommandLineRunner {

    private static final Logger log = LoggerFactory.getLogger(DemoApplication.class);

    @Lazy
    @Autowired
    private VectorStore vectorStore;

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    @Override
    public void run(String... args) throws Exception {
        Document document1 = new Document(UUID.randomUUID().toString(), "Sample content1", Map.of("key1", "value1"));
        Document document2 = new Document(UUID.randomUUID().toString(), "Sample content2", Map.of("key2", "value2"));
		this.vectorStore.add(List.of(document1, document2));
        List<Document> results = this.vectorStore.similaritySearch(SearchRequest.builder().query("Sample content").topK(1).build());

        log.info("Search results: {}", results);

        // Remove the documents from the vector store
		this.vectorStore.delete(List.of(document1.getId(), document2.getId()));
    }

    @Bean
    public ObservationRegistry observationRegistry() {
        return ObservationRegistry.create();
    }
}

自動配置

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

將以下依賴項新增到您的 Maven 專案中

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-azure-cosmos-db</artifactId>
</dependency>

配置屬性

Cosmos DB 向量儲存提供以下配置屬性:

屬性 描述

spring.ai.vectorstore.cosmosdb.databaseName

要使用的 Cosmos DB 資料庫名稱。

spring.ai.vectorstore.cosmosdb.containerName

要使用的 Cosmos DB 容器名稱。

spring.ai.vectorstore.cosmosdb.partitionKeyPath

分割槽鍵的路徑。

spring.ai.vectorstore.cosmosdb.metadataFields

逗號分隔的元資料欄位列表。

spring.ai.vectorstore.cosmosdb.vectorStoreThroughput

向量儲存的吞吐量。

spring.ai.vectorstore.cosmosdb.vectorDimensions

向量的維度數量。

spring.ai.vectorstore.cosmosdb.endpoint

Cosmos DB 的端點。

spring.ai.vectorstore.cosmosdb.key

Cosmos DB 的金鑰(如果金鑰不存在,將使用 [DefaultAzureCredential](learn.microsoft.com/azure/developer/java/sdk/authentication/credential-chains#defaultazurecredential-overview))。

帶過濾器的複雜搜尋

您可以在 Cosmos DB 向量儲存中使用過濾器執行更復雜的搜尋。以下是一個示例,演示瞭如何在搜尋查詢中使用過濾器。

Map<String, Object> metadata1 = new HashMap<>();
metadata1.put("country", "UK");
metadata1.put("year", 2021);
metadata1.put("city", "London");

Map<String, Object> metadata2 = new HashMap<>();
metadata2.put("country", "NL");
metadata2.put("year", 2022);
metadata2.put("city", "Amsterdam");

Document document1 = new Document("1", "A document about the UK", this.metadata1);
Document document2 = new Document("2", "A document about the Netherlands", this.metadata2);

vectorStore.add(List.of(document1, document2));

FilterExpressionBuilder builder = new FilterExpressionBuilder();
List<Document> results = vectorStore.similaritySearch(SearchRequest.builder().query("The World")
    .topK(10)
    .filterExpression((this.builder.in("country", "UK", "NL")).build()).build());

不使用自動配置設定 Azure Cosmos DB 向量儲存

以下程式碼演示瞭如何在不依賴自動配置的情況下設定 CosmosDBVectorStore。[DefaultAzureCredential](learn.microsoft.com/azure/developer/java/sdk/authentication/credential-chains#defaultazurecredential-overview) 推薦用於對 Azure Cosmos DB 進行身份驗證。

@Bean
public VectorStore vectorStore(ObservationRegistry observationRegistry) {
    // Create the Cosmos DB client
    CosmosAsyncClient cosmosClient = new CosmosClientBuilder()
            .endpoint(System.getenv("COSMOSDB_AI_ENDPOINT"))
            .credential(new DefaultAzureCredentialBuilder().build())
            .userAgentSuffix("SpringAI-CDBNoSQL-VectorStore")
            .gatewayMode()
            .buildAsyncClient();

    // Create and configure the vector store
    return CosmosDBVectorStore.builder(cosmosClient, embeddingModel)
            .databaseName("test-database")
            .containerName("test-container")
            // Configure metadata fields for filtering
            .metadataFields(List.of("country", "year", "city"))
            // Set the partition key path (optional)
            .partitionKeyPath("/id")
            // Configure performance settings
            .vectorStoreThroughput(1000)
            .vectorDimensions(1536)  // Match your embedding model's dimensions
            // Add custom batching strategy (optional)
            .batchingStrategy(new TokenCountBatchingStrategy())
            // Add observation registry for metrics
            .observationRegistry(observationRegistry)
            .build();
}

@Bean
public EmbeddingModel embeddingModel() {
    return new TransformersEmbeddingModel();
}

此配置顯示所有可用的構建器選項:

  • databaseName:您的 Cosmos DB 資料庫名稱

  • containerName:資料庫中的容器名稱

  • partitionKeyPath:分割槽鍵的路徑(例如,“/id”)

  • metadataFields:將用於過濾的元資料欄位列表

  • vectorStoreThroughput:向量儲存容器的吞吐量 (RU/s)

  • vectorDimensions:向量的維度數量(應與您的嵌入模型匹配)

  • batchingStrategy:批次文件操作的策略(可選)

手動依賴項設定

將以下依賴項新增到您的 Maven 專案中

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-azure-cosmos-db-store</artifactId>
</dependency>

訪問原生客戶端

Azure Cosmos DB 向量儲存實現透過 getNativeClient() 方法提供對底層原生 Azure Cosmos DB 客戶端 (CosmosClient) 的訪問。

CosmosDBVectorStore vectorStore = context.getBean(CosmosDBVectorStore.class);
Optional<CosmosClient> nativeClient = vectorStore.getNativeClient();

if (nativeClient.isPresent()) {
    CosmosClient client = nativeClient.get();
    // Use the native client for Azure Cosmos DB-specific operations
}

原生客戶端允許您訪問 Azure Cosmos DB 特有的功能和操作,這些功能和操作可能不會透過 VectorStore 介面暴露。