主题
MongoDB Atlas
本节引导你把 MongoDB Atlas 设置为供 Spring AI 使用的向量库。
什么是 MongoDB Atlas？
MongoDB Atlas 是 MongoDB 的全托管云数据库，可在 AWS、Azure 和 GCP 上使用。 Atlas 支持在你的 MongoDB 文档数据上进行原生向量搜索和全文搜索。
MongoDB Atlas Vector Search 允许你把嵌入存储在 MongoDB 文档中、创建向量搜索索引，并使用近似最近邻算法（分层可导航小世界，HNSW）执行 KNN 搜索。 你可以在一个 MongoDB 聚合阶段中使用 $vectorSearch 聚合算子对向量嵌入执行搜索。
前置条件
- 一个运行 MongoDB 6.0.11、7.0.2 或更高版本的 Atlas 集群。要开始使用 MongoDB Atlas，你可以按此处 的说明操作。确保你的 IP 地址已包含在 Atlas 项目的 访问列表 中。
- 一个已启用 Vector Search 且正在运行的 MongoDB Atlas 实例
- 已配置向量搜索索引的集合
- 带有 id（字符串）、content（字符串）、metadata（文档）和 embedding（向量）字段的集合模式
- 用于索引和集合操作的恰当访问权限
自动配置
NOTE
Spring AI 的自动配置、starter 模块的制品名称发生了重大变更。 更多信息请参阅 升级说明。
Spring AI 为 MongoDB Atlas 向量库提供 Spring Boot 自动配置。 要启用它，请将以下依赖添加到你的项目的 Maven pom.xml 文件：
xml
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-vector-store-mongodb-atlas</artifactId>
</dependency>或添加到你的 Gradle build.gradle 构建文件：
groovy
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-vector-store-mongodb-atlas'
}TIP
参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建文件。
TIP
参见 制品仓库 一节，把 Maven Central 和/或 Snapshot 仓库添加到你的构建文件。
向量库实现可以为你初始化所需的模式，但你必须显式开启，方法是在 application.properties 文件中设置 spring.ai.vectorstore.mongodb.initialize-schema=true。 或者，你可以选择不进行初始化，而是使用 MongoDB Atlas UI、Atlas Administration API 或 Atlas CLI 手动创建索引；当索引需要高级映射或额外配置时，这可能很有用。
NOTE
这是一处破坏性变更！在较早的 Spring AI 版本中，此模式初始化默认进行。
请查看配置参数 列表，了解该向量库的默认值和配置选项。
此外，你还需要一个已配置的 EmbeddingModel bean。更多信息参见 EmbeddingModel 一节。
现在你可以在应用中把 MongoDBAtlasVectorStore 作为向量库自动装配：
java
@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 提供：
yaml
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 Boot 自动配置，不如手动配置 MongoDB Atlas 向量库。为此你需要把 spring-ai-mongodb-atlas-store 添加到你的项目：
xml
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mongodb-atlas-store</artifactId>
</dependency>或添加到你的 Gradle build.gradle 构建文件：
groovy
dependencies {
implementation 'org.springframework.ai:spring-ai-mongodb-atlas-store'
}创建一个 MongoTemplate bean：
java
@Bean
public MongoTemplate mongoTemplate() {
return new MongoTemplate(MongoClients.create("<mongodb atlas connection string>"), "<database name>");
}然后使用构建器模式创建 MongoDBAtlasVectorStore bean：
java
@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(OpenAiEmbeddingOptions.builder().apiKey(System.getenv("OPENAI_API_KEY")).build());
}元数据过滤
你也可以在 MongoDB Atlas 上利用通用、可移植的元数据过滤器。
例如，你可以使用文本表达式语言：
java
vectorStore.similaritySearch(SearchRequest.builder()
.query("The World")
.topK(5)
.similarityThreshold(0.7)
.filterExpression("author in ['john', 'jill'] && article_type == 'blog'").build());或以编程方式使用 Filter.Expression DSL：
java
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());NOTE
这些（可移植的）过滤表达式会被自动转换为 MongoDB Atlas 专有的过滤表达式。
例如，这个可移植的过滤表达式：
sql
author in ['john', 'jill'] && article_type == 'blog'会被转换为 MongoDB Atlas 专有的过滤格式：
json
{
"$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）的访问：
java
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 特定功能与操作。