Docs 菜单
Docs 主页
/
MongoDB 阿特拉斯
/ /

开始使用 Spring AI 集成

在此页面上

  • 背景
  • 先决条件
  • 设置环境
  • 创建 Atlas Vector Search 索引
  • 使用 Atlas 作为向量存储
  • 存储自定义数据并运行语义搜索查询
  • 后续步骤

您可以将 Atlas Vector Search 与 Spring AI 集成 使用 MongoDB Java Sync Driver 构建生成式 AI 应用程序。本教程演示如何开始使用 Atlas Vector Search 作为 Spring AI 的向量存储,然后演示如何对数据执行语义搜索。

具体来说,您需要执行以下操作:

  1. 设置环境。

  2. 创建 Atlas Vector Search 索引。

  3. 在 Atlas 上存储向量嵌入数据。

  4. 对数据运行语义搜索查询。

提示

已完成的示例应用程序

要下载本教程演示的应用程序的完整版本,请参阅“后续步骤”部分。

Spring AI 是一个来自 Spring 的应用程序框架 允许您将各种 AI 服务和插件与您的应用程序相结合。您可以将 Spring AI 用于各种基于文本的 AI 使用案例。

您可以将 Atlas 用作向量数据库,并使用 Atlas Vector Search 从数据中检索语义相似的文档来实施 RAG 。要了解有关RAG的更多信息,请参阅使用 Atlas Vector Search 进行检索增强生成 (RAG)。

如要完成本教程,您必须具备以下条件:

  • 运行 MongoDB 6版本的 Atlas 集群。 0 。 11 、 7 。 0 。 2或更高版本。确保您的IP 地址包含在 Atlas 项目的访问列表中。

  • OpenAI API 密钥。您必须拥有一个 OpenAI 付费帐户,并有可用于 API 请求的积分。要了解有关注册 OpenAI 帐户的更多信息,请参阅 OpenAI API 网站。

  • 设置和运行 Java 应用程序的环境。我们建议您使用集成开发环境 (IDE),例如 IntelliJ IDEA Eclipse IDE 配置 Maven 来构建和运行项目。

您必须首先设置本教程的环境,包括添加必要的依赖项和设置配置属性。

1

导航到 Spring Initializr 并使用以下设置配置项目:

  • 项目: Maven

  • 语言: Java

  • Spring Boot:您可以使用所选的默认版本。

  • 项目元数据:

    • Java: 21

    • 您可以为所有其他字段使用默认值。

在 Spring Initializr 右侧,单击ADD DEPENDENCIES ,然后搜索并添加以下依赖项:

  • MongoDB Atlas Vector Database

  • Spring Data MongoDB

最后,单击GENERATE下载 Spring 项目的压缩版本。解压缩文件并在 IDE 中打开。

2
  1. Spring AI 为 Atlas Vector Search 提供了 Spring Boot 自动配置。

    将以下依赖项添加到项目的pom.xml文件中的 dependencies数组中。这些依赖项将 Spring AI 和自动配置库添加到您的应用程序中:

    <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    </dependency>
    <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-spring-boot-autoconfigure</artifactId>
    </dependency>
    <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
  2. 接下来,确保您的pom.xml文件包含 Spring AI 物料清单 (BOM) 的dependencyManagement条目。

    重要

    将用于 Spring AI BOM 的spring-ai.version常量设置为1.0.0-SNAPSHOT ,以将最新的 Spring AI 功能实现到您的应用程序中。

    要了解有关 Spring AI BOM 的更多信息,请参阅 依赖项管理 Spring AI 文档的 部分。

  3. 最后,将 Spring AI Snapshot 存储库添加到pom.xml文件的repositories条目中:

    <repository>
    <id>spring-snapshots</id>
    <name>Spring Snapshots</name>
    <url>https://repo.spring.io/snapshot</url>
    <releases>
    <enabled>false</enabled>
    </releases>
    </repository>

    要了解有关这些存储库的更多信息,请参阅 添加里程碑和快照存储库 Spring AI 文档的 部分。

    完成pom.xml文件的编辑后,重新加载项目以确保依赖项已安装。

3

找到src/main/resources/application.properties文件,并将该文件的内容替换为以下属性。将占位符替换为您的 OpenAI API 密钥和 Atlas 连接字符串:

spring.application.name=springai-mongodb
spring.ai.openai.api-key=<OpenAI API Key>
spring.ai.openai.embedding.options.model=text-embedding-ada-002
spring.data.mongodb.uri=<connection string>
spring.data.mongodb.database=springai_test
spring.ai.vectorstore.mongodb.indexName=vector_index
spring.ai.vectorstore.mongodb.collection-name=vector_store

