# 查询向量
<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)。

在响应中，默认情况下返回向量键。可以选择在响应中包含距离和元数据。

生成查询向量时，所使用的向量嵌入模型应与生成存储在向量索引中的初始向量所用的模型相同。例如，如果您使用 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%\$1。平均召回率衡量查询结果的质量。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))
```

------