インデックスの管理

以降のセクションでは、インデックスの構成、作成、一覧取得、削除を行う方法について説明します。

インデックスの概要

インデックスは、エンベディングベクトルで構成される 1 つまたは複数のファイルです。これらのベクトルは、ベクトル検索でデプロイしてクエリを実行する大量のデータから作成されます。Vector Search では、データでインデックスを更新する方法に応じて 2 種類のインデックスがあります。バッチアップデート用に設計されたインデックスか、ストリーミング更新用に設計されたインデックスを作成できます。

バッチインデックスは、毎週または毎月処理されるシステムなど、一定期間にわたって保存されたデータを使用してインデックスをバッチで更新する場合に適しています。ストリーミングインデックスは、データストアに新しいデータが追加されたときに、インデックスデータを更新したいときに適しています。たとえば、本屋を経営していて、新しい在庫をできるだけ早くオンラインで表示したい場合などです。設定と要件が異なるため、どちらのタイプを選択するかは重要です。

インデックスパラメータを構成する

インデックスを作成する前に、インデックスのパラメータを構成します。

たとえば、index_metadata.json という名前のファイルを作成します。

{
  "contentsDeltaUri": "gs://BUCKET_NAME/path",
  "config": {
    "dimensions": 100,
    "approximateNeighborsCount": 150,
    "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
    "shardSize": "SHARD_SIZE_MEDIUM",
    "algorithm_config": {
      "treeAhConfig": {
        "leafNodeEmbeddingCount": 5000,
        "fractionLeafNodesToSearch": 0.03
      }
    }
  }
}

これらのフィールドの定義については、インデックス構成パラメータをご覧ください。

インデックスを作成する

インデックスサイズ

インデックスデータは、シャードと呼ばれる均等な部分に分割されて処理されます。インデックスを作成するときは、使用するシャードのサイズを指定する必要があります。サポートされているサイズは次のとおりです。

SHARD_SIZE_SMALL: シャードあたり 2 GiB。
SHARD_SIZE_MEDIUM: シャードあたり 20 GiB。
SHARD_SIZE_LARGE: シャードあたり 50 GiB。

インデックスのデプロイに使用できるマシンタイプ（パブリックエンドポイントの使用または VPC エンドポイントの使用を参照）は、インデックスのシャードサイズによって異なります。次の表に、各マシンタイプでサポートされているシャードのサイズを示します。

マシンタイプ	`SHARD_SIZE_SMALL`	`SHARD_SIZE_MEDIUM`	`SHARD_SIZE_LARGE`
`n1-standard-16`
`n1-standard-32`
`e2-standard-2`	（デフォルト）
`e2-standard-16`		（デフォルト）
`e2-highmem-16`			（デフォルト）
`n2d-standard-32`

シャードサイズとマシンタイプが料金にどのように影響するかについては、Vertex AI の料金ページをご覧ください。シャードサイズがパフォーマンスに与える影響については、パフォーマンスに影響する構成パラメータをご覧ください。

バッチアップデート用のインデックスを作成する

次の手順でインデックスを作成してデプロイします。エンベディングがまだ準備できていない場合は、空のバッチインデックスを作成するに進んでください。このオプションでは、インデックス作成時にエンベディングデータは必要ありません。

インデックスを作成するには:

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

LOCAL_PATH_TO_METADATA_FILE: メタデータファイルのローカルパス。
INDEX_NAME: インデックスの表示名。
LOCATION: Vertex AI を使用するリージョン。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。

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

Linux、macOS、Cloud Shell

gcloud ai indexes create \
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE \
    --display-name=INDEX_NAME \
    --region=LOCATION \
    --project=PROJECT_ID

Windows（PowerShell）

gcloud ai indexes create `
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE `
    --display-name=INDEX_NAME `
    --region=LOCATION `
    --project=PROJECT_ID

Windows（cmd.exe）

gcloud ai indexes create ^
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE ^
    --display-name=INDEX_NAME ^
    --region=LOCATION ^
    --project=PROJECT_ID

次のようなレスポンスが返されます。

You can poll for the status of the operation for the response
to include "done": true. Use the following example to poll the status.

  $ gcloud ai operations describe 1234567890123456789 --project=my-test-project --region=us-central1

describe コマンドの詳細については、gcloud AI オペレーションをご覧ください。

REST

リクエストのデータを使用する前に、次のように置き換えます。

INPUT_DIR: インデックスコンテンツの Cloud Storage ディレクトリパス。
INDEX_NAME: インデックスの表示名。
LOCATION: Vertex AI を使用するリージョン。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
PROJECT_NUMBER: プロジェクトに自動生成されたプロジェクト番号。

