# ベクトルのクエリ
<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 Text Embeddings V2 モデルを使用してドキュメントのベクトル埋め込みを生成する場合は、同じ埋め込みモデルを使用して質問をクエリベクトルに変換します。さらに、Amazon Bedrock ナレッジベースは、Amazon Bedrock が S3 データソースからデータを自動的に取得し、コンテンツをテキストブロックに変換し、埋め込みを生成してベクトルインデックスに保存するフルマネージドエンドツーエンド RAG ワークフローを提供します。その後、ナレッジベースをクエリし、ソースデータから取得したチャンクに基づいてレスポンスを生成できます。コンソールで Amazon Bedrock ナレッジベースからベクトルをクエリする方法の詳細については、「[(オプション) S3 ベクトルと 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 のエラスティックスループットを活用して数百万のベクトルを効率的に検索することで、コールドクエリに対して 1 秒未満の応答時間を実現します。これにより、クエリの頻度が低いワークロードに対して高いコスト効率が得られます。ウォームクエリの場合、S3 Vectors は応答時間を 100 ミリ秒まで短縮できるため、クエリパターンが繰り返しまたは頻繁に発生するワークロードにメリットがあります。

ベクトル埋め込みの類似度クエリを実行する場合、ベクトル埋め込みモデル、ベクトルデータセットのサイズ (ベクトルとディメンションの数)、クエリの分布など、いくつかの要因が平均再現率パフォーマンスに影響を与える可能性があります。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))
```

------