Azure Cosmos DB
本节将引导您设置 CosmosDBVectorStore
以存储文档嵌入并执行相似性搜索。
This section walks you through setting up CosmosDBVectorStore
to store document embeddings and perform similarity searches.
What is Azure Cosmos DB?
Azure Cosmos DB 是微软的全球分布式云原生数据库服务,专为关键任务应用程序设计。它提供高可用性、低延迟和横向扩展能力,以满足现代应用程序的需求。它从头开始构建,以全球分布、细粒度多租户和横向可伸缩性为核心。它是 Azure 中的一项基础服务,被微软大多数关键任务应用程序在全球范围内使用,包括 Teams、Skype、Xbox Live、Office 365、Bing、Azure Active Directory、Azure Portal、Microsoft Store 和许多其他服务。它也被数千个外部客户使用,包括 OpenAI 用于 ChatGPT 和其他需要弹性扩展、开箱即用全球分布以及全球低延迟和高可用性的关键任务 AI 应用程序。
Azure Cosmos DB is Microsoft’s globally distributed cloud-native database service designed for mission-critical applications. It offers high availability, low latency, and the ability to scale horizontally to meet modern application demands. It was built from the ground up with global distribution, fine-grained multi-tenancy, and horizontal scalability at its core. It is a foundational service in Azure, used by most of Microsoft’s mission critical applications at global scale, including Teams, Skype, Xbox Live, Office 365, Bing, Azure Active Directory, Azure Portal, Microsoft Store, and many others. It is also used by thousands of external customers including OpenAI for ChatGPT and other mission-critical AI applications that require elastic scale, turnkey global distribution, and low latency and high availability across the planet.
What is DiskANN?
DiskANN(基于磁盘的近似最近邻搜索)是 Azure Cosmos DB 中用于增强向量搜索性能的创新技术。它通过索引存储在 Cosmos DB 中的嵌入,实现对高维数据的有效和可伸缩的相似性搜索。
DiskANN (Disk-based Approximate Nearest Neighbor Search) is an innovative technology used in Azure Cosmos DB to enhance the performance of vector searches. It enables efficient and scalable similarity searches across high-dimensional data by indexing embeddings stored in Cosmos DB.
DiskANN 提供以下优势:
DiskANN provides the following benefits:
-
Efficiency : 通过利用基于磁盘的结构,DiskANN 与传统方法相比,显著减少了查找最近邻所需的时间。
-
Efficiency: By utilizing disk-based structures, DiskANN significantly reduces the time required to find nearest neighbors compared to traditional methods.
-
Scalability : 它可以处理超出内存容量的大型数据集,使其适用于各种应用程序,包括机器学习和人工智能驱动的解决方案。
-
Scalability: It can handle large datasets that exceed memory capacity, making it suitable for various applications, including machine learning and AI-driven solutions.
-
Low Latency : DiskANN 最大程度地减少了搜索操作期间的延迟,确保应用程序即使在大量数据的情况下也能快速检索结果。
-
Low Latency: DiskANN minimizes latency during search operations, ensuring that applications can retrieve results quickly even with substantial data volumes.
在 Spring AI for Azure Cosmos DB 的上下文中,向量搜索将创建和利用 DiskANN 索引,以确保相似性查询的最佳性能。
In the context of Spring AI for Azure Cosmos DB, vector searches will create and leverage DiskANN indexes to ensure optimal performance for similarity queries.
Setting up Azure Cosmos DB Vector Store with Auto Configuration
以下代码演示了如何使用自动配置设置 CosmosDBVectorStore
:
The following code demonstrates how to set up the CosmosDBVectorStore
with auto-configuration:
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();
}
}
Auto Configuration
Spring AI 自动配置、启动器模块的工件名称发生了重大变化。请参阅 upgrade notes 以获取更多信息。 There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the upgrade notes for more information. |
将以下依赖项添加到您的 Maven 项目中:
Add the following dependency to your Maven project:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-vector-store-azure-cosmos-db</artifactId>
</dependency>
Configuration Properties
以下配置属性可用于 Cosmos DB 向量存储:
The following configuration properties are available for the Cosmos DB vector store:
Property | Description |
---|---|
spring.ai.vectorstore.cosmosdb.databaseName |
The name of the Cosmos DB database to use. |
spring.ai.vectorstore.cosmosdb.containerName |
The name of the Cosmos DB container to use. |
spring.ai.vectorstore.cosmosdb.partitionKeyPath |
The path for the partition key. |
spring.ai.vectorstore.cosmosdb.metadataFields |
Comma-separated list of metadata fields. |
spring.ai.vectorstore.cosmosdb.vectorStoreThroughput |
The throughput for the vector store. |
spring.ai.vectorstore.cosmosdb.vectorDimensions |
The number of dimensions for the vectors. |
spring.ai.vectorstore.cosmosdb.endpoint |
The endpoint for the Cosmos DB. |
spring.ai.vectorstore.cosmosdb.key |
The key for the Cosmos DB (if key is not present, [DefaultAzureCredential]([role="bare"]https://learn.microsoft.com/azure/developer/java/sdk/authentication/credential-chains#defaultazurecredential-overview) will be used). |
Complex Searches with Filters
您可以使用 Cosmos DB 向量存储中的过滤器执行更复杂的搜索。下面是一个演示如何在搜索查询中使用过滤器的示例。
You can perform more complex searches using filters in the Cosmos DB vector store. Below is a sample demonstrating how to use filters in your search queries.
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());
Setting up Azure Cosmos DB Vector Store without Auto Configuration
以下代码演示了如何在不依赖自动配置的情况下设置 CosmosDBVectorStore
。建议使用 [DefaultAzureCredential]([role="bare"] [role="bare"]https://learn.microsoft.com/azure/developer/java/sdk/authentication/credential-chains#defaultazurecredential-overview ) 对 Azure Cosmos DB 进行身份验证。
The following code demonstrates how to set up the CosmosDBVectorStore
without relying on auto-configuration. [DefaultAzureCredential]([role="bare"]https://learn.microsoft.com/azure/developer/java/sdk/authentication/credential-chains#defaultazurecredential-overview) is recommended for authentication to 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();
}
此配置显示了所有可用的构建器选项:
This configuration shows all the available builder options:
-
databaseName
:您的 Cosmos DB 数据库的名称 -
databaseName
: The name of your Cosmos DB database -
containerName
:数据库中容器的名称 -
containerName
: The name of your container within the database -
partitionKeyPath
:分区键的路径(例如,“/id”) -
partitionKeyPath
: The path for the partition key (e.g., "/id") -
metadataFields
:将用于过滤的元数据字段列表 -
metadataFields
: List of metadata fields that will be used for filtering -
vectorStoreThroughput
:向量存储容器的吞吐量 (RU/s) -
vectorStoreThroughput
: The throughput (RU/s) for the vector store container -
vectorDimensions
:向量的维度数量(应与您的嵌入模型匹配) -
vectorDimensions
: The number of dimensions for your vectors (should match your embedding model) -
batchingStrategy
:批处理文档操作的策略(可选) -
batchingStrategy
: Strategy for batching document operations (optional)
Manual Dependency Setup
在您的 Maven 项目中添加以下依赖项:
Add the following dependency in your Maven project:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-azure-cosmos-db-store</artifactId>
</dependency>
Accessing the Native Client
Azure Cosmos DB 向量存储实现通过 getNativeClient()
方法提供对底层原生 Azure Cosmos DB 客户端 ( CosmosClient
) 的访问:
The Azure Cosmos DB Vector Store implementation provides access to the underlying native Azure Cosmos DB client (CosmosClient
) through the getNativeClient()
method:
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
接口公开。
The native client gives you access to Azure Cosmos DB-specific features and operations that might not be exposed through the VectorStore
interface.