HTTP メソッドと URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes

リクエストの本文（JSON）:

{
  "display_name": "INDEX_NAME",
  "metadata": {
    "contentsDeltaUri": "INPUT_DIR",
    "config": {
      "dimensions": 100,
      "approximateNeighborsCount": 150,
      "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
      "algorithm_config": {
        "treeAhConfig": {
          "leafNodeEmbeddingCount": 500,
          "leafNodesToSearchPercent": 7
        }
      }
    }
  }
}

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

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

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

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

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

$cred = gcloud auth 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_ID/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"
    }
  }
}

Terraform

次のサンプルでは、google_vertex_ai_index Terraform リソースを使用して、バッチアップデートのインデックスを作成します。

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。

# Cloud Storage bucket name must be unique
resource "random_id" "bucket_name_suffix" {
  byte_length = 8
}

# Create a Cloud Storage bucket
resource "google_storage_bucket" "bucket" {
  name                        = "vertex-ai-index-bucket-${random_id.bucket_name_suffix.hex}"
  location                    = "us-central1"
  uniform_bucket_level_access = true
}

# Create index content
resource "google_storage_bucket_object" "data" {
  name    = "contents/data.json"
  bucket  = google_storage_bucket.bucket.name
  content = <<EOF
{"id": "42", "embedding": [0.5, 1.0], "restricts": [{"namespace": "class", "allow": ["cat", "pet"]},{"namespace": "category", "allow": ["feline"]}]}
{"id": "43", "embedding": [0.6, 1.0], "restricts": [{"namespace": "class", "allow": ["dog", "pet"]},{"namespace": "category", "allow": ["canine"]}]}
EOF
}

resource "google_vertex_ai_index" "default" {
  region       = "us-central1"
  display_name = "sample-index-batch-update"
  description  = "A sample index for batch update"
  labels = {
    foo = "bar"
  }

  metadata {
    contents_delta_uri = "gs://${google_storage_bucket.bucket.name}/contents"
    config {
      dimensions                  = 2
      approximate_neighbors_count = 150
      distance_measure_type       = "DOT_PRODUCT_DISTANCE"
      algorithm_config {
        tree_ah_config {
          leaf_node_embedding_count    = 500
          leaf_nodes_to_search_percent = 7
        }
      }
    }
  }
  index_update_method = "BATCH_UPDATE"

  timeouts {
    create = "2h"
    update = "1h"
  }
}

Vertex AI SDK for Python

Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。詳細については、Vertex AI SDK for Python API のリファレンスドキュメントをご覧ください。

