O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Introdução às embeddings vetoriais com a IA do AlloyDB

1. Introdução

Neste codelab, você vai aprender a usar o AlloyDB AI combinando a pesquisa vetorial com embeddings da Vertex AI. Este laboratório faz parte de uma coleção dedicada aos recursos de IA do AlloyDB. Leia mais na página da IA do AlloyDB na documentação.

Pré-requisitos

Conhecimentos básicos sobre o Google Cloud e o console
Habilidades básicas com a interface de linha de comando e o Cloud Shell

O que você vai aprender

Como implantar um cluster e uma instância principal do AlloyDB
Como se conectar ao AlloyDB de uma VM do Google Compute Engine
Como criar um banco de dados e ativar a IA do AlloyDB
Como carregar dados no banco de dados
Como usar o AlloyDB Studio
Como usar o modelo de incorporação da Gemini Enterprise Agent Platform no AlloyDB
Como usar o Gemini Enterprise Agent Platform Studio
Como enriquecer o resultado usando o modelo generativo da Gemini Enterprise Agent Platform
Como melhorar a performance usando o índice de vetor

O que é necessário

Uma conta e um projeto do Google Cloud
Um navegador da Web, como o Chrome

2. Configuração e requisitos

Configuração do projeto

Faça login no Console do Google Cloud. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.

Use uma conta pessoal em vez de uma conta escolar ou de trabalho.

Crie um projeto ou reutilize um existente. Para criar um projeto no console do Google Cloud, clique no botão "Selecionar um projeto" no cabeçalho, que vai abrir uma janela pop-up.

Na janela "Selecionar um projeto", clique no botão "Novo projeto", que vai abrir uma caixa de diálogo para o novo projeto.

Na caixa de diálogo, coloque o nome do projeto de sua preferência e escolha o local.

O Nome do projeto é o nome de exibição para os participantes do projeto. O nome do projeto não é usado pelas APIs do Google e pode ser alterado a qualquer momento.
O ID do projeto é exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Google Cloud gera automaticamente um ID exclusivo, mas você pode personalizá-lo. Se você não gostar do ID gerado, crie outro aleatório ou forneça o seu para verificar a disponibilidade. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, que normalmente é identificado com o marcador de posição PROJECT_ID.
Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.

Ativar faturamento

Configurar uma conta de faturamento pessoal

Se você configurou o faturamento usando créditos do Google Cloud, pule esta etapa.

Para configurar uma conta de faturamento pessoal, acesse este link para ativar o faturamento no console do Cloud.

Algumas observações:

A conclusão deste laboratório custa menos de US $3 em recursos do Cloud.
Siga as etapas no final deste laboratório para excluir recursos e evitar mais cobranças.
Novos usuários podem aproveitar o teste sem custos financeiros de US$300.

Inicie o Cloud Shell

Embora o Google Cloud e o Spanner possam ser operados remotamente do seu laptop, neste codelab usaremos o Google Cloud Shell, um ambiente de linha de comando executado no Cloud.

No Console do Google Cloud, clique no ícone do Cloud Shell na barra de ferramentas superior à direita:

Ativar o Cloud Shell

Ou pressione G e S. Essa sequência vai ativar o Cloud Shell se você estiver no console do Google Cloud ou usar este link.

O provisionamento e a conexão com o ambiente levarão apenas alguns instantes para serem concluídos: Quando o processamento for concluído, você verá algo como:

Captura de tela do terminal do Google Cloud Shell mostrando que o ambiente foi conectado

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste codelab, todo o trabalho pode ser feito com um navegador. Você não precisa instalar nada.

3. Antes de começar

Ativar API

Saída:

Para usar o AlloyDB, o Compute Engine, os serviços de rede e a Gemini Enterprise Agent Platform, é necessário ativar as respectivas APIs no seu projeto do Google Cloud.

Como ativar as APIs

No terminal do Cloud Shell, verifique se o ID do projeto está configurado:

gcloud config set project [YOUR-PROJECT-ID]

Defina a variável de ambiente PROJECT_ID:

PROJECT_ID=$(gcloud config get-value project)

Ative todas as APIs necessárias:

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com

Resultado esperado

student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$ 
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.

Leia sobre cada API ativada na documentação.

4. Implantar o AlloyDB

Antes de criar um cluster do AlloyDB, aloque um intervalo de IP privado disponível na VPC para ser usado pela instância futura do AlloyDB. Se você não tiver, crie e atribua para uso pelos serviços internos do Google. Depois disso, será possível criar o cluster e a instância.

Criar um intervalo de IP privado

É preciso configurar o Acesso a serviços particulares na VPC para o AlloyDB. Vamos supor que o projeto tem uma rede VPC "padrão" a ser usada para todas as ações.

