Guía de inicio rápido de Vector Search

En la guía de inicio rápido de Vertex AI Vector Search, se explica cómo crear un índice a partir de un conjunto de datos de muestra de un sitio de comercio electrónico ficticio de ropa. En esta guía de inicio rápido, las inserciones ya se han creado. Esta guía de inicio rápido tiene como objetivo ayudarte a crear e implementar un índice en menos de 30 minutos.

Requisitos previos

Para hacer este tutorial, necesitas un Google Cloud proyecto vinculado a una cuenta de facturación. Para crear un proyecto, consulta el artículo Configurar un proyecto y un entorno de desarrollo. Debes crear un proyecto y configurar tu cuenta de facturación.

Elige el entorno de ejecución

Este tutorial se puede ejecutar en Colab o en Vertex AI Workbench.

  • Colab: abre este tutorial en Colab.
  • Vertex AI Workbench: abre este tutorial en Vertex AI Workbench. Si es la primera vez que usas Vertex AI Workbench en tu Google Cloud proyecto, ve a la sección Vertex AI Workbench de la Google Cloud consola y haz clic en Habilitar para habilitar la API Notebooks.

Para ver este cuaderno en GitHub, consulta GitHub.

Coste para completar esta guía de inicio rápido

Completar este tutorial cuesta aproximadamente unos pocos dólares estadounidenses. Los precios de los Google Cloud servicios que se usan en este tutorial están disponibles en las siguientes páginas:

También puedes usar la calculadora de precios para generar una estimación de costes en función del uso previsto.

Configuración

Antes de empezar a usar Vertex AI, debes configurar lo siguiente:

Instalar el SDK de Vertex AI para Python

Se puede acceder a las APIs de Vertex AI y Cloud Storage de varias formas, como a través de la API REST y del SDK de Vertex AI para Python. En este tutorial, se usa el SDK de Vertex AI para Python.

!pip install --upgrade --user google-cloud-aiplatform>=1.29.0 google-cloud-storage

Para usar los paquetes recién instalados en este entorno de ejecución de Jupyter, debes reiniciar el entorno de ejecución, como se muestra en el siguiente fragmento de código.

# Restart kernel after installs so that your environment can access the new packages
import IPython

app = IPython.Application.instance()
app.kernel.do_shutdown(True)

Variables de entorno

Define las variables de entorno. Si se te pide, sustituye your-project-id por el ID de tu proyecto y ejecuta la celda.

# get project ID
PROJECT_ID = ! gcloud config get-value project
PROJECT_ID = PROJECT_ID[0]
LOCATION = "us-central1"
if PROJECT_ID == "(unset)":
    print(f"Please set the project ID manually below")

# define project information
if PROJECT_ID == "(unset)":
  PROJECT_ID = "[your-project-id]"

# generate a unique id for this session
from datetime import datetime
UID = datetime.now().strftime("%m%d%H%M")

Autenticación (solo en Colab)

Si estás ejecutando este cuaderno en Colab, debes ejecutar la siguiente autenticación de celda. Este paso no es obligatorio si usas Vertex AI Workbench, ya que está autenticado previamente.

import sys

# if it's Colab runtime, authenticate the user with Google Cloud
if 'google.colab' in sys.modules:
    from google.colab import auth
    auth.authenticate_user()

Establecer permisos de gestión de identidades y accesos

Debes añadir permisos de acceso a la cuenta de servicio predeterminada para usar los servicios.

  1. Ve a la página Gestión de identidades y accesos de la Google Cloud consola.
  2. Busca el principal de la cuenta de servicio predeterminada de Compute. Debería tener este aspecto: compute@developer.gserviceaccount.com
  3. Haz clic en el botón de edición y asigna a la cuenta de servicio de computación predeterminada los siguientes roles: Usuario de Vertex AI, Administrador de almacenamiento y Administrador de uso de servicios.

Habilitar APIs

Ejecuta el siguiente comando para habilitar las APIs de Compute Engine, Vertex AI y Cloud Storage en este proyecto Google Cloud .

! gcloud services enable compute.googleapis.com aiplatform.googleapis.com storage.googleapis.com --project {PROJECT_ID}

Preparar los datos de muestra

