Gestionar índices

En las siguientes secciones se describe cómo configurar, crear, enumerar y eliminar tus índices.

Resumen del índice

Un índice es un archivo o archivos que contienen tus vectores de inserción. Estos vectores se crean a partir de grandes cantidades de datos que quieres implementar y consultar con Vector Search. Con la búsqueda de vectores, puedes crear dos tipos de índices, en función de cómo quieras actualizarlos con tus datos. Puede crear un índice diseñado para actualizaciones por lotes o un índice diseñado para transmitir sus actualizaciones.

Un índice de lote se usa cuando quieres actualizar tu índice en un lote con datos que se han almacenado durante un periodo determinado, como los sistemas que se procesan semanal o mensualmente. Un índice de streaming es aquel en el que quieres que los datos del índice se actualicen a medida que se añaden datos nuevos a tu almacén de datos. Por ejemplo, si tienes una librería y quieres mostrar el nuevo inventario online lo antes posible. Es importante que elijas el tipo adecuado, ya que la configuración y los requisitos son diferentes.

Configurar parámetros de índice

Antes de crear un índice, configure los parámetros del índice.

Por ejemplo, crea un archivo llamado 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
      }
    }
  }
}

Puedes consultar la definición de cada uno de estos campos en Parámetros de configuración de índice.

Crear un índice

Tamaño del índice

Los datos de índice se dividen en partes iguales llamadas particiones para su procesamiento. Cuando creas un índice, debes especificar el tamaño de los fragmentos que se van a usar. Los tamaños admitidos son los siguientes:

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

Los tipos de máquina que puedes usar para implementar tu índice (con endpoints públicos o con endpoints de VPC) dependen del tamaño de los fragmentos del índice. En la siguiente tabla se muestran los tamaños de partición que admite cada tipo de máquina:

Tipo de máquina SHARD_SIZE_SMALL SHARD_SIZE_MEDIUM SHARD_SIZE_LARGE
n1-standard-16
n1-standard-32
e2-standard-2 (predeterminado)
e2-standard-16 (predeterminado)
e2-highmem-16 (predeterminado)
n2d-standard-32

Para saber cómo afectan el tamaño de los fragmentos y el tipo de máquina a los precios, consulta la página de precios de Vertex AI. Para saber cómo influye el tamaño de los fragmentos en el rendimiento, consulta Parámetros de configuración que influyen en el rendimiento.

Crear un índice para la actualización por lotes

Sigue estas instrucciones para crear e implementar tu índice. Si aún no tienes las inserciones, puedes ir a la sección Crear un índice de lote vacío. Con esta opción, no se necesitan datos de inserciones en el momento de crear el índice.

Para crear un índice, sigue estos pasos:

gcloud

Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

  • LOCAL_PATH_TO_METADATA_FILE: ruta local al archivo de metadatos.
  • INDEX_NAME: nombre visible del índice.
  • LOCATION: la región en la que usas Vertex AI.
  • PROJECT_ID: tu Google Cloud ID de proyecto.

Ejecuta el siguiente comando:

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

Deberías recibir una respuesta similar a la siguiente:

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

Consulta gcloud ai operations para obtener más información sobre el comando describe.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • INPUT_DIR: la ruta del directorio de Cloud Storage del contenido del índice.
  • INDEX_NAME: nombre visible del índice.
  • LOCATION: la región en la que usas Vertex AI.
  • PROJECT_ID: tu Google Cloud ID de proyecto.
  • PROJECT_NUMBER: el número de proyecto que se genera automáticamente.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud: 

