跳到主要内容

MongoDB Atlas

Deepseek 3.2 中英对照 MongoDB Atlas

本节将指导您如何设置MongoDB Atlas作为向量存储，以便与Spring AI一同使用。

什么是 MongoDB Atlas？​

MongoDB Atlas 是 MongoDB 提供的、可在 AWS、Azure 和 GCP 上使用的全托管云数据库。Atlas 支持对 MongoDB 文档数据进行原生向量搜索和全文搜索。

MongoDB Atlas Vector Search 允许您将向量嵌入存储在 MongoDB 文档中，创建向量搜索索引，并使用近似最近邻算法（分层可导航小世界）执行 KNN 搜索。您可以在 MongoDB 聚合阶段使用 $vectorSearch 聚合操作符对您的向量嵌入执行搜索。

先决条件​

  • 一个运行 MongoDB 6.0.11、7.0.2 或更高版本的 Atlas 集群。要开始使用 MongoDB Atlas，您可以按照 此处 的说明进行操作。请确保您的 IP 地址已包含在 Atlas 项目的 访问列表 中。

  • 一个已启用 Vector Search 的正在运行的 MongoDB Atlas 实例

  • 已配置向量搜索索引的集合

  • 包含 id（字符串）、content（字符串）、metadata（文档）和 embedding（向量）字段的集合模式

  • 用于索引和集合操作的正确访问权限

自动配置​

备注

Spring AI的自动配置和starter模块的artifact名称发生了显著变化。更多信息请参阅升级说明。

Spring AI为MongoDB Atlas向量存储提供了Spring Boot自动配置功能。要启用此功能，请将以下依赖项添加到项目的Maven pom.xml文件中：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-mongodb-atlas</artifactId>
</dependency>

或添加到您的 Gradle build.gradle 构建文件中：

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-mongodb-atlas'
}
提示

请参阅 依赖管理 章节，将 Spring AI BOM 添加到您的构建文件中。

:::提示
请参考 Artifact 仓库 部分，将 Maven Central 和/或 Snapshot 仓库添加到你的构建文件中。
:::

向量存储实现可以为您初始化必要的模式，但您必须通过在application.properties文件中设置spring.ai.vectorstore.mongodb.initialize-schema=true来选择启用。或者，您可以选择不进行初始化，并使用 MongoDB Atlas UI、Atlas 管理 API 或 Atlas CLI 手动创建索引，这在索引需要高级映射或额外配置时非常有用。

备注

这是一个破坏性变更！在 Spring AI 的早期版本中，此模式初始化默认会自动执行。

请查看向量存储的配置参数列表，了解其默认值与配置选项。

此外，您还需要一个配置好的 EmbeddingModel 实例。更多信息请参阅 EmbeddingModel 章节。

现在你可以在应用程序中自动装配 MongoDBAtlasVectorStore 作为向量存储：

@Autowired VectorStore vectorStore;

// ...

List<Document> documents = List.of(
    new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
    new Document("The World is Big and Salvation Lurks Around the Corner"),
    new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));

// Add the documents to MongoDB Atlas
vectorStore.add(documents);

// Retrieve documents similar to a query
List<Document> results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());

配置属性​

要连接到 MongoDB Atlas 并使用 MongoDBAtlasVectorStore，你需要提供实例的访问信息。可以通过 Spring Boot 的 application.yml 提供一个简单的配置：

spring:
  data:
    mongodb:
      uri: <mongodb atlas connection string>
      database: <database name>
  ai:
    vectorstore:
      mongodb:
        initialize-schema: true
        collection-name: custom_vector_store
        index-name: custom_vector_index
        path-name: custom_embedding
        metadata-fields-to-filter: author,year

以 spring.ai.vectorstore.mongodb.* 开头的属性用于配置 MongoDBAtlasVectorStore：

