En las siguientes secciones, se describe cómo configurar, crear, enumerar y borrar tus índices.
Descripción general del índice
Un índice es uno o más archivos que constan de los vectores de incorporación. Estos vectores se componen de grandes cantidades de datos que deseas implementar y consultar con la búsqueda de vectores. Con la búsqueda de vectores, puedes crear dos tipos de índices, según cómo planees actualizarlos con tus datos. Puedes crear un índice diseñado para actualizaciones por lotes o un índice diseñado para transmitir tus actualizaciones.
Un índice por lotes sirve cuando quieres actualizar tu índice en un lote, con datos que se almacenaron durante un período determinado, como los sistemas que se procesan semanal o mensualmente. Un índice de transmisión es cuando quieres que los índices de datos se actualicen a medida que se agregan datos nuevos a tu almacén de datos, por ejemplo, si tienes una librería y quieres publicar un nuevo inventario en línea lo antes posible. El tipo que elijas es importante, ya que la configuración y los requisitos son diferentes.
Configura parámetros de índice
Antes de crear un índice, configura los parámetros de tu í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 encontrar la definición de cada uno de estos campos en Parámetros de configuración de índices
Crea un índice
Tamaño del índice
Los datos de índice se dividen en partes iguales denominadas fragmentos con el objetivo de ser procesados. Cuando debes crear un índice, debes especificar el tamaño de los fragmentos que usarás. 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áquinas que puedes usar para implementar tu índice (con extremos públicos o con extremos de VPC) dependen del tamaño de fragmento del índice. En esta tabla, se muestran los tamaños de fragmentos 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 obtener información sobre cómo el tamaño de fragmento y el tipo de máquina afectan los precios, consulta la página de precios de Vertex AI.
Crea un índice para la actualización por lotes
Usa estas instrucciones para crear y, luego, implementar tu índice. Si no tienes tus incorporaciones listas aún, puedes pasar a la sección Crea un índice de lotes vacío. Con esta opción, no se requieren datos de incorporaciones en el momento de la creación del índice.
Para crear un índice, sigue estos pasos:
gcloud
Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:
- LOCAL_PATH_TO_METADATA_FILE: La ruta de acceso local al archivo de metadatos.
- INDEX_NAME: El nombre visible del índice
- LOCATION: la región en la que usas Vertex AI.
- PROJECT_ID: El ID del proyecto de Google Cloud.
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 que figura a continuación:
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 cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- INPUT_DIR: Es la ruta de acceso del directorio de Cloud Storage del contenido del índice.
- INDEX_NAME: El nombre visible del índice
- LOCATION: la región en la que usas Vertex AI.
- PROJECT_ID: El ID del proyecto de Google Cloud.
- PROJECT_NUMBER: el número de proyecto de tu proyecto generado de forma automática.
HTTP method and 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, expande una de estas opciones:
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
{ "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 google_vertex_ai_index
de Terraform a fin de crear un índice para las actualizaciones por lotes.
Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los comandos básicos de Terraform.
Python
Si deseas obtener información para instalar o actualizar el SDK de Vertex AI para Python, consulta Instala el SDK de Vertex AI para Python. Si deseas obtener más información, consulta la documentación de referencia de la API de Python.
Console
Usa estas instrucciones para crear un índice para las actualizaciones por lotes.
- En la sección de Vertex AI de la consola de Google Cloud, ve a la sección Implementación y uso. Elige Vector Search
- Haz clic en . Crea un índice nuevo para abrir el panel Índice. Aparecerá el panel Crea un índice nuevo.
- En el campo Nombre visible, proporciona un nombre para identificar tu índice de forma única.
- En el campo Descripción, proporciona una descripción de para qué es el índice.
- En el campo Región, elige una región del menú desplegable.
- En el campo Cloud Storage, busca y elige la carpeta de Cloud Storage en la que se almacenan tus datos vectoriales.
- En el menú desplegable Tipo de algoritmo, selecciona el tipo de algoritmo que usa la búsqueda de vectores para una búsqueda eficiente. Si eliges el algoritmo de treeAh, ingresa el recuento aproximado de vecinos.
- En el campo Dimensiones, ingresa la cantidad de dimensiones de tus vectores de entrada.
- En el campo Método de actualización, elige Por lotes.
- En el campo Tamaño del fragmento, elige del menú desplegable el tamaño del fragmento que deseas.
- Haz clic en Crear. Tu índice nuevo aparece en tu lista de índices una vez que esté listo. Nota: El tiempo de compilación puede tomar hasta una hora en completarse.
Crea un índice de lotes vacío
Para crear e implementar tu índice de inmediato, puedes crear un índice de lotes vacío. Con esta opción, no se requieren datos de incorporaciones en el momento de la creación del índice.
Para crear un índice vacío, la solicitud es casi idéntica a la creación de un índice para actualizaciones por lotes. La diferencia es que quitas el campo contentsDeltaUri
,
dado que no estás vinculando una ubicación de datos. Este es un ejemplo de índice de lotes 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, "leafNodesToSearchPercent": 7 } } } } }
Crea un índice para las actualizaciones de transmisión
Usa estas instrucciones para crear y, luego, implementar tu índice de transmisión. Si no tienes listas tus incorporaciones aún, ve a Crea un índice vacío para las actualizaciones de la transmisión. Con esta opción, no se requieren datos de incorporaciones en el momento de la creación del índice.
REST
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- INDEX_NAME: El nombre visible del índice
- DESCRIPTION: una descripción del índice.
- INPUT_DIR: Es la ruta de acceso del directorio de Cloud Storage del contenido del índice.
- DIMENSIONS: cantidad de dimensiones del vector de incorporación.
- PROJECT_ID: El ID del proyecto de Google Cloud.
- PROJECT_NUMBER: el número de proyecto de tu proyecto generado de forma automática.
- LOCATION: la región en la que usas Vertex AI.
HTTP method and 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, expande una de estas opciones:
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
{ "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" ] } } }
Console
Usa estas instrucciones para crear un índice para las actualizaciones de transmisión en la consola de Google Cloud.
Para crear un índice disponible para las actualizaciones de transmisión, se requieren pasos similares para configurar un índice de actualización por lotes, excepto que necesitas configurar indexUpdateMethod
como STREAM_UPDATE
.
- En la sección de Vertex AI de la consola de Google Cloud, ve a la sección Implementación y uso. Elige Búsqueda de vectores
- Haz clic en . Crea un índice nuevo para abrir el panel Índice. Aparecerá el panel Crea un índice nuevo.
- En el campo Nombre visible, proporciona un nombre para identificar tu índice de forma única.
- En el campo Descripción, proporciona una descripción de para qué sirve el índice.
- En el campo Región, elige una región del menú desplegable.
- En el campo de Cloud Storage, busca y elige la carpeta de Cloud Storage en la que se almacenan tus datos vectoriales.
- En el menú desplegable Tipo de algoritmo, elige el tipo de algoritmo que usará la Búsqueda de vectores para hacer la búsqueda. Si eliges el algoritmo de treeAh, ingresa el recuento aproximado de vecinos.
- En el campo Dimensiones, ingresa la cantidad de dimensiones de tus vectores de entrada.
- En el campo Método de actualización, elige Transmitir.
- En el campo Tamaño del fragmento, elige del menú desplegable el tamaño del fragmento que deseas.
- Haz clic en Crear. Tu índice nuevo aparecerá en tu lista de índices una vez que esté listo. Nota: El tiempo de compilación puede tomar hasta una hora en completarse.
Python
Si deseas obtener información para instalar o actualizar el SDK de Vertex AI para Python, consulta Instala el SDK de Vertex AI para Python. Si deseas obtener más información, consulta la documentación de referencia de la API de Python.
Crea un índice vacío para las actualizaciones de transmisión
Para crear e implementar tu índice de inmediato, puedes crear un índice vacío para la transmisión. Con esta opción, no se requieren datos de incorporaciones en el momento de la creación del índice.
Para crear un índice vacío, la solicitud es casi idéntica a la creación de un índice
para la transmisión. La diferencia es que quitas el campo contentsDeltaUri
,
dado que no estás vinculando una ubicación de datos. Este es un ejemplo de índice de transmisión 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 lista de índices
gcloud
Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:
- INDEX_NAME: El nombre visible del índice
- LOCATION: la región en la que usas Vertex AI.
- PROJECT_ID: El ID del proyecto de Google Cloud.
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 que figura a continuación:
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 cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- INDEX_NAME: El nombre visible del índice
- LOCATION: la región en la que usas Vertex AI.
- PROJECT_ID: El ID del proyecto de Google Cloud.
- PROJECT_NUMBER: el número de proyecto de tu proyecto generado de forma automática.
HTTP method and URL:
GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes
Para enviar tu solicitud, expande una de estas opciones:
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
{ "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" } ] }
Console
Usa estas instrucciones para ver una lista de tus índices.
- En la sección de Vertex AI de la consola de Google Cloud, ve a la sección Implementación y uso. Elige Vector Search
- Aparecerá una lista de los índices activos.
Ajusta el índice
El ajuste del índice requiere establecer los parámetros de configuración que afectan el rendimiento de los índices implementados, en especial la recuperación y la latencia. Estos parámetros se establecen cuando creas el índice por primera vez. Puedes usar los índices de fuerza bruta para medir la recuperación.
Parámetros de configuración que afectan el rendimiento
Los siguientes parámetros de configuración se pueden establecer en el momento de la creación del índice y pueden afectar la recuperación, la latencia, la disponibilidad y el costo cuando se usa la búsqueda de vectores. Esta guía se aplica en la mayoría de los casos. Sin embargo, siempre experimenta con tus opciones de configuración para asegurarte de que funcionen para tu caso de uso.
Para ver las definiciones de parámetros, consulta Parámetros de configuración de índices.
Parámetro | Acerca de | Impacto en el rendimiento |
---|---|---|
shardSize
|
Controla la cantidad de datos en cada máquina. Cuando elijas un tamaño de fragmento, calcula cuál será el tamaño de 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 apropiado para acomodarlo. Si no hay un límite superior o si tu caso de uso es extremadamente sensible a la variabilidad de la latencia, se recomienda elegir un tamaño de fragmento grande. |
Si configuras una cantidad mayor de fragmentos más pequeños, una mayor cantidad de resultados de candidatos se procesan durante la búsqueda. Más fragmentos pueden afectar el rendimiento de las siguientes maneras:
Si configuras una cantidad menor de fragmentos más grandes, se procesarán menos resultados de candidatos durante la búsqueda. Menos fragmentos pueden afectar el rendimiento de las siguientes maneras:
|
distanceMeasureType
|
Determina el algoritmo que se usa para calcular la distancia entre los puntos de datos y el vector de consulta. |
La siguiente configuración de
|
leafNodeEmbeddingCount
|
La cantidad de incorporaciones para cada nodo hoja. De forma predeterminada, este número se establece en 1000.
Por lo general, cambiar el valor de |
Aumentar la cantidad de incorporaciones para cada nodo hoja puede reducir la latencia pero también reducir la calidad de la recuperación. Puede afectar el rendimiento de las siguientes maneras:
Disminuir la cantidad de incorporaciones para cada nodo hoja puede afectar el rendimiento de las siguientes maneras:
|
Cómo usar un índice de fuerza bruta para medir la recuperación
Para obtener los vecinos más cercanos exactos, usa índices con el algoritmo de fuerza bruta. El algoritmo de fuerza bruta proporciona una recuperación del 100% a expensas de una latencia más alta. El uso de un índice de fuerza bruta para medir la recuperación no suele ser una buena opción para la entrega 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: {} } }, }, }'
Borra un índice
gcloud
Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:
- INDEX_ID: Es el ID del índice.
- LOCATION: la región en la que usas Vertex AI.
- PROJECT_ID: El ID del proyecto de Google Cloud.
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 cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- INDEX_ID: Es el ID del índice.
- LOCATION: la región en la que usas Vertex AI.
- PROJECT_ID: El ID del proyecto de Google Cloud.
- PROJECT_NUMBER: el número de proyecto de tu proyecto generado de forma automática.
HTTP method and URL:
DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID
Para enviar tu solicitud, expande una de estas opciones:
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
{ "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" } }
Console
Usa estas instrucciones para borrar uno o más índices.
- En la sección de Vertex AI de la consola de Google Cloud, ve a la sección Implementación y uso. Elige Vector Search
- Aparecerá una lista de los índices activos.
- Para borrar un índice, ve al menú de opciones que se encuentra en la misma fila que el índice y elige Borrar.
¿Qué sigue?
- Obtén más información sobre los parámetros de configuración de índices.
- Obtén más información para implementar y administrar extremos de índice público.
- Obtén más información para implementar y administrar extremos de índice en una red de VPC.
- Obtén más información sobre cómo actualizar y volver a compilar el índice.
- Obtén más información sobre cómo supervisar un índice.