Guía de inicio rápido de Vector Search

Para ver un ejemplo de cómo comenzar a usar la búsqueda de vectores de Vertex AI, ejecuta el notebook de Jupyter “Comienza a usar Vertex AI Vector Search” en uno de los siguientes entornos:

Abrir en Colab |Abrir en Colab Enterprise |Abrir en notebooks administrados por el usuario de Vertex AI Workbench |Ver en GitHub

En la guía de inicio rápido de Vertex AI Vector Search, aprende a crear un índice a partir de un conjunto de datos de muestra desde un sitio de ropa de comercio electrónico ficticio. Para los fines de esta guía de inicio rápido, los embeddings ya se crearon. El objetivo de esta guía de inicio rápido es brindar una forma de empezar a crear y a implementar un índice en menos de 30 minutos.

Requisitos previos

Para este instructivo, se requiere un proyecto de Google Cloud que esté vinculado a una cuenta de facturación. Para crear un proyecto nuevo, consulta Configura 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 instructivo se puede ejecutar en Colab o en Vertex AI Workbench.

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

Para ver este notebook en GitHub, consulta GitHub.

Costo de completar esta guía de inicio rápido

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

• Vector Search de Vertex AI
• Cloud Storage
• Vertex AI Workbench

También puedes usar la calculadora de precios para generar una estimación de los costos en función de tu uso proyectado.

Importante: Borra tus objetos después del instructivo. Asegúrate de borrar todos los índices, los extremos del índice, los buckets de Cloud Storage y la instancia de Vertex AI Workbench si usas uno después de finalizar este instructivo. Si no se borra este objeto, los recursos restantes pueden generar costos inesperados.

Configuración

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

• Instala el SDK de Vertex AI para Python
• Configure las variables de entorno
• Autenticar (solo Colab)
• Configura los permisos de IAM
• Habilita las API

Instala el SDK de Vertex AI para Python

Se puede acceder a las API de Vertex AI y de Cloud Storage de varias maneras, incluida la API de REST y el SDK de Vertex AI para Python. En este instructivo, 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

Configure las variables de entorno. Si se te solicita, reemplaza your-project-id por el ID del 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 Colab)

Si ejecutas este notebook en Colab, debes ejecutar la siguiente autenticación de celdas. Este paso no es necesario si usas Vertex AI Workbench, ya que está preautenticado.

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()

Configura los permisos de IAM

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

1. Ve a la página de IAM en la consola de Google Cloud.
2. Busca la principal para la cuenta de servicio de procesamiento predeterminada. Debería verse así: [e-mail]
3. Haz clic en el botón Cambiar y otorga acceso a la cuenta de servicio de procesamiento predeterminada con los siguientes roles: usuario de Vertex AI, administrador de almacenamiento y administrador de Service Usage.

Habilita APIs

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

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

Prepara los datos de muestra

En este instructivo, usamos el conjunto de datos TheLook que tiene una tabla de productos con alrededor de 30,000 filas de datos de productos sintéticos para un sitio de ropa de comercio electrónico ficticio.

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

Este archivo está en formato JSONL y cada fila tiene ID para el ID del producto, nombre para el nombre del producto y embedding para el embedding del nombre del producto en 768 dimensiones que se generaron antes con los embeddings de Vertex AI para texto.

Los embeddings de texto representan el significado de los nombres de los productos de indumentaria. En este instructivo, usamos Vector Search para completar una búsqueda semántica de los elementos. Este código de muestra se puede usar como base para otros sistemas de recomendación rápidos en los que puedes encontrar “otros productos similares a este” con rapidez.

Para obtener más información sobre cómo crear los embeddings de datos a partir de datos de BigQuery y almacenarlas en un archivo JSON, consulta Empieza a usar embeddings de texto + Vertex AI Vector Search.

Prepara los datos en Cloud Storage

Para compilar un índice con Vertex AI, coloca el archivo de embedding en un bucket de Cloud Storage. El código siguiente completa dos tareas:

