跳到主要内容

Amazon S3 Vectors

Amazon S3 Vectors Embedding Store 与 Amazon S3 Vectors 集成。这是 Amazon S3 中专为大规模存储与查询向量 embedding 而设计的向量存储能力。

Maven 依赖​

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-community-s3-vectors</artifactId>
    <version>${latest version here}</version>
</dependency>

API​

  • S3VectorsEmbeddingStore

功能​

  • 存储带元数据的 embedding
  • 使用余弦或欧氏距离进行向量相似度搜索
  • 按元数据字段过滤搜索结果
  • 首次插入 embedding 时自动创建索引
  • 支持标准 AWS 凭证提供程序

用法​

基本配置​

S3VectorsEmbeddingStore embeddingStore = S3VectorsEmbeddingStore.builder()
    .vectorBucketName("my-vector-bucket")       // S3 Vectors bucket name (required)
    .indexName("my-index")                       // Index name within the bucket (required)
    .region("us-west-2")                         // AWS region (default: us-east-1)
    .distanceMetric(DistanceMetric.COSINE)       // Distance metric (default: COSINE)
    .createIndexIfNotExists(true)                // Auto-create index (default: true)
    .timeout(Duration.ofSeconds(60))             // API call timeout (default: 30 seconds)
    .credentialsProvider(myCredentialsProvider)  // Custom AWS credentials
    .build();

使用已有的 S3VectorsClient​

如果你已经配置好了 S3VectorsClient，可以直接将其传给构建器：

S3VectorsClient customClient = S3VectorsClient.builder()
    .region(Region.US_WEST_2)
    .credentialsProvider(myCredentialsProvider)
    .build();

S3VectorsEmbeddingStore embeddingStore = S3VectorsEmbeddingStore.builder()
    .s3VectorsClient(customClient)
    .vectorBucketName("my-vector-bucket")
    .indexName("my-index")
    .build();

距离度量​

S3 Vectors embedding store 支持两种距离度量。距离值会自动转换为 [0, 1] 范围内的相关性分数，其中 1 表示最相关的匹配。

余弦距离（默认）​

适用于： 文本 embedding、语义相似度搜索

  • 测量向量之间夹角的余弦
  • 转换为相关性分数：score = (1 - distance + 1) / 2
  • 结果与向量模长无关
.distanceMetric(DistanceMetric.COSINE)  // Default, recommended for text embeddings

欧氏距离​

适用于： 方向和模长都很重要的场景

  • 测量向量之间的直线距离
  • 范围：[0, ∞)
  • 转换为相关性分数：score = 1 / (1 + distance)
.distanceMetric(DistanceMetric.EUCLIDEAN)

过滤​

S3 Vectors embedding store 支持按元数据字段过滤搜索结果。

支持的过滤操作​

  • isEqualTo：等于比较
  • isNotEqualTo：不等于比较
  • isGreaterThan：大于比较
  • isGreaterThanOrEqualTo：大于等于比较
  • isLessThan：小于比较
  • isLessThanOrEqualTo：小于等于比较
  • isIn：IN 操作符（多个值）
  • isNotIn：NOT IN 操作符
  • And：逻辑与
  • Or：逻辑或
  • Not：逻辑非

实现细节​

凭证​

默认情况下，该 store 使用 DefaultCredentialsProvider，遵循标准 AWS 凭证解析链（环境变量、系统属性、凭证文件、EC2 实例配置文件等）。你可以通过构建器提供自定义的 AwsCredentialsProvider。

索引创建​

当 createIndexIfNotExists 设为 true（默认）时，索引会在首次插入 embedding 时自动创建。索引维度和距离度量会根据添加的第一个 embedding 以及配置的距离度量进行设置。

资源清理​

S3VectorsEmbeddingStore 实现了 AutoCloseable。使用完毕后，调用 close() 释放底层 S3VectorsClient 资源，或使用 try-with-resources。

限制​

  • 最大结果数：S3 Vectors 将每次查询的搜索结果限制为 100（topK 范围：1-100）
  • 按过滤条件删除：不支持 removeAll(Filter)；请改用 removeAll(Collection<String> ids)
  • 全部删除：removeAll() 会删除整个索引

示例​