注意

连接字符串应使用以下格式:

mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.net/?<settings>

要了解有关检索连接字符串的更多信息,请参阅Atlas 入门教程。

要在向量存储上启用向量搜索查询,必须在springai_test.vector_store集合上创建 Atlas Vector Search 索引。

注意

必需的访问权限

要创建 Atlas Vector Search 索引,您必须对 Atlas 项目具有Project Data Access Admin或更高访问权限。

1

当您将 Atlas 配置为应用程序中的向量存储时,Spring AI 可以自动初始化后端模式。此初始化包括在包含向量嵌入的集合上创建 Atlas Vector Search 索引。您可以通过将以下设置添加到application.properties文件来启用模式初始化:

spring.ai.vectorstore.mongodb.initialize-schema=true

指定initialize-schema=true会导致 Spring AI 以编程方式在集群上创建 Atlas Vector Search 索引。因此,您必须将应用程序连接到专用集群。如果您运行的是免费或共享层集群,则必须通过 Atlas 用户界面、Atlas 管理 API 或 Atlas CLI 单独创建索引。

要了解更多信息,请参阅创建 Atlas Vector Search 索引。

注意

已知问题:现有索引

如果springai_test.vector_store集合上已有名为vector_index的 Atlas Vector Search 索引,则 Spring AI 不会创建额外的索引。因此,如果现有索引配置了不兼容的设置(例如不同的维度数),您可能会在本教程的后面遇到错误。

确保索引具有以下配置:

{
"fields": [
{
"numDimensions": 1536,
"path": "embedding",
"similarity": "cosine",
"type": "vector"
}
]
}

本部分演示如何将 Atlas 配置为向量数据库(也称为向量存储),以便您可以存储自定义数据的向量嵌入。

在项目中找到src/main/java/com/example/demo/DemoApplication.java文件。在与此文件同一级别,创建一个名为config的目录,然后在此目录中创建一个名为Config.java的文件以设置您的 Spring App 配置。

以下步骤演示如何创建准备向量存储所需的Bean对象。

1

将以下代码粘贴到Config.java文件中以导入必要的类:

import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.ai.openai.OpenAiEmbeddingModel;
import org.springframework.ai.openai.api.OpenAiApi;
import org.springframework.ai.vectorstore.MongoDBAtlasVectorStore;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringBootConfiguration;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.mongodb.core.MongoTemplate;
2

将以下代码粘贴到Config.java文件中,以引用您在应用程序属性文件中设置的值:

@Configuration
@SpringBootConfiguration
@EnableAutoConfiguration
public class Config {
@Value("${spring.ai.openai.api-key}")
private String openAiKey;
@Value("${spring.data.mongodb.database}")
private String databaseName;
@Value("${spring.ai.vectorstore.mongodb.collection-name:vector_store}")
private String collectionName;
@Value("${spring.ai.vectorstore.mongodb.indexName:vector_index}")
private String indexName;
@Value("${spring.data.mongodb.uri}")
private String mongoUri;
@Value("${spring.ai.vectorstore.mongodb.initialize-schema}")
private Boolean initSchema;
// Add beans here...
}
3

接下来,粘贴以下代码以生成OpenAiEmbeddingModel实例,该实例使用 OpenAI API 创建向量嵌入:

@Bean
public EmbeddingModel embeddingModel() {
return new OpenAiEmbeddingModel(new OpenAiApi(openAiKey));
}
4

最后,粘贴以下代码以创建返回VectorStore实例的 Bean。 VectorStore实例使用与您的部署相对应的MongoTemplate以及在上一步中创建的OpenAiEmbeddingModel

@Bean
public VectorStore mongodbVectorStore(MongoTemplate mongoTemplate, EmbeddingModel embeddingModel) {
return new MongoDBAtlasVectorStore(mongoTemplate, embeddingModel,
MongoDBAtlasVectorStore.MongoDBVectorStoreConfig.builder().build(), initSchema);
}

在本节中,您可以了解如何在 Java 应用程序中创建端点,以将自定义数据的向量嵌入存储在 Atlas 中,然后对该数据运行语义搜索查询。

在与config文件夹同一级别,创建一个controller文件夹,然后创建一个Controller.java文件以设置 API 端点。以下步骤演示如何创建GET端点以将数据添加到向量存储中,并使用similaritySearch()方法运行语义搜索查询。

1

将以下代码粘贴到Controller.java文件中以导入必要的类:

import org.springframework.ai.document.Document;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
2

