storing-and-querying-vectors

使用 Amazon S3 Vectors 儲存與查詢向量

概述

Amazon S3 Vectors 是一項經濟高效的 AWS 服務，用於大規模儲存和查詢向量嵌入。針對長期儲存進行最佳化，冷查詢延遲低於 1 秒，熱查詢延遲可低至 100 毫秒。

決策指南

• 數百/數千的持續每秒查詢數 (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'] 解析。在 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"}}]'

限制：

• 每次呼叫不得超過 500 個向量
• 為最佳化成本，您應該批次處理向量
• 對於大量操作，您應該使用 SDK 而非 CLI——向量負載可能過大，不適合 shell 引數
• 遇到 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 使用 s3vectors:* 命名空間，而非 s3:*。請更新 IAM 政策。
RequestTimeoutException 或服務不可用	請求逾時或區域不支援	重試請求。如需區域可用性，請搜尋 AWS 文件中的 "S3 Vectors limitations and restrictions"。

其他資源

• limits-and-patterns.md -- 多租戶模式、批次匯入、SSE-KMS、遷移
• metadata-filtering.md -- 篩選運算子、不可過濾的中繼資料、Bedrock KB 鍵