Vertex Matching Engine を使用する

このガイドでは、ベクトル類似検索を行うために Vertex Matching Engine をどのように構成して使用できるかを説明します。

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

ベクトルマッチングのオンラインクエリのネットワークレイテンシを短縮するには、プライベートサービスアクセス経由で VPC から Vertex AI サービスエンドポイントを呼び出します。各 Google Cloud プロジェクトで、Matching Engine とピアリングできる VPC ネットワークは 1 つだけです。プライベートサービスアクセスが構成された VPC がすでにある場合は、その VPC を使用して Vertex Matching Engine とピアリングできます。

VPC ネットワークピアリング接続の構成は、Google Cloud プロジェクトごとに 1 回だけ必要となる初期タスクです。この設定が完了すると、VPC 内で実行されている任意のクライアントから Matching Engine インデックスを呼び出すことができます。

VPC ネットワークピアリング接続は、ベクトルマッチングのオンラインクエリにのみ必要です。インデックスの作成、デプロイ、削除を行うための API 呼び出しで VPC ネットワークピアリング接続は必要ありません。

Google Cloud プロジェクト管理者またはネットワーク管理者に次の手順を行ってもらいます。

こちらの手順に沿って、Google Cloud プロジェクトの設定、課金の有効化、API の有効化を行います。

プライベート接続を作成する前に、Matching Engine サービスで使用する IP アドレス範囲を割り振る必要があります。これにより、Matching Engine インデックスがデプロイされるサービスプロデューサーのネットワークとユーザーの VPC ネットワークとの間で IP アドレスの競合を回避できます。詳細については、こちらのドキュメントをご覧ください。

# NOTE: `prefix-length=16` means a CIDR block with mask /16 will be reserved
# for use by Google services. Make sure to enable 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 ネットワークピアリングの初期設定が完了したら、その VPC 内に Notebooks インスタンスを作成し、ノートブックからコマンドを発行できます。

Notebooks でサンプルノートブックを起動するか、GitHub でノートブックを表示します。

アクセス制御

Vertex AI は、Identity and Access Management（IAM）を使用してリソースへのアクセスを管理します。リソースへのアクセス権を付与するには、ユーザー、グループ、またはサービスアカウントに 1 つ以上のロールを割り当てます。

Matching Engine を使用するには、これらの事前定義ロールを使用して、プロジェクト単位でリソースに対するさまざまなレベルのアクセス権を付与します。

入力データの形式と構造

このセクションでは、新しいインデックスの作成や既存のインデックスの更新で、Matching Engine にベクトルを提供するための構造と形式について説明します。

入力データのストレージ

入力データを Google Cloud プロジェクトの Cloud Storage バケットに保存します。

入力ディレクトリの構造

このセクションでは、入力データディレクトリを構造化する方法について説明します。

バッチのルートディレクトリ: 入力データファイルのバッチごとにルートディレクトリを作成します。これは 1 つの 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 を使用してファイルをエンコードします。
各行は有効な CSV である必要があります。1 行が 1 レコードとして解釈されます。
最初の値は id にします。これは、有効な UTF-8 文字列にする必要があります。
次の N 個の値が特徴ベクトルになります。N は特徴ベクトルの次元を表します。これは、インデックスの作成時に構成する必要があります。Java 言語仕様で定義されているように、それぞれの値は浮動小数点リテラルにする必要があります。

JSON

ファイルは UTF-8 でエンコードする必要があります。
各行は有効な JSON オブジェクトにする必要があります。これは、レコードとして解釈されます。
各レコードには、ベクトルの ID を指定する id というフィールドが必要です。これは、有効な UTF-8 文字列にする必要があります。
各レコードには embedding というフィールドが必要です。ここには数値の配列を指定します。これは特徴ベクトルです。

AVRO

ファイルは、有効な Avro ファイルである必要があります。

Avro レコードの構造は、JSON 形式で定義されているものと同じにする必要があります。具体的には、次のスキーマに準拠する必要があります。

{
   "type": "record",
   "name": "FeatureVector",
   "fields": [
      {"name": "id", "type": "string"},
      {"name": "embedding",
       "type": {
          "type": "array",
          "items": "float"
        }
      }
   ]
}

