# チュートリアル: S3 Vectors の開始方法
このチュートリアルでは、Amazon S3 コンソールの AWS リージョンで S3 ベクトルバケットとベクトルインデックスを作成します。次に、Amazon Bedrock 埋め込みモデルを使用してデータのベクトル埋め込みを生成し、ベクトルインデックスに保存してセマンティック検索を実行します。
開始するには、AWS アカウントをまだお持ちでない場合はサインアップします。アカウントの設定の詳細については、「[Amazon S3 の開始方法](GetStartedWithS3.md)」を参照してください。
**Topics**
+ [ステップ 1: コンソールでベクトルバケットを作成する](#s3-vectors-create-bucket-tutorial)
+ [ステップ 2: コンソールでベクトルバケットのベクトルインデックスを作成する](#s3-vectors-create-index-tutorial)
+ [ステップ 3: SDK for Python (Boto3) を使用してベクトルインデックスにベクトルを挿入する](#s3-vectors-insert-vectors-tutorial)
+ [ステップ 4. SDK for Python (Boto3) を使用し、ベクトルインデックスのベクトルをクエリする](#s3-vectors-query-vectors-tutorial)
+ [(オプション) S3 Vectors Embed CLI を使用してベクトル埋め込みの作成を自動化する](#s3-vectors-embed-CLI-tutorial)
+ [(オプション) S3 ベクトルと Amazon Bedrock ナレッジベースを統合する](#s3-vectors-bedrock-kb-tutorial)
+ [(オプション) S3 ベクトルと Amazon OpenSearch を統合する](#s3-vectors-opensearch-tutorial)
## ステップ 1: コンソールでベクトルバケットを作成する
S3 ベクトルバケットは、ベクトルの保存とクエリ専用に構築された Amazon S3 バケットの一種です。専用の API オペレーションを使用してベクトルデータの書き込みとクエリを行います。IAM アイデンティティベースのポリシーやリソースベースのポリシーなどのアクセスコントロールメカニズムを使用して、ベクトルデータへのアクセスを制御できます。
このステップでは、Amazon S3 コンソールを使用して最初のベクトルバケットを作成します。ベクトルバケットを作成するその他の方法については、「[ベクトルバケットの作成](s3-vectors-buckets-create.md)」を参照してください。
### ベクトルバケットを作成するには
1. AWS マネジメントコンソール にサインインし、Amazon S3 コンソール ([https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)) を開きます。
1. 左のナビゲーションペインで、**[ベクトルバケット]** を選択します。
1. **[ベクトルバケット]** のページで、**[ベクトルバケットを作成]** をクリックします。
1. **[ベクトルバケットを作成]** ページで、**[ベクトルバケット名]** フィールドに名前を入力します。このチュートリアルでは、ベクトルバケット名として {{media-embeddings}} を使用します。ベクトルバケット名は 3～63 文字で、AWS リージョン内で一意であることが必要です。有効な文字は、小文字 (a～z)、数字 (0～9)、ハイフン (-) です。
**注記**
バケットを作成した後は、ベクトルバケット名を変更することはできません。
1. **[暗号化]** で、**[暗号化タイプを指定する]** を選択します。暗号化タイプに、**AWS Key Management Service キーを用いたサーバー側の暗号化 (SSE-KMS)**、またはデフォルトの **Amazon S3 マネージドキーを用いたサーバー側の暗号化 (SSE-S3)** を指定できます。このチュートリアルでは、**Amazon S3 マネージドキーを用いたサーバー側の暗号化 (SSE-S3)** を選択します。ベクトルバケットの暗号化設定の詳細については、「[S3 Vectors のデータ保護と暗号化](s3-vectors-data-encryption.md)」を参照してください。
**注記**
ベクトルバケットを作成した後は、暗号化タイプを変更することはできません。
1. **[タグ (オプション)]** では、タグをキーと値のペアとして追加して、ベクトルバケットのアクセス許可を整理および指定できます。**キー**と**値**を入力します。別のタグを追加するには、[**タグの追加**] を選択します。ベクトルバケットには最大 50 個のタグを入力できます。詳細については、「[S3 ベクトルバケットでのタグの使用](s3-vectors-tags.md)」を参照してください。
1. **[ベクトルバケットを作成]** を選択します。
## ステップ 2: コンソールでベクトルバケットのベクトルインデックスを作成する
**注記**
ベクトルインデックス設定のパラメータを慎重に選択します。ベクトルインデックスを作成した後、ベクトルインデックス名、ディメンション、距離メトリクス、またはフィルタリング不可能なメタデータキーを更新することはできません。これらの値を変更するには、新しいベクトルインデックスを作成する必要があります。
このステップでは、ベクトルバケットにベクトルインデックスを作成します。ベクトルインデックスは、ベクトル埋め込みの保存とクエリに使用されます。ベクトルインデックスの詳細については、「[ベクトルインデックス](s3-vectors-indexes.md)」を参照してください。
### ベクトルインデックスを作成するには
1. Amazon S3 コンソールの**ベクトルバケット**のリストで、新しく作成されたベクトルバケットに移動します。
1. **[ベクトルインデックスを作成]** を選択します。
1. **[ベクトルインデックスの作成]** ページで、**[ベクトルインデックス名]** フィールドに名前を入力します。このチュートリアルでは、ベクトルインデックス名として {{movies}} を使用します。
ベクトルインデックス名は 3～63 文字で、ベクトルバケット内で一意であることが必要です。有効な文字は、小文字 (a～z)、数字 (0～9)、ハイフン (-)、ドット (.) です。
インデックスを作成した後は、ベクトルインデックス名を変更することはできません。
1. **[ディメンション]** で、ベクトル埋め込みモデルによって各ベクトル内に生成される数を決定する 1～4096 の数値を指定します。埋め込みモデルは、データ (テキスト、画像など) を数値ベクトルに変換する特殊な機械学習 (ML) モデルです。埋め込みモデルは通常、500-2000 の間のディメンションを出力し、各ディメンションは浮動小数点数になります。このチュートリアルでは、Amazon Bedrock の Titan Text v2 埋め込みモデルを使用します。この埋め込みモデルでは、1024 次元のベクトルをデフォルトとして使用するため、ベクトルインデックスのディメンションを `1024` に設定します。
インデックスを作成した後は、ディメンション値を変更することはできません。埋め込みモデルの推奨事項に基づいて、慎重にディメンション値を指定します。
1. **[距離メトリクス]** で、**[コサイン]** (角度類似度を測定する) または **[ユークリッド]** (直線距離を測定する) を距離メトリクスとして選択し、クエリ中にベクトル間の類似度を計算する方法を定義します。このチュートリアルでは、**[コサイン]** を選択します。
インデックスを作成した後は、距離メトリクスを変更することはできません。埋め込みモデルの推奨事項に基づいて、慎重に距離メトリクスを選択します。
1. **[追加の設定] (オプション)** で、フィルタリングが可能でないメタデータキーを指定して、ベクトル埋め込みとともに補足情報を保存できます。
**注記**
インデックスの作成後にベクトルデータを挿入するときに、フィルタリングが可能なメタデータをキーと値のペアとして各ベクトルにアタッチできます。デフォルトでは、ベクトルにアタッチされているすべてのメタデータキーはフィルタリング可能で、類似度クエリでフィルターとして使用できます。ベクトルインデックスの作成中にフィルタリング不可として指定されたメタデータキーのみがフィルタリングから除外されます。
フィルタリングが可能でないメタデータキーはそれぞれ 1～63 文字で、ベクトルインデックス内で一意である必要があります。これらのキーは、類似度クエリ中にフィルタリングする必要のない参照情報を保存するのに役立ちます。例えば、テキスト埋め込みを使用する場合は、元のテキストチャンクを参照目的で保持できます。このチュートリアルでは、ベクトル埋め込みを作成するテキストデータを保存する `source_text` という名前のフィルタリングが可能ではないメタデータキーを追加します。
インデックスを作成した後は、フィルタリングが可能ではないメタデータキーを更新することはできません。メタデータの構造を慎重に計画します。
1. **[暗号化]** で、**[暗号化タイプを指定する]** を選択します。バケットレベルの暗号化設定を使用するか、ベクトルインデックスの暗号化設定を上書きするかを選択できます。バケットレベルの設定を上書きする場合は、ベクトルインデックスの暗号化タイプを **[AWS Key Management Service キーを使用したサーバー側の暗号化 (SSE-KMS)]**、または **[Amazon S3 マネージドキーを用いたサーバー側の暗号化 (SSE-S3)]** として指定するオプションがあります。このチュートリアルでは、**[暗号化のバケット設定を使用する]** を選択します。ベクトルバケットとインデックスの暗号化設定の詳細については、「[S3 Vectors のデータ保護と暗号化](s3-vectors-data-encryption.md)」を参照してください。
1. **[タグ (オプション)]** では、キーと値のペアとしてタグを追加して、AWS Billing and Cost Management を使用してベクトルインデックスのコストを追跡および整理できます。**キー**と**値**を入力します。別のタグを追加するには、[**タグの追加**] を選択します。ベクトルインデックスには最大 50 個のタグを入力できます。詳細については、「[S3 ベクトルバケットでのタグの使用](s3-vectors-tags.md)」を参照してください。
1. **[ベクトルインデックスを作成]** を選択します。
新しいベクトルインデックスがバケット内に表示されることを確認します。
## ステップ 3: SDK for Python (Boto3) を使用してベクトルインデックスにベクトルを挿入する
ベクトルを挿入、一覧表示、クエリするには、AWS SDK、AWS CLI、または Amazon S3 REST API を使用します。
このステップでは、[PutVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_PutVectors.html) API オペレーションを使用してベクトルインデックスにベクトル埋め込みを挿入します。
まず、選択した埋め込みモデルを使用してベクトル埋め込みを生成する必要があります。Amazon Bedrock を使用する場合は、[InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) API オペレーションを使用して任意の埋め込みモデルを指定して埋め込みを生成します。また、単一のコマンドでベクトル埋め込みの生成と挿入を行うには、「[(オプション) S3 Vectors Embed CLI を使用してベクトル埋め込みの作成を自動化する](#s3-vectors-embed-CLI-tutorial)」を参照してください。
以下のコード例では、AWS SDK for Python (Boto3) を使用して Amazon Bedrock から Titan Text Embeddings V2 モデルを使用して 1024 次元のベクトル埋め込みを生成し、`PutVectors` API を使用してベクトルインデックスに保存します。各ベクトルに加えて、キーと値のペアをフィルタリング可能なメタデータとしてアタッチします。さらに、{{source\_text}} という名前のフィルタリングが可能ではないメタデータキーを使用して、各ベクトルが派生する元のテキストを保持します。リクエストスループットを最大化し、速度と効率を最適化するには、ベクトルをバッチで挿入および削除することをお勧めします。詳細については、「[S3 Vectors のベストプラクティス](s3-vectors-best-practices.md)」を参照してください。
```
# Populate a vector index with embeddings 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")
# Texts to convert to embeddings.
texts = [
"Star Wars: A farm boy joins rebels to fight an evil empire in space",
"Jurassic Park: Scientists create dinosaurs in a theme park that goes wrong",
"Finding Nemo: A father fish searches the ocean to find his lost son"
]
# Generate vector embeddings.
embeddings = []
for text in texts:
response = bedrock.invoke_model(
modelId="amazon.titan-embed-text-v2:0",
body=json.dumps({"inputText": text})
)
# Extract embedding from response.
response_body = json.loads(response["body"].read())
embeddings.append(response_body["embedding"])
# Write embeddings into vector index with metadata.
s3vectors.put_vectors(
vectorBucketName="media-embeddings",
indexName="movies",
vectors=[
{
"key": "Star Wars",
"data": {"float32": embeddings[0]},
"metadata": {"source_text": texts[0], "genre":"scifi"}
},
{
"key": "Jurassic Park",
"data": {"float32": embeddings[1]},
"metadata": {"source_text": texts[1], "genre":"scifi"}
},
{
"key": "Finding Nemo",
"data": {"float32": embeddings[2]},
"metadata": {"source_text": texts[2], "genre":"family"}
}
]
)
```
## ステップ 4. SDK for Python (Boto3) を使用し、ベクトルインデックスのベクトルをクエリする
ベクトル埋め込みをベクトルインデックスに保存した後、[QueryVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_QueryVectors.html) API オペレーションを使用して類似度検索を実行できます。
まず、[ステップ 3: SDK for Python (Boto3) を使用してベクトルインデックスにベクトルを挿入する](#s3-vectors-insert-vectors-tutorial) の挿入中に使用されるのと同じ埋め込みモデルを使用して、クエリベクトル埋め込みを生成する必要があります。このチュートリアルでは、SDK for Python (Boto3) を用いて Amazon Bedrock の Titan Text Embeddings V2 モデルを使用します。
類似度検索を実行して、最も近いベクトルを返すことができます。類似度検索では、必要に応じてメタデータキーを使用してフィルタリングし、セマンティックの関連性を維持しながら、特定の条件に基づいて結果を絞り込むことができます。
```
# 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))
```
## (オプション) S3 Vectors Embed CLI を使用してベクトル埋め込みの作成を自動化する
Amazon S3 Vectors Embed CLI は、S3 Vectors でのベクトル埋め込み操作のプロセスを簡素化するスタンドアロンのコマンドラインツールです。単一のコマンドで、Amazon Bedrock を使用したデータのベクトル埋め込みを作成し、S3 ベクトルインデックスへの保存とクエリを実行できます。ツールは、次のコマンドをサポートします。
+ `s3vectors-embed put`: テキスト、ファイルコンテンツ、または S3 オブジェクトのベクトル埋め込みを生成し、S3 ベクトルインデックスにベクトルとして保存します。
+ `s3vectors-embed query`: クエリ入力を埋め込み、S3 ベクトルインデックスの同様のベクトルを検索します。
コマンドと使用の詳細については、「[Amazon S3 Vectors Embed CLI GitHub リポジトリ](https://github.com/awslabs/s3vectors-embed-cli)」を参照してください。
## (オプション) S3 ベクトルと Amazon Bedrock ナレッジベースを統合する
ベクトルデータセットのコスト効率と長期保存のために、Amazon Bedrock ナレッジベースと S3 ベクトルを統合します。
### 前提条件
[前提条件](https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started-console.html)に従い、Amazon Bedrock ナレッジベースを作成するために必要なアクセス許可があることを確認します。
+ S3 Vectors と Amazon Bedrock サービスの両方に対する適切な IAM アクセス許可。S3 Vectors の IAM アクセス許可の詳細については、「[S3 Vectors での ID およびアクセス管理](s3-vectors-access-management.md)」を参照してください。
+ ナレッジベースへの取り込み用に準備されたソースドキュメント。
+ 埋め込みモデルの要件についての理解。
### コンソールで S3 Vectors を使用して Amazon Bedrock ナレッジベースを作成する
Amazon Bedrock ナレッジベースは、フルマネージドのエンドツーエンド RAG ワークフローを提供します。S3 Vectors を使用してナレッジベースを作成すると、Amazon Bedrock は S3 データソースからデータを自動的に取得し、コンテンツをテキストブロックに変換して埋め込みを生成し、ベクトルインデックスに保存します。その後、ナレッジベースをクエリし、ソースデータから取得したチャンクに基づいてレスポンスを生成できます。
**コンソールで S3 Vectors を使用して Amazon Bedrock ナレッジベースを作成するには**
1. [Amazon Bedrock アクセス許可を持つ IAM ロール](https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html)を使用して AWS マネジメントコンソールにサインインし、Amazon Bedrock コンソール ([https://console.aws.amazon.com/bedrock/](https://console.aws.amazon.com/bedrock/)) を開きます。
1. 左側のナビゲーションペインで **[ナレッジベース]** を選択します。
1. **[ナレッジベース]** セクションで、**[作成]** を選択します。ドロップダウンリストで、**[ベクトルストアを含むナレッジベース]** を選択します。
1. このチュートリアルでは、**[ナレッジベース名]**、**[ナレッジベースの説明]**、**[IAM 許可]** をデフォルト値のままにしています。
1. **[データソースタイプを選択してください]** で、ナレッジベースを接続するデータソースを選択します。このチュートリアルでは、**[Amazon S3]** を選択します。
1. (オプション) **[タグ]** または **[アプリケーションログ]** を指定します。
1. [**次へ**] を選択します。
1. このチュートリアルでは、**[データソースを設定]** ページの **[データソース名]**、**[データソースの場所]**、**[解析戦略]**、**[チャンキング戦略]** をデフォルト設定のままにしておきます。
1. **S3 URI** で、ソースファイルを含む S3 汎用バケットを入力するか、**[S3 をブラウズ]** を選択して S3 汎用バケットを選択します。
1. 暗号化された S3 データの場合、**[S3 データのカスタマーマネージド KMS キーを追加]** を選択し、カスタマーマネージド KMS キーを指定します。
1. **[次へ]** を選択して、**[埋め込みモデル]** と **[ベクトルストア]** オプションを指定する次のステップに進みます。
1. **[埋め込みモデル]** セクションで、**[モデルを選択]** を選択し、S3 Vectors との使用に互換性のある埋め込みモデルを選択します。浮動小数点埋め込みを使用する必要があります。バイナリタイプはサポートされていません。
1. (オプション) **[追加設定]** セクションを展開すると、次の設定オプションが表示されます (すべてのモデルがすべての設定をサポートしているわけではありません)。
+ **埋め込みタイプ** – データを浮動小数点 (float32) ベクトル埋め込み (より正確だがコストがかかる) またはバイナリベクトル埋め込み (精度は低下するがコストが低い) に変換するかどうか。S3 ベクトルと統合するには、**[浮動小数点ベクトル埋め込み]** を選択する必要があります。
+ **ベクトルディメンション** – 埋め込みモデルの推奨ディメンションサイズを選択します。
1. **[ベクトルストア]** セクションで、推奨される方法の **[新しいベクトルストアをクイック作成]** を新しいベクトルバケットの自動セットアップに選択するか、または **[既存のベクトルストアを使用]** を選択し、使用できる場合は既存のベクトルバケットを使用します。既存のベクトルストアフローの使用については、「*Amazon Bedrock ユーザーガイド*」の「[Prerequisites for using a vector store you created for a knowledge base](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-setup.html)」を参照してください。
1. **追加設定** - デフォルトでは、ベクトルバケットは Amazon S3 マネージドキーによるサーバー側の暗号化 (SSE-S3) を使用します。AWS Key Management Service キー (SSE-KMS) によるサーバー側の暗号化に独自の KMS キーを使用することを選択して、暗号化設定の制御を強化できます。
1. **[次へ]** を選択してナレッジベースの詳細を確認し、**[ナレッジベースを作成]** を選択します。
**注記**
ナレッジベースの作成にかかる時間は、特定の設定によって異なります。ナレッジベースの作成が完了すると、ナレッジベースのステータスは準備完了または利用可能な状態に変更されます。ナレッジベースの準備ができて使用可能になったら、最初または必要に応じてデータソースの同期が行われ、コンテンツが最新の状態に保たれます。データソースを同期するには、コンソールでナレッジベースを選択し、データソースの概要セクションで **[同期]** を選択します。
## (オプション) S3 ベクトルと Amazon OpenSearch を統合する
[Amazon OpenSearch Service](https://aws.amazon.com/opensearch-service/) は、AWS クラウドにおける OpenSearch のデプロイ、スケーリング、オペレーションを簡素化する完全マネージド型サービスです。S3 Vectors と OpenSearch 間には 2 つの統合があります。1 つは、S3 Vectors から OpenSearch Serverless にベクトルデータをエクスポートして、高性能な検索機能を提供することです。もう 1 つは、S3 Vectors を OpenSearch 内のコスト効率の高いストレージエンジンとして使用し、OpenSearch の機能へのアクセスを維持することです。
詳細については、「[OpenSearch Service での S3 Vectors の使用](s3-vectors-opensearch.md)」を参照してください。