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 プロジェクト管理者またはネットワーク管理者が行う必要があります。

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 コマンドを使用します。

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
        }
      }
    }
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexes"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexes" | Select-Object -Expand Content

次のような 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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexes"

PowerShell（Windows）

次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexes" | Select-Object -Expand Content

次のような 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 コマンドを使用します。

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
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X PATCH \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexes/INDEX_ID"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method PATCH `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexes/INDEX_ID" | Select-Object -Expand Content

次のような 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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

curl -X DELETE \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexes/INDEX_ID"

PowerShell（Windows）

次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method DELETE `
  -Headers $headers `
  -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexes/INDEX_ID" | Select-Object -Expand Content

次のような 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"
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints" | Select-Object -Expand Content

次のような 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"
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:deployIndex"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:deployIndex" | Select-Object -Expand Content

次のような 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
    }
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:deployIndex"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:deployIndex" | Select-Object -Expand Content

次のような 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
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:mutateDeployedIndex"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:mutateDeployedIndex" | Select-Object -Expand Content

次のような 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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints"

PowerShell（Windows）

次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints" | Select-Object -Expand Content

次のような 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"
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:undeployIndex"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:undeployIndex" | Select-Object -Expand Content

次のような 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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

curl -X DELETE \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID"

PowerShell（Windows）

次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method DELETE `
  -Headers $headers `
  -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID" | Select-Object -Expand Content

次のような 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 でノートブックを表示する。

Vertex AI Matching Engine の使用

VPC ネットワーク ピアリング接続を設定する

サンプル ノートブック

IAM によるアクセス制御

入力データの形式と構造

入力データのストレージ

入力ディレクトリの構造

データファイルの形式

CSV

JSON

AVRO

インデックスの管理

インデックス メタデータ ファイル

インデックスの作成

gcloud

REST とコマンドライン

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

インデックスの一覧表示

gcloud

REST とコマンドライン

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

インデックスの内容の更新

gcloud

REST とコマンドライン

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

インデックスを削除する

gcloud

REST とコマンドライン

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

インデックスのデプロイと管理

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

gcloud

REST とコマンドライン

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

インデックスのデプロイ

gcloud

REST とコマンドライン

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

自動スケーリングを有効にする

gcloud

REST とコマンドライン

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

DeployedIndex を変更する

gcloud

REST とコマンドライン

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

IndexEndpoints の一覧表示

gcloud

REST とコマンドライン

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

インデックスのデプロイ解除

gcloud

REST とコマンドライン

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

IndexEndpoint の削除

gcloud

REST とコマンドライン

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

最近傍を取得するインデックスのクエリ

インデックスの調整

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

ブルート フォース インデックスを使用した再現率の測定

IndexEndpoint をモニタリングする

割り当て

よくある質問

予約する IP アドレスの数

IP 枯渇エラーの解決方法

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

サポートの利用

VPC ネットワークピアリング接続を設定する

サンプルノートブック

インデックスメタデータファイル

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

`DeployedIndex` を変更する

`IndexEndpoints` の一覧表示

`IndexEndpoint` の削除

ブルートフォースインデックスを使用した再現率の測定

`IndexEndpoint` をモニタリングする

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