def vector_search_create_index(
    project: str, location: str, display_name: str, gcs_uri: Optional[str] = None
) -> aiplatform.MatchingEngineIndex:
    """Create a vector search index.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        display_name (str): Required. The index display name
        gcs_uri (str): Optional. The Google Cloud Storage uri for index content

    Returns:
        The created MatchingEngineIndex.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create Index
    index = aiplatform.MatchingEngineIndex.create_tree_ah_index(
        display_name=display_name,
        contents_delta_uri=gcs_uri,
        description="Matching Engine Index",
        dimensions=100,
        approximate_neighbors_count=150,
        leaf_node_embedding_count=500,
        leaf_nodes_to_search_percent=7,
        index_update_method="BATCH_UPDATE",  # Options: STREAM_UPDATE, BATCH_UPDATE
        distance_measure_type=aiplatform.matching_engine.matching_engine_index_config.DistanceMeasureType.DOT_PRODUCT_DISTANCE,
    )

    return index

Java

このサンプルを試す前に、Vertex AI クイックスタート: クライアントライブラリの使用にある Java の設定手順を完了してください。詳細については、Vertex AI Java API のリファレンスドキュメントをご覧ください。

Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。


import com.google.cloud.aiplatform.v1.CreateIndexRequest;
import com.google.cloud.aiplatform.v1.Index;
import com.google.cloud.aiplatform.v1.Index.IndexUpdateMethod;
import com.google.cloud.aiplatform.v1.IndexServiceClient;
import com.google.cloud.aiplatform.v1.IndexServiceSettings;
import com.google.cloud.aiplatform.v1.LocationName;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.util.concurrent.TimeUnit;

public class CreateIndexSample {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String location = "YOUR_LOCATION";
    String displayName = "YOUR_INDEX_DISPLAY_NAME";
    String contentsDeltaUri = "gs://YOUR_BUCKET/";
    String metadataJson =
        String.format(
            "{\n"
                + "  \"contentsDeltaUri\": \"%s\",\n"
                + "  \"config\": {\n"
                + "    \"dimensions\": 100,\n"
                + "        \"approximateNeighborsCount\": 150,\n"
                + "        \"distanceMeasureType\": \"DOT_PRODUCT_DISTANCE\",\n"
                + "        \"shardSize\": \"SHARD_SIZE_MEDIUM\",\n"
                + "        \"algorithm_config\": {\n"
                + "      \"treeAhConfig\": {\n"
                + "        \"leafNodeEmbeddingCount\": 5000,\n"
                + "            \"fractionLeafNodesToSearch\": 0.03\n"
                + "      }\n"
                + "    }\n"
                + "  }\n"
                + "}",
            contentsDeltaUri);

    createIndexSample(project, location, displayName, metadataJson);
  }

  public static Index createIndexSample(
      String project, String location, String displayName, String metadataJson) throws Exception {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IndexServiceClient indexServiceClient =
        IndexServiceClient.create(
            IndexServiceSettings.newBuilder()
                .setEndpoint(location + "-aiplatform.googleapis.com:443")
                .build())) {
      Value.Builder metadataBuilder = Value.newBuilder();
      JsonFormat.parser().merge(metadataJson, metadataBuilder);

      CreateIndexRequest request =
          CreateIndexRequest.newBuilder()
              .setParent(LocationName.of(project, location).toString())
              .setIndex(
                  Index.newBuilder()
                      .setDisplayName(displayName)
                      .setMetadata(metadataBuilder)
                      .setIndexUpdateMethod(IndexUpdateMethod.BATCH_UPDATE))
              .build();

      return indexServiceClient.createIndexAsync(request).get(5, TimeUnit.MINUTES);
    }
  }
}

コンソール

バッチアップデートのインデックスを作成するには、次の操作を使用します。

Google Cloud コンソールの [Vertex AI] セクションで、[デプロイと使用] セクションに移動します。[ベクトル検索] を選択します。
[ベクトル検索] に移動
[ 新しいインデックスの作成] をクリックして、[インデックス] ペインを開きます。[新しいインデックスの作成] ペインが表示されます。
[表示名] フィールドに、インデックスを一意に識別する名前を入力します。
[説明] フィールドに、インデックスの説明を入力します。
[リージョン] フィールドで、プルダウンからリージョンを選択します。
[Cloud Storage] フィールドで、ベクトルデータが保存されている Cloud Storage フォルダを検索して選択します。
[アルゴリズムの種類] プルダウンで、ベクトル検索で効率的な検索に使用されるアルゴリズムの種類を選択します。treeAh アルゴリズムを選択した場合は、近似近傍数を入力します。
[ディメンション] フィールドに、入力ベクトルの次元数を入力します。
[更新方法] フィールドで [バッチ] を選択します。
[シャードのサイズ] フィールドで、目的のシャードサイズをプルダウンから選択します。
[作成] をクリックします。新しいインデックスが準備できるとリストに表示されます。注: ビルドが完了するまでに 1 時間ほどかかることがあります。

空のバッチインデックスを作成する

インデックスをすぐに作成してデプロイするには、空のバッチインデックスを作成します。このオプションでは、インデックス作成時にエンベディングデータは必要ありません。

空のインデックスを作成するためのリクエストは、バッチ更新用のインデックスを作成する場合とほぼ同じです。異なるのは、データロケーションをリンクしないため contentsDeltaUri フィールドを削除する点です。次に、空のバッチインデックスの例を示します。

空のインデックスリクエストの例

{
  "display_name": INDEX_NAME,
  "indexUpdateMethod": "BATCH_UPDATE",
  "metadata": {
    "config": {
      "dimensions": 100,
      "approximateNeighborsCount": 150,
      "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
      "algorithm_config": {
        "treeAhConfig": {
          "leafNodeEmbeddingCount": 500,
          "leafNodesToSearchPercent": 7
        }
      }
    }
  }
}

ストリーミング更新用のインデックスを作成する

ストリーミングインデックスを作成してデプロイする手順は次のとおりです。エンベディングの準備ができていない場合は、ストリーミング更新用の空のインデックスを作成するに進みます。このオプションでは、インデックス作成時にエンベディングデータは必要ありません。

REST

リクエストのデータを使用する前に、次のように置き換えます。

INDEX_NAME: インデックスの表示名。
DESCRIPTION: インデックスの説明。
INPUT_DIR: インデックスコンテンツの Cloud Storage ディレクトリパス。
DIMENSIONS: エンベディングベクトルの次元数。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
PROJECT_NUMBER: プロジェクトに自動生成されたプロジェクト番号。
LOCATION: Vertex AI を使用するリージョン。

HTTP メソッドと URL:

POST https://ENDPOINT-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes

リクエストの本文（JSON）:

{
  displayName: "INDEX_NAME",
  description: "DESCRIPTION",
  metadata: {
     contentsDeltaUri: "INPUT_DIR",
     config: {
        dimensions: "DIMENSIONS",
        approximateNeighborsCount: 150,
        distanceMeasureType: "DOT_PRODUCT_DISTANCE",
        algorithmConfig: {treeAhConfig: {leafNodeEmbeddingCount: 10000, leafNodesToSearchPercent: 2}}
     },
  },
  indexUpdateMethod: "STREAM_UPDATE"
}

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

curl（Linux、macOS、Cloud Shell）

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

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

PowerShell（Windows）

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

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

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

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.ui.CreateIndexOperationMetadata",
    "genericMetadata": {
      "createTime": "2023-12-05T23:17:45.416117Z",
      "updateTime": "2023-12-05T23:17:45.416117Z",
      "state": "RUNNING",
      "worksOn": [
        "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID"
      ]
    }
  }
}

Terraform

次のサンプルでは、google_vertex_ai_index Terraform リソースを使用して、ストリーミング更新のインデックスを作成しています。

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。

# Cloud Storage bucket name must be unique
resource "random_id" "default" {
  byte_length = 8
}

# Create a Cloud Storage bucket
resource "google_storage_bucket" "bucket" {
  name                        = "vertex-ai-index-bucket-${random_id.default.hex}"
  location                    = "us-central1"
  uniform_bucket_level_access = true
}

# Create index content
resource "google_storage_bucket_object" "data" {
  name    = "contents/data.json"
  bucket  = google_storage_bucket.bucket.name
  content = <<EOF
{"id": "42", "embedding": [0.5, 1.0], "restricts": [{"namespace": "class", "allow": ["cat", "pet"]},{"namespace": "category", "allow": ["feline"]}]}
{"id": "43", "embedding": [0.6, 1.0], "restricts": [{"namespace": "class", "allow": ["dog", "pet"]},{"namespace": "category", "allow": ["canine"]}]}
EOF
}

resource "google_vertex_ai_index" "streaming_index" {
  region       = "us-central1"
  display_name = "sample-index-streaming-update"
  description  = "A sample index for streaming update"
  labels = {
    foo = "bar"
  }

  metadata {
    contents_delta_uri = "gs://${google_storage_bucket.bucket.name}/contents"
    config {
      dimensions                  = 2
      approximate_neighbors_count = 150
      distance_measure_type       = "DOT_PRODUCT_DISTANCE"
      algorithm_config {
        tree_ah_config {
          leaf_node_embedding_count    = 500
          leaf_nodes_to_search_percent = 7
        }
      }
    }
  }
  index_update_method = "STREAM_UPDATE"

  timeouts {
    create = "2h"
    update = "1h"
  }
}

Vertex AI SDK for Python

def vector_search_create_streaming_index(
    project: str, location: str, display_name: str, gcs_uri: Optional[str] = None
) -> aiplatform.MatchingEngineIndex:
    """Create a vector search index.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        display_name (str): Required. The index display name
        gcs_uri (str): Optional. The Google Cloud Storage uri for index content

    Returns:
        The created MatchingEngineIndex.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create Index
    index = aiplatform.MatchingEngineIndex.create_tree_ah_index(
        display_name=display_name,
        contents_delta_uri=gcs_uri,
        description="Matching Engine Index",
        dimensions=100,
        approximate_neighbors_count=150,
        leaf_node_embedding_count=500,
        leaf_nodes_to_search_percent=7,
        index_update_method="STREAM_UPDATE",  # Options: STREAM_UPDATE, BATCH_UPDATE
        distance_measure_type=aiplatform.matching_engine.matching_engine_index_config.DistanceMeasureType.DOT_PRODUCT_DISTANCE,
    )

    return index

