Vertex AI Matching Engine の使用

このガイドでは、ベクトル類似検索を行うために 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 プロジェクト管理者またはネットワーク管理者が行う必要があります。

  1. Cloud プロジェクトの設定、課金の有効化、API の有効化を行うには、以下の始める前に手順を完了します。

  2. 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

  1. インデックス メタデータを定義します
  2. gcloud ai indexes create コマンドを使用します。
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 フィールドが設定されている場合、他のインデックス フィールド(displayNamedescriptionuserLabels など)は同じ呼び出しでは更新できません。

gcloud

  1. インデックス メタデータ ファイルを更新します
  2. gcloud ai indexes update コマンドを使用します。
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 つのタスクがあります。

  1. 必要に応じて IndexEndpoint を作成するか、既存の IndexEndpoint を再利用します。
  2. IndexEndpoint ID を取得します。
  3. インデックスを IndexEndpoint にデプロイします。

VPC ネットワーク内での IndexEndpoint の作成

Index を既存の IndexEndpoint にデプロイする場合は、この手順をスキップできます。

インデックスを使用してベクトル マッチングのオンライン クエリを実行する前に、VPC ネットワークのピアリング ネットワーク内の IndexEndpointIndex をデプロイする必要があります。まず、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 は自動スケーリングをサポートしており、ワークロードの需要に応じてノード数を自動的に変更できます。需要が高い場合、ノードがノードプールに追加されます。指定した最大サイズを超えることはありません。需要が少ない場合、ノードプールは指定した最小サイズにスケールダウンされます。使用中の実際のノードと変更は、現在のレプリカをモニタリングすることで確認できます。

自動スケーリングを有効にするには、インデックスをデプロイするときに maxReplicaCountminReplicaCount を指定します。

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 が表示されるまで、オペレーションのステータスをポーリングできます。
  • minReplicaCountmaxReplicaCount の両方とも設定されていない場合、この 2 つはデフォルトで 2 に設定されます。
  • maxReplicaCount のみが設定されている場合、minReplicaCount はデフォルトで 2 に設定されます。
  • minReplicaCount のみが設定されている場合、maxReplicaCount の値は minReplicaCount と一致します。

DeployedIndex を変更する

MutateDeployedIndex API を使用すると、すでにデプロイされているインデックスのデプロイ リソース(minReplicaCountmaxReplicaCount など)を更新できます。

  • インデックスのデプロイ後にユーザーが 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 をクエリするには、ポート 10000DEPLOYED_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 で実行してください。

インデックスの調整

インデックスを調整するには、デプロイされたインデックスのパフォーマンス(特に再現率とレイテンシ)に影響する構成パラメータを設定する必要があります。これらのパラメータは、インデックス作成時に設定されます。ブルート フォース インデックスを使用して、再現率を測定できます。

再現率とレイテンシに影響する構成パラメータ

  1. distanceMeasureType

    次の値を使用できます。

    • SQUARED_L2_DISTANCE: ユークリッド距離(L2)
    • L1_DISTANCE: マンハッタン距離(L1)
    • COSINE_DISTANCE: コサイン距離(1 - コサイン類似度)
    • DOT_PRODUCT_DISTANCE: vDot ドット積(ドット積の負の値)これがデフォルト値です。

    ほとんどの場合、類似度マッチングに使用される埋め込みベクトルは、指標学習モデル(Siamese networks、Two-Tower モデルとも呼ばれます)で計算されます。これらのモデルでは、距離指標を使用して対照損失関数を計算します。マッチング インデックスの distanceMeasureType パラメータの値が、埋め込みベクトルを生成したモデルで使用される距離測定方法と一致するのが理想的です。

  2. approximateNeighborsCount

    正確な並べ替えが実行される前に近似検索によってデフォルトで検索される近傍数。正確な並べ替えとは、近似探索アルゴリズムによって返された結果が、よりコストの高い距離計算によって並べ替えられる手続きです。この値を大きくすると再現率が向上し、それに比例してレイテンシも増加する可能性があります。

  3. treeAhConfig.leafNodesToSearchPercent

    クエリごとに検索するリーフの割合。この値を大きくすると再現率が向上し、それに比例してレイテンシも増加する可能性があります。デフォルト値は 10 またはリーフの 10% です。

  4. 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 枯渇エラーを解決するには、次の手順を行います。

  1. 未使用の DeployedIndex があるかどうかを確認します。未使用のものがあれば、デプロイを解除して一部の IP スペースを解放します。

  2. 既存の予約済み IP 範囲を拡張するか、より多くの IP 範囲を割り振ります。

詳細については、IP アドレス範囲の枯渇をご覧ください。

以前の DeployedIndex のデプロイ解除時に、デプロイ済みのインデックス ID を再利用できない理由

UndeployIndex クリーンアップは、オペレーションの確認成功を受信した後、少なくとも 10~20 分かかります。同じ ID を再利用する前に 10~20 分待つか、別の ID を使用することをおすすめします。

サポートの利用

Matching Engine の使用で問題が発生した場合、サポートを利用する方法は 2 つあります。いずれの場合も、以下の情報をご提供ください。

  • 実際のプロジェクト ID
  • 問題が発生したコマンドまたはコード。
  • コマンドまたはコードを実行した環境。たとえば、Compute Engine インスタンスまたはオンプレミスのパソコンで実行していた、など。
  • 予期した動作と実際の動作の違い。

Cloud カスタマーケア チケットを作成する

カスタマーケア パッケージをご利用の場合は、サポート チケットを送信できます。Cloud カスタマーケア パッケージの入手方法については、カスタマーケアをご覧ください。

  1. Google Cloud Console で、[ケース] ページに移動します。

    [ケース] に移動

  2. [ケースを作成] をクリックします。

    • [タイトル] フィールドに「Matching Engine serving」と入力します。
    • [カテゴリ] フィールドで、[機械学習] を選択します。
    • [コンポーネント] フィールドで、[Vertex AI Matching Engine] を選択します。
    • [説明] フィールドに必要な情報を入力して、質問に回答します。
    • [送信] をクリックします。

メールを送信する

カスタマーケア パッケージをお持ちでない場合は、次のメールアドレスにメッセージを送信できます。

gcp-ann-feedback@google.com

次のステップ