Crie o intervalo de IP privado:

gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default

Crie uma conexão privada com o intervalo de IP alocado:

gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default
Created [https://www.googleapis.com/compute/v1/projects/test-project-402417/global/addresses/psa-range].

student@cloudshell:~ (test-project-402417)$ gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default
Operation "operations/pssn.p24-4470404856-595e209f-19b7-4669-8a71-cbd45de8ba66" finished successfully.

student@cloudshell:~ (test-project-402417)$

Criar cluster do AlloyDB

Criar um cluster do AlloyDB na região us-central1

Defina a senha do usuário postgres. Você pode definir sua própria senha ou usar uma função aleatória para gerar uma.

export PGPASSWORD=`openssl rand -hex 16`

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ export PGPASSWORD=`openssl rand -hex 12`

Anote a senha do PostgreSQL para uso futuro:

echo $PGPASSWORD

Você vai precisar dessa senha no futuro para se conectar à instância como o usuário postgres. Salve essa senha para usar nas etapas seguintes.

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ echo $PGPASSWORD
bbefbfde7601985b0dee5723 (Note: Yours will be different!)

Criar um cluster de teste sem custo financeiro

Se você nunca usou o AlloyDB, crie um cluster de teste sem custo financeiro:

Defina variáveis de ambiente para a região e o nome do cluster:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01

Execute o comando para criar o cluster:

gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION \
    --subscription-type=TRIAL

Saída esperada do console:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION \
    --subscription-type=TRIAL
Operation ID: operation-1697655441138-6080235852277-9e7f04f5-2012fce4
Creating cluster...done.

Crie uma instância principal do AlloyDB para o cluster na mesma sessão do Cloud Shell. Se você se desconectar, será necessário definir as variáveis de ambiente de região e nome do cluster novamente.

gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=8 \
    --region=$REGION \
    --cluster=$ADBCLUSTER

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=8 \
    --region=$REGION \
    --availability-type ZONAL \
    --cluster=$ADBCLUSTER
Operation ID: operation-1697659203545-6080315c6e8ee-391805db-25852721
Creating instance...done.

Criar cluster padrão do AlloyDB

Se não for seu primeiro cluster do AlloyDB no projeto, continue com a criação de um cluster padrão. Se você já criou um cluster de teste sem custo financeiro, pule esta etapa.

Defina variáveis de ambiente para a região e o nome do cluster:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01

Execute o comando para criar o cluster:

gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION

Saída esperada do console:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION 
Operation ID: operation-1697655441138-6080235852277-9e7f04f5-2012fce4
Creating cluster...done.

gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --cluster=$ADBCLUSTER

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --availability-type ZONAL \
    --cluster=$ADBCLUSTER
Operation ID: operation-1697659203545-6080315c6e8ee-391805db-25852721
Creating instance...done.

5. Conectar-se ao AlloyDB

O AlloyDB é implantado usando uma conexão somente privada. Portanto, você precisa de uma VM do Compute Engine com o cliente PostgreSQL instalado para trabalhar com o banco de dados.

Implantar a VM do GCE

Crie uma VM do GCE na mesma região e VPC que o cluster do AlloyDB.

No Cloud Shell, execute:

export ZONE=us-central1-a
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-13 AND family!=debian-13-arm64" --format="value(name)") \
    --scopes=https://www.googleapis.com/auth/cloud-platform

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ export ZONE=us-central1-a
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-13 AND family!=debian-13-arm64" --format="value(name)") \
    --scopes=https://www.googleapis.com/auth/cloud-platform

Created [https://www.googleapis.com/compute/v1/projects/test-project-402417/zones/us-central1-a/instances/instance-1].
NAME: instance-1
ZONE: us-central1-a
MACHINE_TYPE: n1-standard-1
PREEMPTIBLE: 
INTERNAL_IP: 10.128.0.2
EXTERNAL_IP: 34.71.192.233
STATUS: RUNNING

Instalar o cliente do Postgres

Instale o software do cliente PostgreSQL na VM implantada.

Conecte-se à VM:

gcloud compute ssh instance-1 --zone=us-central1-a

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ gcloud compute ssh instance-1 --zone=us-central1-a
Updating project ssh metadata...working..Updated [https://www.googleapis.com/compute/v1/projects/test-project-402417].                                                                                                                                                         
Updating project ssh metadata...done.                                                                                                                                                                                                                                              
Waiting for SSH key to propagate.
Warning: Permanently added 'compute.5110295539541121102' (ECDSA) to the list of known hosts.
Linux instance-1 6.12.101+deb13-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.12.101-1 (2026-08-05) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
student@instance-1:~$

Instale o comando em execução do software na VM:

sudo apt-get update
sudo apt-get install --yes postgresql-client

Saída esperada do console:

student@instance-1:~$ sudo apt-get update
sudo apt-get install --yes postgresql-client
Get:1 file:/etc/apt/mirrors/debian.list Mirrorlist [30 B]
Get:2 file:/etc/apt/mirrors/debian-security.list Mirrorlist [39 B]                      
Hit:3 https://deb.debian.org/debian trixie InRelease                                    
Get:4 https://deb.debian.org/debian trixie-updates InRelease [47.3 kB]
Get:5 https://deb.debian.org/debian trixie-backports InRelease [54.0 kB]
Get:6 https://deb.debian.org/debian-security trixie-security InRelease [43.4 kB]
Hit:10 https://packages.cloud.google.com/apt google-compute-engine-trixie-stable InRelease
...redacted...
update-alternatives: using /usr/share/postgresql/17/man/man1/psql.1.gz to provide /usr/share/man/man1/psql.1.gz (psql.1.gz) in auto mode
Setting up postgresql-client (17+278) ...
Processing triggers for man-db (2.13.1-1) ...
Processing triggers for libc-bin (2.41-12+deb13u3) ...

Conectar-se à instância

Conecte-se à instância principal pela VM com psql.

Na mesma guia do Cloud Shell com a sessão SSH aberta na VM instance-1.

Use o valor da senha do AlloyDB (PGPASSWORD) e o ID do cluster do AlloyDB para se conectar ao AlloyDB pela VM do GCE:

export PGPASSWORD=<Noted password>

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres sslmode=require"

Saída esperada do console:

student@instance-1:~$ export PGPASSWORD=CQhOi5OygD4ps6ty
student@instance-1:~$ export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres sslmode=require"
psql (17.10 (Debian 17.10-0+deb13u1), server 17.9)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: postgresql)
Type "help" for help.

postgres=>

Feche a sessão psql:

exit

6. Preparar banco de dados

Crie um banco de dados, ative a integração de IA da Agent Platform, crie objetos de banco de dados e importe dados.

Conceder as permissões necessárias ao AlloyDB

Adicione permissões da Gemini Enterprise Agent Platform ao agente de serviço do AlloyDB.

Abra outra guia do Cloud Shell pelo sinal "+" na parte superior.

Na nova guia do Cloud Shell, execute:

PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Saída esperada do console:

student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-11039]
student@cloudshell:~ (test-project-001-402417)$ gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
Updated IAM policy for project [test-project-001-402417].
bindings:
- members:
  - serviceAccount:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com
  role: roles/aiplatform.user
- members:
...
etag: BwYIEbe_Z3U=
version: 1

Feche a guia pelo comando de execução "sair" na guia:

exit

Criar banco de dados

Início rápido para criar um banco de dados.

Na sessão da VM do GCE, execute:

Crie o banco de dados:

psql "host=$INSTANCE_IP user=postgres" -c "CREATE DATABASE quickstart_db"

Saída esperada do console:

student@instance-1:~$ psql "host=$INSTANCE_IP user=postgres" -c "CREATE DATABASE quickstart_db"
CREATE DATABASE
student@instance-1:~$

Ativar a integração da Vertex AI

Ative a integração da Vertex AI e as extensões pgvector no banco de dados.

Na VM do GCE, execute:

psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE"
psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS vector"

Saída esperada do console:

student@instance-1:~$ psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE"
psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS vector"
CREATE EXTENSION
CREATE EXTENSION
student@instance-1:~$

Importar dados

Faça o download dos dados preparados e importe-os para o novo banco de dados.

Na VM do GCE, execute:

gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_demo_schema.sql |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_products.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_products from stdin csv header"
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_inventory.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_inventory from stdin csv header"
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_stores.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_stores from stdin csv header"

Saída esperada do console:

student@instance-1:~$ gsutil cat gs://cloud-training/gcc/gcc-tech-004/cymbal_demo_schema.sql |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"
SET
SET
SET
SET
SET
 set_config 
------------
 
(1 row)
SET
SET
SET
SET
SET
SET
CREATE TABLE
ALTER TABLE
CREATE TABLE
ALTER TABLE
CREATE TABLE
ALTER TABLE
CREATE TABLE
ALTER TABLE
CREATE SEQUENCE
ALTER TABLE
ALTER SEQUENCE
ALTER TABLE
ALTER TABLE
ALTER TABLE
student@instance-1:~$ gsutil cat gs://cloud-training/gcc/gcc-tech-004/cymbal_products.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_products from stdin csv header"
COPY 941
student@instance-1:~$ gsutil cat gs://cloud-training/gcc/gcc-tech-004/cymbal_inventory.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_inventory from stdin csv header"
COPY 263861
student@instance-1:~$ gsutil cat gs://cloud-training/gcc/gcc-tech-004/cymbal_stores.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_stores from stdin csv header"
COPY 4654
student@instance-1:~$

7. Calcular embeddings

Depois de importar os dados, você terá os dados de produtos na tabela "cymbal_products", o inventário mostrando o número de produtos disponíveis em cada loja na tabela "cymbal_inventory" e a lista das lojas na tabela "cymbal_stores". Você precisa calcular os dados vetoriais com base nas descrições dos produtos e pode usar funções como google_ml.embedding para isso. Leia mais sobre a tecnologia usada na documentação.

É fácil gerar embeddings para algumas linhas, mas como fazer isso de forma eficiente se tivermos milhares? Esta seção explica como gerar e gerenciar incorporações para tabelas grandes. Leia mais sobre diferentes opções e técnicas no guia.

Ativar a geração rápida de incorporações

Conecte-se ao banco de dados usando o psql da VM com o IP da instância do AlloyDB e a senha do postgres:

psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"

Verifique a versão da extensão google_ml_integration.

SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';

A versão precisa ser 1.5.2 ou mais recente. Confira um exemplo da saída:

quickstart_db=> SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
 extversion 
------------
 1.6
(1 row)

A versão padrão precisa ser 1.6 ou mais recente, mas se a instância mostrar uma versão mais antiga, provavelmente será necessário atualizar. Verifique se a manutenção foi desativada para a instância.

Verifique se a flag de banco de dados google_ml_integration.enable_faster_embedding_generation está ativada. Na mesma sessão do psql, verifique o valor da flag:

show google_ml_integration.enable_faster_embedding_generation;

Se a flag estiver na posição correta, a saída esperada será assim:

quickstart_db=> show google_ml_integration.enable_faster_embedding_generation;                          
 google_ml_integration.enable_faster_embedding_generation 
----------------------------------------------------------
 on
(1 row)

Se o valor da flag mostrar "off", atualize a instância. Faça isso usando o console da Web ou o comando gcloud, conforme descrito na documentação.

Saia da sessão psql:

exit;

Para atualizar a flag usando a gcloud, execute:

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags google_ml_integration.enable_faster_embedding_generation=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

Isso pode levar alguns minutos, mas o valor da flag será alterado para "on". Depois disso, siga para as próximas etapas.

Criar coluna de embedding

Conecte-se ao banco de dados usando psql e crie uma coluna virtual com o tipo de dados de vetor para ser usado pela função de incorporação na tabela "cymbal_products".

psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"

Na sessão psql, depois de se conectar ao banco de dados, execute:

ALTER TABLE cymbal_products ADD COLUMN embedding vector(768);

O comando cria uma coluna virtual para incorporações futuras.

Saída esperada do console:

quickstart_db=> ALTER TABLE cymbal_products ADD COLUMN embedding vector(768);
ALTER TABLE
quickstart_db=>

Gere embeddings em lotes de 50 linhas. Na mesma sessão psql, execute:

Ative a marcação de tempo para medir quanto tempo vai levar:

\timing

Execute o comando:

CALL ai.initialize_embeddings(
    model_id => 'text-embedding-005',
    table_name => 'cymbal_products',
    content_column => 'product_description',
    embedding_column => 'embedding',
    batch_size => 50
);

A saída do console mostrou menos de 2 segundos para a geração de incorporações:

quickstart_db=> CALL ai.initialize_embeddings(
    model_id => 'text-embedding-005',
    table_name => 'cymbal_products',
    content_column => 'product_description',
    embedding_column => 'embedding',
    batch_size => 50
);
NOTICE:  Initialize embedding completed successfully for table cymbal_products
CALL
Time: 1458.704 ms (00:01.459)
quickstart_db=>

Teste diferentes tamanhos de lote e veja se isso muda o tempo de execução.

Por padrão, as incorporações não são atualizadas se a coluna "product_description" correspondente estiver sendo atualizada ou se uma linha inteira for inserida. Mas você pode fazer isso definindo o parâmetro incremental_refresh_mode.

Crie uma coluna "product_embeddings" e faça com que ela seja atualizada automaticamente:

ALTER TABLE cymbal_products ADD COLUMN product_embedding vector(768);
CALL ai.initialize_embeddings(
    model_id => 'text-embedding-005',
    table_name => 'cymbal_products',
    content_column => 'product_description',
    embedding_column => 'product_embedding',
    batch_size => 50,
    incremental_refresh_mode => 'transactional'
);

Insira uma nova linha na tabela.

INSERT INTO "cymbal_products" ("uniq_id", "crawl_timestamp", "product_url", "product_name", "product_description", "list_price", "sale_price", "brand", "item_number", "gtin", "package_size", "category", "postal_code", "available", "product_embedding", "embedding") VALUES ('fd604542e04b470f9e6348e640cff794', NOW(), 'https://example.com/new_product', 'New Cymbal Product', 'This is a new cymbal product description.', 199.99, 149.99, 'Example Brand', 'EB123', '1234567890', 'Single', 'Cymbals', '12345', TRUE, NULL, NULL);

Consulte a tabela para comparar duas colunas de incorporação:

SELECT uniq_id,embedding, (product_embedding::real[])[1:5] as product_embedding  FROM cymbal_products WHERE uniq_id='fd604542e04b470f9e6348e640cff794';

A saída mostra que product_embedding é preenchido automaticamente, enquanto embedding permanece vazio:

quickstart_db=> SELECT uniq_id,embedding, (product_embedding::real[])[1:5] as product_embedding  FROM cymbal_products WHERE uniq_id='fd604542e04b470f9e6348e640cff794';
             uniq_id              | embedding |                       product_embedding                       
----------------------------------+-----------+---------------------------------------------------------------
 fd604542e04b470f9e6348e640cff794 |           | {0.015003494,-0.005349732,-0.059790313,-0.0087091,-0.0271452}
(1 row)

Time: 3.295 ms

8. Executar pesquisa de similaridade

Faça uma pesquisa de similaridade com base nos embeddings de vetor gerados usando a IA do AlloyDB.

A consulta SQL pode ser executada na mesma interface de linha de comando psql ou, como alternativa, no AlloyDB Studio. Qualquer saída complexa e de várias linhas funciona melhor no AlloyDB Studio.

Conectar-se ao AlloyDB Studio

Para abrir o AlloyDB Studio, siga estas etapas:

No console do Google Cloud, acesse a página "Clusters" do AlloyDB para PostgreSQL.
Selecione a instância principal para abrir a interface da Web.

3. Em seguida, clique em "AlloyDB Studio" à esquerda:

Selecione o banco de dados quickstart_db, o usuário postgres, forneça a senha observada e clique em "Autenticar".

Essa ação abre a interface do AlloyDB Studio.

Selecione a guia "Consulta sem título" para abrir o editor de SQL.

Isso abre um editor em que é possível executar comandos SQL, conforme mostrado na imagem a seguir:

Se você preferir usar o psql da linha de comando, siga a rota alternativa e conecte-se ao banco de dados na sessão SSH da VM, conforme descrito nos capítulos anteriores.

Executar pesquisa de similaridade

Execute uma consulta para receber uma lista de produtos disponíveis mais relacionados ao pedido de um cliente. A frase de pesquisa transmitida ao modelo de incorporação na Gemini Enterprise Agent Platform (a mesma que usamos para gerar incorporações para nossos produtos) para receber o valor do vetor de "Que tipo de árvores frutíferas crescem bem aqui?"

Execute a consulta:

SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        (cp.embedding <=> embedding('text-embedding-005','What kind of fruit trees grow well here?')::vector) as distance
FROM
        cymbal_products cp
JOIN cymbal_inventory ci on
        ci.uniq_id=cp.uniq_id
JOIN cymbal_stores cs on
        cs.store_id=ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
        distance ASC
LIMIT 10;

Esta é a saída esperada:

quickstart_db=> SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        (cp.embedding <=> embedding('text-embedding-005','What kind of fruit trees grow well here?')::vector) as distance
FROM
        cymbal_products cp
JOIN cymbal_inventory ci on
        ci.uniq_id=cp.uniq_id
JOIN cymbal_stores cs on
        cs.store_id=ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
        distance ASC
LIMIT 10;
      product_name       |                                   description                                    | sale_price | zip_code |      distance       
-------------------------+----------------------------------------------------------------------------------+------------+----------+---------------------
 Cherry Tree             | This is a beautiful cherry tree that will produce delicious cherries. It is an d |      75.00 |    93230 | 0.43922018972266397
 Meyer Lemon Tree        | Meyer Lemon trees are California's favorite lemon tree! Grow your own lemons by  |         34 |    93230 |  0.4685112926118228
 Toyon                   | This is a beautiful toyon tree that can grow to be over 20 feet tall. It is an e |      10.00 |    93230 |  0.4835677149651668
 California Lilac        | This is a beautiful lilac tree that can grow to be over 10 feet tall. It is an d |       5.00 |    93230 |  0.4947204525907498
 California Peppertree   | This is a beautiful peppertree that can grow to be over 30 feet tall. It is an e |      25.00 |    93230 |  0.5054166905547247
 California Black Walnut | This is a beautiful walnut tree that can grow to be over 80 feet tall. It is a d |     100.00 |    93230 |  0.5084219510932597
 California Sycamore     | This is a beautiful sycamore tree that can grow to be over 100 feet tall. It is  |     300.00 |    93230 |  0.5140519790508755
 Coast Live Oak          | This is a beautiful oak tree that can grow to be over 100 feet tall. It is an ev |     500.00 |    93230 |  0.5143126438081371
 Fremont Cottonwood      | This is a beautiful cottonwood tree that can grow to be over 100 feet tall. It i |     200.00 |    93230 |  0.5174774727252058
 Madrone                 | This is a beautiful madrona tree that can grow to be over 80 feet tall. It is an |      50.00 |    93230 |  0.5227400803389093

Você recebe 10 produtos com descrições semanticamente próximas à frase de pesquisa, ordenados pela distância, com o mais semelhante na parte superior.

9. Melhorar resposta

Você pode melhorar a resposta a um aplicativo cliente usando o resultado da consulta e preparar uma saída significativa usando os resultados da consulta fornecidos como parte do comando para um modelo de linguagem generativa de base.

Para isso, gere um JSON com os principais resultados da pesquisa vetorial e use esse JSON gerado como complemento de um comando para um modelo de IA generativa na Agent Platform para criar uma saída significativa. A primeira etapa gera o JSON, que é testado no Agent Platform Studio. A última etapa incorpora tudo em uma instrução SQL que pode ser usada em um aplicativo.

Gerar saída no formato JSON

Modifique a consulta para gerar a saída no formato JSON e retorne apenas uma linha para transmitir à Agent Platform.

Execute a consulta:

WITH trees as (
SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        cp.uniq_id as product_id
FROM
        cymbal_products cp
JOIN cymbal_inventory ci on
        ci.uniq_id=cp.uniq_id
JOIN cymbal_stores cs on
        cs.store_id=ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
        (cp.embedding <=> embedding('text-embedding-005','What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1)
SELECT json_agg(trees) FROM trees;

O JSON na saída:

[{"product_name":"Cherry Tree","description":"This is a beautiful cherry tree that will produce delicious cherries. It is an d","sale_price":75.00,"zip_code":93230,"product_id":"d536e9e823296a2eba198e52dd23e712"}]

Executar o comando no Vertex AI Studio

Use o JSON gerado como parte do comando para o modelo de IA generativa no Vertex AI Studio.

Abra o Gemini Enterprise Agent Platform Studio no console do Google Cloud.

Escreva seu comando na interface:

Insira o seguinte comando:

You are a friendly advisor helping to find a product based on the customer's needs.

Based on the client request we have loaded a list of products closely related to search.

The list in JSON format with list of values like {"product_name":"name","description":"some description","sale_price":10,"zip_code": 10234, "produt_id": "02056727942aeb714dc9a2313654e1b0"}

Here is the list of products:

{"product_name":"Cherry Tree","description":"This is a beautiful cherry tree that will produce delicious cherries. It is an d","sale_price":75.00,"zip_code":93230,"product_id":"d536e9e823296a2eba198e52dd23e712"}

The customer asked "What tree is growing the best here?"

You should give information about the product, price and some supplemental information

Este é o resultado quando executamos o comando :

A resposta inclui preço, descrição e informações complementares que o modelo recebe de fontes externas com base em informações sobre a árvore e o local.

Executar o comando no PSQL

O mesmo resultado pode ser alcançado executando "Use a integração da IA do AlloyDB com a Gemini Enterprise Agent Platform para receber a mesma resposta de um modelo generativo usando SQL diretamente no banco de dados". Antes de usar o modelo gemini-3.6-flash, é preciso registrá-lo.

Registre o modelo gemini-3.6-flash:

No AlloyDB Studio, execute:

CALL google_ml.create_model(
model_id => 'gemini-3.6-flash',
model_request_url => 'https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.6-flash:generateContent',
model_provider => 'google',
model_type => 'llm'
);

Você pode verificar a lista de modelos registrados selecionando informações de google_ml.model_info_view.

SELECT model_id,model_type FROM google_ml.model_info_view WHERE model_id ILIKE '%flash%';

Confira um exemplo de saída

quickstart_db=> SELECT model_id,model_type FROM google_ml.model_info_view WHERE model_id ILIKE '%flash%';
       model_id        | model_type 
-----------------------+------------
 gemini-3.6-flash      | llm
 gemini-2.0-flash      | llm
 gemini-2.5-flash      | llm
 gemini-2.0-flash-lite | llm
 gemini-2.5-flash-lite | llm
(5 rows)

Agora você pode usar o JSON gerado em uma subconsulta como parte do comando para o modelo gemini-3.6-flash usando SQL.

Na sessão do psql ou do AlloyDB Studio, execute a seguinte consulta:

WITH trees AS (
SELECT
        cp.product_name,
        cp.product_description AS description,
        cp.sale_price,
        cs.zip_code,
        cp.uniq_id AS product_id
FROM
        cymbal_products cp
JOIN cymbal_inventory ci ON
        ci.uniq_id = cp.uniq_id
JOIN cymbal_stores cs ON
        cs.store_id = ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
        (cp.embedding <=> embedding('text-embedding-005',
        'What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1),
prompt AS (
SELECT
        'You are a friendly advisor helping to find a product based on the customer''s needs.
Based on the client request we have loaded a list of products closely related to search.
The list in JSON format with list of values like {"product_name":"name","product_description":"some description","sale_price":10}
Here is the list of products:' || json_agg(trees) || 'The customer asked "What kind of fruit trees grow well here?"
You should give information about the product, price and some supplemental information' AS prompt_text
FROM
        trees),
response AS (
SELECT
        google_ml.predict_row( model_id =>'gemini-3.6-flash',
        request_body => json_build_object('contents',
        json_build_object('role',
        'user',
        'parts',
        json_build_object('text',
        prompt_text))))->'candidates'->0->'content'->'parts'->0->'text' AS resp
FROM
        prompt)
SELECT
REPLACE(resp::text, '\n', CHR(10))
FROM
        response;

Esta é a saída esperada. A saída pode ser diferente devido à natureza não determinística dos modelos de IA generativa:

"Hello there! I'd be delighted to help you pick out a wonderful fruit tree for your space. Based on our local selection, a fantastic option that grows very well is the **Cherry Tree**! Here are the details on this beautiful tree: * **Product:** Cherry Tree * **Price:** $75.00 ### Why it's a great choice: * **Delicious Harvest:** It produces tasty, fresh cherries right in your backyard. * **Size & Benefits:** It's a deciduous tree that grows to about 15 feet tall, making it ideal for providing both lovely shade and a bit of privacy. * **Year-Round Beauty:** It features lush, dark green leaves throughout the summer that transform into a stunning red in the autumn. * **Growing Requirements:** Cherry trees thrive best in cool, moist climates with sandy soil, and are perfectly suited for USDA hardiness zones 4 through 9. Please let me know if you have any questions about planting or if you'd like help adding this to your order!"

10. Criar índice vetorial

Como esse conjunto de dados é pequeno, os tempos de resposta dependem principalmente das interações com os modelos na Gemini Enterprise Agent Platform. No entanto, quando você consulta milhões de vetores, a pesquisa vetorial pode consumir uma parte significativa do tempo de resposta e aumentar a carga no banco de dados. Para melhorar o desempenho da pesquisa, crie um índice de vetor.

Criar índice do ScaNN

Para criar um índice ScaNN, é necessário ativar uma extensão adicional. A extensão alloydb_scann fornece uma interface para trabalhar com índices vetoriais de vizinho mais próximo aproximado (ANN) usando o algoritmo ScaNN do Google.

Executar no AlloyDB Studio:

CREATE EXTENSION IF NOT EXISTS alloydb_scann;

O índice pode ser criado no modo MANUAL ou AUTO. O modo MANUAL é ativado por padrão, e você pode criar e manter um índice como qualquer outro. Mas se você ativar o modo AUTO, poderá criar o índice sem precisar fazer nenhuma manutenção. Leia em detalhes sobre todas as opções na documentação. Não temos linhas suficientes para criar o índice no modo AUTO. Por isso, você vai criá-lo como MANUAL.

Execute no AlloyDB Studio:

CREATE INDEX cymbal_products_embeddings_scann ON cymbal_products
  USING scann (embedding cosine)
  WITH (num_leaves=10, max_num_levels = 1);

Leia sobre o ajuste de parâmetros de índice na documentação.

Saída esperada:

quickstart_db=> CREATE INDEX cymbal_products_embeddings_scann ON cymbal_products
  USING scann (embedding cosine)
  WITH (num_leaves=10, max_num_levels = 1);
CREATE INDEX
quickstart_db=>

Comparar resposta

Repita a consulta que usamos para receber o valor máximo na pesquisa semântica:

WITH trees as (
SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        cp.uniq_id as product_id
FROM
        cymbal_products cp
JOIN cymbal_inventory ci on
        ci.uniq_id=cp.uniq_id
JOIN cymbal_stores cs on
        cs.store_id=ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
        (cp.embedding <=> embedding('text-embedding-005','What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1)
SELECT json_agg(trees) FROM trees;

Saída esperada:

[{"product_name":"Cherry Tree","description":"This is a beautiful cherry tree that will produce delicious cherries. It is an d","sale_price":75.00,"zip_code":93230,"product_id":"d536e9e823296a2eba198e52dd23e712"}]

A mesma "Cherry Tree" na saída.

Verifique o uso do índice:

EXPLAIN (analyze) 
WITH trees as (
SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        cp.uniq_id as product_id
FROM
        cymbal_products cp
JOIN cymbal_inventory ci on
        ci.uniq_id=cp.uniq_id
JOIN cymbal_stores cs on
        cs.store_id=ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
        (cp.embedding <=> embedding('text-embedding-005','What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1)
SELECT json_agg(trees) FROM trees;

Saída esperada (editada para fins de esclarecimento):

...
 Aggregate  (cost=27.24..27.25 rows=1 width=32) (actual time=0.964..0.965 rows=1 loops=1)
   ->  Subquery Scan on trees  (cost=18.91..27.23 rows=1 width=142) (actual time=0.953..0.954 rows=1 loops=1)
         ->  Limit  (cost=18.91..27.22 rows=1 width=158) (actual time=0.948..0.949 rows=1 loops=1)
               ->  Nested Loop  (cost=18.91..7126.86 rows=855 width=158) (actual time=0.948..0.948 rows=1 loops=1)
                     ->  Nested Loop  (cost=18.63..7103.59 rows=855 width=907) (actual time=0.931..0.931 rows=1 loops=1)
                           ->  Index Scan using cymbal_products_embeddings_scann on cymbal_products cp  (cost=18.21..343.15 rows=942 width=903) (actual time=0.906..0.908 rows=2 loops=1)
                                 Order By: (embedding <=> '[-0.106554024,0.035774965,-0.027267234,-0.045653425,-0.03286045,0.02124319...

Na saída, é possível ver que a consulta estava usando "Index Scan using cymbal_products_embeddings_scann on cymbal_products".

A consulta retorna a mesma cerejeira que apareceu na parte de cima dos resultados da pesquisa antes da criação do índice. Como os índices de vizinho mais próximo aproximado (ANN) trocam a acurácia absoluta pela velocidade de pesquisa, as consultas baseadas em índice podem retornar ocasionalmente resultados principais ligeiramente diferentes de uma pesquisa exata sem indexação. No entanto, o índice vetorial oferece um aumento significativo no desempenho, mantendo alta precisão.

Para saber mais, teste outros tipos de índice de vetor ou encontre mais laboratórios e exemplos com integração do LangChain na página de documentação.

11. Limpar o ambiente

Destrua as instâncias e o cluster do AlloyDB quando terminar o laboratório.

Excluir o cluster do AlloyDB e todas as instâncias

O cluster é destruído com a opção force, que também exclui todas as instâncias pertencentes a ele.

Se o terminal foi desconectado, conecte-se novamente e defina as variáveis de projeto e ambiente no Cloud Shell:

gcloud config set project <YOUR_PROJECT_ID>

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export PROJECT_ID=$(gcloud config get-value project)

Exclua o cluster:

gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force

Saída esperada do console:

student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
All of the cluster data will be lost when the cluster is deleted.

Do you want to continue (Y/n)?  Y

Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f
Deleting cluster...done.

Excluir backups do AlloyDB

Exclua todos os backups do AlloyDB do cluster:

for i in $(gcloud alloydb backups list \
  --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" \
  --format="value(name)" \
  --sort-by=~createTime) ; do \
  gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done

Saída esperada do console:

student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f
Deleting backup...done.

Agora você pode destruir a VM.

Excluir a VM do GCE

No Cloud Shell, execute:

export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet

Saída esperada do console:

student@cloudshell:~ (test-project-001-402417)$ export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet
Deleted

12. Parabéns

Parabéns por concluir o codelab.

Este laboratório faz parte do programa de aprendizado "IA pronta para produção com o Google Cloud".

Confira o currículo completo para diminuir a distância entre o protótipo e a produção.
Compartilhe seu progresso com a hashtag #ProductionReadyAI.

O que vimos

Como implantar um cluster e uma instância principal do AlloyDB
Como se conectar ao AlloyDB de uma VM do Google Compute Engine
Como criar um banco de dados e ativar a IA do AlloyDB
Como carregar dados no banco de dados
Como usar o AlloyDB Studio
Como usar o modelo de incorporação da Gemini Enterprise Agent Platform no AlloyDB
Como usar o Gemini Enterprise Agent Platform Studio
Como enriquecer o resultado usando o modelo generativo da Gemini Enterprise Agent Platform
Como melhorar a performance usando o índice de vetor

13. Pesquisa

Saída:

Como você usará este tutorial?

Apenas leitura

Leitura e exercícios