管理索引

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

索引總覽

索引是包含嵌入向量的一或多個檔案。這些向量是由大量資料所組成，您想透過 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 定價頁面。如要瞭解分片大小對效能的影響，請參閱「影響效能的設定參數」。

建立批次更新的索引

請按照這些操作說明建立及部署索引。如果還沒準備好嵌入內容，可以跳到「建立空白批次索引」。使用這個選項時，建立索引時不需要嵌入資料。

注意： dimensions 欄位僅適用於密集嵌入。

如要建立索引，請按照下列步驟操作：

gcloud

使用下列任何指令資料之前，請先替換以下項目：

• LOCAL_PATH_TO_METADATA_FILE：中繼資料檔案的本機路徑。
• INDEX_NAME：索引的顯示名稱。
• LOCATION：您使用 Vertex AI 的區域。
• PROJECT_ID：您的 Google Cloud 專案 ID。

執行下列指令：

Linux、macOS 或 Cloud Shell

注意： 請確認您已透過執行下列任一指令，初始化 Google Cloud CLI 的驗證和專案： gcloud init； 或 gcloud auth login 和 gcloud config set project。

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

Windows (PowerShell)

注意： 請確認您已透過執行下列任一指令，初始化 Google Cloud CLI 的驗證和專案： gcloud init； 或 gcloud auth login 和 gcloud config set project。

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

Windows (cmd.exe)

注意： 請確認您已透過執行下列任一指令，初始化 Google Cloud CLI 的驗證和專案： gcloud init； 或 gcloud auth login 和 gcloud config set project。

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

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

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

Python

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

在試用這個範例之前，請先按照Java使用用戶端程式庫的 Vertex AI 快速入門中的操作說明進行設定。 詳情請參閱 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 專區中，前往「Deploy and Use」(部署及使用) 專區。選取「Vector Search」

   前往 Vector Search

2. 按一下「建立新索引」，開啟「索引」窗格。畫面上會顯示「建立新索引」窗格。
3. 在「顯示名稱」欄位中，提供可專門用來識別索引的名稱。
4. 在「Description」(說明) 欄位中，提供索引用途的說明。
5. 在「Region」(區域) 欄位中，從下拉式選單選取區域。
6. 在「Cloud Storage」欄位中，搜尋並選取儲存向量資料的 Cloud Storage 資料夾。
7. 在「演算法類型」下拉式選單中，選取 Vector Search 用於高效率搜尋的演算法類型。如果選取 treeAh 演算法，請輸入近似鄰點數量。
8. 在「維度」欄位中，輸入輸入向量的維度數量。
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
        }
      }
    }
  }
}
  

建立串流更新的索引

請按照這些操作說明建立及部署串流索引。如果還沒準備好嵌入內容，請跳至「為串流更新建立空白索引」。使用這個選項時，建立索引時不需要嵌入資料。

注意： dimensions 欄位僅適用於密集嵌入。

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

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

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://ENDPOINT-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://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"
  }
}

Python

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

在試用這個範例之前，請先按照Java使用用戶端程式庫的 Vertex AI 快速入門中的操作說明進行設定。 詳情請參閱 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 專區中，前往「Deploy and Use」(部署及使用) 專區。選取「Vector Search」

   前往 Vector Search

2. 按一下「建立新索引」，開啟「索引」窗格。畫面上會顯示「建立新索引」窗格。
3. 在「顯示名稱」欄位中，提供可專門識別索引的名稱。
4. 在「Description」(說明) 欄位中，提供索引用途的說明。
5. 在「Region」(區域) 欄位中，從下拉式選單選取區域。
6. 在「Cloud Storage」欄位中，搜尋並選取儲存向量資料的 Cloud Storage 資料夾。
7. 在「演算法類型」下拉式選單中，選取 Vector Search 用於執行搜尋的演算法類型。如果選取 treeAh 演算法，請輸入近似鄰點數量。
8. 在「維度」欄位中，輸入輸入向量的維度數量。
9. 在「更新方法」欄位中，選取「串流」。
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

注意： 請確認您已透過執行下列任一指令，初始化 Google Cloud CLI 的驗證和專案： gcloud init； 或 gcloud auth login 和 gcloud config set project。

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

Windows (PowerShell)

注意： 請確認您已透過執行下列任一指令，初始化 Google Cloud CLI 的驗證和專案： gcloud init； 或 gcloud auth login 和 gcloud config set project。

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

