storing-and-querying-vectors

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

概述

Amazon S3 Vectors 是一项经济高效的 AWS 服务，可大规模存储和查询向量嵌入。该服务针对长期存储进行了优化，冷查询延迟低于 1 秒，热查询延迟最低可达 100 ms。

决策指南

• 每秒数百／数千次持续查询（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 数组作为 float32 用于 put-vectors 或 query-vectors。批量生成嵌入时，请使用 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	将 s3vectors:GetVectors 添加到 IAM policy。
返回结果少于 --top-k	匹配筛选条件的向量较少	这是预期行为——筛选会在查询时执行。放宽筛选条件。
429 TooManyRequestsException	超出每个索引的速率限制	采用退避策略重试。若需持续提高吞吐量，可将负载分片到多个索引。搜索 AWS 文档 "S3 Vectors limitations and restrictions"，查看当前限制。
AccessDeniedException	缺少 s3vectors:* IAM 操作权限	S3 Vectors 使用 s3vectors:* 命名空间，而非 s3:*。更新 IAM policy。
RequestTimeoutException 或服务不可用	请求超时或区域不受支持	重试请求。要查询区域可用性，请搜索 AWS 文档 "S3 Vectors limitations and restrictions"。

更多资源

• limits-and-patterns.md -- 多租户模式、批量导入、SSE-KMS、迁移
• metadata-filtering.md -- 筛选运算符、不可筛选的元数据、Bedrock KB 键