Amazon S3 Vectors でベクトルを保存・検索する

概要

Amazon S3 Vectors は、ベクトルエンベディングをスケールで保存・検索するための、コスト効率的な AWS サービスです。長期保存に最適化されており、コールドクエリでは 100ms 程度、ウォームクエリではサブ秒レベルのレイテンシーを実現します。

決定ガイド

• 毎秒数百～数千のクエリ (QPS) が継続的に必要: このツールは不適切です。OpenSearch の使用をお勧めします。
• ハイブリッド検索、集約、ファセット検索: OpenSearch と S3 Vectors (ストレージエンジン) の併用をお勧めします。OpenSearch との統合については、AWS ドキュメントで "Using S3 Vectors with OpenSearch Service" を検索してください。
• 階層型 (バルク + ホット): S3 Vectors でストレージ + OpenSearch Serverless でリアルタイム処理。references/limits-and-patterns.md を参照してください。
• コスト効率的なストレージ、不定期なクエリ、RAG: S3 Vectors が最適です。進めてください。

最新のガイダンスについては、AWS ドキュメントで "S3 Vectors best practices" を検索してください。

一般的なタスク

開始前にリクエストを分類してください:

• シンプルクエリ: 既存インデックス、ステップ 6 にスキップ
• 標準: 既存インデックスをリストアップして、関連するものがあれば再利用を提案する必要があります。ない場合は、ステップ 2～6 に従って、新しいインデックスを作成してベクトルを保存してください
• マイグレーションまたはマルチテナント: 最初に references/limits-and-patterns.md を読んでから、ステップ 2～6 に進んでください

接続している場合、AWS MCP サーバーツールを使用してコマンドを実行する必要があります。AWS MCP が利用できない場合のみ AWS CLI にフォールバックしてください。実行前に各ステップをユーザーに説明する必要があります。

1. 依存関係の確認

制約:

• AWS MCP ツールまたは AWS CLI が利用可能かどうかを確認し、不足している場合はユーザーに通知する必要があります
• ターゲット AWS リージョンを確認する必要があります

2. ベクトルバケットの作成

バケット名をユーザーと確認する必要があります。名前: 3～63 文字、小文字、数字、ハイフンのみ。暗号化 (デフォルト SSE-S3 またはコンプライアンス用 SSE-KMS) は作成後変更できません。

aws s3vectors create-vector-bucket \
  --vector-bucket-name <BUCKET_NAME>

制約:

• 暗号化は作成後に変更できないことを説明する必要があります
• SSE-KMS の場合、KMS キーポリシーは S3 Vectors サービスプリンシパル indexing.s3vectors.amazonaws.com に kms:GenerateDataKey と kms:Decrypt を付与する必要があります。KMS キーの完全な ARN を使用する必要があります (エイリアスは不可)。references/limits-and-patterns.md でコマンド例を参照してください。

3. ベクトルインデックスの作成

すべてのパラメータは 作成後は変更不可 です。

事前チェックリスト (すべてをユーザーと確認):

1. 次元 (必須、整数 1～4096) -- エンベディングモデルの出力と一致する必要があります
2. 距離メトリック (必須) -- cosine または euclidean。エンベディングモデルの推奨メトリックを使用してください
3. フィルター不可能なメタデータキー (オプション、最大 10 個、1～63 文字) -- 作成時に宣言するか、今後使用できなくなります。Bedrock Knowledge Bases 統合の場合は、AWS ドキュメントで "S3 Vectors Bedrock Knowledge Bases prerequisites" を検索して必要なキー名を確認してください。
4. 暗号化 (オプション) -- バケットから継承されます。必要に応じてインデックスごとにオーバーライド可能です。

aws s3vectors create-index \
  --vector-bucket-name <BUCKET_NAME> \
  --index-name <INDEX_NAME> \
  --dimension <DIM> \
  --distance-metric <cosine|euclidean> \
  --data-type float32 \
  --metadata-configuration '{"nonFilterableMetadataKeys":["<KEY1>","<KEY2>"]}'

フィルター不可能なキーが不要な場合は --metadata-configuration を省略してください。

インデックス名: 3～63 文字、小文字、数字、ハイフン、ドット。バケット内で一意。フィルター可能なメタデータ: 2 KB 制限。総メタデータ (フィルター可能 + フィルター不可能の合計): 40 KB。references/metadata-filtering.md を参照してください。