{
  "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 tu solicitud, despliega una de estas opciones:

Deberías recibir una respuesta JSON similar a la siguiente:

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

En el siguiente ejemplo se usa el recurso de Terraform google_vertex_ai_index para crear un índice de actualizaciones por lotes.

Para saber cómo aplicar o quitar una configuración de Terraform, consulta Comandos básicos de 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 cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python. 

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 probar este ejemplo, sigue las Java instrucciones de configuración de la guía de inicio rápido de Vertex AI con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de Vertex AI.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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

Sigue estas instrucciones para crear un índice para las actualizaciones por lotes.

  1. En la sección Vertex AI de la Google Cloud consola, ve a la sección Desplegar y usar. Selecciona Vector Search.

    Ir a Vector Search

  2. Haz clic en Crear índice para abrir el panel Índice. Aparecerá el panel Crear un índice.
  3. En el campo Nombre visible, indica un nombre único para identificar tu índice.
  4. En el campo Descripción, indica para qué sirve el índice.
  5. En el campo Región, selecciona una región en el menú desplegable.
  6. En el campo Cloud Storage, busca y selecciona la carpeta de Cloud Storage en la que se almacenan tus datos vectoriales.
  7. En el menú desplegable Tipo de algoritmo, seleccione el tipo de algoritmo que Búsqueda vectorial usa para realizar búsquedas eficientes. Si selecciona el algoritmo treeAh, introduzca el número aproximado de vecinos.
  8. En el campo Dimensiones, introduzca el número de dimensiones de sus vectores de entrada.
  9. En el campo Método de actualización, seleccione Lote.
  10. En el campo Tamaño de fragmento, seleccione el tamaño de fragmento que quiera en el menú desplegable.
  11. Haz clic en Crear. El nuevo índice aparecerá en la lista de índices cuando esté listo. Nota: El tiempo de compilación puede tardar hasta una hora en completarse.

Crear un índice de lote vacío

Para crear y desplegar tu índice de inmediato, puedes crear un índice de lote vacío. Con esta opción, no se necesitan datos de inserciones en el momento de crear el índice.

Para crear un índice vacío, la solicitud es casi idéntica a la de crear un índice para actualizaciones por lotes. La diferencia es que eliminas el campo contentsDeltaUri, ya que no vas a vincular ninguna ubicación de datos. Aquí tienes un ejemplo de índice de lote vacío:

Ejemplo de solicitud de índice vacía

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

Crear un índice para las actualizaciones en streaming

Sigue estas instrucciones para crear e implementar tu índice de streaming. Si aún no tienes las inserciones, ve a Crear un índice vacío para las actualizaciones de streaming. Con esta opción, no se necesitan datos de inserciones en el momento de crear el índice.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • INDEX_NAME: nombre visible del índice.
  • DESCRIPTION: una descripción del índice.
  • INPUT_DIR: la ruta del directorio de Cloud Storage del contenido del índice.
  • DIMENSIONS: número de dimensiones del vector de inserción.
  • PROJECT_ID: tu Google Cloud ID de proyecto.
  • PROJECT_NUMBER: el número de proyecto que se genera automáticamente.
  • LOCATION: la región en la que usas Vertex AI.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud: 

{
  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 tu solicitud, despliega una de estas opciones:

Deberías recibir una respuesta JSON similar a la siguiente:

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

En el siguiente ejemplo se usa el recurso de Terraform google_vertex_ai_index para crear un índice de actualizaciones en streaming.

Para saber cómo aplicar o quitar una configuración de Terraform, consulta Comandos básicos de 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 cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python. 

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

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

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

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

    return index

Java

Antes de probar este ejemplo, sigue las Java instrucciones de configuración de la guía de inicio rápido de Vertex AI con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de Vertex AI.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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

Sigue estas instrucciones para crear un índice de actualizaciones en streaming en la Google Cloud consola.

Para crear un índice disponible para las actualizaciones en streaming, debes seguir los mismos pasos que para configurar un índice de actualización por lotes, pero debes definir indexUpdateMethod como STREAM_UPDATE.

  1. En la sección Vertex AI de la Google Cloud consola, ve a la sección Desplegar y usar. Selecciona Búsqueda vectorial.

    Ve a Vector Search

  2. Haz clic en Crear índice para abrir el panel Índice. Aparecerá el panel Crear un índice.
  3. En el campo Nombre visible, indica un nombre único para identificar tu índice.
  4. En el campo Descripción, indica para qué sirve el índice.
  5. En el campo Región, selecciona una región en el menú desplegable.
  6. En el campo Cloud Storage, busca y selecciona la carpeta de Cloud Storage en la que se almacenan tus datos vectoriales.
  7. En el menú desplegable Tipo de algoritmo, selecciona el tipo de algoritmo que Vector Search usará para realizar la búsqueda. Si selecciona el algoritmo treeAh, introduzca el número aproximado de vecinos.
  8. En el campo Dimensiones, introduzca el número de dimensiones de los vectores de entrada.
  9. En el campo Método de actualización, selecciona Stream.
  10. En el campo Tamaño de fragmento, seleccione el tamaño que quiera en el menú desplegable.
  11. Haz clic en Crear. El nuevo índice aparecerá en la lista de índices cuando esté listo. Nota: El tiempo de compilación puede tardar hasta una hora en completarse.

Crear un índice vacío para las actualizaciones en streaming

Para crear y desplegar tu índice de inmediato, puedes crear un índice vacío para la transmisión. Con esta opción, no se necesitan datos de inserciones en el momento de crear el índice.

Para crear un índice vacío, la solicitud es casi idéntica a la de crear un índice para la transmisión. La diferencia es que eliminas el campo contentsDeltaUri, ya que no vas a vincular ninguna ubicación de datos. Aquí tienes un ejemplo de índice de streaming vacío:

Ejemplo de solicitud de índice vacía

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

Mostrar índices

gcloud

Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

  • INDEX_NAME: nombre visible del índice.
  • LOCATION: la región en la que usas Vertex AI.
  • PROJECT_ID: tu Google Cloud ID de proyecto.

Ejecuta el siguiente comando:

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

Deberías recibir una respuesta similar a la siguiente:

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

Consulta gcloud ai operations para obtener más información sobre el comando describe.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • INDEX_NAME: nombre visible del índice.
  • LOCATION: la región en la que usas Vertex AI.
  • PROJECT_ID: tu Google Cloud ID de proyecto.
  • PROJECT_NUMBER: el número de proyecto que se genera automáticamente.

Método HTTP y URL: 

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

Para enviar tu solicitud, despliega una de estas opciones:

Deberías recibir una respuesta JSON similar a la siguiente:

{
 "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 cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python. 

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

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

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

    # List Indexes
    return aiplatform.MatchingEngineIndex.list()

Java

Antes de probar este ejemplo, sigue las Java instrucciones de configuración de la guía de inicio rápido de Vertex AI con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de Vertex AI.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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

Sigue estas instrucciones para ver una lista de tus índices.

  1. En la sección Vertex AI de la Google Cloud consola, ve a la sección Desplegar y usar. Selecciona Vector Search.

    Ir a Vector Search

  2. Se muestra una lista de tus índices activos.

Ajustar el índice

Para optimizar el índice, es necesario definir los parámetros de configuración que influyen en el rendimiento de los índices implementados, especialmente en la sensibilidad y la latencia. Estos parámetros se definen cuando crea el índice por primera vez. Puedes usar índices de fuerza bruta para medir la recuperación.

Parámetros de configuración que influyen en el rendimiento

Los siguientes parámetros de configuración se pueden definir al crear el índice y pueden influir en la sensibilidad, la latencia, la disponibilidad y el coste al usar la búsqueda vectorial. Estas directrices se aplican a la mayoría de los casos. Sin embargo, siempre debes experimentar con tus configuraciones para asegurarte de que funcionan en tu caso práctico.

Para ver las definiciones de los parámetros, consulta Parámetros de configuración de índices.

Parámetro Información Impacto en el rendimiento
shardSize

Controla la cantidad de datos de cada máquina.

Cuando elijas el tamaño de los fragmentos, calcula el tamaño que tendrá tu conjunto de datos en el futuro. Si el tamaño de tu conjunto de datos tiene un límite superior, elige el tamaño de fragmento adecuado para adaptarlo. Si no hay un límite superior o si tu caso práctico es extremadamente sensible a la variabilidad de la latencia, te recomendamos que elijas un tamaño de fragmento grande.

Si configura un número mayor de fragmentos más pequeños, se procesará un número mayor de resultados candidatos durante la búsqueda. Tener más particiones puede afectar al rendimiento de las siguientes formas:

  • Recuperación: aumentada
  • Latencia: puede aumentar y ser más variable
  • Disponibilidad: las interrupciones de fragmentos afectan a un porcentaje menor de datos
  • Coste: puede aumentar si se usa el mismo tipo de máquina con más particiones.

Si configura un número menor de particiones más grandes, se procesarán menos resultados candidatos durante la búsqueda. Si hay menos particiones, el rendimiento puede verse afectado de las siguientes formas:

  • Recuperación: disminuida
  • Latencia: reducida y con menos variabilidad
  • Disponibilidad: las interrupciones de fragmentos afectan a un mayor porcentaje de datos
  • Coste: puede disminuir si se usa el mismo tipo de máquina con menos particiones.
distanceMeasureType

Determina el algoritmo que se usa para calcular la distancia entre los puntos de datos y el vector de consulta.

Los siguientes ajustes de distanceMeasureType pueden ayudar a reducir la latencia de las consultas:

  • DOT_PRODUCT_DISTANCE está optimizado para reducir la latencia
  • DOT_PRODUCT_DISTANCE combinado con el ajuste FeatureNormType en UNIT_L2_NORM es la opción recomendada para la similitud del coseno.
leafNodeEmbeddingCount

El número de inserciones de cada nodo hoja. De forma predeterminada, este número es 1000.

Por lo general, cambiar el valor de leafNodeEmbeddingCount tiene menos efecto que cambiar el valor de otros parámetros.

Aumentar el número de inserciones de cada nodo hoja puede reducir la latencia, pero también la calidad de la recuperación. Puede afectar al rendimiento de las siguientes formas:

  • Recuerdo: ha disminuido debido a que la búsqueda está menos orientada
  • Latencia: reducida, siempre que el valor no sea superior a 15.000 en la mayoría de los casos prácticos.
  • Disponibilidad: sin impacto
  • Coste: puede disminuir porque se necesitan menos réplicas para la misma QPS.

Reducir el número de inserciones de cada nodo hoja puede afectar al rendimiento de las siguientes formas:

  • Cobertura: puede aumentar porque se recogen más hojas segmentadas.
  • Latencia: aumentada
  • Disponibilidad: sin impacto
  • Coste: puede aumentar porque se necesitan más réplicas para el mismo QPS.

Usar un índice de fuerza bruta para medir el recuerdo

Para obtener los vecinos más cercanos exactos, usa índices con el algoritmo de fuerza bruta. El algoritmo de fuerza bruta proporciona una cobertura del 100% a costa de una latencia mayor. Usar un índice de fuerza bruta para medir la recuperación no suele ser una buena opción para el servicio de producción, pero puede resultarte útil para evaluar la recuperación de varias opciones de indexación sin conexión.

Para crear un índice con el algoritmo de fuerza bruta, especifica brute_force_config en los metadatos del í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: {}
          }
       },
    },
}'

