Amazon S3 Vectors ストア

⚠️ Amazon S3 Vectors はプレビュー段階のサービスです。 プレビュー機能は予告なく変更・削除される場合があり、AWS の SLA 対象外です。 動作、制限、リージョンでの提供状況は随時変更される可能性があります。 このライブラリは AWS との整合性維持のため、破壊的変更を加える場合があります。

S3Vectors クラスは、Amazon S3 Vectors（プレビュー）  を用いたベクトル検索を提供します。ベクトルはベクトルバケットに保存され、ベクトルインデックスで類似検索が実行され、JSON ベースのメタデータフィルターで絞り込みが可能です。

インストール

npm install @mastra/s3vectors

使用例

import { S3Vectors } from "@mastra/s3vectors";
 
const store = new S3Vectors({
  vectorBucketName: process.env.S3_VECTORS_BUCKET_NAME!, // 例: "my-vector-bucket"
  clientConfig: {
    region: process.env.AWS_REGION!, // 認証情報はデフォルトの AWS プロバイダーチェーンを使用
  },
  // オプション: 大きな/長文のフィールドをインデックス作成時にフィルタ不可としてマーク
  nonFilterableMetadataKeys: ["content"],
});
 
// インデックスを作成（名前は正規化される: "_" → "-"、小文字化）
await store.createIndex({
  indexName: "my_index",
  dimension: 1536,
  metric: "cosine", // "euclidean" もサポート。"dotproduct" はサポートされない
});
 
// ベクトルをアップサート（id を省略した場合は自動生成）。メタデータ内の日付はエポック 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 },
  ],
});
 
// メタデータフィルタでクエリ（暗黙の AND は正規化される）
const results = await store.query({
  indexName: "my-index",
  queryVector: [0.1, 0.2 /* … */],
  topK: 10, // サービス側の制限が適用される場合あり（一般的に 30）
  filter: { genre: { $in: ["documentary", "comedy"] }, year: { $gte: 2020 } },
  includeVector: false, // 生のベクトルを含めるには true に設定（二次フェッチが発生する場合あり）
});
 
// リソースをクリーンアップ（基盤の HTTP ハンドラーをクローズ）
await store.disconnect();

コンストラクターのオプション

手法

createIndex()

設定済みのベクターバケットに新しいベクトルインデックスを作成します。インデックスが既に存在する場合、この呼び出しはスキーマを検証し、実質的に何も行いません（既存の metric と dimension は保持されます）。

upsert()

ベクトルを追加または置換します（レコード全体の書き込み）。ids が指定されていない場合は UUID が生成されます。

query()

必要に応じてメタデータでフィルタリングし、最近傍検索を行います。

スコアリング: 結果には score = 1/(1 + distance) が含まれ、基盤となる距離のランキングを保ちながら、値が高いほど良い指標になります。

describeIndex()

インデックスの情報を返します。

戻り値:

interface IndexStats {
  dimension: number;
  count: number; // ListVectors のページネーションで算出 (O(n))
  metric: "cosine" | "euclidean";
}

deleteIndex()

インデックスとそのデータを削除します。

listIndexes()

構成済みのベクターバケット内のすべてのインデックスを一覧します。

戻り値: Promise<string[]> ---MDX_CONTENTEND---

updateVector()

インデックス内の特定のIDに対して、ベクトルまたはメタデータを更新します。

deleteVector()

ID で指定したベクターを削除します。

disconnect()

基盤となる AWS SDK の HTTP ハンドラーをクローズして、ソケットを解放します。

応答の種類

クエリ結果は次の形式で返されます：

interface QueryResult {
  id: string;
  score: number; // 1/(1 + distance)
  metadata: Record<string, any>;
  vector?: number[]; // includeVector が true の場合のみ含まれる
}

フィルター構文

S3 Vectors は演算子と値型の厳密なサブセットのみをサポートします。Mastra フィルター・トランスレーターは次の処理を行います:

• 暗黙の AND を正規化: {a:1,b:2} → { $and: [{a:1},{b:2}] }。
• Date 値を正規化し、数値比較や配列要素向けにエポック ms に変換します。
• 等価位置（field: value または $eq/$ne）での Date を不許可。等価値は string | number | boolean に限ります。
• 等価に対する null/undefined を拒否。配列の等価は未対応（$in/$nin を使用）。
• 最上位の論理演算子として許可されるのは $and / $or のみ。
• 論理演算子にはフィールド条件（直接の演算子ではなく）が含まれている必要があります。

サポートされる演算子:

• 論理: $and, $or（空でない配列）
• 基本: $eq, $ne（string | number | boolean）
• 数値: $gt, $gte, $lt, $lte（number または Date → エポック ms）
• 配列: $in, $nin（string | number | boolean の空でない配列；Date → エポック ms）
• 要素: $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' | など
    console.log(error.details); // 追加のエラー情報
  }
}

環境変数

アプリを連携する際の一般的な環境変数:

• S3_VECTORS_BUCKET_NAME: S3 のベクター用バケット名（vectorBucketName の設定に使用）。
• AWS_REGION: S3 ベクター用バケットの 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 を使用してください。

関連項目

• メタデータフィルター