Java


import com.google.cloud.aiplatform.v1.CreateIndexRequest;
import com.google.cloud.aiplatform.v1.Index;
import com.google.cloud.aiplatform.v1.Index.IndexUpdateMethod;
import com.google.cloud.aiplatform.v1.IndexServiceClient;
import com.google.cloud.aiplatform.v1.IndexServiceSettings;
import com.google.cloud.aiplatform.v1.LocationName;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.util.concurrent.TimeUnit;

public class CreateStreamingIndexSample {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String location = "YOUR_LOCATION";
    String displayName = "YOUR_INDEX_DISPLAY_NAME";
    String contentsDeltaUri = "gs://YOUR_BUCKET/";
    String metadataJson =
        String.format(
            "{\n"
                + "  \"contentsDeltaUri\": \"%s\",\n"
                + "  \"config\": {\n"
                + "    \"dimensions\": 100,\n"
                + "        \"approximateNeighborsCount\": 150,\n"
                + "        \"distanceMeasureType\": \"DOT_PRODUCT_DISTANCE\",\n"
                + "        \"shardSize\": \"SHARD_SIZE_MEDIUM\",\n"
                + "        \"algorithm_config\": {\n"
                + "      \"treeAhConfig\": {\n"
                + "        \"leafNodeEmbeddingCount\": 5000,\n"
                + "            \"fractionLeafNodesToSearch\": 0.03\n"
                + "      }\n"
                + "    }\n"
                + "  }\n"
                + "}",
            contentsDeltaUri);