インデックスの管理

このセクションでは、インデックスを作成、削除、更新する方法について説明します。インデックスに関する 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 beta ai indexes create を使用してリクエストを送信します

gcloud beta ai indexes create \
  --display-name=INDEX_NAME \
  --description=test \
  --metadata-file=LOCAL_PATH_TO_METADATA_FILE \
  --project=PROJECT_ID \
  --region=us-central1

別の方法として、インデックスメタデータを直接渡す curl API 呼び出しのサンプルを以下に示します。

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",
          algorithm_config: {
          treeAhConfig: {
            leafNodeEmbeddingCount: 500,
            leafNodesToSearchPercent: 7
            }
          }
       }
    }
}'

出力例は次のとおりです。

{
  "name": "projects/xxx/locations/us-central1/indexes/xxxx/operations/yyyy",
  "metadata": {...}
}

オペレーションの出力で、"name": "projects/xxxx/locations/us-central1/indexes/xxx/operations/yyyy" を含む行を探します。yyyy の部分はオペレーション ID です。正常に完了するまでオペレーションをポーリングします。"done": true がレスポンスに含まれるまで待ちます。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexes/xxxx/operations/yyyy"

インデックスの一覧表示

インデックスを一覧表示するには、gcloud beta ai indexes list を実行します。

gcloud beta ai indexes list \
  --project=PROJECT_ID \
  --region=us-central1

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

既存のインデックスの内容を更新するには、IndexService.UpdateIndex メソッドを使用します。

Index の既存の内容を置き換えるには:

Index.metadata.contentsDeltaUri を、更新するベクトルを含む Cloud Storage URI に設定します。
isCompleteOverwrite を true に設定します。

また、IndexService.UpdateIndex の呼び出し時に contentsDeltaUri フィールドが設定されている場合、他のインデックスフィールド（displayName、description、userLabels など）は同じ呼び出しでは更新できません。

curl API 呼び出しの例を次に示します。

curl -X PATCH -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/${INDEX_ID} \
-d '{
   metadata: {
       contentsDeltaUri: "'${INPUT_DIR}'",
       isCompleteOverwrite: <true|false>
    },
}'

インデックスの作成と同様に、正常に実行されるまで、UpdateIndex 呼び出しから返されたオペレーションをポーリングします。

Index に関連するデプロイがある場合（Index.deployed_indexes フィールドを参照）、元の Index への特定の変更が完了すると、その変更を反映するため、バックグラウンドで非同期的に DeployedIndex が自動更新されます。

変更が伝播されたかどうかを確認するには、更新インデックスオペレーションの終了時間と DeployedIndex.index_sync_time を比較します。

インデックスの削除

すべての Index.deployed_indexes のデプロイを解除するまで、その Index は削除できません。

curl -X DELETE -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/${INDEX_ID}

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

インデックスのデプロイは、次の 3 つのタスクから構成されます。

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

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

インデックスを使用してベクトルマッチングのオンラインクエリを実行する前に、VPC ネットワークのピアリングネットワーク内の IndexEndpoint に Index をデプロイする必要があります。したがって、最初の手順は IndexEndpoint を作成することです。同じ VPC ネットワークを共有する IndexEndpoint には複数のインデックスをデプロイできます。

curl API 呼び出しの例を次に示します。

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/indexEndpoints \
-d '{
    display_name: "'${DISPLAY_NAME}'",
    network: "'${VPC_NETWORK_NAME}'",
}'

出力例は次のとおりです。

{
  "name": "projects/xxx/locations/us-central1/indexEndpoints/xxxx/operations/yyyy",
  "metadata": {...}
}

オペレーションの出力で、"name": "projects/xxxx/locations/us-central1/indexEndpoints/xxx/operations/yyyy" を含む行を探します。yyyy の部分はオペレーション ID です。正常に完了するまでオペレーションをポーリングします。"done": true がレスポンスに含まれるまで待ちます。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexEndpoints/xxxx/operations/yyyy"

インデックスのデプロイ

インデックスをデプロイするには:

curl -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/indexEndpoints/${INDEX_ENDPOINT_ID}:deployIndex \
-d '{
  deployedIndex: {
    id: "'${DEPLOYED_INDEX_ID}'",
    index: "'${INDEX_RESOURCE_NAME}'",
    displayName: "'${DISPLAY_NAME}'"
  }
}'

