Faça a gestão dos índices

As secções seguintes descrevem como configurar, criar, listar e eliminar os seus índices.

Vista geral do índice

Um índice é um ficheiro ou ficheiros que consistem nos seus vetores de incorporação. Estes vetores são criados a partir de grandes quantidades de dados que quer implementar e consultar com a pesquisa vetorial. Com a pesquisa vetorial, pode criar dois tipos de índices, consoante a forma como planeia atualizá-los com os seus dados. Pode criar um índice concebido para atualizações em lote ou um índice concebido para transmitir as suas atualizações.

Um índice de lote destina-se a quando quer atualizar o seu índice num lote, com dados que foram armazenados durante um determinado período, como sistemas que são processados semanal ou mensalmente. Um índice de streaming ocorre quando quer que os dados do índice sejam atualizados à medida que são adicionados novos dados ao seu repositório de dados. Por exemplo, se tiver uma livraria e quiser apresentar o novo inventário online o mais rapidamente possível. O tipo que escolher é importante, uma vez que a configuração e os requisitos são diferentes.

Configure os parâmetros do índice

Antes de criar um índice, configure os parâmetros do índice.

Por exemplo, crie um ficheiro com o nome 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
      }
    }
  }
}

Pode encontrar a definição de cada um destes campos em Parâmetros de configuração do índice.

Crie um índice

Tamanho do índice

Os dados do índice são divididos em partes iguais denominadas fragmentos para processamento. Quando cria um índice, tem de especificar o tamanho dos fragmentos a usar. Os tamanhos suportados são os seguintes:

  • SHARD_SIZE_SMALL: 2 GiB por fragmento.
  • SHARD_SIZE_MEDIUM: 20 GiB por fragmento.
  • SHARD_SIZE_LARGE: 50 GiB por fragmento.

Os tipos de máquinas que pode usar para implementar o seu índice (usando pontos finais públicos ou usando pontos finais de VPC) dependem do tamanho do fragmento do índice. A tabela seguinte mostra os tamanhos dos fragmentos que cada tipo de máquina suporta:

Tipo de máquina SHARD_SIZE_SMALL SHARD_SIZE_MEDIUM SHARD_SIZE_LARGE
n1-standard-16
n1-standard-32
e2-standard-2 (predefinição)
e2-standard-16 (predefinição)
e2-highmem-16 (predefinição)
n2d-standard-32

Para saber como o tamanho do fragmento e o tipo de máquina afetam os preços, consulte a página de preços do Vertex AI. Para saber como o tamanho dos fragmentos afeta o desempenho, consulte o artigo Parâmetros de configuração que afetam o desempenho.

Crie um índice para a atualização em lote

Use estas instruções para criar e implementar o seu índice. Se ainda não tiver as incorporações prontas, pode avançar para Criar um índice de lotes vazio. Com esta opção, não são necessários dados de incorporações no momento da criação do índice.

Para criar um índice:

gcloud

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

  • LOCAL_PATH_TO_METADATA_FILE: o caminho local para o ficheiro de metadados.
  • INDEX_NAME: nome a apresentar do índice.
  • LOCATION: a região onde está a usar o Vertex AI.
  • PROJECT_ID: o seu Google Cloud ID do projeto.

Execute o seguinte comando:

Linux, macOS ou 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

Deve receber uma resposta semelhante à seguinte:

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

Consulte gcloud ai operations para saber mais sobre o comando describe.

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • INPUT_DIR: O caminho do diretório do Cloud Storage do conteúdo do índice.
  • INDEX_NAME: nome a apresentar do índice.
  • LOCATION: a região onde está a usar o Vertex AI.
  • PROJECT_ID: o seu Google Cloud ID do projeto.
  • PROJECT_NUMBER: o número do projeto gerado automaticamente para o seu projeto.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

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

O exemplo seguinte usa o recurso do Terraform google_vertex_ai_index para criar um índice para atualizações em lote.

Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do 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

Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da 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

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local. 


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

Consola

Use estas instruções para criar um índice para atualizações em lote.

  1. Na secção do Vertex AI da Google Cloud consola, aceda à secção Implementar e usar. Selecione Vector Search

    Aceda a Vector Search

  2. Clique em Criar novo índice para abrir o painel Índice. É apresentado o painel Criar um novo índice.
  3. No campo Nome a apresentar, indique um nome para identificar exclusivamente o seu índice.
  4. No campo Descrição, indique para que serve o índice.
  5. No campo Região, selecione uma região no menu pendente.
  6. No campo Cloud Storage, pesquise e selecione a pasta do Cloud Storage onde os seus dados vetoriais estão armazenados.
  7. No menu pendente Tipo de algoritmo, selecione o tipo de algoritmo que a pesquisa vetorial usa para uma pesquisa eficiente. Se selecionar o algoritmo treeAh, introduza a contagem aproximada de vizinhos.
  8. No campo Dimensões, introduza o número de dimensões dos seus vetores de entrada.
  9. No campo Método de atualização, selecione Em lote.
  10. No campo Tamanho do fragmento, selecione no menu pendente o tamanho do fragmento que quer.
  11. Clique em Criar. O novo índice aparece na sua lista de índices assim que estiver pronto. Nota: o tempo de compilação pode demorar até uma hora a ser concluído.

