Azure Cosmos DB 向量数据库

Azure Cosmos DB NoSQL 向量数据库

Spring AI 支持使用 Azure Cosmos DB for NoSQL 作为向量数据库，通过其向量嵌入和索引功能。

先决条件

1. Azure 账户：您需要一个拥有有效订阅的 Azure 账户。
2. Azure Cosmos DB for NoSQL 资源：在您的 Azure 账户中创建一个 Azure Cosmos DB for NoSQL 账户。
   • 在创建过程中，请确保选择”NoSQL” API。
   • 记下您的 Cosmos DB 端点和主密钥，因为在应用程序配置中将会用到它们。
3. 向量嵌入功能：目前，Azure Cosmos DB for NoSQL 中的向量搜索功能处于预览阶段。您需要按照这些说明注册预览版。

添加依赖

将 spring-ai-azure-cosmos-db-store-spring-boot-starter 依赖项添加到您的 pom.xml 文件中：

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

您还需要一个 EmbeddingClient 实现来为您的文档生成向量嵌入。例如，您可以添加 spring-ai-openai-spring-boot-starter 以使用 OpenAI 的嵌入模型：

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

配置属性

在您的 application.properties 或 application.yml 文件中配置 Azure Cosmos DB 和嵌入客户端属性。

Azure Cosmos DB 属性

# Azure Cosmos DB 配置
spring.ai.vectorstore.cosmosdb.endpoint=YOUR_COSMOS_DB_ENDPOINT # 例如 https://your-account.documents.azure.com:443/
spring.ai.vectorstore.cosmosdb.key=YOUR_COSMOS_DB_PRIMARY_KEY
spring.ai.vectorstore.cosmosdb.database-name=your_database_name
spring.ai.vectorstore.cosmosdb.container-name=your_container_name # 将在其中存储向量的容器
spring.ai.vectorstore.cosmosdb.create-container-if-not-exists=true # 如果容器不存在则创建 (可选, 默认为 false)

# 向量索引策略 (在容器创建时应用)
spring.ai.vectorstore.cosmosdb.indexing-policy.vector-indexes[0].path="/embedding" # JSON 文档中包含向量的路径
spring.ai.vectorstore.cosmosdb.indexing-policy.vector-indexes[0].type="vector-ivf" # 索引类型，例如 vector-ivf, vector-hnsw
spring.ai.vectorstore.cosmosdb.indexing-policy.vector-indexes[0].num-lists=1 # 对于 IVF (默认为 1)
spring.ai.vectorstore.cosmosdb.indexing-policy.vector-indexes[0].dimensions=1536 # 嵌入向量的维度 (例如 OpenAI text-embedding-ada-002 为 1536)
spring.ai.vectorstore.cosmosdb.indexing-policy.vector-indexes[0].distance-function="cosine" # 距离函数，例如 cosine, euclidean, dotproduct

如果 create-container-if-not-exists 设置为 true，则当容器尚不存在时，将使用提供的 indexing-policy 创建它。 如果容器已存在，则现有索引策略将保持不变，并且提供的 indexing-policy 配置将被忽略。 确保嵌入客户端输出的维度与索引策略中配置的 dimensions 匹配。

嵌入客户端属性 (例如 OpenAI)

# OpenAI EmbeddingClient 配置
spring.ai.openai.api-key=YOUR_OPENAI_API_KEY
spring.ai.openai.embedding.options.model=text-embedding-ada-002

使用 VectorStore

将 VectorStore bean 注入到您的组件中以与之交互：

import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.ai.document.Document;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class MyVectorStoreService {

    private final VectorStore vectorStore;

    @Autowired
    public MyVectorStoreService(VectorStore vectorStore) {
        this.vectorStore = vectorStore;
    }

    public void addDocuments(List<Document> documents) {
        vectorStore.add(documents);
    }

    public List<Document> findSimilarDocuments(String query, int k) {
        return vectorStore.similaritySearch(query, k);
    }
}

创建 CosmosDBVectorStore Bean (可选)

Spring Boot 会自动配置 CosmosDBVectorStore bean。但是，如果您需要自定义配置，可以定义自己的 bean：

