跳到主要内容

Amazon S3 Vector 存储

S3Vectors 类使用 Amazon S3 Vectors（预览版）提供 Vector 搜索。它将 Vector 存储在 Vector bucket 中，并在 Vector index 中执行相似度搜索，同时支持基于 JSON 的元数据过滤器。

注意

Amazon S3 Vectors 是一项预览版服务。预览功能可能随时变更或移除，恕不另行通知，并且不受 AWS SLA 保障。其行为、限制和区域可用性都可能随时变化。为了与 AWS 保持一致，此库可能会引入破坏性变更。

安装
安装的直接链接

npm install @mastra/s3vectors@latest

用法示例
用法示例的直接链接

import { S3Vectors } from '@mastra/s3vectors'

const store = new S3Vectors({
  vectorBucketName: process.env.S3_VECTORS_BUCKET_NAME!, // e.g. "my-vector-bucket"
  clientConfig: {
    region: process.env.AWS_REGION!, // credentials use the default AWS provider chain
  },
  // Optional: mark large/long-text fields as non-filterable at index creation time
  nonFilterableMetadataKeys: ['content'],
})

// Create an index (names are normalized: "_" → "-" and lowercased)
await store.createIndex({
  indexName: 'my_index',
  dimension: 1536,
  metric: 'cosine', // "euclidean" also supported; "dotproduct" is NOT supported
})

// Upsert vectors (ids auto-generated if omitted). Date values in metadata are serialized to epoch ms.
const ids = await store.upsert({
  indexName: 'my_index',
  vectors: [
    [0.1, 0.2 /* … */],
    [0.3, 0.4 /* … */],
  ],
  metadata: [
    {
      text: 'doc1',
      genre: 'documentary',
      year: 2023,
      createdAt: new Date('2024-01-01'),
    },
    { text: 'doc2', genre: 'comedy', year: 2021 },
  ],
})

// Query with metadata filters (implicit AND is canonicalized)
const results = await store.query({
  indexName: 'my-index',
  queryVector: [0.1, 0.2 /* … */],
  topK: 10, // Service-side limits may apply (commonly 30)
  filter: { genre: { $in: ['documentary', 'comedy'] }, year: { $gte: 2020 } },
  includeVector: false, // set true to include raw vectors (may trigger a secondary fetch)
})

// Clean up resources (closes the underlying HTTP handler)
await store.disconnect()

构造函数选项
构造函数选项的直接链接

vectorBucketName:

string
目标 S3 Vectors Vector bucket 的名称。

clientConfig?:

S3VectorsClientConfig
AWS SDK v3 客户端选项（例如 region、credentials）。

nonFilterableMetadataKeys?:

string[]
不应支持过滤的元数据键（创建索引时应用）。适用于 content 等大型文本字段。

方法
方法的直接链接

createIndex()
createindex的直接链接

在配置的 Vector bucket 中创建新的 Vector index。如果该索引已经存在，此调用会验证 schema 并且不执行任何操作（保留现有度量和维度）。

indexName:

string
逻辑索引名称。会在内部进行规范化：下划线替换为连字符，并将名称转换为小写。

dimension:

number
Vector 维度（必须与你的嵌入模型匹配）

metric?:

'cosine' | 'euclidean'
= cosine
用于相似度搜索的距离度量。S3 Vectors 不支持 dotproduct。

upsert()
upsert的直接链接

添加或替换 Vector（写入完整记录）。如果未提供 ids，则会生成 UUID。

indexName:

string
要向其中执行 upsert 的索引名称

vectors:

number[][]
嵌入 Vector 数组

metadata?:

Record<string, any>[]
每个 Vector 的元数据

ids?:

string[]
可选的 Vector ID（未提供时自动生成）

query()
query的直接链接

搜索最近邻，并可选择应用元数据过滤。

indexName:

string
要查询的索引名称

queryVector:

number[]
用于查找相似 Vector 的查询 Vector

topK?:

number
= 10
要返回的结果数量

filter?:

S3VectorsFilter
基于 JSON 的元数据过滤器，支持 $and、$or、$eq、$ne、$gt、$gte、$lt、$lte、$in、$nin、$exists。

includeVector?:

boolean
= false
是否在结果中包含 Vector
备注

结果中包含 score = 1/(1 + distance)，因此分数越高越好，同时保留底层的距离排序。