他のオペレーションと同様に、レスポンスからオペレーション ID を取得し、その ID を使用してオペレーションが完了するまでポーリングします。

自動スケーリングの有効化

Matching Engine は自動スケーリングをサポートしており、ワークロードの需要に応じてノード数を自動的に変更できます。需要が高い場合、ノードがノードプールに追加されます（指定した最大サイズを超えることはありません）。需要が少ない場合、ノードプールは指定した最小サイズにスケールダウンされます（使用中の実際のノードと変更は、現在のレプリカをモニタリングすることで確認できます）。

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

curl -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/indexEndpoints/${INDEX_ENDPOINT_ID}:deployIndex \
-d '{
  deployedIndex: {
    id: "'${DEPLOYED_INDEX_ID}'",
    index: "'${INDEX_RESOURCE_NAME}'",
    displayName: "'${DISPLAY_NAME}'"
    automaticResources: {
      minReplicaCount: 2,
      maxReplicaCount: 5
    }
  }
}'

minReplicaCount と maxReplicaCount の両方とも設定されていない場合、この 2 つはデフォルトで 1 に設定されます。
maxReplicaCount のみが設定されている場合、minReplicaCount はデフォルトで 1 に設定されます。
minReplicaCount のみが設定されている場合、maxReplicaCount の値は minReplicaCount と一致します。

`IndexEndpoints` の一覧表示

IndexEndpoints を一覧表示し、関連する DeployedIndex インスタンスの情報を表示するには、次のコマンドを実行します。

curl -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/indexEndpoints

レスポンスは次のとおりです。

{
  "indexEndpoints": [
    {
      "name": "projects/<ProjectId>/locations/us-central1/indexEndpoints/<IndexEndpoingId>",
      "displayName": "...",
      "deployedIndexes": [
        {
          "id": "<user specified deployed index id>",
          "index": "projects/<ProjectId>/locations/us-central1/indexes/<IndexId>",
          "displayName": "demo",
          "createTime": "2021-06-18T00:19:13.242212Z",
          "privateEndpoints": {
            "matchGrpcAddress": "10.29.2.5"
          },
          "indexSyncTime": "2021-08-13T19:52:48.671205Z",
          "automaticResources": {
            "minReplicaCount": 1,
            "maxReplicaCount": 1
          }
        }
        ...
      ],
      "etag": "AMEw9yP9cMX3cjWFRuyLqI6YbB2UQcb-OU3tMwx9_B2p_MUiMlsMKPWX5KCphr1vbyiv",
      "createTime": "2021-06-18T00:16:59.320793Z",
      "updateTime": "2021-06-18T00:16:59.850034Z",
      "network": "projects/<ProjectId>/global/networks/<NetworkId>"
    },
    ...
  ]
}

詳細については、IndexEndpoint のリファレンスドキュメントをご覧ください。

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

インデックスをデプロイ解除するには、次のコマンドを実行します。

curl -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/indexEndpoints/${INDEX_ENDPOINT_ID}:undeployIndex \
-d '{
  deployed_index_id: "'${DEPLOYED_INDEX_ID}'",
}'

`IndexEndpoint` の削除

IndexEndpoint を削除する前に、それに関連するすべてのインデックスをデプロイ解除する必要があります。

curl -X DELETE -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/indexEndpoints/${INDEX_ENDPOINT_ID}

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

各 DeployedIndex には IndexEndpoints の一覧表示で取得できる DEPLOYED_INDEX_SERVER_IP があります。DeployedIndex をクエリするには、その DEPLOYED_INDEX_SERVER_IP をポート 10000 に接続し、MatchRequest または BatchMatchRequest メソッドを呼び出します。

次の例では grpc_cli を使用します。