En este tutorial, usamos el conjunto de datos TheLook,que tiene una tabla de productos con unas 5000 filas de datos de producto sintéticos de un sitio de comercio electrónico de ropa ficticio.

Conjunto de datos de ejemplo

A partir de esta tabla, hemos preparado el archivo product-embs.json.

Inserciones de productos de muestra

Este archivo está en formato JSONL y cada fila tiene un ID de producto, un nombre de producto y una inserción del nombre del producto en 768 dimensiones, que se generó anteriormente con las inserciones de texto de Vertex AI.

Las inserciones de texto representan el significado de los nombres de los productos de ropa. En este tutorial, usamos Vector Search para completar una búsqueda semántica de los elementos. Este código de ejemplo se puede usar como base para otros sistemas de recomendación rápidos en los que puedes encontrar rápidamente "otros productos similares a este".

Para obtener más información sobre cómo crear las inserciones a partir de los datos de una tabla de BigQuery y almacenarlas en un archivo JSON, consulta Introducción a las inserciones de texto y a Vertex AI Vector Search.

Preparar los datos en Cloud Storage

Para crear un índice con Vertex AI, coloca el archivo de inserciones en un segmento de Cloud Storage. El siguiente código realiza dos tareas:

  1. Crea un segmento de Cloud Storage.
  2. Copia el archivo de ejemplo en tu segmento de Cloud Storage.
BUCKET_URI = f"gs://{PROJECT_ID}-vs-quickstart-{UID}"

! gcloud storage buckets create $BUCKET_URI --location=$LOCATION --project=$PROJECT_ID
! gcloud storage cp "gs://github-repo/data/vs-quickstart/product-embs.json" $BUCKET_URI

Para usar la búsqueda de vectores y ejecutar consultas, también debe copiar el archivo de incrustación en el directorio local:

! gcloud storage cp "gs://github-repo/data/vs-quickstart/product-embs.json" . # for query tests

Crear y desplegar un índice de búsqueda vectorial

Consulta cómo crear un índice, un endpoint de índice y, a continuación, desplegar el índice en el endpoint.

Crear un índice

Ahora es el momento de cargar las incrustaciones en Vector Search. Las APIs están disponibles en el paquete aiplatform del SDK.

# init the aiplatform package
from google.cloud import aiplatform
aiplatform.init(project=PROJECT_ID, location=LOCATION)

Crea un MatchingEngineIndex con su función create_tree_ah_index (Matching Engine es el nombre anterior de Vector Search).

# create Index
my_index = aiplatform.MatchingEngineIndex.create_tree_ah_index(
    display_name = f"vs-quickstart-index-{UID}",
    contents_delta_uri = BUCKET_URI,
    dimensions = 768,
    approximate_neighbors_count = 100,
)

El método MatchingEngineIndex.create_tree_ah_index() crea un índice. Si el conjunto de datos es pequeño, este proceso tardará menos de 10 minutos. De lo contrario, tardará unos 60 minutos o más, en función del tamaño del conjunto de datos. Puede consultar el estado de la creación del índice en la consola de búsqueda vectorial. Google Cloud

Ver índices

Parámetros para crear el índice:

  • contents_delta_uri: el URI del directorio de Cloud Storage donde has almacenado los archivos JSON de los embeddings
  • dimensions: tamaño de la dimensión de cada inserción. En este caso, es 768, ya que estás usando las incrustaciones de la API Text Embeddings.
  • approximate_neighbors_count: cuántos elementos similares quieres obtener en los casos típicos

Para obtener más información sobre cómo crear el índice y los parámetros disponibles, consulta Crear y gestionar el índice.

Crear un endpoint de índice y desplegar el índice

Para usar el índice, debes crear un endpoint de índice. Funciona como una instancia de servidor que acepta solicitudes de consulta para tu índice.

## create `IndexEndpoint`
my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint.create(
    display_name = f"vs-quickstart-index-endpoint-{UID}",
    public_endpoint_enabled = True
)

Con el endpoint de índice, implementa el índice especificando un ID de índice implementado único.

DEPLOYED_INDEX_ID = f"vs_quickstart_deployed_{UID}"

# deploy the Index to the Index Endpoint
my_index_endpoint.deploy_index(
    index = my_index, deployed_index_id = DEPLOYED_INDEX_ID
)

