Guía de inicio rápido de Vector Search

En la guía de inicio rápido de la búsqueda de vectores de Agent Platform de Gemini Enterprise, 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 Google Cloud proyecto 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 Agent Platform Workbench de Gemini Enterprise.

  • Colab: Abre este instructivo en Colab.
  • Agent Platform Workbench de Gemini Enterprise: Abre este instructivo en Agent Platform Workbench de Gemini Enterprise. Si es la primera vez que usas Agent Platform Workbench de Gemini Enterprise en tu Google Cloud proyecto, ve a la sección Agent Platform Workbench de Gemini Enterprise de la Google Cloud consola 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 Google Cloud servicios que se usan en este instructivo están disponibles en las siguientes páginas:

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

Configuración

Antes de comenzar a usar Agent Platform de Gemini Enterprise, debes configurar lo siguiente:

Instala el SDK de Agent Platform para Python

Se puede acceder a las APIs de Agent Platform de Gemini Enterprise y de Cloud Storage de varias maneras, incluida la API de REST y el SDK de Agent Platform para Python. En este instructivo, se usa el SDK de Agent Platform 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 Agent Platform Workbench de Gemini Enterprise, 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. Dirígete a la página IAM en la Google Cloud consola.
  2. Busca la principal para la cuenta de servicio de procesamiento predeterminada. Debería verse así: compute@developer.gserviceaccount.com
  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 Agent Platform de Gemini Enterprise, administrador de almacenamiento y administrador de Service Usage.

Habilita las APIs

Ejecuta el siguiente comando para habilitar las APIs de Compute Engine, Agent Platform de Gemini Enterprise, y Cloud Storage con este Google Cloud proyecto.

! 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 5,000 filas de datos de productos sintéticos para un sitio de ropa de comercio electrónico ficticio.

Conjunto de datos de muestra

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

Muestra de embeddings de productos

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 Agent Platform de Gemini Enterprise 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 a partir de los datos de una tabla de BigQuery y almacenarlos en un archivo JSON, consulta Empieza a usar embeddings de texto + búsqueda de vectores de Agent Platform de Gemini Enterprise.

Prepara los datos en Cloud Storage

Para compilar un índice con Agent Platform de Gemini Enterprise, 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 = 100,
)

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 Vector Search Google Cloud .

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 Agent Platform de la Google Cloud consola, ve a la Implementar y usar sección. 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 Vector Search Google Cloud 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 Vector Search Google Cloud . En la sección Agent Platform de la Google Cloud consola, ve a la sección Implementar y usar. 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 Vector Search Google Cloud . En la sección Agent Platform de la Google Cloud consola, ve a la sección Implementar y usar. 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)