S3 向量库

本节引导你设置 S3VectorStore 以存储文档嵌入并执行相似度搜索。

AWS S3 向量库 是一种无服务器的对象存储，支持大规模地存储并查询向量。

S3 向量库 API 扩展了 AWS S3 Bucket 的核心能力，让你能把 S3 当作向量数据库使用：

• 在哈希或 JSON 文档中存储向量及相关的元数据
• 检索向量
• 执行向量搜索

前置条件

1. 一个 S3 向量库 Bucket

• 如何创建 S3 Vector Bucket

1. 用于计算文档嵌入的 EmbeddingModel 实例。有多个可选方案：

• 如有需要，为 EmbeddingModel 配置一个 API 密钥，以生成 S3VectorStore 所存储的嵌入。

自动配置

Spring AI 为 S3 向量库提供 Spring Boot 自动配置。 要启用它，请将以下依赖添加到你的项目的 Maven pom.xml 文件：

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

或添加到你的 Gradle build.gradle 构建文件。

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-s3'
}

TIP

参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建文件。

TIP

参见 制品仓库 一节，把 Maven Central 和/或 Snapshot 仓库添加到你的构建文件。

请查看该向量库的配置参数 列表，了解默认值和配置选项。

此外，你还需要一个已配置的 EmbeddingModel bean。更多信息参见 EmbeddingModel 一节。

现在你可以在应用中把 S3VectorStore 作为向量库自动装配。

@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 S3 Vector Store Bucket
vectorStore.add(documents);

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

配置属性

要连接到 AWS S3 向量库并使用 S3VectorStore，你需要创建一个 S3VectorsClient 的 Bean，它必须配备正确的凭据（Credentials）和区域（Region）。

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

属性	描述	默认值
spring.ai.vectorstore.s3.index-name	存储向量的索引名	spring-ai-index
spring.ai.vectorstore.s3.vector-bucket-name	存放向量的 bucket 名	my-vector-bucket-on-aws

元数据过滤

你也可以在 S3 向量库上利用通用、可移植的元数据过滤器。

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

vectorStore.similaritySearch(SearchRequest.builder()
        .query("The World")
        .topK(TOP_K)
        .similarityThreshold(SIMILARITY_THRESHOLD)
        .filterExpression("country in ['UK', 'NL'] && year >= 2020").build());

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

FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.similaritySearch(SearchRequest.builder()
        .query("The World")
        .topK(TOP_K)
        .similarityThreshold(SIMILARITY_THRESHOLD)
        .filterExpression(b.and(
                b.in("country", "UK", "NL"),
                b.gte("year", 2020)).build()).build());

NOTE

这些（可移植的）过滤表达式会被自动转换为 AWS SDK Java V2 过滤文档对象。

例如，这个可移植的过滤表达式：

country in ['UK', 'NL'] && year >= 2020

会被转换为 S3 向量库的过滤格式：

{"$and": [{"country": {"$in": ["UK", "NL"]}}, {"year": {"$gte": 2020}}]}

基于过滤的删除

你也可以按过滤表达式删除文档：

vectorStore.delete("country in ['UK', 'NL'] && year >= 2020");

或以编程方式：

FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.delete(b.and(
        b.in("country", "UK", "NL"),
        b.gte("year", 2020)).build());

NOTE

S3 Vectors 不提供服务端过滤删除（filter-delete）API。

基于过滤的删除会列出索引中的所有向量（分页，每页 500 条），并在本地求值过滤表达式。 对于大型索引，此操作的开销与存储向量的总数成正比。

手动配置

与其使用 Spring Boot 自动配置，不如手动配置 S3 向量库。为此你需要把 spring-ai-s3-vector-store 添加到你的项目：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-s3-vector-store</artifactId>
</dependency>

或添加到你的 Gradle build.gradle 构建文件。

dependencies {
    implementation 'org.springframework.ai:spring-ai-s3-vector-store'
}

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

@Bean
VectorStore s3VectorStore(S3VectorsClient s3VectorsClient, EmbeddingModel embeddingModel) {
    S3VectorStore.Builder builder = new S3VectorStore.Builder(s3VectorsClient, embeddingModel); // Required a must
    builder.indexName(properties.getIndexName()) // Required indexName must be specified
            .vectorBucketName(properties.getVectorBucketName()) // Required vectorBucketName must be specified
            .filterExpressionConverter(yourConverter);  // Optional if you want to override default filterConverter
    return builder.build();
	}

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

访问原生客户端

S3 向量库实现提供对底层原生 S3VectorsClient 客户端的访问：

S3VectorStore vectorStore = context.getBean(S3VectorStore.class);
Optional<S3VectorsClient> nativeClient = vectorStore.getNativeClient();

if (nativeClient.isPresent()) {
    S3VectorsClient s3Client = nativeClient.get();
    // Use the native client for S3-Vector-Store-specific operations
}

原生客户端让你得以访问那些可能未通过 VectorStore 接口暴露的 S3-Vector-Store 特定功能与操作。