Crie um índice de lote vazio

Para criar e implementar o seu índice imediatamente, pode criar um índice de lote vazio. Com esta opção, não são necessários dados de incorporações no momento da criação do índice.

Para criar um índice vazio, o pedido é quase idêntico ao de criação de um índice para atualizações em lote. A diferença é que remove o campo contentsDeltaUri, uma vez que não está a associar uma localização de dados. Segue-se um exemplo de um índice de lote vazio:

Exemplo de pedido de índice vazio

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

Crie um índice para atualizações de streaming

Use estas instruções para criar e implementar o seu índice de streaming. Se ainda não tiver os encaixes prontos, avance para Crie um índice vazio para atualizações de streaming. Com esta opção, não são necessários dados de incorporações no momento da criação do índice.

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • INDEX_NAME: nome a apresentar do índice.
  • DESCRIPTION: uma descrição do índice.
  • INPUT_DIR: O caminho do diretório do Cloud Storage do conteúdo do índice.
  • DIMENSIONS: número de dimensões do vetor de incorporação.
  • PROJECT_ID: o seu Google Cloud ID do projeto.
  • PROJECT_NUMBER: o número do projeto gerado automaticamente para o seu projeto.
  • LOCATION: a região onde está a usar o Vertex AI.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

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

O exemplo seguinte usa o recurso do Terraform google_vertex_ai_index para criar um índice para atualizações de streaming.

Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do 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

Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da 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

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local. 


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

Consola

Use estas instruções para criar um índice para atualizações de streaming na Google Cloud consola.

Para criar um índice disponível para atualizações de streaming, são necessários passos semelhantes aos da configuração de um índice de atualização em lote, exceto que tem de definir indexUpdateMethod como STREAM_UPDATE.

  1. Na secção Vertex AI da Google Cloud consola, aceda à secção Implementar e usar. Selecione Vector Search

    Aceda a Vector Search

  2. Clique em Criar novo índice para abrir o painel Índice. É apresentado o painel Criar um novo índice.
  3. No campo Nome a apresentar, indique um nome para identificar exclusivamente o seu índice.
  4. No campo Descrição, indique a finalidade do índice.
  5. No campo Região, selecione uma região no menu pendente.
  6. No campo Cloud Storage, pesquise e selecione a pasta do Cloud Storage onde os seus dados vetoriais estão armazenados.
  7. No menu pendente Tipo de algoritmo, selecione o tipo de algoritmo que a pesquisa vetorial vai usar para realizar a sua pesquisa. Se selecionar o algoritmo treeAh, introduza a contagem aproximada de vizinhos.
  8. No campo Dimensões, introduza o número de dimensões dos seus vetores de entrada.
  9. No campo Método de atualização, selecione Stream.
  10. No campo Tamanho do fragmento, selecione no menu pendente o tamanho do fragmento pretendido.
  11. Clique em Criar. O novo índice aparece na sua lista de índices assim que estiver pronto. Nota: o tempo de compilação pode demorar até uma hora a ser concluído.

Crie um índice vazio para atualizações de streaming

Para criar e implementar o seu índice imediatamente, pode criar um índice vazio para streaming. Com esta opção, não são necessários dados de incorporações no momento da criação do índice.

Para criar um índice vazio, o pedido é quase idêntico ao de criar um índice para streaming. A diferença é que remove o campo contentsDeltaUri, uma vez que não está a associar uma localização de dados. Segue-se um exemplo de um índice de streaming vazio:

Exemplo de pedido de índice vazio

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

Listar índices

gcloud

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

  • INDEX_NAME: nome a apresentar do índice.
  • LOCATION: a região onde está a usar o Vertex AI.
  • PROJECT_ID: o seu Google Cloud ID do projeto.

Execute o seguinte comando:

Linux, macOS ou 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

Deve receber uma resposta semelhante à seguinte:

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

Consulte gcloud ai operations para saber mais sobre o comando describe.

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • INDEX_NAME: nome a apresentar do índice.
  • LOCATION: a região onde está a usar o Vertex AI.
  • PROJECT_ID: o seu Google Cloud ID do projeto.
  • PROJECT_NUMBER: o número do projeto gerado automaticamente para o seu projeto.

Método HTTP e URL: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

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

Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da 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

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local. 


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

Consola

Siga estas instruções para ver uma lista dos seus índices.

  1. Na secção do Vertex AI da Google Cloud consola, aceda à secção Implementar e usar. Selecione Vector Search

    Aceda a Vector Search

  2. É apresentada uma lista dos seus índices ativos.

Ajustar o índice

A otimização do índice requer a definição dos parâmetros de configuração que afetam o desempenho dos índices implementados, especialmente a capacidade de memorização e a latência. Estes parâmetros são definidos quando cria o índice pela primeira vez. Pode usar índices de força bruta para medir a capacidade de memorização.

