Guia de início rápido da Pesquisa de vetores

No guia de início rápido do Vector Search da Vertex AI, aprenda a criar um índice com base em um conjunto de dados de amostra de um site de e-commerce fictício de roupas. Para este guia de início rápido, os embeddings já foram criados. Este guia de início rápido é uma maneira de começar a criar e implantar um índice em menos de 30 minutos.

Pré-requisitos

Este tutorial requer um projeto do Google Cloud vinculado a uma conta de faturamento. Para criar um novo projeto, consulte Configurar um projeto e um ambiente de desenvolvimento. Crie um projeto e configure sua conta de faturamento.

Escolha o ambiente de execução

Este tutorial pode ser executado no Colab ou no Vertex AI Workbench.

Colab: abra este tutorial no Colab.
Vertex AI Workbench: abra este tutorial no Vertex AI Workbench. Se esta for a primeira vez que você está usando o Vertex AI Workbench no projeto do Google Cloud, acesse a seção "Vertex AI Workbench" do console do Google Cloud e clique em Ativar para habilitar a API Notebooks.

Para visualizar esse notebook no GitHub, acesse o GitHub.

Custo para concluir este guia de início rápido

O custo para concluir este tutorial é de aproximadamente alguns dólares americanos. Os preços dos serviços do Google Cloud usados neste tutorial estão disponíveis nas seguintes páginas:

Também é possível usar a calculadora de preços para gerar uma estimativa de custo com base no uso previsto.

Instalação

Antes de começar a usar a Vertex AI, você precisa configurar o seguinte:

Instale o SDK da Vertex AI para Python
Definir as variáveis de ambiente
Autenticar (somente Colab)
Defina as permissões do IAM
Ativar as APIs

Instale o SDK da Vertex AI para Python

As APIs Vertex AI e Cloud Storage podem ser acessadas de várias maneiras, incluindo a API REST e o SDK da Vertex AI para Python. Neste tutorial, usamos o SDK da Vertex AI para Python.

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

Para usar os pacotes recém-instalados nesse ambiente de execução do Jupyter, você precisa reiniciar o ambiente de execução, conforme mostrado no snippet de código a seguir.

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

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

Variáveis de ambiente

Defina as variáveis de ambiente. Se solicitado, substitua your-project-id pelo ID do projeto e execute a célula.

# 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")

Autenticação (somente Colab)

Se você estiver executando este notebook no Colab, será necessário executar a seguinte autenticação de células. Esta etapa não é necessária se você estiver usando o Vertex AI Workbench porque ele é pré-autenticado.

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

Defina as permissões do IAM

É necessário adicionar permissões de acesso à conta de serviço padrão para usar os serviços.

Acesse a página "IAM" no console do Google Cloud.
Procure o principal da conta de serviço padrão do Compute. Ele deverá ter esta aparência: compute@developer.gserviceaccount.com
Clique no botão de edição e conceda à conta de serviço padrão do Compute os seguinte papéis: usuário da Vertex AI, administrador do Storage e administrador do Service Usage.

Ative as APIs

Execute o comando a seguir para ativar as APIs do Compute Engine, da Vertex AI e do Cloud Storage com este projeto do Google Cloud.

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

Preparar os dados de amostra

Neste tutorial, usamos o conjunto de dados TheLook, que tem uma tabela de produtos com cerca de 30 mil linhas de dados sintéticos do produtos para um site fictício de e-commerce.

Com base nessa tabela, preparamos o arquivo product-embs.json.

Esse arquivo está no formato JSONL, e cada linha tem um ID para o ID do produto, um nome para o nome do produto e um embedding para o embedding do nome do produto em 768 dimensões que foram geradas anteriormente com embeddings da Vertex AI para texto.

Os embeddings de texto representam o significado dos nomes dos produtos de vestuário. Neste tutorial, usamos o Vector Search para concluir uma pesquisa semântica dos itens. Esse exemplo de código pode ser usado como base para outros sistemas de recomendação rápida em que você pode encontrar rapidamente "outros produtos semelhantes a este".

Para saber como criar embeddings com base nos dados em uma tabela do BigQuery e armazená-los em um arquivo JSON, consulte Introdução a embeddings de texto e à pesquisa de vetor da Vertex AI.

Preparar os dados no Cloud Storage

Para criar um índice com a Vertex AI, coloque o arquivo de embedding em um bucket do Cloud Storage. O código a seguir conclui duas tarefas:

Cria um bucket do Cloud Storage.
Copia o arquivo de exemplo para o bucket do Cloud Storage.

