# 查询向量
<a name="s3-vectors-query"></a>

可以使用 [QueryVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_QueryVectors.html) API 操作运行相似性查询，其中，您可以指定查询向量、要返回的相关结果数（前 K 个最近邻居）和索引 ARN。此外，可以在查询中使用元数据筛选条件，以便仅搜索与筛选条件匹配的向量。如果您发出请求来对不可筛选的元数据字段进行筛选，则该请求将返回 `400 Bad Request` 错误。有关元数据筛选的更多信息，请参阅[元数据筛选](s3-vectors-metadata-filtering.md)。

在响应中，默认情况下返回向量键。可以选择在响应中包含距离和元数据。当 `topK` 超过页面大小时，将跨多个页面返回结果。响应包含用于检索下一页的 `nextToken`。继续使用相同的 `queryVector`、`topK` 和 `filter` 参数发出 `QueryVectors` 请求，从每个响应中传递 `nextToken`，直到 `nextToken` 不再存在。或者，您可以使用 AWS SDK 中的内置分页器自动迭代所有页面，而无需手动处理 `nextToken`。执行查询后，分页令牌在几分钟内保持有效。如果分页令牌过期，请重新发出原始查询以启动新会话。在两次页面检索之间写入向量索引的内容不会反映在该查询会话中。有关 `topK` 和页面大小的具体限制，请参阅[限制和局限性](s3-vectors-limitations.md)。

生成查询向量时，所使用的向量嵌入模型应与生成存储在向量索引中的初始向量所用的模型相同。例如，如果您使用 Amazon Bedrock 中的 Amazon Titan 文本嵌入 V2 模型来生成文档的向量嵌入，请使用相同的嵌入模型将问题转换为查询向量。此外，Amazon Bedrock 知识库提供一个完全托管式的端到端 RAG 工作流程，其中 Amazon Bedrock 自动从 S3 数据来源获取数据、将内容转换为文本块、生成嵌入并将其存储在向量索引中。然后，可以查询知识库，并根据从源数据中检索的分块生成响应。有关在控制台中如何从 Amazon Bedrock 知识库中查询向量的更多信息，请参阅[（可选）将 S3 Vectors 与 Amazon Bedrock 知识库集成](s3-vectors-getting-started.md#s3-vectors-bedrock-kb-tutorial)。

此外，开源 Amazon S3 Vectors Embed CLI 工具提供了一种从命令行执行语义搜索的简化方法。这个开源工具通过使用 Amazon Bedrock 基础模型处理向量嵌入生成以及对 S3 向量索引执行语义搜索操作，从而简化了查询流程。有关使用此工具查询向量数据的更多信息，请参阅[使用 `s3vectors-embed-cli` 创建向量嵌入并执行语义搜索](s3-vectors-cli.md)。

S3 Vectors 利用 Amazon S3 的弹性吞吐量在数十亿个向量中高效搜索，从而实现亚秒级冷查询响应时间。因此，它对查询频率较低的工作负载极具成本效益。对于热查询，S3 Vectors 的响应时间可低至 100 ms，尤其适合具有重复或频繁查询模式的工作负载。当跨多个页面返回查询结果时，可以立即访问后续页面。

要对向量嵌入执行相似性查询，有几个因素可能会影响平均召回性能，包括向量嵌入模型、向量数据集的大小（向量和维度的数量）以及查询的分布。对于大多数数据集，S3 Vectors 的平均召回率为 90%\+。平均召回率衡量查询结果的质量。90% 的平均召回率意味着：响应包含存储在向量索引（相对于查询向量）中的实际最接近向量（实际情况）的 90%。但是，由于实际性能可能因特定的使用案例而异，因此我们建议您使用具有代表性的数据和查询来进行自己的测试，以验证 S3 Vectors 是否符合召回要求。

## 使用 AWS SDK
<a name="querty-vectors-sdk"></a>

------
#### [ SDK for Python ]

```
# Query a vector index with an embedding from Amazon Titan Text Embeddings V2.
import boto3 
import json 

# Create Bedrock Runtime and S3 Vectors clients in the AWS Region of your choice. 
bedrock = boto3.client("bedrock-runtime", region_name="us-west-2")
s3vectors = boto3.client("s3vectors", region_name="us-west-2") 

# Query text to convert to an embedding. 
input_text = "adventures in space"

# Generate the vector embedding.
response = bedrock.invoke_model(
    modelId="amazon.titan-embed-text-v2:0",
    body=json.dumps({"inputText": input_text})
) 

# Extract embedding from response.
model_response = json.loads(response["body"].read())
embedding = model_response["embedding"]

# Query vector index.
response = s3vectors.query_vectors(
    vectorBucketName="media-embeddings",
    indexName="movies",
    queryVector={"float32": embedding}, 
    topK=3, 
    returnDistance=True,
    returnMetadata=True
)
print(json.dumps(response["vectors"], indent=2))

# Query vector index with a metadata filter.
response = s3vectors.query_vectors(
    vectorBucketName="media-embeddings",
    indexName="movies",
    queryVector={"float32": embedding}, 
    topK=3, 
    filter={"genre": "scifi"},
    returnDistance=True,
    returnMetadata=True
)
print(json.dumps(response["vectors"], indent=2))

# Paginated query with manual nextToken handling.
query_params = dict(
    vectorBucketName="media-embeddings",
    indexName="movies",
    queryVector={"float32": embedding},
    topK=500,
    returnDistance=True,
    returnMetadata=True,
)
response = s3vectors.query_vectors(**query_params)
for vector in response["vectors"]:
    print(vector)
while response.get("nextToken") is not None:
    response = s3vectors.query_vectors(**query_params, nextToken=response["nextToken"])
    for vector in response["vectors"]:
        print(vector)

# Use the built-in paginator to automatically iterate through all pages.
paginator = s3vectors.get_paginator("query_vectors")

for page in paginator.paginate(
    vectorBucketName="media-embeddings",
    indexName="movies",
    queryVector={"float32": embedding},
    topK=500,
    returnDistance=True,
    returnMetadata=True,
):
    for vector in page["vectors"]:
        print(vector)
```

------