Parâmetros de configuração que afetam o desempenho

Os seguintes parâmetros de configuração podem ser definidos no momento da criação do índice e podem afetar a capacidade de memorização, a latência, a disponibilidade e o custo quando usar a pesquisa vetorial. Estas orientações aplicam-se à maioria dos casos. No entanto, experimente sempre as suas configurações para se certificar de que funcionam para o seu exemplo de utilização.

Para ver as definições dos parâmetros, consulte o artigo Parâmetros de configuração do índice.

Parâmetro Acerca de Impacto no desempenho
shardSize

Controla a quantidade de dados em cada máquina.

Quando escolher um tamanho de fragmento, estime o tamanho do conjunto de dados no futuro. Se o tamanho do conjunto de dados tiver um limite superior, escolha o tamanho do fragmento adequado para o acomodar. Se não existir um limite superior ou se o seu exemplo de utilização for extremamente sensível à variabilidade da latência, recomendamos que escolha um tamanho de fragmento grande.

Se configurar um número maior de fragmentos mais pequenos, é processado um número maior de resultados candidatos durante a pesquisa. Mais fragmentos podem afetar o desempenho das seguintes formas:

  • Recordação: aumentada
  • Latência: potencialmente aumentada, mais variabilidade
  • Disponibilidade: as indisponibilidades de fragmentos afetam uma percentagem menor de dados
  • Custo: pode aumentar se o mesmo tipo de máquina for usado com mais fragmentos

Se configurar um número menor de fragmentos maiores, são processados menos resultados candidatos durante a pesquisa. Um número inferior de fragmentos pode afetar o desempenho das seguintes formas:

  • Recordação: diminuída
  • Latência: reduzida, menos variabilidade
  • Disponibilidade: as indisponibilidades de fragmentos afetam uma percentagem maior de dados
  • Custo: pode diminuir se o mesmo tipo de máquina for usado com menos fragmentos
distanceMeasureType

Determina o algoritmo usado para o cálculo da distância entre os pontos de dados e o vetor de consulta.

As seguintes definições distanceMeasureType podem ajudar a reduzir a latência das consultas:

  • DOT_PRODUCT_DISTANCE está mais otimizado para reduzir a latência
  • Recomendamos a combinação de DOT_PRODUCT_DISTANCE com a definição de FeatureNormType como UNIT_L2_NORM para a semelhança de cossenos
leafNodeEmbeddingCount

O número de incorporações para cada nó folha. Por predefinição, este número está definido como 1000.

Geralmente, a alteração do valor de leafNodeEmbeddingCount tem menos efeito do que a alteração do valor de outros parâmetros.

Aumentar o número de incorporações para cada nó folha pode reduzir a latência, mas reduz a qualidade da capacidade de memorização. Pode afetar o desempenho das seguintes formas:

  • Relembrar: diminuiu devido a uma pesquisa menos segmentada
  • Latência: reduzida, desde que o valor não seja >15 mil para a maioria dos exemplos de utilização
  • Disponibilidade: nenhum impacto
  • Custo: pode diminuir porque são necessárias menos réplicas para o mesmo QPS

Diminuir o número de incorporações para cada nó folha pode afetar o desempenho das seguintes formas:

  • Recuperação: pode aumentar porque são recolhidas mais folhas segmentadas
  • Latência: aumentada
  • Disponibilidade: nenhum impacto
  • Custo: pode aumentar porque são necessárias mais réplicas para o mesmo QPS

Usar um índice de força bruta para medir a capacidade de memorização

Para obter os vizinhos mais próximos exatos, use índices com o algoritmo de força bruta. O algoritmo de força bruta oferece uma taxa de recolha de 100% à custa de uma latência mais elevada. Normalmente, usar um índice de força bruta para medir a capacidade de memorização não é uma boa escolha para a publicação de produção, mas pode ser útil para avaliar a capacidade de memorização de várias opções de indexação offline.

Para criar um índice com o algoritmo de força bruta, especifique brute_force_config nos metadados do índice:

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: {}
          }
       },
    },
}'

Elimine um índice

gcloud

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

  • INDEX_ID: o ID do índice.
  • LOCATION: a região onde está a usar o Vertex AI.
  • PROJECT_ID: o seu Google Cloud ID do projeto.

Execute o seguinte comando:

Linux, macOS ou 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

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • INDEX_ID: o ID do índice.
  • LOCATION: a região onde está a usar o Vertex AI.
  • PROJECT_ID: o seu Google Cloud ID do projeto.
  • PROJECT_NUMBER: o número do projeto gerado automaticamente para o seu projeto.

Método HTTP e URL: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

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

Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da 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

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local. 


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

Consola

Siga estas instruções para eliminar um ou mais índices.

  1. Na secção do Vertex AI da Google Cloud consola, aceda à secção Implementar e usar. Selecione Vector Search

    Aceda a Vector Search

  2. É apresentada uma lista dos seus índices ativos.
  3. Para eliminar um índice, aceda ao menu de  opções que se encontra na mesma linha do índice e selecione Eliminar.

O que se segue?