1. Crea un bucket de Cloud Storage.
2. Copia el archivo de ejemplo en tu bucket 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

Si quieres usar Vector Search para ejecutar consultas, también debes copiar el archivo de embedding en el directorio local:

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

Compila e implementa un índice de Vector Search

Aprende a crear un índice, crea un extremo de índice y, luego, implementa el índice en el extremo.

Crea un índice

Es hora de cargar los embeddings a 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 = 10,
)

El método MatchingEngineIndex.create_tree_ah_index() compila un índice. Esto lleva menos de 10 minutos si el conjunto de datos es pequeño; de lo contrario, alrededor de 60 minutos o más según el tamaño del conjunto de datos. Puedes comprobar el estado de la creación del índice en la consola de Google Cloud de Vector Search

Ver índices

Los parámetros para crear un índice son los siguientes:

• contents_delta_uri: el URI del directorio de Cloud Storage en el que almacenaste los archivos JSON de embedding
• dimensions: Tamaño de las dimensiones de cada embedding. En este caso, es 768, ya que usas los embeddings de la API de embeddings de texto.
• approximate_neighbors_count: cuántos elementos similares deseas recuperar en casos típicos

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

Crea un extremo de índice e implementa el índice

Para usar el índice, debes crear un extremo 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 extremo del índice, especifica el ID del índice implementado único para implementarlo.

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 implementa este índice en un extremo de índice, puede tardar unos 30 minutos en compilar e iniciar el backend de forma automática. Para ver el estado de la implementación del índice, en la sección Vertex AI de la consola de Google Cloud, ve a la sección Implementar y usar. Selecciona Índices.

Ver índices

Ejecuta una consulta con Vector Search

En el siguiente código, se encuentra una embedding para un nombre de producto específico y se encuentran nombres de productos similares con Vector Search.

Haz que un embedding ejecute una consulta

Primero, carga el archivo JSON del embedding para compilar un dict de nombres de producto y embeddings.

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 product_embs, puedes especificar un ID de producto para obtener su embedding.

 # 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']

Ejecuta una consulta

Pasa el embedding a la función Endpoint.find_neighbors() para encontrar 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]}")

La función find_neighbors() solo tarda milisegundos en recuperar los elementos similares incluso cuando tienes miles de millones de elementos en el índice, gracias al algoritmo ScaNN Vector Search admite el ajuste de escala automático, que puede cambiar el tamaño de la cantidad de nodos de forma automática según las demandas de tus cargas de trabajo.

Realiza una limpieza

En caso de que uses tu propio proyecto de Cloud, no un proyecto temporal en Qwiklabs, asegúrate de borrar todos los índices, los extremos de índice y los depósitos de Cloud Storage después de finalizar este instructivo. De lo contrario, es posible que generes costos inesperados por los recursos restantes.

Si usaste Workbench, es posible que también debas borrar los notebooks 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

Utilidades

La creación o implementación de índices puede tomar tiempo, y en ese período, podrías perder la conexión con el entorno de ejecución de Colab. Si pierdes la conexión, en lugar de crear o implementar tu índice nuevo otra vez, puedes comprobar la consola de Google Cloud de Vector Search y usar los existentes para continuar.

Obtén un índice existente

Para obtener un objeto de índice que ya existe, reemplaza el siguiente your-index-id con el ID de índice y ejecuta la celda. Para obtener el ID de índice, revisa la consola de Google Cloud de Vector Search. En la sección Vertex AI de Google Cloud Console, ve a la sección Implementación y uso. Selecciona Índices.

Ver índices

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

Obtén un extremo de índice existente

Para obtener un objeto de extremo de índice que ya existe, reemplaza el siguiente your-index-endpoint-id con el ID del extremo del índice y ejecuta la celda. Para obtener el extremo del índice, revisa la consola de Google Cloud de Vector Search. En la sección Vertex AI de la consola de Google Cloud, ve a la sección Implementación y uso. Selecciona Extremos de índice.

Consulta extremos de índice

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