Si es la primera vez que implementas este índice en un endpoint de índice, pueden pasar unos 30 minutos hasta que se cree e inicie el backend automáticamente. Para ver el estado de la implementación del índice, ve a la sección Implementar y usar de la sección Vertex AI de laGoogle Cloud consola. Selecciona Índices.

Ver índices

Ejecutar una consulta con Vector Search

En el siguiente código, se busca una inserción para un nombre de producto específico y se buscan nombres de productos similares con la búsqueda vectorial.

Obtener una inserción para ejecutar una consulta

Primero, carga el archivo JSON de inserciones para crear un dict de nombres de productos e inserciones.

import json

# build dicts for product names and embs
product_names = {}
product_embs = {}
with open('product-embs.json') as f:
    for l in f.readlines():
        p = json.loads(l)
        id = p['id']
        product_names[id] = p['name']
        product_embs[id] = p['embedding']

Con el diccionario product_embs, puedes especificar un ID de producto para obtener una inserción.

 # Get the embedding for ID 6523 "cloudveil women's excursion short"
 # You can also try with other IDs such as 12711, 18090, 19536 and 11863
query_emb = product_embs['6523']

Ejecutar una consulta

Pasa la inserción al método Endpoint.find_neighbors() para buscar nombres de productos similares.

# run query
response = my_index_endpoint.find_neighbors(
    deployed_index_id = DEPLOYED_INDEX_ID,
    queries = [query_emb],
    num_neighbors = 10
)

# show the results
for idx, neighbor in enumerate(response[0]):
    print(f"{neighbor.distance:.2f} {product_names[neighbor.id]}")

El método find_neighbors() solo tarda unos milisegundos en obtener los elementos similares, incluso cuando tienes miles de millones de elementos en el índice, gracias al algoritmo ScaNN. Búsqueda vectorial también admite el autoescalado, que puede cambiar automáticamente el tamaño del número de nodos en función de las demandas de tus cargas de trabajo.

Eliminar los recursos utilizados

Si usas tu propio proyecto de Cloud y no un proyecto temporal de Qwiklabs, asegúrate de eliminar todos los índices, los endpoints de índice y los contenedores de Cloud Storage después de completar este tutorial. De lo contrario, es posible que incurras en costes inesperados por los recursos restantes.

Si has usado Workbench, es posible que también tengas que eliminar los cuadernos de la consola.


# wait for a confirmation
input("Press Enter to delete Index Endpoint, Index and Cloud Storage bucket:")

# delete Index Endpoint
my_index_endpoint.undeploy_all()
my_index_endpoint.delete(force = True)

# delete Index
my_index.delete()

# delete Cloud Storage bucket
! gcloud storage rm {BUCKET_URI} --recursive

Servicios públicos

La creación o la implementación de índices puede llevar un tiempo, y es posible que pierdas la conexión con el entorno de ejecución de Colab durante ese tiempo. Si pierdes la conexión, en lugar de crear o implementar de nuevo tu nuevo índice, puedes consultar la consola de búsqueda vectorialGoogle Cloud y usar los índices que ya tengas para continuar.

Obtener un índice

Para obtener un objeto de índice que ya exista, sustituye el siguiente your-index-id por el ID del índice y ejecuta la celda. Puedes obtener el ID del índice consultando la consola de búsqueda vectorial. Google Cloud En la sección Vertex AI de la Google Cloud consola, ve a la sección Desplegar y usar. Selecciona Índices.

Ver índices

my_index_id = "[your-index-id]"
my_index = aiplatform.MatchingEngineIndex(my_index_id)

Obtener un endpoint de índice

Para obtener un objeto de endpoint de índice que ya exista, sustituye el siguiente your-index-endpoint-id por el ID del endpoint de índice y ejecuta la celda. Puedes obtener el endpoint del índice consultando la consola de búsqueda vectorial Google Cloud . En la sección Vertex AI de la Google Cloud consola, ve a la sección Desplegar y usar. Selecciona Index Endpoints (Indexar endpoints).

Ver Endpoints de índice

my_index_endpoint_id = "[your-index-endpoint-id]"
my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint(my_index_endpoint_id)