管理索引

下列各節將說明如何設定、建立、列出及刪除索引。

索引總覽

索引是包含嵌入向量的檔案。這些向量是由您想透過 Vector Search 部署及查詢的大量資料所建立。您可以使用向量搜尋建立兩種索引,具體取決於您打算如何使用資料更新索引。您可以建立專為批次更新設計的索引,或是專為串流更新設計的索引。

當您想要以批次方式更新索引,並使用在指定時間內儲存的資料時 (例如每週或每月處理的系統),就會用到批次索引。當您希望在資料儲存庫中新增新資料時更新索引資料時,就需要使用串流索引,例如,如果您是書店,希望盡快在線上顯示新商品目錄,您選擇的類型非常重要,因為設定和需求各不相同。

設定索引參數

建立索引前,請先設定索引的參數。

例如,建立名為 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。

您可以使用公開端點虛擬私有雲端點,部署索引的機器類型取決於索引的分片大小。下表列出每個機器類型支援的分片大小:

機型 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 operations

REST

使用任何要求資料之前,請先替換以下項目:

  • INPUT_DIR:索引內容的 Cloud Storage 目錄路徑。
  • INDEX_NAME:索引的顯示名稱。
  • LOCATION:您使用 Vertex AI 的區域。
  • PROJECT_ID:您的 Google Cloud 專案 ID
  • PROJECT_NUMBER:系統自動產生的專案編號

HTTP 方法和網址:

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

如要傳送要求,請展開以下其中一個選項:

您應該會收到如下的 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"
  }
}

Python 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK,請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 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);
    }
  }
}

控制台

請按照下列操作說明建立索引,以便進行批次更新。

  1. 在 Google Cloud 控制台的 Vertex AI 專區中,前往「部署及使用」專區。選取「向量搜尋」

    前往 Vector Search

  2. 按一下「 建立新索引,開啟「索引」窗格。畫面上會顯示「Create a new index」窗格。
  3. 在「Display name」欄位中,提供用於識別索引的不重複名稱。
  4. 在「Description」欄位中,提供索引的用途說明。
  5. 在「Region」欄位中,從下拉式選單中選取所需地區。
  6. 在 Cloud Storage 欄位中,搜尋並選取儲存向量資料的 Cloud Storage 資料夾。
  7. 在「演算法類型」下拉式選單中,選取 Vector Search 用於高效率搜尋的演算法類型。如果您選取 treeAh 演算法,請輸入近似鄰點數量。
  8. 在「Dimensions」欄位中,輸入輸入向量的維度數量。
  9. 在「更新方法」欄位中,選取「批次」
  10. 在「分片大小」欄位中,從下拉式選單中選取所需的分片大小。
  11. 按一下「建立」,新的索引準備就緒後,就會顯示在索引清單中。注意:建構作業最多可能需要一小時才能完成。

建立空白批次索引

如要立即建立及部署索引,您可以建立空白批次索引。使用這個選項時,建立索引時不需要嵌入資料。

如要建立空白索引,要求幾乎與建立批次更新索引相同。差別在於您會移除 contentsDeltaUri 欄位,因為您並未連結資料位置。以下是空白批次索引範例:

空白索引要求範例

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

建立用於串流更新的索引

請按照這些操作說明建立及部署串流索引。如果您尚未準備好內嵌項目,請跳到「建立空白索引以進行串流更新」一節。使用這個選項時,建立索引時不需要嵌入資料。

REST

使用任何要求資料之前,請先替換以下項目:

  • INDEX_NAME:索引的顯示名稱。
  • DESCRIPTION:索引的說明。
  • INPUT_DIR:索引內容的 Cloud Storage 目錄路徑。
  • DIMENSIONS:嵌入向量的維度數量。
  • PROJECT_ID:您的 Google Cloud 專案 ID
  • PROJECT_NUMBER:系統自動產生的專案編號
  • LOCATION:您使用 Vertex AI 的區域。

HTTP 方法和網址:

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

如要傳送要求,請展開以下其中一個選項:

您應該會收到如下的 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"
  }
}

Python 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK,請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件

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

在試用這個範例之前,請先按照 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 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 控制台中建立串流更新索引。

如要建立可用於串流更新的索引 ,您必須採取與設定批次更新索引類似的步驟,但需要將 indexUpdateMethod 設為 STREAM_UPDATE

  1. 在 Google Cloud 控制台的 Vertex AI 專區中,前往「部署及使用」專區。選取「Vector Search」

    前往 Vector Search

  2. 按一下「 建立新索引,開啟「索引」窗格。畫面上會顯示「Create a new index」(建立新索引) 窗格。
  3. 在「Display name」欄位中,輸入用於識別索引的名稱。
  4. 在「Description」欄位中,提供索引的用途說明。
  5. 在「Region」欄位中,從下拉式選單中選取所需地區。
  6. 在 Cloud Storage 欄位中,搜尋並選取儲存向量資料的 Cloud Storage 資料夾。
  7. 在「演算法類型」下拉式選單中,選取 Vector Search 用於執行搜尋的演算法類型。如果您選取 treeAh 演算法,請輸入近似鄰點數量。
  8. 在「維度」欄位中輸入輸入向量的維度數量。
  9. 在「Update method」欄位中,選取「Stream」
  10. 在「分片大小」欄位中,從下拉式選單中選取所需的分片大小。
  11. 按一下「建立」,新的索引準備就緒後,就會顯示在索引清單中。 注意:建構作業最多可能需要一小時才能完成。