4. エンベディングの生成 (必要に応じて)

ユーザーが既にエンベディングを持っている場合は、ステップ 5 (保存) またはステップ 6 (クエリ) にスキップしてください。

制約:

• エンベディングモデルが指定されていない場合、どのモデルを使用するかをユーザーに確認する必要があります
• デフォルトモデルを仮定してはいけません
• 次元はステップ 3 と一致する必要があります
• 保存とクエリに同じモデルを使用する必要があります

Bedrock invoke-model でエンベディングを生成します:

aws bedrock-runtime invoke-model \
  --model-id <MODEL_ID> \
  --content-type application/json \
  --cli-binary-format raw-in-base64-out \
  --body '{"inputText": "your text"}' \
  invoke-model-output.json

CLI v2 では --cli-binary-format raw-in-base64-out を使用する必要があります。出力ファイルは CLI で必須です。レスポンスキーはモデルに依存します (例: Titan の場合 embedding、Cohere の場合 embeddings)。Titan の場合、json.load(open('invoke-model-output.json'))['embedding'] で解析します。embedding 配列を put-vectors または query-vectors で float32 として使用してください。バッチエンベディング生成の場合は、AWS SDK または CLI を使用してください。

5. ベクトルの保存

aws s3vectors put-vectors \
  --vector-bucket-name <BUCKET_NAME> \
  --index-name <INDEX_NAME> \
  --vectors '[{"key":"<ID>","data":{"float32":[<EMBEDDING>]},"metadata":{"topic":"science"}}]'

制約:

• 1 回の呼び出しで 500 ベクトルを超えてはいけません
• コスト最適化のためにベクトルをバッチ処理する必要があります
• バルク操作の場合、CLI の代わりに SDK を使用する必要があります。ベクトルペイロードがシェル引数に対して大きすぎる可能性があります
• 429 TooManyRequestsException 発生時は、バックオフ付きリトライを実装する必要があります
• バッチパターンについては references/limits-and-patterns.md を参照してください

6. ベクトルのクエリ

必要に応じてエンベディングを生成 (ステップ 4)、その後クエリを実行:

aws s3vectors query-vectors \
  --vector-bucket-name <BUCKET_NAME> \
  --index-name <INDEX_NAME> \
  --query-vector '{"float32":[<EMBEDDING>]}' \
  --top-k 10 \
  --return-distance

オプション: --return-metadata および/または --filter '{"topic":{"$eq":"science"}}' を追加 (どちらも GetVectors 権限が必要)。references/metadata-filtering.md を参照してください。

レスポンスの例: {"vectors": [{"key": "id1", "distance": 0.45, "metadata": {"topic": "science"}}, ...], "distanceMetric": "cosine"}

制約:

• --filter または --return-metadata を使用する場合、s3vectors:QueryVectors と s3vectors:GetVectors の両方の IAM 権限が必要です。GetVectors がない場合、これらのオプションは 403 を返します。

トラブルシューティング

エラー	原因	解決方法
DimensionMismatch	次元がインデックスと一致していない	一致するモデルを使用するか、インデックスを削除して再作成してください (ユーザーに確認 -- すべてのベクトルが削除されます)。
--filter または --return-metadata で 403 Forbidden	s3vectors:GetVectors が不足	IAM ポリシーに s3vectors:GetVectors を追加してください。
--top-k より少ない結果	フィルタに一致するベクトルが少ない	予想される動作 -- フィルタリングはインラインです。フィルタを広げてください。
429 TooManyRequestsException	インデックスあたりのレート制限を超過	バックオフ付きリトライを実行してください。持続的なスループットの場合はインデックス全体でシャーディングしてください。現在の制限については AWS ドキュメントで "S3 Vectors limitations and restrictions" を検索してください。
AccessDeniedException	s3vectors:* IAM アクション が不足	S3 Vectors は s3:* ではなく s3vectors:* ネームスペースを使用します。IAM ポリシーを更新してください。
RequestTimeoutException またはサービス利用不可	リクエストタイムアウトまたはリージョンが非対応	リクエストを再試行してください。リージョンの可用性については AWS ドキュメントで "S3 Vectors limitations and restrictions" を検索してください。

追加リソース

• limits-and-patterns.md -- マルチテナントパターン、バッチ取り込み、SSE-KMS、マイグレーション
• metadata-filtering.md -- フィルタ演算子、フィルター不可能なメタデータ、Bedrock KB キー