describeIndex()
describeindex的直接链接

返回索引的相关信息。

indexName:

string
要描述的索引名称。

返回：

interface IndexStats {
  dimension: number
  count: number // computed via ListVectors pagination (O(n))
  metric: 'cosine' | 'euclidean'
}

deleteIndex()
deleteindex的直接链接

删除索引及其数据。

indexName:

string
要删除的索引。

listIndexes()
listindexes的直接链接

列出已配置 Vector bucket 中的所有索引。

返回：Promise<string[]>

updateVector()
updatevector的直接链接

更新索引中特定 ID 对应的 Vector 或元数据。

indexName:

string
包含该 Vector 的索引。

id:

string
要更新的 ID。

update:

object
包含 Vector 和/或元数据的更新数据

update.vector?:

number[]
要更新的新 Vector 数据

update.metadata?:

Record<string, any>
要更新的新元数据

deleteVector()
deletevector的直接链接

按 ID 删除特定 Vector。

indexName:

string
包含该 Vector 的索引。

id:

string
要删除的 ID。

disconnect()
disconnect的直接链接

关闭底层 AWS SDK HTTP handler，以释放 socket。

响应类型
响应类型的直接链接

查询结果以以下格式返回：

interface QueryResult {
  id: string
  score: number // 1/(1 + distance)
  metadata: Record<string, any>
  vector?: number[] // Only included if includeVector is true
}

过滤器语法
过滤器语法的直接链接

S3 Vectors 仅支持一组严格限定的运算符和值类型。Mastra 过滤器转换器会：

  • 将隐式 AND 规范化：{a:1,b:2} → { $and: [{a:1},{b:2}] }。
  • 将 Date 值规范化为 epoch 毫秒数，以用于数值比较和数组元素。
  • 禁止在相等比较中使用 Date（field: value 或 $eq/$ne）。相等比较值必须是 string | number | boolean。
  • 拒绝将 null/undefined 用于相等比较。不支持数组相等比较（请使用 $in/$nin）。
  • 顶层逻辑运算符只允许使用 $and / $or。
  • 逻辑运算符必须包含字段条件（不能直接包含运算符）。

支持的运算符：

  • 逻辑： $and、$or（非空数组）
  • 基本： $eq、$ne（string | number | boolean）
  • 数值： $gt、$gte、$lt、$lte（number 或 Date → epoch 毫秒数）
  • 数组： $in、$nin（由 string | number | boolean 构成的非空数组；Date → epoch 毫秒数）
  • 元素： $exists（boolean）

不支持/不允许（会被拒绝）： $not、$nor、$regex、$all、$elemMatch、$size、$text 等。

示例：

// Implicit AND
{ genre: { $in: ["documentary", "comedy"] }, year: { $gte: 2020 } }

// Explicit logicals and ranges
{
  $and: [
    { price: { $gte: 100, $lte: 1000 } },
    { $or: [{ stock: { $gt: 0 } }, { preorder: true }] }
  ]
}

// Dates in range (converted to epoch ms)
{ timestamp: { $gt: new Date("2024-01-01T00:00:00Z") } }
备注

如果在创建索引时设置了 nonFilterableMetadataKeys，这些键仍会存储，但不能用于过滤器。

错误处理
错误处理的直接链接

该存储会抛出可捕获的类型化错误：

try {
  await store.query({
    indexName: 'index-name',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details) // Additional error context
  }
}

环境变量
环境变量的直接链接

连接应用时通常使用以下环境变量：

  • S3_VECTORS_BUCKET_NAME：你的 S3 Vector bucket 名称（用于填充 vectorBucketName）。
  • AWS_REGION：S3 Vectors bucket 所在的 AWS 区域。
  • AWS 凭证：通过标准 AWS SDK Provider chain 提供（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_PROFILE 等）。

最佳实践
最佳实践的直接链接

  • 选择与你的嵌入模型匹配的度量（cosine 或 euclidean）。不支持 dotproduct。
  • 保持可过滤元数据小巧且结构化（string/number/boolean）。将大型文本（例如 content）存储为不可过滤数据。
  • 对嵌套元数据使用点分路径，对复杂逻辑使用显式 $and/$or。
  • 避免在热路径上调用 describeIndex()。count 通过分页的 ListVectors 计算（O(n)）。
  • 仅在需要原始 Vector 时使用 includeVector: true。
On this page