./grpc_cli call ${DEPLOYED_INDEX_SERVER_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.BatchMatch 'requests: [{deployed_index_id: "<deployed index id 1>", requests: [{deployed_index_id: "<deployed index id 1>", float_val: [-0.1,..<your query input>]}, {deployed_index_id: "<deployed index id 1>", float_val: [-0.1,..<your query input>]}]}]'

これらの API の呼び出しは、サービスとピアリングされた同じ VPC で実行されているクライアントから行う必要があります。

サンプルノートブックを起動して、クエリの作成方法や Notebooks でクエリを実行する方法についての付加的な説明を確認できます。

インデックスの調整

このセクションでは、デプロイされたインデックスのパフォーマンス（特に再現率とレイテンシ）に影響する構成パラメータについて説明します。これらのパラメータは、インデックス作成時に設定されます。また、ブルートフォースインデックスを使用して再現率を測定する方法についても説明します。

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

1）'distanceMeasureType'

サポートされている値は次の通りです。

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

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

2）approximateNeighborsCount

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

3）treeAhConfig.leafNodesToSearchPercent

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

4）treeAhConfig.leafNodeEmbeddingCount

各リーフノードの埋め込み数。デフォルトは 1,000 です。

このパラメータは、再現率と直線的な相関関係はありません。この値を増減しても、再現値が増減するとは限りません。各ユースケースには、通常、テストが必要になるスイートスポットがあります。ただし、このパラメータの効果は他のパラメータよりも低くなります。

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

ブルートフォースアルゴリズムのインデックスを使用すると正確な最近傍を取得できます（レイテンシは高くなりますが、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` をモニタリングする

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 Matching Engine の割り当てと割り当ての増加をリクエストする方法をご確認ください。

よくある質問

予約する IP アドレスの数

割り振り可能な IP 範囲に制限がない場合は、IP の不足が発生しないように、/16 などの大きな IP 範囲を予約することをおすすめします。

ただし、IP 範囲を過剰に割り振りたくない場合は、データサイズとトラフィックから概算を行うことができます。各シャードでは Avro 形式のデータを約 20 GB ホストできます。シャードの各レプリカは、約 800～1,000 qps を処理できます（各レプリカが処理する正確な qps は、エンベディングのサイズ、ディメンション、アルゴリズム構成などによって異なります。正確な数値を把握するために、負荷テストを行うことを強くおすすめします。）。必要なインデックスノードの総数は、（シャードの数 × シャードあたりのレプリカ数）になります。

たとえば、データサイズが 30 GB で、qps が 1,200 の場合、少なくとも 2 つのシャードと、シャードごとに 2 つのレプリカが必要です（デプロイされるインデックスノードは合計で 4 つになります）。

デプロイされるインデックスノードの概算を行ったら、下の表から IP 範囲のプレフィックスを選択します。

デプロイされるインデックスノードの合計数	推奨の予約済み IP プレフィックス
1 - 10	/21
11 - 25	/20
26 - 50	/19
51 - 120	/18

IP 不足エラーが発生した場合の対処方法

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

また、既存の予約済み IP 範囲を拡張することや、より多くの IP 範囲を割り振ることもできます。詳しい手順については、こちらをご覧ください。

以前の DeployedIndex のデプロイを解除しても、デプロイされたインデックス ID を再利用できないのはなぜですか？

Google では、お客様がデプロイ解除エラーの処理について心配する必要がないように、成功したオペレーションを常に返しています。ただし、基礎となるクリーンアップジョブが完了するまでに少なくとも 10～20 分かかります。同じ ID を再利用する前に 10～20 分ほどお待ちください。あるいは、別の ID をご使用ください。

サポートの利用

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

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

クラウドサポートチケットを作成する

Google サポートパッケージをご利用の場合は、サポートチケットを提出できます。Google サポートパッケージの入手方法については、Google Cloud サポートをご覧ください。

Cloud Console で、[サポート] セクションの [ケース] に移動し、[ケースを作成します] をクリックします。

[タイトル] フィールドに「Matching Engine Serving」と入力します。
[カテゴリ] で [Machine Learing] を選択します。
[コンポーネント] で [Vertex: Other] を選択します。
説明フィールドの上部に「Vertex Matching Engine」というフレーズを追加します。
残りの説明と他のフィールドにできる限り詳しく入力します。

メールを送信する

Google サポートパッケージをお持ちでない場合は、次のアドレスにメールを送信してください。

gcp-ann-feedback@google.com

次のステップ

Notebooks でサンプルノートブックを起動するか、GitHub でノートブックを表示する。