import com.azure.cosmos.CosmosAsyncClient;
import com.azure.cosmos.CosmosClientBuilder;
import org.springframework.ai.embedding.EmbeddingClient;
import org.springframework.ai.vectorstore.azure.cosmosdb.CosmosDBVectorStore;
import org.springframework.ai.vectorstore.azure.cosmosdb.CosmosDBVectorStoreConfig;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MyCosmosDbConfig {

    @Bean
    public CosmosAsyncClient cosmosAsyncClient() {
        // 从属性或直接创建 CosmosAsyncClient
        return new CosmosClientBuilder()
            .endpoint("YOUR_COSMOS_DB_ENDPOINT")
            .key("YOUR_COSMOS_DB_PRIMARY_KEY")
            .buildAsyncClient();
    }

    @Bean
    public CosmosDBVectorStore cosmosDBVectorStore(CosmosAsyncClient cosmosAsyncClient, EmbeddingClient embeddingClient) {
        CosmosDBVectorStoreConfig config = CosmosDBVectorStoreConfig.builder("your_database_name", "your_container_name")
            // .createContainerIfNotExists(true) // 按需设置
            // .indexingPolicy(...) // 按需设置索引策略
            .build();
        return new CosmosDBVectorStore(cosmosAsyncClient, embeddingClient, config);
    }
}

向量索引

Azure Cosmos DB for NoSQL 支持多种类型的向量索引，例如 vector-ivf 和 vector-hnsw。索引的选择取决于您的特定用例和性能要求。

• vector-ivf (Inverted File Index)：适用于大型数据集，并在准确性和查询速度之间提供良好的平衡。它将向量空间划分为簇，并在查询时仅搜索最相关的簇。
• vector-hnsw (Hierarchical Navigable Small World)：一种基于图的索引，以其高查询召回率和低延迟而闻名，尤其适用于高维数据。

您可以在 application.properties 中的 spring.ai.vectorstore.cosmosdb.indexing-policy.vector-indexes 下或在以编程方式配置 CosmosDBVectorStoreConfig 时配置索引类型、维度、距离函数和特定于类型的参数 (例如 num-lists for IVF)。

// 示例索引策略 JSON
{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    {
      "path": "/*"
    }
  ],
  "excludedPaths": [
    {
      "path": "/\"_etag\"/?"
    }
  ],
  "vectorIndexes": [
    {
      "path": "/embedding", // 确保这与您的文档结构匹配
      "type": "vector-ivf",
      "numLists": 1,
      "dimensions": 1536,
      "distanceFunction": "cosine"
    }
  ]
}

有关向量索引的更多详细信息，请参阅 Azure Cosmos DB for NoSQL 向量索引文档。

元数据过滤

Cosmos DB 向量存储支持使用 SQL WHERE子句 和 相似性搜索过滤器表达式 进行元数据过滤。这些过滤器应用于相似性搜索查询期间，以根据其元数据字段缩小结果范围。

过滤器表达式直接转换为 Cosmos DB SQL WHERE 子句。

例如，如果您有带有元数据字段 genre 和 year 的文档，则可以按如下方式进行过滤：

import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.filter.Filter;
import org.springframework.ai.vectorstore.filter.FilterExpressionBuilder;

// ...

FilterExpressionBuilder b = new FilterExpressionBuilder();

// WHERE genre = 'drama' AND year > 2020
Filter filter = new Filter(b.eq("genre", "drama").and(b.gt("year", 2020)).build());

SearchRequest request = SearchRequest.query("A tragic hero") // 示例查询通常保留英文
    .withTopK(5)
    .withSimilarityThreshold(0.75)
    .withFilter(filter);

List<Document> results = vectorStore.similaritySearch(request);

这将转换为类似于以下的 Cosmos DB 查询：

SELECT c.id, c.content, c.metadata, VectorDistance(c.embedding, @embeddingParam) AS similarity
FROM c
WHERE c.metadata.genre = 'drama' AND c.metadata.year > 2020
ORDER BY VectorDistance(c.embedding, @embeddingParam)

确保您的容器中存在用于过滤的元数据字段，并且它们已正确索引 (如果需要提高性能)。 并非所有 Spring AI 过滤器表达式操作符都直接映射到 Cosmos DB SQL 函数。支持基本比较 (EQ, NE, GT, GTE, LT, LTE)、逻辑运算符 (AND, OR, NOT) 和 IN / NIN。

删除数据

CosmosDBVectorStore 支持通过文档 ID 删除数据。

boolean deleted = vectorStore.delete(List.of("documentId1", "documentId2"));

总结

通过将 Spring AI 与 Azure Cosmos DB for NoSQL 集成，您可以利用 Azure 的可扩展且全球分布的数据库服务来满足您的向量存储需求，并结合 Spring AI 的简化抽象来构建强大的 AI 应用程序。

文档有误？请协助编辑

发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！