MongoDB Atlas

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

本节将指导你设置 MongoDB Atlas 作为向量存储并与 Spring AI 集成使用。

MongoDB Atlas 是什么？

MongoDB Atlas 是 MongoDB 提供的全托管云数据库服务，支持在 AWS、Azure 和 GCP 平台部署。Atlas 提供对 MongoDB 文档数据的原生向量搜索和全文检索功能。

MongoDB Atlas 向量搜索支持：

将嵌入向量存储在 MongoDB 文档中
创建向量搜索索引
使用近似最近邻算法（HNSW）执行 KNN 搜索
通过 $vectorSearch 聚合操作符对向量嵌入执行搜索

先决条件

运行 MongoDB 6.0.11、7.0.2 或更高版本的 Atlas 集群。要开始使用 MongoDB Atlas，可按照此处的说明操作。确保你的 IP 地址已包含在 Atlas 项目的访问列表中。
启用了向量搜索功能的 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 和/或快照仓库添加到你的构建文件中。

向量存储实现可自动初始化所需 Schema，但需在 application.properties 文件中设置 spring.ai.vectorstore.mongodb.initialize-schema=true 显式启用。也可选择手动初始化：通过 MongoDB Atlas 界面、Atlas 管理 API 或 Atlas CLI 创建索引，适用于需要高级映射或额外配置的场景。

注意：此为破坏性变更！旧版 Spring AI 中 Schema 初始化默认为自动执行。

请查看向量存储的配置参数列表以了解默认值及可配置选项。

此外，你需要一个配置好的 EmbeddingModel Bean。详情请参阅 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`	可用于过滤的元数据字段列表（以逗号分隔）。	empty list

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

可用于过滤的元数据字段列表（以逗号分隔）。

empty list

手动配置

若不使用 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>");
}

随后通过 Builder 模式创建 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：

参阅 Spring AI 集成入门指南。
有关使用 Spring AI 和 MongoDB 演示检索增强生成（RAG）的综合代码示例，请参阅本详细教程。

访问原生客户端

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
}

原生客户端可访问 MongoDB 特有功能及操作，这些可能未通过 VectorStore 接口暴露。