    createStreamingIndexSample(project, location, displayName, metadataJson);
  }

  public static Index createStreamingIndexSample(
      String project, String location, String displayName, String metadataJson) throws Exception {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IndexServiceClient indexServiceClient =
        IndexServiceClient.create(
            IndexServiceSettings.newBuilder()
                .setEndpoint(location + "-aiplatform.googleapis.com:443")
                .build())) {
      Value.Builder metadataBuilder = Value.newBuilder();
      JsonFormat.parser().merge(metadataJson, metadataBuilder);

      CreateIndexRequest request =
          CreateIndexRequest.newBuilder()
              .setParent(LocationName.of(project, location).toString())
              .setIndex(
                  Index.newBuilder()
                      .setDisplayName(displayName)
                      .setMetadata(metadataBuilder)
                      .setIndexUpdateMethod(IndexUpdateMethod.STREAM_UPDATE))
              .build();

      return indexServiceClient.createIndexAsync(request).get(5, TimeUnit.MINUTES);
    }
  }
}

コンソール

Google Cloud コンソールでストリーミング更新用のインデックスを作成するには、次の操作を使用します。

ストリーミングアップデートで使用可能なインデックスを作成するには、バッチアップデート用インデックスの設定と同様の操作を行う必要があります。ただし、STREAM_UPDATE を indexUpdateMethod に設定する必要があります。

Google Cloud コンソールの [Vertex AI] セクションで、[デプロイと使用] セクションに移動します。[ベクトル検索] を選択します。
[ベクトル検索] に移動
[ 新しいインデックスの作成] をクリックして、[インデックス] ペインを開きます。[新しいインデックスの作成] ペインが表示されます。
[表示名] フィールドに、インデックスを一意に識別する名前を入力します。
[説明] フィールドに、インデックスの説明を入力します。
[リージョン] フィールドで、プルダウンからリージョンを選択します。
[Cloud Storage] フィールドで、ベクトルデータが保存されている Cloud Storage フォルダを検索して選択します。
[アルゴリズムの種類] プルダウンで、ベクトル検索で検索に使用するアルゴリズムの種類を選択します。treeAh アルゴリズムを選択した場合は、近似近傍数を入力します。
[ディメンション] フィールドに、入力ベクトルの次元数を入力します。
[更新方法] フィールドで [ストリーム] を選択します。
[シャードのサイズ] フィールドで、目的のシャードサイズをプルダウンから選択します。
[作成] をクリックします。新しいインデックスが準備できるとリストに表示されます。注: ビルドが完了するまでに 1 時間ほどかかることがあります。

ストリーミング更新用の空のインデックスを作成する

インデックスをすぐに作成してデプロイするには、ストリーミング用の空のインデックスを作成します。このオプションでは、インデックス作成時にエンベディングデータは必要ありません。

空のインデックスを作成するためのリクエストは、ストリーミング用のインデックスを作成する場合とほぼ同じです。異なるのは、データロケーションをリンクしないため contentsDeltaUri フィールドを削除する点です。次に、空のストリーミングインデックスの例を示します。

空のインデックスリクエストの例

{
  "display_name": INDEX_NAME,
  "indexUpdateMethod": "STREAM_UPDATE",
  "metadata": {
    "config": {
      "dimensions": 100,
      "approximateNeighborsCount": 150,
      "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
      "algorithm_config": {
        "treeAhConfig": {
          "leafNodeEmbeddingCount": 500,
          "leafNodesToSearchPercent": 7
        }
      }
    }
  }
}

