Amazon S3 向量儲存

S3Vectors 類別使用 Amazon S3 Vectors（預覽版）提供向量搜尋功能。它會將向量儲存在向量儲存貯體中，並在向量索引內執行相似度搜尋，同時支援以 JSON 為基礎的元資料篩選條件。

注意

Amazon S3 Vectors 是預覽版服務。預覽功能可能會在不另行通知的情況下變更或移除，亦不受 AWS 服務水平協議（SLA）保障。其行為、限制及區域供應情況隨時可能變更。為與 AWS 保持一致，此程式庫可能會引入破壞性變更。

安裝

npm

npm install @mastra/s3vectors@latest

pnpm

pnpm add @mastra/s3vectors@latest

Yarn

yarn add @mastra/s3vectors@latest

Bun

bun add @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 向量儲存貯體名稱。

clientConfig?:

S3VectorsClientConfig

AWS SDK v3 用戶端選項（例如 region、credentials）。

nonFilterableMetadataKeys?:

string[]

不應用於篩選的元資料鍵（建立索引時套用）。適合用於 content 等大型文字欄位。

方法

createIndex()

在已設定的向量儲存貯體中建立新的向量索引。如果索引已存在，此呼叫會驗證結構描述而不執行任何操作（保留現有的度量及維度）。

indexName:

string

邏輯索引名稱。系統會在內部將名稱標準化：以連字號取代底線，並將名稱轉為小寫。

dimension:

number

向量維度（必須與嵌入模型相符）

metric?:

'cosine' | 'euclidean'

= cosine

相似度搜尋所用的距離度量。S3 Vectors 不支援 dotproduct。

upsert()

新增或取代向量（寫入完整記錄）。如果未提供 ids，系統會產生 UUID。

indexName:

string

要寫入或更新資料的索引名稱

vectors:

number[][]

嵌入向量陣列

metadata?:

Record<string, any>[]

每個向量的元資料

ids?:

string[]

選填的向量 ID（如未提供則自動產生）

query()

搜尋最近鄰，並可選擇使用元資料篩選條件。

indexName:

string

要查詢的索引名稱

queryVector:

number[]

用於尋找相似向量的查詢向量

topK?:

number

= 10

要傳回的結果數目

filter?:

S3VectorsFilter

以 JSON 為基礎的元資料篩選條件，支援 $and、$or、$eq、$ne、$gt、$gte、$lt、$lte、$in、$nin、$exists。

includeVector?:

boolean

= false

是否在結果中包含向量

備註

結果包含 score = 1/(1 + distance)，因此在保留底層距離排名的同時，分數越高代表結果越佳。

describeIndex()

傳回索引的相關資料。

indexName:

string

要描述的索引名稱。

傳回：

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

deleteIndex()

刪除索引及其資料。

indexName:

string

要刪除的索引。

listIndexes()

列出已設定向量儲存貯體中的所有索引。

傳回：Promise<string[]>

updateVector()

在索引內更新特定 ID 的向量或元資料。

indexName:

string

包含該向量的索引。

id:

string

要更新的 ID。

update:

object

包含向量及／或元資料的更新資料

update.vector?:

number[]

要更新的新向量資料

update.metadata?:

Record<string, any>

要更新的新元資料

deleteVector()

按 ID 刪除特定向量。

indexName:

string

包含該向量的索引。

id:

string

要刪除的 ID。

disconnect()

關閉底層 AWS SDK HTTP 處理常式以釋放通訊端。

回應類型

查詢結果會以下列格式傳回：

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 向量儲存貯體名稱（用於填入 vectorBucketName）。
• AWS_REGION：S3 Vectors 儲存貯體所在的 AWS 區域。
• AWS 憑證：透過標準 AWS SDK 供應者鏈（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_PROFILE 等）提供。

最佳實踐

• 選擇與嵌入模型相符的度量（cosine 或 euclidean）。系統不支援 dotproduct。
• 可篩選的元資料應保持精簡且具結構（string/number/boolean）。大型文字（例如 content）應儲存為不可篩選。
• 對巢狀元資料使用點分隔路徑，並對複雜邏輯明確使用 $and/$or。
• 避免在熱路徑中呼叫 describeIndex()。count 是使用分頁的 ListVectors 計算（O(n)）。
• 只在需要原始向量時才使用 includeVector: true。

相關內容

• Metadata 篩選器