Spring AI 实战：用 MongoDB Atlas 搭建高性能向量存储

在构建智能应用时，向量存储是实现语义搜索和推荐系统的关键组件。本文将深入讲解如何将 MongoDB Atlas 配置为 Spring AI 的向量存储，涵盖原理、配置步骤和最佳实践，帮助你在 Java 生态中快速集成向量搜索能力。

一、MongoDB Atlas：不止是文档数据库

MongoDB Atlas 是 MongoDB 官方提供的完全托管云数据库服务，支持 AWS、Azure 和 GCP。除了传统的文档存储，Atlas 还原生支持向量搜索和全文搜索，这使得它成为构建 AI 应用的理想选择。

核心能力：Atlas 向量搜索允许你将嵌入向量直接存储在 MongoDB 文档中，创建向量搜索索引，并使用 HNSW（Hierarchical Navigable Small Worlds）算法执行高效的近似最近邻搜索。你只需要在 MongoDB 聚合管道中使用 $vectorSearch 运算符即可完成搜索。

与其他向量数据库（如 Pinecone、Weaviate）相比，MongoDB Atlas 的优势在于：无需额外维护，直接利用已有的 MongoDB 基础设施；支持混合搜索，可以同时进行向量搜索和传统字段过滤；生态丰富，与 Spring AI、LangChain 等框架无缝集成。

二、先决条件：环境准备

在开始之前，请确保满足以下条件：

• Atlas 集群：运行 MongoDB 版本 6.0.11、7.0.2 或更高版本。如果还没有集群，可以按照 官方指南 快速创建免费层集群。
• 网络配置：确保你的 IP 地址已添加到 Atlas 项目的 访问列表 中，否则无法连接。
• 向量搜索索引：在目标集合上启用向量搜索，并创建合适的索引。
• 集合模式：集合必须包含以下字段：id（字符串）、content（字符串）、metadata（文档）、embedding（向量数组）。
• 权限：确保数据库用户对索引和集合具有读写权限。

⚠️ 常见坑点：很多开发者忘记配置 IP 访问列表，导致连接超时。另外，向量索引的定义必须与 embedding 字段的维度匹配（例如 OpenAI 的 text-embedding-ada-002 是 1536 维）。

三、Spring Boot 自动配置：快速集成

Spring AI 为 MongoDB Atlas 向量存储提供了开箱即用的自动配置。你只需添加依赖并配置少量参数即可使用。

3.1 添加依赖

在 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'
}

3.2 配置属性

在 application.properties 中设置以下关键属性：

Spring AI 自动配置、启动器模块的工件名称发生了重大变化。请参阅升级说明以获取更多信息。

初始化模式：Spring AI 的向量存储实现可以自动创建所需的集合和索引，但你需要显式设置 spring.ai.vectorstore.mongodb.initialize-schema=true 来启用。不过，在生产环境中，推荐手动创建索引，因为自动创建可能无法满足高级映射需求（如自定义索引类型、多字段索引等）。你可以使用 MongoDB Atlas UI、Atlas 管理 API 或 Atlas CLI 手动创建。

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

请参阅工件仓库部分，将 Maven Central 和/或快照仓库添加到您的构建文件中。

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

3.3 注入并使用向量存储

完成配置后，你可以在 Spring Bean 中直接注入 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")),

实践技巧：如果你使用 TypeScript 或 Python 开发前端应用，可以将 Spring AI 后端暴露为 REST API，前端通过 HTTP 调用向量搜索功能。对于 Go 或 Rust 等其他语言，也可以使用 MongoDB 的官方驱动直接操作向量集合。

四、最佳实践与性能优化

在实际项目中，以下经验可以帮助你避免常见问题：

• 索引设计：向量搜索索引的 numDimensions 必须与嵌入向量的维度完全一致。如果使用 OpenAI 的 embedding 模型，通常是 1536 维。
• 批量操作：插入大量文档时，使用 addAll() 方法批量插入，而不是逐条插入，可以显著提升性能。
• 混合搜索：利用 MongoDB 的聚合管道，可以在 $vectorSearch 后追加 $match、$sort 等阶段，实现向量相似度 + 传统字段过滤的混合搜索。
• 监控与调优：在 Atlas 监控面板中关注 索引使用率 和 查询延迟，如果发现搜索缓慢，可以考虑增加集群规格或优化索引。

[AFFILIATE_SLOT_1]

五、常见问题与解决方案

• 连接失败：检查 IP 访问列表、用户名密码、集群连接字符串是否正确。使用 mongosh 测试连接。
• 索引未创建：如果设置了 initialize-schema=true 但索引未自动创建，请检查集合名称和字段名是否与预期一致。
• 搜索返回空结果：确认 embedding 字段已正确填充，且索引状态为 ACTIVE（在 Atlas UI 中查看）。
• 性能不佳：考虑调整 HNSW 参数 m 和 efConstruction，或使用 exact 搜索模式进行测试。

[AFFILIATE_SLOT_2]

总结

通过本文，你了解了如何将 MongoDB Atlas 配置为 Spring AI 的向量存储，从环境准备、依赖配置到代码注入。MongoDB Atlas 向量搜索让你无需额外引入专用向量数据库，即可在现有 MongoDB 基础设施上实现高效的语义搜索。结合 Spring AI 的自动配置，你可以在几分钟内搭建一个生产级的向量搜索服务，无论是构建聊天机器人、推荐系统还是知识库搜索，都能轻松应对。