Windows (cmd.exe)

注意： 請確認您已透過執行下列任一指令，初始化 Google Cloud CLI 的驗證和專案： gcloud init； 或 gcloud auth login 和 gcloud config set project。

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

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

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

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)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

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

Python

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

在試用這個範例之前，請先按照Java使用用戶端程式庫的 Vertex AI 快速入門中的操作說明進行設定。 詳情請參閱 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 專區中，前往「Deploy and Use」(部署及使用) 專區。選取「Vector Search」

   前往 Vector Search

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

調整索引

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

影響效能的設定參數

您可以在建立索引時設定下列設定參數，這些參數在使用向量搜尋時可能會影響喚回度、延遲時間、可用性和費用。這項指引適用於大多數情況。不過，請務必實驗各種設定，確保設定符合您的用途。

如需參數定義，請參閱「索引設定參數」。

參數	關於	效能影響
shardSize	控制每部機器的資料量。 選擇分片大小時，請估算資料集未來的大小。如果資料集大小有上限，請選擇適當的分片大小來容納資料集。如果沒有上限，或是您的用途對延遲變異性極為敏感，建議選擇較大的分片大小。	如果設定較多較小的資料分割，搜尋時會處理較多的候選結果。更多分片可能會對效能造成以下影響： 喚回度：提升 延遲時間：可能增加，變異性更高 可用性：資料分片中斷會影響較小比例的資料 費用：如果使用相同機器類型，但分片數量較多，費用可能會增加 如果設定較少較大的資料分割，搜尋時處理的候選結果就會較少。分片數量較少可能會對效能造成以下影響： 喚回度：降低 延遲時間：縮短，減少變異性 可用性：分片中斷會影響較大比例的資料 費用：如果使用相同機器類型，但分片較少，費用可能會降低
distanceMeasureType	決定用於計算資料點與查詢向量之間距離的演算法。	下列 distanceMeasureType 設定有助於縮短查詢延遲時間： DOT_PRODUCT_DISTANCE 最適合縮短延遲時間 建議將 DOT_PRODUCT_DISTANCE 與 FeatureNormType 設為 UNIT_L2_NORM，以計算餘弦相似度
leafNodeEmbeddingCount	每個分葉節點的嵌入數量。預設值為 1000。 一般來說，變更 leafNodeEmbeddingCount 的值，影響會比變更其他參數的值小。	增加每個分葉節點的嵌入項目數量可縮短延遲時間，但會降低回想品質。這可能會對效能造成下列影響： 召回率：因目標搜尋量減少而降低 延遲時間：降低 (只要大多數用途的值不超過 15, 000) 可用性：沒有影響 費用：可降低，因為相同 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: {}
          }
       },
    },
}'

刪除索引

注意： 您必須先解除部署所有 index.deployed_indexes，才能刪除 index。

gcloud

使用下列任何指令資料之前，請先替換以下項目：

• INDEX_ID：索引的 ID。
• LOCATION：您使用 Vertex AI 的區域。
• PROJECT_ID：您的 Google Cloud 專案 ID。

執行下列指令：

Linux、macOS 或 Cloud Shell

注意： 請確認您已透過執行下列任一指令，初始化 Google Cloud CLI 的驗證和專案： gcloud init； 或 gcloud auth login 和 gcloud config set project。

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

Windows (PowerShell)

注意： 請確認您已透過執行下列任一指令，初始化 Google Cloud CLI 的驗證和專案： gcloud init； 或 gcloud auth login 和 gcloud config set project。

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

Windows (cmd.exe)

注意： 請確認您已透過執行下列任一指令，初始化 Google Cloud CLI 的驗證和專案： gcloud init； 或 gcloud auth login 和 gcloud config set project。

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

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

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

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)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

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

Python

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

在試用這個範例之前，請先按照Java使用用戶端程式庫的 Vertex AI 快速入門中的操作說明進行設定。 詳情請參閱 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 專區中，前往「Deploy and Use」(部署及使用) 專區。選取「Vector Search」

   前往 Vector Search

2. 系統會顯示有效索引清單。
3. 如要刪除索引，請前往索引所在列的選項選單，然後選取「刪除」。

後續步驟

• 瞭解索引設定參數
• 瞭解如何部署及管理公開索引端點
• 瞭解如何在虛擬私有雲網路中部署及管理索引端點
• 瞭解如何更新及重建索引
• 瞭解如何監控索引