建立用於串流更新的空白索引

如要立即建立及部署索引,您可以建立用於串流的空白索引。使用這個選項時,建立索引時不需要嵌入資料。

如要建立空白索引,要求幾乎與建立串流索引相同。差別在於您會移除 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 operations

REST

使用任何要求資料之前,請先替換以下項目:

  • INDEX_NAME:索引的顯示名稱。
  • LOCATION:您使用 Vertex AI 的區域。
  • PROJECT_ID:您的 Google Cloud 專案 ID
  • PROJECT_NUMBER:系統自動產生的專案編號

HTTP 方法和網址:

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

如要傳送要求,請展開以下其中一個選項:

您應該會收到如下的 JSON 回應:

{
 "indexes": [
   {
     "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID",
     "displayName": "INDEX_NAME",
     "metadataSchemaUri": "gs://google-cloud-aiplatform/schema/matchingengine/metadata/nearest_neighbor_search_1.0.0.yaml",
     "metadata": {
       "config": {
         "dimensions": 100,
         "approximateNeighborsCount": 150,
         "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
         "featureNormType": "NONE",
         "algorithmConfig": {
           "treeAhConfig": {
             "maxLeavesToSearch": 50,
             "leafNodeCount": 10000
           }
         }
       }
     },
     "etag": "AMEw9yNU8YX5IvwuINeBkVv3yNa7VGKk11GBQ8GkfRoVvO7LgRUeOo0qobYWuU9DiEc=",
     "createTime": "2020-11-08T21:56:30.558449Z",
     "updateTime": "2020-11-08T22:39:25.048623Z"
   }
 ]
}

Python 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK,請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件

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

在試用這個範例之前,請先按照 Vertex AI 快速入門:使用用戶端程式庫中的操作說明設定 Java。詳情請參閱 Vertex AI Java API 參考說明文件

如要向 Vertex AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


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

控制台

請按照下列操作說明查看索引清單。

  1. 在 Google Cloud 控制台的 Vertex AI 專區中,前往「部署及使用」專區。選取「向量搜尋」

    前往 Vector Search

  2. 系統會顯示有效索引清單。

調整索引

調整索引時,您必須設定會影響已部署索引效能的設定參數,尤其是喚回率和延遲時間。這些參數會在首次建立索引時設定。您可以使用暴力索引來評估回憶率。

影響效能的設定參數

下列設定參數可在建立索引時設定,並可影響使用向量搜尋時的喚回率、延遲時間、可用性和費用。這項指引適用於大多數情況。不過,請務必嘗試設定,確保設定適用於您的用途。

如要瞭解參數定義,請參閱「索引設定參數」。

參數 關於 效能影響
shardSize

控制每部機器上的資料量。

選擇分割區大小時,請預估資料集未來的大小。如果資料集的大小有上限,請選擇適當的分片大小來配合。如果沒有上限,或是您的用途對延遲變化極為敏感,建議選擇較大的區塊大小。

如果您設定較多個較小的資料分割,系統在搜尋期間會處理較多候選結果。較多切片可能會對效能造成以下影響:

  • 喚回度:增加
  • 延遲時間:可能增加,變化更大
  • 可用性:資料分片發生異常時,影響的資料比例較小
  • 費用:如果使用相同的機器類型,且分割區數量增加,費用可能會提高

如果您設定較少數量的較大資料分割,系統在搜尋期間處理的候選結果就會減少。較少的分片可能會對效能造成以下影響:

  • 喚回度:降低
  • 延遲:減少、變化性降低
  • 可用性:區塊發生異常時,會影響更多資料
  • 成本:如果使用相同的機器類型,且分割區較少,成本可能會降低
distanceMeasureType

決定用於計算資料點與查詢向量之間距離的演算法。

下列 distanceMeasureType 設定有助於縮短查詢延遲時間:

  • DOT_PRODUCT_DISTANCE 最適合用於縮短延遲時間
  • 建議將 DOT_PRODUCT_DISTANCEFeatureNormType 設定為 UNIT_L2_NORM,以便計算餘弦相似度
leafNodeEmbeddingCount

每個分葉節點的嵌入項目數量。預設值為 1000。

一般來說,變更 leafNodeEmbeddingCount 的值比變更其他參數的值影響較小。

增加每個分葉節點的嵌入項目數量,雖然可以縮短延遲時間,但會降低回憶品質。這可能會影響效能,具體影響如下:

  • 回想:由於指定搜尋次數減少,因此有所下降
  • 延遲時間:在大多數情況下,只要值不超過 15k
  • 供應情形:沒有影響
  • 費用:可降低,因為相同的 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 方法和網址:

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

如要傳送要求,請展開以下其中一個選項:

您應該會收到如下的 JSON 回應:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeleteOperationMetadata",
    "genericMetadata": {
      "createTime": "2022-01-08T02:35:56.364956Z",
      "updateTime": "2022-01-08T02:35:56.364956Z"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Python 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK,請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for Python API 參考說明文件

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

在試用這個範例之前,請先按照 Vertex AI 快速入門:使用用戶端程式庫中的操作說明設定 Java。詳情請參閱 Vertex AI Java API 參考說明文件

如要向 Vertex AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


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 專區中,前往「部署及使用」專區。選取「向量搜尋」

    前往 Vector Search

  2. 系統會顯示有效索引清單。
  3. 如要刪除索引,請前往與索引位於同一列的 選項選單,然後選取「Delete」

後續步驟