粘贴以下代码以执行以下任务:

  • 注释Controller类以将其标记为应用程序控制器。

  • 创建映射以将请求映射到/tutorial路径。

  • 自动装配VectorStore bean。

@RestController
@RequestMapping("/tutorial")
public class Controller {
@Autowired
private VectorStore vectorStore;
// Add endpoints here...
}
3

将以下代码粘贴到控制器中以创建一个GET端点,该端点创建样本文档并将它们作为向量嵌入保存到向量存储中:

@GetMapping("/add")
public String addDocuments() {
List<Document> docs = List.of(
new Document("Proper tuber planting involves site selection, proper timing, and exceptional care. Choose spots with well-drained soil and adequate sun exposure. Tubers are generally planted in spring, but depending on the plant, timing varies. Always plant with the eyes facing upward at a depth two to three times the tuber's height. Ensure 4 inch spacing between small tubers, expand to 12 inches for large ones. Adequate moisture is needed, yet do not overwater. Mulching can help preserve moisture and prevent weed growth.", Map.of("author", "A", "type","post")),
new Document("Successful oil painting necessitates patience, proper equipment, and technique. Begin with a carefully prepared, primed canvas. Sketch your composition lightly before applying paint. Use high-quality brushes and oils to create vibrant, long-lasting artworks. Remember to paint 'fat over lean,' meaning each subsequent layer should contain more oil to prevent cracking. Allow each layer to dry before applying another. Clean your brushes often and avoid solvents that might damage them. Finally, always work in a well-ventilated space.", Map.of("author", "A")),
new Document("For a natural lawn, selection of the right grass type suitable for your climate is crucial. Balanced watering, generally 1 to 1.5 inches per week, is important; overwatering invites disease. Opt for organic fertilizers over synthetic versions to provide necessary nutrients and improve soil structure. Regular lawn aeration helps root growth and prevents soil compaction. Practice natural pest control and consider overseeding to maintain a dense sward, which naturally combats weeds and pest.", Map.of("author", "B", "type","post"))
);
vectorStore.add(docs);
return "Documents added successfully!\n";
}
4

将以下代码粘贴到控制器中以创建GET端点,该端点对短语"learn how to grow things"执行语义搜索查询并返回两个最相关的结果:

1@GetMapping("/search")
2public List<Map<String, Object>> searchDocuments() {
3
4 List<Document> results = vectorStore.similaritySearch(
5 SearchRequest
6 .query("learn how to grow things")
7 .withTopK(2)
8 );
9
10 return results.stream().map(doc -> Map.of(
11 "content", doc.getContent(),
12 "metadata", doc.getMetadata()
13 )).collect(Collectors.toList());
14}
5

要使用元数据筛选来执行搜索,可以使用 Java Sync 驱动程序中的Filter.Expression构建器类。

您可以使用MQL匹配表达式来预过滤文档。此示例筛选author字段值为"A"的文档。然后,它对短语"learn how to grow things"执行语义搜索查询。

在前面步骤中定义的searchDocuments()方法主体中,将调用similaritySearch()方法的代码(前面区块中的4 - 8行)替换为以下代码:

FilterExpressionBuilder b = new FilterExpressionBuilder();
List<Document> results = vectorStore.similaritySearch(
SearchRequest.defaults()
.withQuery("learn how to grow things")
.withTopK(2)
.withSimilarityThreshold(0.5)
.withFilterExpression(b.eq("author", "A").build())
);

注意

您必须将元数据字段的路径添加到 Atlas Vector Search 索引中。要了解更多信息,请参阅“如何为向量搜索的字段进行索引”教程的关于filter类型部分。

要了解有关元数据预过滤的更多信息,请参阅Atlas Vector Search 预过滤。

运行应用程序后,您可以访问端点以首先将文档添加到向量存储中,然后执行语义搜索查询。

1

使用 IDE 工具构建并运行应用程序。如果使用默认设置,应用程序则在本地端口8080上运行。

2

确认应用程序正在运行后,在终端中运行以下命令以访问add端点,该端点会将样本数据转换为向量嵌入并将嵌入插入 Atlas:

curl -X GET http://localhost:8080/tutorial/add

提示

访问端点后,您可以导航到集群中的springai_test.vector_store集合,在 Atlas 用户界面中查看向量嵌入。

然后,在终端中运行以下命令以访问search端点以执行语义搜索:

curl -X GET http://localhost:8080/tutorial/search

您可以查看并下载 此应用的完整版本 来自 GitHub。您可以使用完整的应用程序对自己的应用程序进行故障排除或快速测试功能。

MongoDB 还提供以下开发者资源:

后退

干草堆

来年

Amazon 基岩版