BUCKET_URI = f"gs://{PROJECT_ID}-vs-quickstart-{UID}"

! gsutil mb -l $LOCATION -p $PROJECT_ID $BUCKET_URI
! gsutil cp "gs://github-repo/data/vs-quickstart/product-embs.json" $BUCKET_URI

Para usar o Vector Search para executar consultas, você também precisa copiar o arquivo de embedding no diretório local:

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

Criar e implantar um índice da Pesquisa de vetor

Saiba como criar um índice, um endpoint de índice e implantar o índice no endpoint.

Criar um índice

Agora é hora de carregar os embeddings no Vector Search. As APIs estão disponíveis no pacote aiplatform do SDK.

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

Crie um MatchingEngineIndex com a respectiva função create_tree_ah_index (Matching Engine é o nome anterior do 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,
)

O método MatchingEngineIndex.create_tree_ah_index() cria um índice. Isso levará menos de 10 minutos se o conjunto de dados for pequeno. Caso contrário, levará cerca de 60 minutos ou mais, dependendo do tamanho do conjunto de dados. Você pode verificar o status da criação do índice no console do Vector Search do Google Cloud

Consulte os índices

Os parâmetros para criar o índice:

contents_delta_uri: o URI do diretório do Cloud Storage em que você armazenou os arquivos JSON de embedding.
dimensions: tamanho da dimensão de cada embedding. Nesse caso, ele é 768 porque você está usando os embeddings da API de embeddings de texto.
approximate_neighbors_count: quantos itens semelhantes você quer recuperar em casos típicos.

Para saber mais sobre como criar o índice e os parâmetros disponíveis, consulte Criar e gerenciar o índice.

Criar endpoint de índice e implantar o índice

Para usar um índice, é preciso criar um endpoint de índice. Ele funciona como uma instância do servidor que aceita solicitações de consulta para o índice.

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

Com o endpoint do índice, implante o índice especificando um ID de índice implantado exclusivo.

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
)

Se for a primeira vez que esse índice é implantado em um endpoint de índice, pode levar cerca de 30 minutos para que o back-end seja criado e iniciado automaticamente. Para conferir o status da implantação do índice, na seção Vertex AI do console do Google Cloud, acesse a seção Implantar e usar. Selecione Índices.

Consulte os índices

Executar uma consulta com o Vector Search

No código a seguir, ele encontra um embedding para um nome de produto especificado e encontra nomes de produtos semelhantes com o Vector Search.

Receber um embedding para executar uma consulta

Primeiro, carregue o arquivo JSON de embedding para criar um dict de nomes dos produtos e 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']

Com o dicionário product_embs, é possível especificar um ID do produto para receber um embedding dele.

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

Executar uma consulta

Transmita o embedding ao método Endpoint.find_neighbors() para encontrar nomes dos produtos semelhantes.

# 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]}")

Graças ao algoritmo ScaNN, o método find_neighbors() leva apenas milissegundos para buscar itens semelhantes, mesmo quando há bilhões de itens no índice. O Vector Search também oferece suporte ao escalonamento automático, que pode redimensionar automaticamente o número de nós com base nas demandas das cargas de trabalho.

Limpar

Caso você esteja usando seu projeto do Cloud, e não um projeto temporário no Qwiklabs, exclua todos os índices, endpoints de índice e buckets do Cloud Storage depois de concluir este tutorial. Caso contrário, os recursos restantes poderão gerar custos inesperados.

Se você usou o Workbench, talvez precise excluir os notebooks do console.


# 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
! gsutil rm -r {BUCKET_URI}

Utilitários

Pode levar algum tempo para criar ou implantar índices e, nesse tempo, você pode perder a conexão com o ambiente de execução do Colab. Se você perder a conexão, em vez de criar ou implantar o novo índice novamente, verifique o console do Vector Search do Google Cloud e use os já existentes para continuar.

Receber um índice atual

Para receber um objeto de índice que já existe, substitua o seguinte your-index-id pelo ID do índice e execute a célula. Você pode conseguir o ID do índice no console do Google Cloud do Vector Search Na seção Vertex AI do console do Google Cloud, acesse a seção Implantar e usar. Selecione Índices.

Consulte os índices

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

Receber um endpoint de índice atual

Para conseguir um objeto de endpoint de índice que já existe, substitua o seguinte your-index-endpoint-id pelo ID do endpoint do índice e execute a célula. Você pode acessar o endpoint do índice no Vector Search do console do Google Cloud. Na seção Vertex AI do console do Google Cloud, acesse a seção Implantar e usar. Selecione Endpoints de índice.

Consultar endpoints de índice

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