storing-and-querying-vectors

Amazon S3 Vectors でベクトルを保存およびクエリする

概要

Amazon S3 Vectors は、大規模なベクトル埋め込みの保存とクエリに対応する、コスト効率の高い AWS サービスです。長期保存に最適化されており、コールドクエリではサブ秒のレイテンシ、ウォームクエリでは最短 100ms のレイテンシを実現します。

選択ガイド

• 数百／数千 QPS の持続的なクエリ：適切なツールではありません。OpenSearch を推奨します。
• ハイブリッド検索、集計、ファセット検索：S3 Vectors をストレージエンジンとして使用する OpenSearch を推奨します。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'] で解析してください。put-vectors または query-vectors では、embedding 配列を 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 キー