インデックスを一覧表示する

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

INDEX_NAME: インデックスの表示名。
LOCATION: Vertex AI を使用するリージョン。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。

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

Linux、macOS、Cloud Shell

gcloud ai indexes list \
    --region=LOCATION \
    --project=PROJECT_ID

Windows（PowerShell）

gcloud ai indexes list `
    --region=LOCATION `
    --project=PROJECT_ID

Windows（cmd.exe）

gcloud ai indexes list ^
    --region=LOCATION ^
    --project=PROJECT_ID

次のようなレスポンスが返されます。

You can poll for the status of the operation for the response
to include "done": true. Use the following example to poll the status.

  $ gcloud ai operations describe 1234567890123456789 --project=my-test-project --region=us-central1

describe コマンドの詳細については、gcloud AI オペレーションをご覧ください。

REST

リクエストのデータを使用する前に、次のように置き換えます。

INDEX_NAME: インデックスの表示名。
LOCATION: Vertex AI を使用するリージョン。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
PROJECT_NUMBER: プロジェクトに自動生成されたプロジェクト番号。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes

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

curl（Linux、macOS、Cloud Shell）

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

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

PowerShell（Windows）

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

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/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"
   }
 ]
}

Vertex AI SDK for Python

def vector_search_list_index(
    project: str, location: str
) -> List[aiplatform.MatchingEngineIndex]:
    """List vector search indexes.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name

    Returns:
        List of aiplatform.MatchingEngineIndex
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # List Indexes
    return aiplatform.MatchingEngineIndex.list()

Java


import com.google.cloud.aiplatform.v1.Index;
import com.google.cloud.aiplatform.v1.IndexServiceClient;
import com.google.cloud.aiplatform.v1.IndexServiceClient.ListIndexesPagedResponse;
import com.google.cloud.aiplatform.v1.IndexServiceSettings;
import com.google.cloud.aiplatform.v1.LocationName;

public class ListIndexesSample {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String location = "YOUR_LOCATION";

    for (Index index : listIndexesSample(project, location).iterateAll()) {
      System.out.println(index.getName());
    }
  }

  public static ListIndexesPagedResponse listIndexesSample(String project, String location)
      throws Exception {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IndexServiceClient indexServiceClient =
        IndexServiceClient.create(
            IndexServiceSettings.newBuilder()
                .setEndpoint(location + "-aiplatform.googleapis.com:443")
                .build())) {
      String parent = LocationName.of(project, location).toString();
      return indexServiceClient.listIndexes(parent);
    }
  }
}

コンソール

インデックスのリストを表示するには、次の操作を使用します。

Google Cloud コンソールの [Vertex AI] セクションで、[デプロイと使用] セクションに移動します。[ベクトル検索] を選択します。
[ベクトル検索] に移動
アクティブなインデックスのリストが表示されます。

インデックスの調整

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

パフォーマンスに影響する構成パラメータ

次の構成パラメータはインデックス作成時に設定できます。ベクトル検索を使用する場合、再現率、レイテンシ、可用性、コストに影響する可能性があります。このガイダンスはほとんどのケースに適用されます。ただし、必ず構成をテストして、ユースケースに適していることを確認してください。

パラメータの定義については、インデックス構成パラメータをご覧ください。

パラメータ概要パフォーマンスへの影響

パラメータ	概要	パフォーマンスへの影響
`shardSize`	各マシン上のデータ量を制御します。シャードのサイズを選択する際は、将来のデータセットのサイズを推定します。データセットのサイズに上限がある場合は、それに適したシャードサイズを選択します。上限がない場合や、レイテンシの変動に影響を受けやすいユースケースの場合は、大きなシャードサイズを選択することをおすすめします。	シャードのサイズを小さくしてシャード数を増やすと、検索時に処理される候補結果の数が多くなります。シャード数が多いと、次のようにパフォーマンスに影響します。再現率: 増加レイテンシ: 増加する可能性があり、変動が大きくなる可用性: シャードの停止が影響するデータの割合は小さいコスト: 同じマシンタイプをより多くのシャードで使用すると増加する可能性があるシャードのサイズを大きくしてシャード数を減らすと、検索時に処理される候補結果が少なくなります。シャード数が少ないと、次のようにパフォーマンスに影響する可能性があります。再現率: 減少レイテンシ: 低下、変動は減少可用性: シャードの停止がデータの大部分に影響コスト: 同じマシンタイプをより少数のシャードで使用すると削減可能
`distanceMeasureType`	データポイントとクエリベクトルの間の距離の計算に使用するアルゴリズムを決定します。	次の `distanceMeasureType` 設定は、クエリのレイテンシの短縮に役立ちます。 `DOT_PRODUCT_DISTANCE` はレイテンシの短縮に最も適しています。コサイン類似度では、`DOT_PRODUCT_DISTANCE` と `FeatureNormType` を `UNIT_L2_NORM` に設定することをおすすめします。
`leafNodeEmbeddingCount`	各リーフノードの埋め込み数。デフォルトでは 1000 に設定されています。通常、`leafNodeEmbeddingCount` の値を変更する影響は、他のパラメータの値を変更する場合よりも少なくなります。	各リーフノードの埋め込み数を増やすと、レイテンシは短くなりますが、再現率は低下します。これにより、次のようにパフォーマンスに影響する可能性があります。再現率: ターゲットとなる検索が減少するため減少レイテンシ: ほとんどのユースケースで、値が 15,000 を超えない限り低下可用性: 影響なしコスト: 同じ QPS に必要なレプリカが少なくなるため、削減可能各リーフノードの埋め込み数を減らすと、パフォーマンスに次のような影響が生じる可能性があります。再現率: ターゲットリーフの収集量が増えるため、増加する可能性があるレイテンシ: 増加可用性: 影響なしコスト: 同じ QPS に必要なレプリカが増えるため、コストが増加する可能性がある

shardSize

各マシン上のデータ量を制御します。

シャードのサイズを選択する際は、将来のデータセットのサイズを推定します。データセットのサイズに上限がある場合は、それに適したシャードサイズを選択します。上限がない場合や、レイテンシの変動に影響を受けやすいユースケースの場合は、大きなシャードサイズを選択することをおすすめします。

シャードのサイズを小さくしてシャード数を増やすと、検索時に処理される候補結果の数が多くなります。シャード数が多いと、次のようにパフォーマンスに影響します。

再現率: 増加
レイテンシ: 増加する可能性があり、変動が大きくなる
可用性: シャードの停止が影響するデータの割合は小さい
コスト: 同じマシンタイプをより多くのシャードで使用すると増加する可能性がある

シャードのサイズを大きくしてシャード数を減らすと、検索時に処理される候補結果が少なくなります。シャード数が少ないと、次のようにパフォーマンスに影響する可能性があります。

再現率: 減少
レイテンシ: 低下、変動は減少
可用性: シャードの停止がデータの大部分に影響
コスト: 同じマシンタイプをより少数のシャードで使用すると削減可能

distanceMeasureType

データポイントとクエリベクトルの間の距離の計算に使用するアルゴリズムを決定します。

次の distanceMeasureType 設定は、クエリのレイテンシの短縮に役立ちます。

DOT_PRODUCT_DISTANCE はレイテンシの短縮に最も適しています。
コサイン類似度では、DOT_PRODUCT_DISTANCE と FeatureNormType を UNIT_L2_NORM に設定することをおすすめします。

leafNodeEmbeddingCount

各リーフノードの埋め込み数。デフォルトでは 1000 に設定されています。

通常、leafNodeEmbeddingCount の値を変更する影響は、他のパラメータの値を変更する場合よりも少なくなります。

各リーフノードの埋め込み数を増やすと、レイテンシは短くなりますが、再現率は低下します。これにより、次のようにパフォーマンスに影響する可能性があります。

再現率: ターゲットとなる検索が減少するため減少
レイテンシ: ほとんどのユースケースで、値が 15,000 を超えない限り低下
可用性: 影響なし
コスト: 同じ QPS に必要なレプリカが少なくなるため、削減可能

各リーフノードの埋め込み数を減らすと、パフォーマンスに次のような影響が生じる可能性があります。

再現率: ターゲットリーフの収集量が増えるため、増加する可能性がある
レイテンシ: 増加
可用性: 影響なし
コスト: 同じ QPS に必要なレプリカが増えるため、コストが増加する可能性がある

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

確な最近傍を取得するには、ブルートフォースアルゴリズムのインデックスを使用します。ブルートフォースアルゴリズムを使用すると、レイテンシは高くなりますが、100% の再現率を達成できます。ブルートフォースインデックスを使用して再現率を測定する方法は、本番環境サービスに適していませんが、さまざまなインデックス登録オプションの再現率をオフラインで評価するのに役立ちます。

ブルートフォースアルゴリズムを使用してインデックスを作成するには、インデックスメタデータに brute_force_config を指定します。

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer `gcloud auth print-access-token`" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexes \
-d '{
    displayName: "'${DISPLAY_NAME}'",
    description: "'${DESCRIPTION}'",
    metadata: {
       contentsDeltaUri: "'${INPUT_DIR}'",
       config: {
          dimensions: 100,
          approximateNeighborsCount: 150,
          distanceMeasureType: "DOT_PRODUCT_DISTANCE",
          featureNormType: "UNIT_L2_NORM",
          algorithmConfig: {
             bruteForceConfig: {}
          }
       },
    },
}'

インデックスを削除する

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

INDEX_ID: インデックスの ID。
LOCATION: Vertex AI を使用するリージョン。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。

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

Linux、macOS、Cloud Shell

gcloud ai indexes delete INDEX_ID \
    --region=LOCATION \
    --project=PROJECT_ID

Windows（PowerShell）

gcloud ai indexes delete INDEX_ID `
    --region=LOCATION `
    --project=PROJECT_ID

Windows（cmd.exe）

gcloud ai indexes delete INDEX_ID ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

リクエストのデータを使用する前に、次のように置き換えます。

INDEX_ID: インデックスの ID。
LOCATION: Vertex AI を使用するリージョン。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
PROJECT_NUMBER: プロジェクトに自動生成されたプロジェクト番号。

HTTP メソッドと URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID

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

curl（Linux、macOS、Cloud Shell）

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

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

PowerShell（Windows）

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

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

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_NUMBER/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"
  }
}

Vertex AI SDK for Python

def vector_search_delete_index(
    project: str, location: str, index_name: str
) -> None:
    """Delete a vector search index.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_name (str): Required. The index to update. A fully-qualified index
          resource name or a index ID.  Example:
          "projects/123/locations/us-central1/indexes/my_index_id" or
          "my_index_id".
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index instance from an existing index
    index = aiplatform.MatchingEngineIndex(index_name=index_name)

    # Delete the index
    index.delete()