Eliminar un índice

gcloud

Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

  • INDEX_ID: ID del índice.
  • LOCATION: la región en la que usas Vertex AI.
  • PROJECT_ID: tu Google Cloud ID de proyecto.

Ejecuta el siguiente comando:

Linux, macOS o 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 los datos de la solicitud, haz las siguientes sustituciones:

  • INDEX_ID: ID del índice.
  • LOCATION: la región en la que usas Vertex AI.
  • PROJECT_ID: tu Google Cloud ID de proyecto.
  • PROJECT_NUMBER: el número de proyecto que se genera automáticamente.

Método HTTP y URL: 

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

Para enviar tu solicitud, despliega una de estas opciones:

Deberías recibir una respuesta JSON similar a la siguiente:

{
  "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 cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python. 

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

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

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

    # Delete the index
    index.delete()

Java

Antes de probar este ejemplo, sigue las Java instrucciones de configuración de la guía de inicio rápido de Vertex AI con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de Vertex AI.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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

Sigue estas instrucciones para eliminar uno o varios índices.

  1. En la sección Vertex AI de la Google Cloud consola, ve a la sección Desplegar y usar. Selecciona Vector Search.

    Ir a Vector Search

  2. Se muestra una lista de tus índices activos.
  3. Para eliminar un índice, ve al menú de  opciones que está en la misma fila que el índice y selecciona Eliminar.

Siguientes pasos