このガイドでは、ベクトル類似検索を行うために Vertex AI Matching Engine をどのように構成して使用できるかを説明します。
VPC ネットワーク ピアリング接続を設定する
ベクトル マッチングのオンライン クエリのネットワーク レイテンシを短縮するには、プライベート サービス アクセスを使用して、Virtual Private Cloud(VPC)から Vertex AI サービス エンドポイントを呼び出します。各 Google Cloud プロジェクトで、Matching Engine とピアリングできる VPC ネットワークは 1 つだけです。プライベート サービス アクセスが構成された VPC がすでにある場合は、その VPC を使用して Vertex AI Matching Engine とピアリングできます。
VPC ネットワーク ピアリング接続の構成は、Google Cloud プロジェクトごとに 1 回だけ必要となる初期タスクです。この設定が完了すると、VPC 内で実行されている任意のクライアントから Matching Engine インデックスを呼び出すことができます。
VPC ネットワーク ピアリング接続は、ベクトル マッチングのオンライン クエリにのみ必要です。インデックスの作成、デプロイ、削除を行うための API 呼び出しで VPC ネットワーク ピアリング接続は必要ありません。
次の手順は、Cloud プロジェクト管理者またはネットワーク管理者が行う必要があります。
Cloud プロジェクトの設定、課金の有効化、API の有効化を行うには、以下の始める前に手順を完了します。
VPC ネットワークとサービス プロデューサーのネットワーク間の IP アドレスの競合を回避するには、Matching Engine のインデックスがデプロイされている Matching Engine サービスに IP アドレス範囲を割り振る必要があります。詳細については、IP アドレス範囲の割り振りをご覧ください。
# Note: `prefix-length=16` means a CIDR block with mask /16 is reserved for # use by Google services. Make sure to enable the Service Networking API. gcloud compute addresses create $PEERING_RANGE_NAME \ --global \ --prefix-length=16 \ --description="peering range for Matching Engine service" \ --network=$NETWORK_NAME \ --purpose=VPC_PEERING \ --project=$PROJECT_ID
# Create the VPC connection. gcloud services vpc-peerings connect \ --service=servicenetworking.googleapis.com \ --network=$NETWORK_NAME \ --ranges=$PEERING_RANGE_NAME \ --project=$PROJECT_ID
プライベート接続を作成したら、ピアリングした VPC 内で実行されている任意の仮想マシン(VM)インスタンスから、Matching Engine のインデックスをオンラインで呼び出すことができます。
サンプル ノートブック
VPC ネットワーク ピアリングの初期設定が完了したら、その VPC 内にユーザー管理のノートブック インスタンスを作成し、ノートブックからコマンドを発行できます。
Vertex AI Workbench でサンプル ノートブックを起動するか、GitHub でノートブックを表示します。
IAM によるアクセス制御
Vertex AI は、Identity and Access Management(IAM)を使用してリソースへのアクセスを管理します。リソースへのアクセス権を付与するには、ユーザー、グループ、またはサービス アカウントに 1 つ以上のロールを割り当てます。
Matching Engine を使用するには、これらの事前定義ロールを使用して、プロジェクト単位でリソースに対するさまざまなレベルのアクセス権を付与します。
入力データの形式と構造
新しいインデックスの作成や既存のインデックスの更新を行うには、以下のセクションで説明する形式と構造のベクトルを Matching Engine に提供します。
入力データのストレージ
入力データを Cloud プロジェクトの Cloud Storage バケットに保存します。
入力ディレクトリの構造
入力データ ディレクトリを次のように構造化します。
- バッチのルート ディレクトリ: 入力データファイルのバッチごとにルート ディレクトリを作成します。単一の Cloud Storage ディレクトリをルート ディレクトリとして使用します。次の例で、ルート ディレクトリの名前は
batch_root
です。 ファイルの命名: 個々のデータファイルを
batch_root
の直下に配置します。使用するファイル形式に応じて接尾辞.csv
、.json
、または.avro
を使用して、ファイル名を設定します。Matching Engine は、各データファイルをレコードのセットとして解釈します。
レコードの形式は、ファイル名の接尾辞によって決まります。詳しくは、次のセクションをご覧ください。
各レコードには ID と特徴ベクトルが必要です。また、必要に応じて制限やクラウディングなどの追加フィールドも指定できます。
delete ディレクトリ:
batch_root
の下にdelete
サブディレクトリを作成できます。このディレクトリは省略可能です。batch_root/delete
の直下にある各ファイルは、レコード ID のテキスト ファイルであり、各行には 1 つの ID が含まれます。各 ID には有効な UTF-8 文字列を指定する必要があります。
その他のディレクトリとファイルはすべて無視されます。
すべてのデータファイルのすべてのレコード(
delete
にあるものを含む)から 1 つの入力バッチが構成されます。データファイル内のレコードの相対的な順序は重要ではありません。1 つの ID は、1 つのバッチにつき 1 回しか使用できません。
- 注: 通常のデータファイルと
delete
データファイルの両方で ID を指定することはできません。
- 注: 通常のデータファイルと
delete
の下にあるデータファイルのすべての ID が、次のインデックス バージョンから削除されます。通常のデータファイルからのレコードは次のバージョンに含まれます。インデックスの古いバージョンの値は上書きされる可能性があります。
データファイルの形式
データファイルの形式は CSV、JSON、または Avro です。
CSV
- UTF-8 を使用してファイルをエンコードします。
- 各行が 1 つのレコードとして解釈されるように、有効な CSV にします。
- 最初の値を
id
にし、id
を有効な UTF-8 文字列にします。 - 次の N 個の値を特徴ベクトルの次元にします。これは、インデックスの作成時に構成されます。Java 言語仕様で定義されているように、それぞれの値を浮動小数点リテラルにします。
JSON
- UTF-8 を使用してファイルをエンコードします。
- 各行がレコードとして解釈されるように、有効な JSON オブジェクトにします。
- 各レコードに
id
という名前のフィールドを含めます。この値は、ベクトルの ID となる有効な UTF-8 文字列にする必要があります。 - 各レコードに、
embedding
という名前のフィールドを含めます。この値は、数値の配列にする必要があります。これは特徴ベクトルです。
AVRO
- 有効な Avro ファイルを使用します。
次のスキーマに準拠するレコードを作成します。
{ "type": "record", "name": "FeatureVector", "fields": [ { "name": "id", "type": "string" }, { "name": "embedding", "type": { "type": "array", "items": "float" } }, { "name": "restricts", "type": [ "null", { "type": "array", "items": { "type": "record", "name": "Restrict", "fields": [ { "name": "namespace", "type": "string" }, { "name": "allow", "type": [ "null", { "type": "array", "items": "string" } ] }, { "name": "deny", "type": [ "null", { "type": "array", "items": "string" } ] } ] } } ] }, { "name": "crowding_tag", "type": [ "null", "string" ] } ] }
インデックスの管理
以下のセクションでは、インデックスの作成、削除、更新を行う方法について説明します。詳細については、インデックスに関する API ドキュメントをご覧ください。
インデックス メタデータ ファイル
インデックスを作成する前に、インデックスのパラメータを構成する必要があります。
例として、index_metadata.json
という名前のファイルを作成します。
{ "contentsDeltaUri": "gs://BUCKET_NAME/path", "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 500, "leafNodesToSearchPercent": 7 } } } }
これらの各フィールドの定義については、インデックスの構成または次のスキーマ内の定義をご覧ください。
title: NearestNeighborSearch
type: object
properties:
contentsDeltaUri:
type: string
description: >
Allows inserting, updating or deleting the contents of the Matching Engine Index.
The string must be a valid Cloud Storage directory path. If this
field is set when calling IndexService.UpdateIndex, then no other
Index field can be also updated as part of the same call.
The expected structure and format of the files this URI points to is
described at https://cloud.google.com/vertex-ai/docs/matching-engine/using-matching-engine#input-data-format
writeOnly: true
isCompleteOverwrite:
type: boolean
description: >
If this field is set together with contentsDeltaUri when calling IndexService.UpdateIndex,
then existing content of the Index will be replaced by the data from the contentsDeltaUri.
default: false
config:
type: object
description: >
The configuration of the Matching Engine Index.
required:
- dimensions
- algorithmConfig
properties:
dimensions:
type: integer
format: int32
description: >
The number of dimensions of the input vectors.
approximateNeighborsCount:
type: integer
format: int32
description: >
The default number of neighbors to find via approximate search before exact reordering is
performed. Exact reordering is a procedure where results returned by an
approximate search algorithm are reordered via a more expensive distance computation.
Required if tree-AH algorithm is used.
distanceMeasureType:
description: >
The distance measure used in nearest neighbor search.
oneOf:
- enum: [SQUARED_L2_DISTANCE]
description: >
Euclidean (L_2) Distance
- enum: [L1_DISTANCE]
description: >
Manhattan (L_1) Distance
- enum: [COSINE_DISTANCE]
description: >
Cosine Distance. Defined as 1 - cosine similarity.
- enum: [DOT_PRODUCT_DISTANCE]
description: >
Dot Product Distance. Defined as a negative of the dot product
default: DOT_PRODUCT_DISTANCE
featureNormType:
description: >
Type of normalization to be carried out on each vector.
oneOf:
- enum: [UNIT_L2_NORM]
description: >
Unit L2 normalization type.
- enum: [NONE]
description: >
No normalization type is specified.
default: NONE
algorithmConfig:
description: >
The configuration with regard to the algorithms used for efficient search.
oneOf:
- type: object
description: >
Configuration options for using the tree-AH algorithm (Shallow tree + Asymmetric Hashing).
Please refer to this paper for more details: https://arxiv.org/abs/1908.10396
properties:
type:
type: string
enum: [treeAhConfig]
leafNodeEmbeddingCount:
type: integer
format: int64
description: >
Number of embeddings on each leaf node. The default value is 1000 if not set.
leafNodesToSearchPercent:
type: number
format: int32
description: >
The default percentage of leaf nodes that any query may be searched. Must be in
range 1-100, inclusive. The default value is 10 (means 10%) if not set.
- type: object
description: >
Configuration options for using brute force search, which simply implements the
standard linear search in the database for each query.
properties:
type:
type: string
enum: [bruteForceConfig]
discriminator:
propertyName: type
このメタデータ スキーマ ファイルは、Cloud Storage からダウンロードできます。
インデックスの作成
インデックスを作成するには:
gcloud
gcloud ai indexes create \
--metadata-file=LOCAL_PATH_TO_METADATA_FILE \
--display-name=INDEX_NAME \
--project=PROJECT_ID \
--region=LOCATION
次のように置き換えます。
- LOCAL_PATH_TO_METADATA_FILE: メタデータ ファイルのローカル ファイル パス。
- INDEX_NAME: インデックスの表示名。
- PROJECT_ID: プロジェクトの ID
- LOCATION: Vertex AI を使用するリージョン。
REST とコマンドライン
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION: 使用するリージョン。
- PROJECT: プロジェクト ID またはプロジェクト番号。
- INDEX_NAME: インデックスの表示名。
- INPUT_DIR: インデックス コンテンツの Cloud Storage ディレクトリ パス。
- PROJECT_NUMBER: プロジェクトのプロジェクト番号(レスポンスに表示される)
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/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" } } }
"done": true
が表示されるまで、オペレーションのステータスをポーリングできます。インデックスの一覧表示
gcloud
gcloud ai indexes list
コマンドを使用します。
gcloud ai indexes list \
--project=PROJECT_ID \
--region=LOCATION
次のように置き換えます。
- PROJECT_ID: プロジェクトの ID
- LOCATION: Vertex AI を使用するリージョン。
REST とコマンドライン
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION: 使用するリージョン。
- PROJECT: プロジェクト ID またはプロジェクト番号。
- INDEX_NAME: インデックスの表示名。
- PROJECT_NUMBER: プロジェクトのプロジェクト番号(レスポンスに表示される)
HTTP メソッドと URL:
GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/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" } ] }
インデックスの内容の更新
既存の Index
の内容を更新するには、IndexService.UpdateIndex
メソッドを使用します。
Index
の既存の内容を置き換えるには:
Index.metadata.contentsDeltaUri
を、更新するベクトルを含む Cloud Storage URI に設定します。isCompleteOverwrite
を true に設定します。
IndexService.UpdateIndex
の呼び出し時に contentsDeltaUri
フィールドが設定されている場合、他のインデックス フィールド(displayName
、description
、userLabels
など)は同じ呼び出しでは更新できません。
gcloud
gcloud ai indexes update INDEX_ID \
--metadata-file=LOCAL_PATH_TO_METADATA_FILE \
--project=PROJECT_ID \
--region=LOCATION
次のように置き換えます。
- INDEX_ID: インデックスの ID。
- LOCAL_PATH_TO_METADATA_FILE: メタデータ ファイルのローカル ファイル パス。
- PROJECT_ID: プロジェクトの ID
- LOCATION: Vertex AI を使用するリージョン。
REST とコマンドライン
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION: 使用するリージョン。
- PROJECT: プロジェクト ID またはプロジェクト番号。
- INPUT_DIR: インデックス コンテンツの Cloud Storage ディレクトリ パス。
- PROJECT_NUMBER: プロジェクトのプロジェクト番号(レスポンスに表示される)
HTTP メソッドと URL:
PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexes/INDEX_ID
JSON 本文のリクエスト:
{ "metadata": { "contentsDeltaUri": "INPUT_DIR", "isCompleteOverwrite": true } }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UpdateIndexOperationMetadata", "genericMetadata": { "createTime": "2022-01-12T23:56:14.480948Z", "updateTime": "2022-01-12T23:56:14.480948Z" } } }
"done": true
が表示されるまで、オペレーションのステータスをポーリングできます。Index
に関連するデプロイがある場合(Index.deployed_indexes
フィールドを参照)、元の Index
への特定の変更が完了すると、その変更を反映するため、バックグラウンドで非同期的に DeployedIndex
が自動更新されます。
変更が伝播されたかどうかを確認するには、更新インデックス オペレーションの終了時間と DeployedIndex.index_sync_time
を比較します。
インデックスを削除する
すべての Index.deployed_indexes
のデプロイを解除するまで、その Index
は削除できません。
gcloud
gcloud ai indexes delete
コマンドを使用します。
gcloud ai indexes delete INDEX_ID \
--project=PROJECT_ID \
--region=LOCATION
次のように置き換えます。
- INDEX_ID: インデックスの ID。
- PROJECT_ID: プロジェクトの ID
- LOCATION: Vertex AI を使用するリージョン。
REST とコマンドライン
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION: 使用するリージョン。
- PROJECT: プロジェクト ID またはプロジェクト番号。
- INDEX_ID: インデックスの ID。
- PROJECT_NUMBER: プロジェクトのプロジェクト番号(レスポンスに表示される)
HTTP メソッドと URL:
DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/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" } }
インデックスのデプロイと管理
インデックスのデプロイには、次の 3 つのタスクがあります。
- 必要に応じて
IndexEndpoint
を作成するか、既存のIndexEndpoint
を再利用します。 IndexEndpoint
ID を取得します。- インデックスを
IndexEndpoint
にデプロイします。
VPC ネットワーク内での IndexEndpoint
の作成
Index
を既存の IndexEndpoint
にデプロイする場合は、この手順をスキップできます。
インデックスを使用してベクトル マッチングのオンライン クエリを実行する前に、VPC ネットワークのピアリング ネットワーク内の IndexEndpoint
に Index
をデプロイする必要があります。まず、IndexEndpoint
を作成します。同じ VPC ネットワークを共有する IndexEndpoint
には、複数のインデックスをデプロイできます。
gcloud
次の例では、gcloud ai index-endpoints create
コマンドを使用します。
gcloud ai index-endpoints create \
--display-name=INDEX_ENDPOINT_NAME \
--network=VPC_NETWORK_NAME \
--project=PROJECT_ID \
--region=LOCATION
次のように置き換えます。
- INDEX_ENDPOINT_NAME: インデックス エンドポイントの表示名。
- VPC_NETWORK_NAME: インデックス エンドポイントのピアリング先となる Google Compute Engine ネットワーク名。
- PROJECT_ID: プロジェクトの ID
- LOCATION: Vertex AI を使用するリージョン。
Google Cloud CLI ツールで IndexEndpoint
が作成されるまでに数分かかることがあります。
REST とコマンドライン
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION: 使用するリージョン。
- PROJECT: プロジェクト ID またはプロジェクト番号。
- INDEX_ENDPOINT_NAME: インデックス エンドポイントの表示名。
- VPC_NETWORK_NAME: インデックス エンドポイントのピアリング先となる Google Compute Engine ネットワーク名。
- PROJECT_NUMBER: プロジェクトのプロジェクト番号(レスポンスに表示される)
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints
JSON 本文のリクエスト:
{ "display_name": "INDEX_ENDPOINT_NAME", "network": "VPC_NETWORK_NAME" }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateIndexEndpointOperationMetadata", "genericMetadata": { "createTime": "2022-01-13T04:09:56.641107Z", "updateTime": "2022-01-13T04:09:56.641107Z" } } }
"done": true
が表示されるまで、オペレーションのステータスをポーリングできます。インデックスのデプロイ
gcloud
次の例では、gcloud ai index-endpoints deploy-index
コマンドを使用します。
gcloud ai index-endpoints deploy-index INDEX_ENDPOINT_ID \
--deployed-index-id=DEPLOYED_INDEX_ID \
--display-name=DEPLOYED_INDEX_NAME \
--index=INDEX_ID \
--project=PROJECT_ID \
--region=LOCATION
次のように置き換えます。
- INDEX_ENDPOINT_ID: インデックス エンドポイントの ID。
- DEPLOYED_INDEX_ID: デプロイされたインデックスの ID。
- DEPLOYED_INDEX_NAME: デプロイされたインデックスの表示名。
- INDEX_ID: インデックスの ID。
- PROJECT_ID: プロジェクトの ID
- LOCATION: Vertex AI を使用するリージョン。
REST とコマンドライン
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION: Vertex AI を使用するリージョン。
- PROJECT: プロジェクト ID またはプロジェクト番号。
- INDEX_ENDPOINT_ID: インデックス エンドポイントの ID。
- DEPLOYED_INDEX_ID: デプロイされたインデックスの ID。
- DEPLOYED_INDEX_NAME: デプロイされたインデックスの表示名。
- INDEX_ID: インデックスの ID。
- PROJECT_NUMBER: プロジェクトのプロジェクト番号(レスポンスに表示される)
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:deployIndex
JSON 本文のリクエスト:
{ "deployedIndex": { "id": "DEPLOYED_INDEX_ID", "index": "projects/PROJECT/locations/LOCATION/indexes/INDEX_ID", "displayName": "DEPLOYED_INDEX_NAME" } }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_ID/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployIndexOperationMetadata", "genericMetadata": { "createTime": "2020-10-19T17:53:16.502088Z", "updateTime": "2020-10-19T17:53:16.502088Z" }, "deployedIndexId": "DEPLOYED_INDEX_ID" } }
"done": true
が表示されるまで、オペレーションのステータスをポーリングできます。自動スケーリングを有効にする
Matching Engine は自動スケーリングをサポートしており、ワークロードの需要に応じてノード数を自動的に変更できます。需要が高い場合、ノードがノードプールに追加されます。指定した最大サイズを超えることはありません。需要が少ない場合、ノードプールは指定した最小サイズにスケールダウンされます。使用中の実際のノードと変更は、現在のレプリカをモニタリングすることで確認できます。
自動スケーリングを有効にするには、インデックスをデプロイするときに maxReplicaCount
と minReplicaCount
を指定します。
gcloud
次の例では、gcloud ai index-endpoints deploy-index
コマンドを使用します。
gcloud ai index-endpoints deploy-index INDEX_ENDPOINT_ID \
--deployed-index-id=DEPLOYED_INDEX_ID \
--display-name=DEPLOYED_INDEX_NAME \
--index=INDEX_ID \
--min-replica-count=MIN_REPLICA_COUNT \
--max-replica-count=MAX_REPLICA_COUNT \
--project=PROJECT_ID \
--region=LOCATION
次のように置き換えます。
- INDEX_ENDPOINT_ID: インデックス エンドポイントの ID。
- DEPLOYED_INDEX_ID: デプロイされたインデックスの ID。
- DEPLOYED_INDEX_NAME: デプロイされたインデックスの表示名。
- INDEX_ID: インデックスの ID。
- MIN_REPLICA_COUNT: デプロイされたインデックスが常にデプロイされるマシンレプリカの最小数。指定する場合、値は 1 以上にする必要があります。
- MAX_REPLICA_COUNT: デプロイされたインデックスをデプロイ可能なマシンレプリカの最大数。
- PROJECT_ID: プロジェクトの ID
- LOCATION: Vertex AI を使用するリージョン。
REST とコマンドライン
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION: Vertex AI を使用するリージョン。
- PROJECT: プロジェクト ID またはプロジェクト番号。
- INDEX_ENDPOINT_ID: インデックス エンドポイントの ID。
- DEPLOYED_INDEX_ID: デプロイされたインデックスの ID。
- DEPLOYED_INDEX_NAME: デプロイされたインデックスの表示名。
- INDEX_ID: インデックスの ID。
- MIN_REPLICA_COUNT: デプロイされたインデックスが常にデプロイされるマシンレプリカの最小数。指定する場合、値は 1 以上にする必要があります。
- MAX_REPLICA_COUNT: デプロイされたインデックスをデプロイ可能なマシンレプリカの最大数。
- PROJECT_NUMBER: プロジェクトのプロジェクト番号(レスポンスに表示される)
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:deployIndex
JSON 本文のリクエスト:
{ "deployedIndex": { "id": "DEPLOYED_INDEX_ID", "index": "projects/PROJECT/locations/LOCATION/indexes/INDEX_ID", "displayName": "DEPLOYED_INDEX_NAME", "automaticResources": { "minReplicaCount": MIN_REPLICA_COUNT, "maxReplicaCount": MAX_REPLICA_COUNT } } }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_ID/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployIndexOperationMetadata", "genericMetadata": { "createTime": "2020-10-19T17:53:16.502088Z", "updateTime": "2020-10-19T17:53:16.502088Z" }, "deployedIndexId": "DEPLOYED_INDEX_ID" } }
"done": true
が表示されるまで、オペレーションのステータスをポーリングできます。minReplicaCount
とmaxReplicaCount
の両方とも設定されていない場合、この 2 つはデフォルトで 2 に設定されます。maxReplicaCount
のみが設定されている場合、minReplicaCount
はデフォルトで 2 に設定されます。minReplicaCount
のみが設定されている場合、maxReplicaCount
の値はminReplicaCount
と一致します。
DeployedIndex
を変更する
MutateDeployedIndex
API を使用すると、すでにデプロイされているインデックスのデプロイ リソース(minReplicaCount
、maxReplicaCount
など)を更新できます。
- インデックスのデプロイ後にユーザーが
machineType
を変更することはできません。 - リクエストで
maxReplicaCount
が指定されていない場合、DeployedIndex
は既存のmaxReplicaCount
を引き続き使用します。
gcloud
次の例では、gcloud ai index-endpoints mutate-deployed-index
コマンドを使用します。
gcloud ai index-endpoints mutate-deployed-index INDEX_ENDPOINT_ID \
--deployed-index-id=DEPLOYED_INDEX_ID \
--min-replica-count=MIN_REPLICA_COUNT \
--max-replica-count=MAX_REPLICA_COUNT \
--project=PROJECT_ID \
--region=LOCATION
次のように置き換えます。
- INDEX_ENDPOINT_ID: インデックス エンドポイントの ID。
- DEPLOYED_INDEX_ID: デプロイされたインデックスの ID。
- MIN_REPLICA_COUNT: デプロイされたインデックスが常にデプロイされるマシンレプリカの最小数。指定する場合、値は 1 以上にする必要があります。
- MAX_REPLICA_COUNT: デプロイされたインデックスをデプロイ可能なマシンレプリカの最大数。
- PROJECT_ID: プロジェクトの ID
- LOCATION: Vertex AI を使用するリージョン。
REST とコマンドライン
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION: Vertex AI を使用するリージョン。
- PROJECT: プロジェクト ID またはプロジェクト番号。
- INDEX_ENDPOINT_ID: インデックス エンドポイントの ID。
- DEPLOYED_INDEX_ID: デプロイされたインデックスの ID。
- MIN_REPLICA_COUNT: デプロイされたインデックスが常にデプロイされるマシンレプリカの最小数。指定する場合、値は 1 以上にする必要があります。
- MAX_REPLICA_COUNT: デプロイされたインデックスをデプロイ可能なマシンレプリカの最大数。
- PROJECT_NUMBER: プロジェクトのプロジェクト番号(レスポンスに表示される)
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:mutateDeployedIndex
JSON 本文のリクエスト:
{ "id": "DEPLOYED_INDEX_ID", "automaticResources": { "minReplicaCount": MIN_REPLICA_COUNT, "maxReplicaCount": MAX_REPLICA_COUNT } }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_ID/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.MutateDeployedIndexOperationMetadata", "genericMetadata": { "createTime": "2022-01-24T20:36:37.902782Z", "updateTime": "2022-01-24T20:36:37.902782Z" }, "deployedIndexId": "gcloud_deployed_index_2" } }
"done": true
が表示されるまで、オペレーションのステータスをポーリングできます。IndexEndpoints
の一覧表示
IndexEndpoint
リソースを一覧表示し、関連する DeployedIndex
インスタンスの情報を表示するには、次のコードを実行します。
gcloud
次の例では、gcloud ai index-endpoints list
コマンドを使用します。
gcloud ai index-endpoints list \
--project=PROJECT_ID \
--region=LOCATION
次のように置き換えます。
- PROJECT_ID: プロジェクトの ID
- LOCATION: Vertex AI を使用するリージョン。
REST とコマンドライン
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION: 使用するリージョン。
- PROJECT: プロジェクト ID またはプロジェクト番号。
- PROJECT_NUMBER: プロジェクトのプロジェクト番号(レスポンスに表示される)
HTTP メソッドと URL:
GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "indexEndpoints": [ { "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID", "displayName": "INDEX_ENDPOINT_NAME", "deployedIndexes": [ { "id": "DEPLOYED_INDEX_ID", "index": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID", "displayName": "DEPLOYED_INDEX_ID", "createTime": "2021-06-04T02:23:40.178286Z", "privateEndpoints": { "matchGrpcAddress": "GRPC_ADDRESS" }, "indexSyncTime": "2022-01-13T04:22:00.151916Z", "automaticResources": { "minReplicaCount": 2, "maxReplicaCount": 10 } } ], "etag": "AMEw9yP367UitPkLo-khZ1OQvqIK8Q0vLAzZVF7QjdZ5O3l7Zow-mzBo2l6xmiuuMljV", "createTime": "2021-03-17T04:47:28.460373Z", "updateTime": "2021-06-04T02:23:40.930513Z", "network": "VPC_NETWORK_NAME" } ] }
詳細については、IndexEndpoint
のリファレンス ドキュメントをご覧ください。
インデックスのデプロイ解除
インデックスのデプロイを解除するには、次のコードを実行します。
gcloud
次の例では、gcloud ai index-endpoints undeploy-index
コマンドを使用します。
gcloud ai index-endpoints undeploy-index INDEX_ENDPOINT_ID \
--deployed-index-id=DEPLOYED_INDEX_ID \
--project=PROJECT_ID \
--region=LOCATION
次のように置き換えます。
- INDEX_ENDPOINT_ID: インデックス エンドポイントの ID。
- DEPLOYED_INDEX_ID: デプロイされたインデックスの ID。
- PROJECT_ID: プロジェクトの ID
- LOCATION: Vertex AI を使用するリージョン。
REST とコマンドライン
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION: 使用するリージョン。
- PROJECT: プロジェクト ID またはプロジェクト番号。
- INDEX_ENDPOINT_ID: インデックス エンドポイントの ID。
- DEPLOYED_INDEX_ID: デプロイされたインデックスの ID。
- PROJECT_NUMBER: プロジェクトのプロジェクト番号(レスポンスに表示される)
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:undeployIndex
JSON 本文のリクエスト:
{ "deployed_index_id": "DEPLOYED_INDEX_ID" }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UndeployIndexOperationMetadata", "genericMetadata": { "createTime": "2022-01-13T04:09:56.641107Z", "updateTime": "2022-01-13T04:09:56.641107Z" } } }
IndexEndpoint
の削除
IndexEndpoint
を削除する前に、それに関連するすべてのインデックスをデプロイ解除する必要があります。
gcloud
次の例では、gcloud ai index-endpoints delete
コマンドを使用します。
gcloud ai index-endpoints delete INDEX_ENDPOINT_ID \
--project=PROJECT_ID \
--region=LOCATION
次のように置き換えます。
- INDEX_ENDPOINT_ID: インデックス エンドポイントの ID。
- PROJECT_ID: プロジェクトの ID
- LOCATION: Vertex AI を使用するリージョン。
REST とコマンドライン
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION: 使用するリージョン。
- PROJECT: プロジェクト ID またはプロジェクト番号。
- INDEX_ENDPOINT_ID: インデックス エンドポイントの ID。
- PROJECT_NUMBER: プロジェクトのプロジェクト番号(レスポンスに表示される)
HTTP メソッドと URL:
DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeleteOperationMetadata", "genericMetadata": { "createTime": "2022-01-13T04:36:19.142203Z", "updateTime": "2022-01-13T04:36:19.142203Z" } }, "done": true, "response": { "@type": "type.googleapis.com/google.protobuf.Empty" } }
最近傍を取得するインデックスのクエリ
各 DeployedIndex
には DEPLOYED_INDEX_SERVER_IP
があり、IndexEndpoints
をリストすることで取得できます。DeployedIndex
をクエリするには、ポート 10000
で DEPLOYED_INDEX_SERVER_IP
に接続し、MatchRequest
または BatchMatchRequest
メソッドを呼び出します。
次の例では、grpc_cli
を使用しています。
./grpc_cli call ${DEPLOYED_INDEX_SERVER_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.BatchMatch 'requests: [{deployed_index_id: "", requests: [{deployed_index_id: " ", float_val: [-0.1,.. ]}, {deployed_index_id: " ", float_val: [-0.1,.. ]}]}]'
これらの API は、サービスとピアリングされた同じ VPC で実行されているクライアントから呼び出す必要があります。
クエリの作成方法の詳細については、サンプル ノートブックを起動し、Vertex AI Workbench で実行してください。
インデックスの調整
インデックスを調整するには、デプロイされたインデックスのパフォーマンス(特に再現率とレイテンシ)に影響する構成パラメータを設定する必要があります。これらのパラメータは、インデックス作成時に設定されます。ブルート フォース インデックスを使用して、再現率を測定できます。
再現率とレイテンシに影響する構成パラメータ
distanceMeasureType
次の値を使用できます。
SQUARED_L2_DISTANCE
: ユークリッド距離(L2)L1_DISTANCE
: マンハッタン距離(L1)COSINE_DISTANCE
: コサイン距離(1 - コサイン類似度)DOT_PRODUCT_DISTANCE
: vDot ドット積(ドット積の負の値)これがデフォルト値です。
ほとんどの場合、類似度マッチングに使用される埋め込みベクトルは、指標学習モデル(Siamese networks、Two-Tower モデルとも呼ばれます)で計算されます。これらのモデルでは、距離指標を使用して対照損失関数を計算します。マッチング インデックスの
distanceMeasureType
パラメータの値が、埋め込みベクトルを生成したモデルで使用される距離測定方法と一致するのが理想的です。approximateNeighborsCount
正確な並べ替えが実行される前に近似検索によってデフォルトで検索される近傍数。正確な並べ替えとは、近似探索アルゴリズムによって返された結果が、よりコストの高い距離計算によって並べ替えられる手続きです。この値を大きくすると再現率が向上し、それに比例してレイテンシも増加する可能性があります。
treeAhConfig.leafNodesToSearchPercent
クエリごとに検索するリーフの割合。この値を大きくすると再現率が向上し、それに比例してレイテンシも増加する可能性があります。デフォルト値は
10
またはリーフの 10% です。treeAhConfig.leafNodeEmbeddingCount
各リーフノードの埋め込み数。デフォルトでは
1000
に設定されています。このパラメータは、再現率と直線的な相関関係はありません。
treeAhConfig.leafNodeEmbeddingCount
パラメータの値を増減しても、再現値が増減するとは限りません。試行して最適な値を見つけてください。通常、treeAhConfig.leafNodeEmbeddingCount
パラメータの値を変更する影響は、他のパラメータ値を変更する場合よりも少なくなります。
ブルート フォース インデックスを使用した再現率の測定
確な最近傍を取得するには、ブルート フォース アルゴリズムのインデックスを使用します。ブルート フォース アルゴリズムを使用すると、レイテンシは高くなりますが、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: {} } }, }, }'
サンプル ノートブックでは、ブルート フォース インデックスを使用して再現率を測定する方法を説明しています。
IndexEndpoint
をモニタリングする
Google では、IndexEndpoint
をモニタリングするための指標を 2 つ用意しています。
aiplatform.googleapis.com/matching_engine/current_shards
DeployedIndex
のシャード数。データが追加または削除されると、Matching Engine はインデックスを自動的に再シャーディングして最適なパフォーマンスを実現します。この指標は、デプロイされたインデックスの現在のシャード数を示します。aiplatform.googleapis.com/matching_engine/current_replicas
DeployedIndex
で使用されているアクティブなレプリカ サーバーの合計数。Matching Engine は、インデックスをデプロイする際にユーザーが指定した最小レプリカ数と最大レプリカ数に基づき、クエリの量に合わせてレプリカ サーバーの起動と終了を自動的に行います。インデックスに複数のシャードがある場合、シャードごとに異なる数のレプリカ サーバーを使用できることに注意してください。この指標は、特定のインデックスのシャードのすべてのレプリカ サーバーを合計した数です。
Metrics Explorer でこれらの指標を選択、クエリ、表示する方法をご確認ください。
割り当て
Vertex AI Matching Engine の割り当てと割り当ての増加をリクエストする方法をご確認ください。
よくある質問
予約する IP アドレスの数
割り振り可能な IP 範囲に制限がない場合は、将来の IP の枯渇に備えるため、/16 のような大きな IP 範囲を予約することをおすすめします。
ただし、IP 範囲を過剰に割り振りたくない場合は、データサイズとトラフィックから概算を行うことができます。各シャードは、約 20 GB のデータを Avro 形式でホストできます。各シャードのレプリカで処理可能な秒間クエリ数(QPS)は約 800~1,000 です。各レプリカが処理する正確な QPS は、エンベディングのサイズ、ディメンション、アルゴリズム構成などによって異なります。負荷テストで正確な数値を決定することを強くおすすめします。
デプロイが必要なインデックス ノードの総数は(シャードの数 × シャードあたりのレプリカ数)になります。たとえば、データサイズが 30 GB で、QPS が 1,200 の場合、少なくとも 2 つのシャードと、シャードごとに 2 つのレプリカが必要です(デプロイされるインデックス ノードは合計で 4 つになります)。
デプロイされるインデックス ノードの概算を行ったら、下の表から IP 範囲のプレフィックスを選択します。
デプロイされるインデックス ノードの合計数 | 推奨の予約済み IP プレフィックス |
---|---|
1 - 10 | /21 |
11 - 25 | /20 |
26 - 50 | /19 |
51 - 120 | /18 |
IP 枯渇エラーの解決方法
IP 枯渇エラーを解決するには、次の手順を行います。
未使用の DeployedIndex があるかどうかを確認します。未使用のものがあれば、デプロイを解除して一部の IP スペースを解放します。
既存の予約済み IP 範囲を拡張するか、より多くの IP 範囲を割り振ります。
詳細については、IP アドレス範囲の枯渇をご覧ください。
以前の DeployedIndex のデプロイ解除時に、デプロイ済みのインデックス ID を再利用できない理由
UndeployIndex クリーンアップは、オペレーションの確認成功を受信した後、少なくとも 10~20 分かかります。同じ ID を再利用する前に 10~20 分待つか、別の ID を使用することをおすすめします。
サポートの利用
Matching Engine の使用で問題が発生した場合、サポートを利用する方法は 2 つあります。いずれの場合も、以下の情報をご提供ください。
- 実際のプロジェクト ID
- 問題が発生したコマンドまたはコード。
- コマンドまたはコードを実行した環境。たとえば、Compute Engine インスタンスまたはオンプレミスのパソコンで実行していた、など。
- 予期した動作と実際の動作の違い。
Cloud カスタマーケア チケットを作成する
カスタマーケア パッケージをご利用の場合は、サポート チケットを送信できます。Cloud カスタマーケア パッケージの入手方法については、カスタマーケアをご覧ください。
Google Cloud Console で、[ケース] ページに移動します。
[ケースを作成] をクリックします。
- [タイトル] フィールドに「
Matching Engine serving
」と入力します。 - [カテゴリ] フィールドで、[機械学習] を選択します。
- [コンポーネント] フィールドで、[Vertex AI Matching Engine] を選択します。
- [説明] フィールドに必要な情報を入力して、質問に回答します。
- [送信] をクリックします。
- [タイトル] フィールドに「
メールを送信する
カスタマーケア パッケージをお持ちでない場合は、次のメールアドレスにメッセージを送信できます。
gcp-ann-feedback@google.com
次のステップ
- Vertex AI Workbench でサンプル ノートブックを起動するか、GitHub でノートブックを表示する。