Azure Cosmos DB

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

本节将指导你配置 CosmosDBVectorStore 以存储文档向量并执行相似性搜索。

Azure Cosmos DB 是什么？

Azure Cosmos DB 是微软推出的全球分布式云原生数据库服务，专为关键业务应用设计，具有高可用性、低延迟及水平扩展能力。其核心架构从零构建，原生支持全球分布、细粒度多租户和水平扩展。作为 Azure 基础服务，已被微软大多数全球级关键业务采用，包括 Teams、Skype、Xbox Live、Office 365、Bing、Azure Active Directory、Azure 门户、Microsoft Store 等。同时服务数千外部客户，包括 OpenAI 的 ChatGPT 及其他需要弹性扩展、开箱即用全球分布、跨洲际低延迟与高可用的关键 AI 应用。

DiskANN 是什么？

基于磁盘的近似最近邻搜索（Disk-based Approximate Nearest Neighbor Search，DiskANN）是 Azure Cosmos DB 中用于增强向量搜索性能的创新技术。它通过对 Cosmos DB 中存储的向量建立索引，实现高效可扩展的高维数据相似性搜索。

DiskANN 具有以下优势：

高效性：相比传统方法，DiskANN 通过基于磁盘的结构显著缩短最近邻搜索时间。
可扩展性：支持处理超出内存容量的大规模数据集，适用于机器学习及 AI 驱动型解决方案等场景。
低延迟：优化搜索操作延迟，确保应用即使在海量数据下仍能快速获取结果。

在 Spring AI 的 Azure Cosmos DB 集成中，向量搜索将创建并利用 DiskANN 索引，以确保相似性查询的最佳性能。

通过自动配置建立 Azure Cosmos DB 向量存储

以下代码演示如何通过自动配置建立 CosmosDBVectorStore：

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	分区 Key 路径。
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）。

属性

说明

spring.ai.vectorstore.cosmosdb.databaseName

使用的 Cosmos DB 数据库名称。

spring.ai.vectorstore.cosmosdb.containerName

使用的 Cosmos DB 容器名称。

spring.ai.vectorstore.cosmosdb.partitionKeyPath

分区 Key 路径。

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）。

带过滤器的复杂搜索

可在 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 进行 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();
}

此配置展示所有可用的构建器（Builder）选项：

databaseName：Cosmos DB 数据库名称
containerName：数据库内的容器名称
partitionKeyPath：分区 Key 路径（例如 "/id"）
metadataFields：用于过滤的元数据字段列表
vectorStoreThroughput：向量存储容器的吞吐量（RU/秒）
vectorDimensions：向量的维度数（需与嵌入模型匹配）
batchingStrategy：文档批量操作策略（可选）

手动依赖配置

将以下依赖添加至 Maven 项目：

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

访问原生客户端

Azure Cosmos DB 向量存储实现通过 getNativeClient() 方法提供对底层原生客户端（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 接口暴露。