属性描述默认值
spring.ai.vectorstore.mongodb.initialize-schema是否初始化所需架构false
spring.ai.vectorstore.mongodb.collection-name用于存储向量的集合名称vector_store
spring.ai.vectorstore.mongodb.index-name向量搜索索引的名称vector_index
spring.ai.vectorstore.mongodb.path-name向量存储的路径embedding
spring.ai.vectorstore.mongodb.metadata-fields-to-filter可用于筛选的元数据字段列表，以逗号分隔空列表

手动配置​

如果不使用 Spring Boot 的自动配置，你也可以手动配置 MongoDB Atlas 向量存储。为此，你需要将 spring-ai-mongodb-atlas-store 添加到你的项目中：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mongodb-atlas-store</artifactId>
</dependency>

或添加到您的 Gradle build.gradle 构建文件中：

dependencies {
    implementation 'org.springframework.ai:spring-ai-mongodb-atlas-store'
}

创建 MongoTemplate 的 Bean：

@Bean
public MongoTemplate mongoTemplate() {
    return new MongoTemplate(MongoClients.create("<mongodb atlas connection string>"), "<database name>");
}

然后使用构建器模式创建 MongoDBAtlasVectorStore bean：

@Bean
public VectorStore vectorStore(MongoTemplate mongoTemplate, EmbeddingModel embeddingModel) {
    return MongoDBAtlasVectorStore.builder(mongoTemplate, embeddingModel)
        .collectionName("custom_vector_store")           // Optional: defaults to "vector_store"
        .vectorIndexName("custom_vector_index")          // Optional: defaults to "vector_index"
        .pathName("custom_embedding")                    // Optional: defaults to "embedding"
        .numCandidates(500)                             // Optional: defaults to 200
        .metadataFieldsToFilter(List.of("author", "year")) // Optional: defaults to empty list
        .initializeSchema(true)                         // Optional: defaults to false
        .batchingStrategy(new TokenCountBatchingStrategy()) // Optional: defaults to TokenCountBatchingStrategy
        .build();
}

// This can be any EmbeddingModel implementation
@Bean
public EmbeddingModel embeddingModel() {
    return new OpenAiEmbeddingModel(new OpenAiApi(System.getenv("OPENAI_API_KEY")));
}

元数据过滤​

你也可以在MongoDB Atlas中使用通用的、可移植的元数据过滤器。

例如，你可以使用文本表达式语言：

vectorStore.similaritySearch(SearchRequest.builder()
        .query("The World")
        .topK(5)
        .similarityThreshold(0.7)
        .filterExpression("author in ['john', 'jill'] && article_type == 'blog'").build());

或者以编程方式使用 Filter.Expression DSL：

FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.similaritySearch(SearchRequest.builder()
        .query("The World")
        .topK(5)
        .similarityThreshold(0.7)
        .filterExpression(b.and(
                b.in("author", "john", "jill"),
                b.eq("article_type", "blog")).build()).build());
备注

这些（可移植的）过滤表达式会自动转换为专有的 MongoDB Atlas 过滤表达式。

例如，这个便携式过滤器表达式：

author in ['john', 'jill'] && article_type == 'blog'

会转换为专有的 MongoDB Atlas 过滤器格式：

{
  "$and": [
    {
      "$or": [
        { "metadata.author": "john" },
        { "metadata.author": "jill" }
      ]
    },
    {
      "metadata.article_type": "blog"
    }
  ]
}

教程和代码示例​

要开始使用 Spring AI 和 MongoDB：

访问原生客户端​

MongoDB Atlas 向量存储实现通过 getNativeClient() 方法提供了对底层原生 MongoDB 客户端 (MongoClient) 的访问权限：

MongoDBAtlasVectorStore vectorStore = context.getBean(MongoDBAtlasVectorStore.class);
Optional<MongoClient> nativeClient = vectorStore.getNativeClient();

if (nativeClient.isPresent()) {
    MongoClient client = nativeClient.get();
    // Use the native client for MongoDB-specific operations
}

原生客户端让您能够访问可能未通过VectorStore接口公开的MongoDB特有功能与操作。