storing-and-querying-vectors

使用 Amazon S3 Vectors 存储和查询向量

概述

Amazon S3 Vectors 是一项经济高效的 AWS 服务，用于大规模存储和查询向量嵌入。针对长期存储进行了优化，冷查询延迟低于秒级，热查询延迟低至 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 密钥策略必须授予 kms:GenerateDataKey 和 kms:Decrypt 给 S3 Vectors 服务主体 indexing.s3vectors.amazonaws.com。您必须使用完整的 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 键