Java


import com.google.cloud.aiplatform.v1.IndexName;
import com.google.cloud.aiplatform.v1.IndexServiceClient;
import com.google.cloud.aiplatform.v1.IndexServiceSettings;
import java.util.concurrent.TimeUnit;

public class DeleteIndexSample {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String location = "YOUR_LOCATION";
    String indexId = "YOUR_INDEX_ID";

    deleteIndexSample(project, location, indexId);
  }

  public static void deleteIndexSample(String project, String location, String indexId)
      throws Exception {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IndexServiceClient indexServiceClient =
        IndexServiceClient.create(
            IndexServiceSettings.newBuilder()
                .setEndpoint(location + "-aiplatform.googleapis.com:443")
                .build())) {
      String indexName = IndexName.of(project, location, indexId).toString();
      indexServiceClient.deleteIndexAsync(indexName).get(5, TimeUnit.MINUTES);
    }
  }
}

コンソール

1 つ以上のインデックスを削除するには、次の操作を行います。

Google Cloud コンソールの [Vertex AI] セクションで、[デプロイと使用] セクションに移動します。[ベクトル検索] を選択します。
[ベクトル検索] に移動
アクティブなインデックスのリストが表示されます。
インデックスを削除するには、インデックスと同じ行にある [ オプション] メニューに移動して、[削除] を選択します。

次のステップ

インデックス構成パラメータについて学習する
パブリックインデックスエンドポイントをデプロイして管理する方法を学習する
VPC ネットワークにインデックスエンドポイントをデプロイして管理する方法を学習する
インデックスの更新と再構築の方法を学習する
インデックスのモニタリング方法を学習する

インデックスの管理

インデックスの概要

インデックス パラメータを構成する

インデックスを作成する

インデックス サイズ

バッチ アップデート用のインデックスを作成する

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Terraform

Vertex AI SDK for Python

Java

コンソール

空のバッチ インデックスを作成する

空のインデックス リクエストの例

ストリーミング更新用のインデックスを作成する

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Terraform

Vertex AI SDK for Python

Java

コンソール

ストリーミング更新用の空のインデックスを作成する

空のインデックス リクエストの例

インデックスを一覧表示する

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Vertex AI SDK for Python

Java

コンソール

インデックスの調整

パフォーマンスに影響する構成パラメータ

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

インデックスを削除する

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Vertex AI SDK for Python

Java

コンソール

次のステップ

インデックスパラメータを構成する

インデックスサイズ

バッチアップデート用のインデックスを作成する

空のバッチインデックスを作成する

空のインデックスリクエストの例

空のインデックスリクエストの例

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