以下のセクションでは、インデックスの構成、作成、一覧表示、削除を行う方法について説明します。
インデックスの概要
インデックスは、エンベディング ベクトルで構成される 1 つまたは複数のファイルです。これらのベクトルは、ベクトル検索でデプロイしてクエリを実行する大量のデータから作成されます。Vector Search では、データでインデックスを更新する方法に応じて 2 種類のインデックスがあります。バッチ アップデート用に設計されたインデックスか、ストリーミング更新用に設計されたインデックスを作成できます。
バッチ インデックスは、毎週または毎月処理されるシステムなど、一定期間にわたって保存されたデータを使用してインデックスをバッチで更新する場合に適しています。ストリーミング インデックスは、データストアに新しいデータが追加されたときに、インデックス データを更新したいときに適しています。たとえば、本屋を経営していて、新しい在庫をできるだけ早くオンラインで表示したい場合などです。設定と要件が異なるため、どちらのタイプを選択するかは重要です。
インデックス パラメータを構成する
インデックスを作成する前に、インデックスのパラメータを構成します。
たとえば、index_metadata.json
という名前のファイルを作成します。
{ "contentsDeltaUri": "gs://BUCKET_NAME/path", "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "shardSize": "SHARD_SIZE_MEDIUM", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 5000, "leafNodesToSearchPercent": 3 } } } }
これらのフィールドの定義については、インデックス構成パラメータをご覧ください。
インデックスを作成する
インデックス サイズ
インデックス データは、シャードと呼ばれる均等な部分に分割されて処理されます。インデックスを作成するときは、使用するシャードのサイズを指定する必要があります。サポートされているサイズは次のとおりです。
SHARD_SIZE_SMALL
: シャードあたり 2 GiB。SHARD_SIZE_MEDIUM
: シャードあたり 20 GiB。SHARD_SIZE_LARGE
: シャードあたり 50 GiB。
インデックスのデプロイに使用できるマシンタイプ(パブリック エンドポイントの使用または VPC エンドポイントの使用を参照)は、インデックスのシャードサイズによって異なります。次の表に、各マシンタイプでサポートされているシャードのサイズを示します。
マシンタイプ | SHARD_SIZE_SMALL |
SHARD_SIZE_MEDIUM |
SHARD_SIZE_LARGE |
---|---|---|---|
n1-standard-16 |
|||
n1-standard-32 |
|||
e2-standard-2 |
(デフォルト) | ||
e2-standard-16 |
(デフォルト) | ||
e2-highmem-16 |
(デフォルト) | ||
n2d-standard-32 |
シャードサイズとマシンタイプが料金にどのように影響するかについては、Vertex AI の料金ページをご覧ください。
バッチ アップデート用のインデックスを作成する
次の手順でインデックスを作成してデプロイします。エンベディングがまだ準備できていない場合は、空のバッチ インデックスを作成するに進んでください。このオプションでは、インデックス作成時にエンベディング データは必要ありません。
インデックスを作成するには:
gcloud
後述のコマンドデータを使用する前に、次のように置き換えます。
- LOCAL_PATH_TO_METADATA_FILE: メタデータ ファイルのローカルパス。
- INDEX_NAME: インデックスの表示名。
- LOCATION: Vertex AI を使用するリージョン。
- PROJECT_ID: Google Cloud プロジェクト ID。
次のコマンドを実行します。
Linux、macOS、Cloud Shell
gcloud ai indexes create \ --metadata-file=LOCAL_PATH_TO_METADATA_FILE \ --display-name=INDEX_NAME \ --region=LOCATION \ --project=PROJECT_ID
Windows(PowerShell)
gcloud ai indexes create ` --metadata-file=LOCAL_PATH_TO_METADATA_FILE ` --display-name=INDEX_NAME ` --region=LOCATION ` --project=PROJECT_ID
Windows(cmd.exe)
gcloud ai indexes create ^ --metadata-file=LOCAL_PATH_TO_METADATA_FILE ^ --display-name=INDEX_NAME ^ --region=LOCATION ^ --project=PROJECT_ID
次のようなレスポンスが返されます。
You can poll for the status of the operation for the response to include "done": true. Use the following example to poll the status. $ gcloud ai operations describe 1234567890123456789 --project=my-test-project --region=us-central1
describe
コマンドの詳細については、gcloud AI オペレーションをご覧ください。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- INPUT_DIR: インデックス コンテンツの Cloud Storage ディレクトリ パス。
- INDEX_NAME: インデックスの表示名。
- LOCATION: Vertex AI を使用するリージョン。
- PROJECT_ID: Google Cloud プロジェクト ID。
- PROJECT_NUMBER: プロジェクトに自動生成されたプロジェクト番号。
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes
リクエストの本文(JSON):
{ "display_name": "INDEX_NAME", "metadata": { "contentsDeltaUri": "INPUT_DIR", "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 500, "leafNodesToSearchPercent": 7 } } } } }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateIndexOperationMetadata", "genericMetadata": { "createTime": "2022-01-08T01:21:10.147035Z", "updateTime": "2022-01-08T01:21:10.147035Z" } } }
Terraform
次のサンプルでは、google_vertex_ai_index
Terraform リソースを使用して、バッチ アップデートのインデックスを作成します。
Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。
Python
Python をインストールまたは更新する方法については、Vertex AI SDK for Python をインストールするをご覧ください。詳細については、Python API リファレンス ドキュメントをご覧ください。
コンソール
バッチ アップデートのインデックスを作成するには、次の操作を使用します。
- Google Cloud コンソールの [Vertex AI] セクションで、[デプロイと使用] セクションに移動します。[ベクトル検索] を選択します。
- [ 新しいインデックスの作成] をクリックして、[インデックス] ペインを開きます。[新しいインデックスの作成] ペインが表示されます。
- [表示名] フィールドに、インデックスを一意に識別する名前を入力します。
- [説明] フィールドに、インデックスの説明を入力します。
- [リージョン] フィールドで、プルダウンからリージョンを選択します。
- [Cloud Storage] フィールドで、ベクトルデータが保存されている Cloud Storage フォルダを検索して選択します。
- [アルゴリズムの種類] プルダウンで、ベクトル検索で効率的な検索に使用されるアルゴリズムの種類を選択します。treeAh アルゴリズムを選択した場合は、近似近傍数を入力します。
- [ディメンション] フィールドに、入力ベクトルの次元数を入力します。
- [更新方法] フィールドで [バッチ] を選択します。
- [シャードのサイズ] フィールドで、目的のシャードサイズをプルダウンから選択します。
- [作成] をクリックします。新しいインデックスが準備できるとリストに表示されます。注: ビルドが完了するまでに 1 時間ほどかかることがあります。
空のバッチ インデックスを作成する
インデックスをすぐに作成してデプロイするには、空のバッチ インデックスを作成します。このオプションでは、インデックス作成時にエンベディング データは必要ありません。
空のインデックスを作成するためのリクエストは、バッチ更新用のインデックスを作成する場合とほぼ同じです。異なるのは、データ ロケーションをリンクしないため contentsDeltaUri
フィールドを削除する点です。次に、空のバッチ インデックスの例を示します。
空のインデックス リクエストの例
{ "display_name": INDEX_NAME, "indexUpdateMethod": "BATCH_UPDATE", "metadata": { "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 500, "leafNodesToSearchPercent": 7 } } } } }
ストリーミング更新用のインデックスを作成する
ストリーミング インデックスを作成してデプロイする手順は次のとおりです。エンベディングの準備ができていない場合は、ストリーミング更新用の空のインデックスを作成するに進みます。このオプションでは、インデックス作成時にエンベディング データは必要ありません。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- INDEX_NAME: インデックスの表示名。
- DESCRIPTION: インデックスの説明。
- INPUT_DIR: インデックス コンテンツの Cloud Storage ディレクトリ パス。
- DIMENSIONS: エンベディング ベクトルの次元数。
- PROJECT_ID: Google Cloud プロジェクト ID。
- PROJECT_NUMBER: プロジェクトに自動生成されたプロジェクト番号。
- LOCATION: Vertex AI を使用するリージョン。
HTTP メソッドと URL:
POST https://ENDPOINT-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes
リクエストの本文(JSON):
{ displayName: "INDEX_NAME", description: "DESCRIPTION", metadata: { contentsDeltaUri: "INPUT_DIR", config: { dimensions: "DIMENSIONS", approximateNeighborsCount: 150, distanceMeasureType: "DOT_PRODUCT_DISTANCE", algorithmConfig: {treeAhConfig: {leafNodeEmbeddingCount: 10000, leafNodesToSearchPercent: 2}} }, }, indexUpdateMethod: "STREAM_UPDATE" }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.ui.CreateIndexOperationMetadata", "genericMetadata": { "createTime": "2023-12-05T23:17:45.416117Z", "updateTime": "2023-12-05T23:17:45.416117Z", "state": "RUNNING", "worksOn": [ "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID" ] } } }
コンソール
Google Cloud コンソールでストリーミング更新用のインデックスを作成するには、次の操作を使用します。
ストリーミング アップデートで使用可能なインデックスを作成するには、バッチ アップデート用インデックスの設定と同様の操作を行う必要があります。ただし、STREAM_UPDATE
を indexUpdateMethod
に設定する必要があります。
- Google Cloud コンソールの [Vertex AI] セクションで、[デプロイと使用] セクションに移動します。[ベクトル検索] を選択します。
- [ 新しいインデックスの作成] をクリックして、[インデックス] ペインを開きます。[新しいインデックスの作成] ペインが表示されます。
- [表示名] フィールドに、インデックスを一意に識別する名前を入力します。
- [説明] フィールドに、インデックスの説明を入力します。
- [リージョン] フィールドで、プルダウンからリージョンを選択します。
- [Cloud Storage] フィールドで、ベクトルデータが保存されている Cloud Storage フォルダを検索して選択します。
- [アルゴリズムの種類] プルダウンで、ベクトル検索で検索に使用するアルゴリズムの種類を選択します。treeAh アルゴリズムを選択した場合は、近似近傍数を入力します。
- [ディメンション] フィールドに、入力ベクトルの次元数を入力します。
- [更新方法] フィールドで [ストリーム] を選択します。
- [シャードのサイズ] フィールドで、目的のシャードサイズをプルダウンから選択します。
- [作成] をクリックします。新しいインデックスが準備できるとリストに表示されます。注: ビルドが完了するまでに 1 時間ほどかかることがあります。
Python
Python をインストールまたは更新する方法については、Vertex AI SDK for Python をインストールするをご覧ください。詳細については、Python API リファレンス ドキュメントをご覧ください。
ストリーミング更新用の空のインデックスを作成する
インデックスをすぐに作成してデプロイするには、ストリーミング用の空のインデックスを作成します。このオプションでは、インデックス作成時にエンベディング データは必要ありません。
空のインデックスを作成するためのリクエストは、ストリーミング用のインデックスを作成する場合とほぼ同じです。異なるのは、データ ロケーションをリンクしないため contentsDeltaUri
フィールドを削除する点です。次に、空のストリーミング インデックスの例を示します。
空のインデックス リクエストの例
{ "display_name": INDEX_NAME, "indexUpdateMethod": "STREAM_UPDATE", "metadata": { "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 500, "leafNodesToSearchPercent": 7 } } } } }
インデックスを一覧表示する
gcloud
後述のコマンドデータを使用する前に、次のように置き換えます。
- INDEX_NAME: インデックスの表示名。
- LOCATION: Vertex AI を使用するリージョン。
- PROJECT_ID: Google Cloud プロジェクト ID。
次のコマンドを実行します。
Linux、macOS、Cloud Shell
gcloud ai indexes list \ --region=LOCATION \ --project=PROJECT_ID
Windows(PowerShell)
gcloud ai indexes list ` --region=LOCATION ` --project=PROJECT_ID
Windows(cmd.exe)
gcloud ai indexes list ^ --region=LOCATION ^ --project=PROJECT_ID
次のようなレスポンスが返されます。
You can poll for the status of the operation for the response to include "done": true. Use the following example to poll the status. $ gcloud ai operations describe 1234567890123456789 --project=my-test-project --region=us-central1
describe
コマンドの詳細については、gcloud AI オペレーションをご覧ください。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- INDEX_NAME: インデックスの表示名。
- LOCATION: Vertex AI を使用するリージョン。
- PROJECT_ID: Google Cloud プロジェクト ID。
- PROJECT_NUMBER: プロジェクトに自動生成されたプロジェクト番号。
HTTP メソッドと URL:
GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "indexes": [ { "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID", "displayName": "INDEX_NAME", "metadataSchemaUri": "gs://google-cloud-aiplatform/schema/matchingengine/metadata/nearest_neighbor_search_1.0.0.yaml", "metadata": { "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "featureNormType": "NONE", "algorithmConfig": { "treeAhConfig": { "maxLeavesToSearch": 50, "leafNodeCount": 10000 } } } }, "etag": "AMEw9yNU8YX5IvwuINeBkVv3yNa7VGKk11GBQ8GkfRoVvO7LgRUeOo0qobYWuU9DiEc=", "createTime": "2020-11-08T21:56:30.558449Z", "updateTime": "2020-11-08T22:39:25.048623Z" } ] }
コンソール
インデックスのリストを表示するには、次の操作を使用します。
- Google Cloud コンソールの [Vertex AI] セクションで、[デプロイと使用] セクションに移動します。[ベクトル検索] を選択します。
- アクティブなインデックスのリストが表示されます。
インデックスの調整
インデックスをチューニングするには、デプロイされたインデックスのパフォーマンス(特に再現率とレイテンシ)に影響する構成パラメータを設定する必要があります。これらのパラメータは、最初にインデックスを作成したときに設定しています。ブルート フォース インデックスを使用して、再現率を測定できます。
パフォーマンスに影響する構成パラメータ
次の構成パラメータはインデックス作成時に設定できます。ベクトル検索を使用する場合、再現率、レイテンシ、可用性、コストに影響する可能性があります。このガイダンスはほとんどのケースに適用されます。ただし、必ず構成をテストして、ユースケースに適していることを確認してください。
パラメータの定義については、インデックス構成パラメータをご覧ください。
パラメータ | 概要 | パフォーマンスへの影響 |
---|---|---|
shardSize
|
各マシン上のデータ量を制御します。 シャードのサイズを選択する際は、将来のデータセットのサイズを推定します。データセットのサイズに上限がある場合は、それに適したシャードサイズを選択します。上限がない場合や、レイテンシの変動に影響を受けやすいユースケースの場合は、大きなシャードサイズを選択することをおすすめします。 |
シャードのサイズを小さくしてシャード数を増やすと、検索時に処理される候補結果の数が多くなります。シャード数が多いと、次のようにパフォーマンスに影響します。
シャードのサイズを大きくしてシャード数を減らすと、検索時に処理される候補結果が少なくなります。シャード数が少ないと、次のようにパフォーマンスに影響する可能性があります。
|
distanceMeasureType
|
データポイントとクエリベクトルの間の距離の計算に使用するアルゴリズムを決定します。 |
次の
|
leafNodeEmbeddingCount
|
各リーフノードの埋め込み数。デフォルトでは 1000 に設定されています。
通常、 |
各リーフノードの埋め込み数を増やすと、レイテンシは短くなりますが、再現率は低下します。これにより、次のようにパフォーマンスに影響する可能性があります。
各リーフノードの埋め込み数を減らすと、パフォーマンスに次のような影響が生じる可能性があります。
|
ブルート フォース インデックスを使用した再現率の測定
確な最近傍を取得するには、ブルート フォース アルゴリズムのインデックスを使用します。ブルート フォース アルゴリズムを使用すると、レイテンシは高くなりますが、100% の再現率を達成できます。ブルート フォース インデックスを使用して再現率を測定する方法は、本番環境サービスに適していませんが、さまざまなインデックス登録オプションの再現率をオフラインで評価するのに役立ちます。
ブルート フォース アルゴリズムを使用してインデックスを作成するには、インデックス メタデータに brute_force_config
を指定します。
curl -X POST -H "Content-Type: application/json" \ -H "Authorization: Bearer `gcloud auth print-access-token`" \ https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexes \ -d '{ displayName: "'${DISPLAY_NAME}'", description: "'${DESCRIPTION}'", metadata: { contentsDeltaUri: "'${INPUT_DIR}'", config: { dimensions: 100, approximateNeighborsCount: 150, distanceMeasureType: "DOT_PRODUCT_DISTANCE", featureNormType: "UNIT_L2_NORM", algorithmConfig: { bruteForceConfig: {} } }, }, }'
インデックスを削除する
gcloud
後述のコマンドデータを使用する前に、次のように置き換えます。
- INDEX_ID: インデックスの ID。
- LOCATION: Vertex AI を使用するリージョン。
- PROJECT_ID: Google Cloud プロジェクト ID。
次のコマンドを実行します。
Linux、macOS、Cloud Shell
gcloud ai indexes delete INDEX_ID \ --region=LOCATION \ --project=PROJECT_ID
Windows(PowerShell)
gcloud ai indexes delete INDEX_ID ` --region=LOCATION ` --project=PROJECT_ID
Windows(cmd.exe)
gcloud ai indexes delete INDEX_ID ^ --region=LOCATION ^ --project=PROJECT_ID
REST
リクエストのデータを使用する前に、次のように置き換えます。
- INDEX_ID: インデックスの ID。
- LOCATION: Vertex AI を使用するリージョン。
- PROJECT_ID: Google Cloud プロジェクト ID。
- PROJECT_NUMBER: プロジェクトに自動生成されたプロジェクト番号。
HTTP メソッドと URL:
DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeleteOperationMetadata", "genericMetadata": { "createTime": "2022-01-08T02:35:56.364956Z", "updateTime": "2022-01-08T02:35:56.364956Z" } }, "done": true, "response": { "@type": "type.googleapis.com/google.protobuf.Empty" } }
コンソール
1 つ以上のインデックスを削除するには、次の操作を行います。
- Google Cloud コンソールの [Vertex AI] セクションで、[デプロイと使用] セクションに移動します。[ベクトル検索] を選択します。
- アクティブなインデックスのリストが表示されます。
- インデックスを削除するには、インデックスと同じ行にある [ オプション] メニューに移動して、[削除] を選択します。
次のステップ
- インデックス構成パラメータについて学習する
- パブリック インデックス エンドポイントをデプロイして管理する方法を学習する
- VPC ネットワークにインデックス エンドポイントをデプロイして管理する方法を学習する
- インデックスの更新と再構築の方法を学習する
- インデックスのモニタリング方法を学習する