Introdução à pesquisa híbrida no AlloyDB e no Apache Solr

1. Introdução

Neste codelab, você vai aprender a realizar uma pesquisa híbrida no AlloyDB usando pgvector e um índice escalonável de vizinho mais próximo (ScaNN), combinado com a capacidade de pesquisa de texto completo do Apache Solr por um Foreign Data Wrapper (FDW). 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.

O Apache Solr é uma plataforma de pesquisa corporativa de código aberto criada no Apache Lucene, projetada para recursos de pesquisa de texto completo rápidos, escalonáveis e altamente disponíveis. A integração do Solr com o AlloyDB usando um Foreign Data Wrapper (FDW) permite que os usuários consultem índices do Solr diretamente do PostgreSQL, além de tabelas de banco de dados estruturadas. Para saber mais, acesse a documentação do Apache Solr.

Pré-requisitos

• Conhecimentos básicos sobre o Google Cloud e o console
• Habilidades básicas na interface de linha de comando e no Google 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
• Gerar embeddings com a Vertex AI
• Como criar um índice vetorial do ScaNN para melhorar a pesquisa vetorial
• Como criar um Foreign Data Wrapper (FDW) para o Apache Solr
• Realize uma pesquisa híbrida combinando a pesquisa semântica no AlloyDB com a pesquisa de texto completo no Solr.

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.

1. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto na nuvem do Google Cloud.
2. Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

Atenção: o ID do projeto é globalmente exclusivo e não pode ser usado por outras pessoas após a seleção. Você é o único usuário com esse ID. Mesmo que um projeto seja excluído, o ID não poderá ser usado novamente.

Observação: se você usa uma conta do Gmail, defina o local padrão como Sem organização. Se você usa uma conta do Google Workspace, escolha um local adequado para a organização.

Ativar faturamento

Para ativar o faturamento, você tem duas opções. Você pode usar sua conta de faturamento pessoal ou resgatar créditos seguindo estas etapas.

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 e ative 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 possa ser operado remotamente em seu laptop, neste codelab vamos usar o Google Cloud Shell, um ambiente de linha de comando executado no Cloud.

O Cloud Shell é um ambiente de linha de comando executado no Google Cloud que vem pré-carregado com as ferramentas necessárias.

1. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.
2. Depois de se conectar ao Cloud Shell, verifique sua autenticação:

   gcloud auth list
   

3. Confirme se o projeto está configurado:

   gcloud config get project
   

4. Se o projeto não estiver definido como esperado, faça o seguinte:

   export PROJECT_ID=<YOUR_PROJECT_ID>
   gcloud config set project $PROJECT_ID
   

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:

Alguns recursos ativados vão ter custos. Em circunstâncias normais, se o cluster do AlloyDB e a VM de computação forem destruídos após a conclusão do laboratório, o custo de todos os recursos não vai exceder US $3. É recomendável conferir o faturamento e confirmar se o exercício é adequado para você.

Para usar o AlloyDB, o Compute Engine, os serviços de rede e a Vertex AI, é necessário ativar as APIs respectivas 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 \
                       secretmanager.googleapis.com

Resultado esperado

student@cloudshell:~ (alloydb-hybrid-search)$ gcloud config set project alloydb-hybrid-search
[environment: untagged] Read more to tag: g.co/cloud/project-env-tag.
Updated property [core/project].
student@cloudshell:~ (alloydb-hybrid-search)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-32544]
student@cloudshell:~ (alloydb-hybrid-search)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com \
                       secretmanager.googleapis.com
Operation "operations/acat.p2-350113473377-5ffc2f22-caa9-4857-b2f4-018657d8bf6e" finished successfully.

Apresentação das APIs

• A API AlloyDB (alloydb.googleapis.com) permite criar, gerenciar e escalonar clusters do AlloyDB para PostgreSQL. Ele oferece um serviço de banco de dados totalmente gerenciado e compatível com PostgreSQL, projetado para cargas de trabalho empresariais transacionais e analíticas exigentes.
• A API Compute Engine (compute.googleapis.com) permite criar e gerenciar máquinas virtuais (VMs), discos permanentes e configurações de rede. Ele fornece a base principal de infraestrutura como serviço (IaaS) necessária para executar suas cargas de trabalho e hospedar a infraestrutura subjacente de muitos serviços gerenciados.
• A API Cloud Resource Manager (cloudresourcemanager.googleapis.com) permite gerenciar de forma programática os metadados e a configuração do seu projeto do Google Cloud. Ele permite organizar recursos, processar políticas de gerenciamento de identidade e acesso (IAM) e validar permissões em toda a hierarquia do projeto.
• A API Service Networking (servicenetworking.googleapis.com) permite automatizar a configuração da conectividade particular entre sua rede de nuvem privada virtual (VPC) e os serviços gerenciados do Google. Ele é especificamente necessário para estabelecer o acesso a IP particular para serviços como o AlloyDB, para que eles possam se comunicar com segurança com seus outros recursos.
• A API Vertex AI (aiplatform.googleapis.com) permite que seus aplicativos criem, implantem e escalonem modelos de machine learning. Ela oferece a interface unificada para todos os serviços de IA do Google Cloud, incluindo acesso a modelos de IA generativa (como o Gemini) e treinamento de modelos personalizados.
• A API Secret Manager (secretmanager.googleapis.com) é um serviço de gerenciamento de secrets e credenciais que permite armazenar e gerenciar dados sensíveis, como chaves de API, nomes de usuário, senhas, certificados e muito mais.

Opcionalmente, configure a região padrão para usar os modelos de embedding da Vertex AI. Leia mais sobre os locais disponíveis para a Vertex AI. No exemplo, usamos a região "us-central1".

gcloud config set compute/region us-central1

4. Implantar o AlloyDB

Antes de criar um cluster do AlloyDB, é necessário ter um intervalo de IP privado disponível na VPC para ser usado pela instância futura do AlloyDB. Se não tivermos, precisamos criar e atribuir para uso por serviços internos do Google. Depois disso, será possível criar o cluster e a instância.

Criar um intervalo de IP privado

Observação:essa etapa é necessária apenas se você ainda não tiver um intervalo de IP particular não utilizado atribuído para trabalhar com serviços internos do Google.

É 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

Depois de conectadas, atualize o peering para exportar rotas personalizadas:

gcloud compute networks peerings update servicenetworking-googleapis-com \
    --network=default \
    --export-custom-routes

Observação:a execução dos comandos de peering pode levar alguns minutos.

Saída esperada do console:

student@cloudshell:~ (alloydb-hybrid-search)$ 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/alloydb-hybrid-search/global/addresses/psa-range].

student@cloudshell:~ (alloydb-hybrid-search)$ gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default
Operation "operations/pssn.p24-350113473377-fadad49e-7e14-472a-8888-26951e40a1f7" finished successfully.

student@cloudshell:~ (alloydb-hybrid-search)$ gcloud compute networks peerings update servicenetworking-googleapis-com \
    --network=default \
    --export-custom-routes
Updated [https://www.googleapis.com/compute/v1/projects/alloydb-hybrid-search/global/networks/default].

Criar cluster do AlloyDB

Nesta seção, vamos 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 12`

Saída esperada do console:

student@cloudshell:~ (alloydb-hybrid-search)$ 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. Recomendamos que você copie e guarde em um local seguro, como um gerenciador de senhas.

Saída esperada do console:

student@cloudshell:~ (alloydb-hybrid-search)$ echo $PGPASSWORD
<generated password>

Criar cluster do AlloyDB

Defina a região e o nome do cluster do AlloyDB. Vamos usar a região us-central1 e alloydb-hybrid-search como nome do cluster:

export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search

Observação:se você não estiver usando o AlloyDB, crie um cluster de teste sem custo financeiro executando o comando de criação de cluster abaixo com a seguinte flag: --subscription-type=TRIAL

Execute o comando para criar o cluster:

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

Saída esperada do console:

student@cloudshell:~ (alloydb-hybrid-search)$ export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
student@cloudshell:~ (alloydb-hybrid-search)$ gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION \
    --database-version=POSTGRES_17
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.

Observação:a criação da instância geralmente leva de 6 a 10 minutos para ser concluída.

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

Saída esperada do console:

admin_@cloudshell:~ (my-project-93954-gke)$ gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --availability-type ZONAL \
    --cluster=$ADBCLUSTER
Operation ID: operation-1784244706986-656c2d7f3c8f2-59a9e52a-1e7b1b01
Creating instance...done.                                                                                                                                                                                                                                                     

5. Conectar-se ao AlloyDB

O AlloyDB é implantado usando uma conexão somente privada. Por isso, precisamos de uma VM com o cliente do PostgreSQL instalado para trabalhar com o banco de dados. Também vamos usar essa VM para executar uma instância do Apache Solr.

Implantar a VM do GCE

Crie uma VM do GCE na mesma região e VPC que o cluster do AlloyDB. Verifique se o disco de inicialização é grande o suficiente para executar o Solr. Aqui, especificamos um disco de inicialização de 20 GB na flag --create-disk.

No Cloud Shell, execute:

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

Saída esperada do console:

student@cloudshell:~ (alloydb-hybrid-search)$ export ZONE=us-central1-a
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --network=default \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-12 AND family!=debian-12-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: X.X.X.X
EXTERNAL_IP: X.X.X.X
STATUS: RUNNING

Instalar o cliente Postgres

Instale o software do cliente PostgreSQL na VM implantada.

Conecte-se à VM:

Observação: a primeira conexão SSH com a VM pode levar mais tempo, porque o processo inclui a criação da Chave RSA para conexão segura e a propagação da parte pública da chave para o projeto.

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

Saída esperada do console:

admin_@cloudshell:~ (my-project-93954-gke)$ gcloud compute ssh instance-1 --zone=us-central1-a
Updating project ssh metadata...working..Updated [https://www.googleapis.com/compute/v1/projects/alloydb-hybrid-search].                                                                                                                                                         
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.us-central1-a.c.gleb-test-short-001-418811.internal 6.1.0-18-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.76-1 (2024-02-01) 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.

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 https://packages.cloud.google.com/apt google-compute-engine-bullseye-stable InRelease [5146 B]
Get:2 https://packages.cloud.google.com/apt cloud-sdk-bullseye InRelease [6406 B]   
Hit:3 https://deb.debian.org/debian bullseye InRelease  
Get:4 https://deb.debian.org/debian-security bullseye-security InRelease [48.4 kB]
Get:5 https://packages.cloud.google.com/apt google-compute-engine-bullseye-stable/main amd64 Packages [1930 B]
Get:6 https://deb.debian.org/debian bullseye-updates InRelease [44.1 kB]
Get:7 https://deb.debian.org/debian bullseye-backports InRelease [49.0 kB]
...redacted...
Setting up postgresql-client (15+248+deb12u1) ...
Processing triggers for man-db (2.11.2-2) ...
Processing triggers for libc-bin (2.36-9+deb12u14) ...

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>

Observação:sua VM pode não ter as permissões necessárias para visualizar instâncias do AlloyDB. Conceda à conta de serviço padrão roles/alloydb.viewer

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
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 PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
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 (15.18 (Debian 15.18-0+deb12u1), server 17.9)
WARNING: psql major version 15, server major version 17.
         Some psql features might not work.
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

postgres=> 

Feche a sessão psql:

exit

6. Preparar banco de dados

Precisamos criar um banco de dados, ativar a integração da Vertex AI, criar objetos de banco de dados e importar os dados.

Conceder as permissões necessárias ao AlloyDB

Adicione permissões da Vertex AI 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:

admin_@cloudshell:~ (my-project-93954-gke)$ 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"
Your active configuration is: [cloudshell-30137]

Updated IAM policy for project [my-project-93954-gke].
bindings:
- members:
<redacted>
version: 1

Feche a guia clicando em "X" ou executando o comando:

exit

Criar banco de dados

Crie um banco de dados chamado quickstart.

Na sessão da VM do GCE, execute:

Observação: se a sessão SSH tiver sido encerrada, você precisará redefinir as variáveis de ambiente, como as seguintes:

export PGPASSWORD=<Noted password>

export PROJECT_ID=$(gcloud config get-value project)

export REGION=us-central1

export ADBCLUSTER=alloydb-hybrid-search

export INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")

Criar 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

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"
NOTICE:  extension "google_ml_integration" already exists, skipping
CREATE EXTENSION
CREATE EXTENSION

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:~$ 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"
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
COPY 941
COPY 263861
COPY 4654

Em seguida, vamos definir as flags de banco de dados necessárias. É possível usar o console da Web e gerenciar flags na instância principal ou usar o comando gcloud da seguinte maneira:

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags google_ml_integration.enable_faster_embedding_generation=on,scann.enable_preview_features=on,google_ml_integration.enable_preview_ai_functions=on,google_ml_integration.enable_ai_query_engine=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

Saída esperada do console

student@cloudshell:~ (alloydb-hybrid-search)$ export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags google_ml_integration.enable_faster_embedding_generation=on,scann.enable_preview_features=on,google_ml_integration.enable_preview_ai_functions=on,google_ml_integration.enable_ai_query_engine=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY
Your active configuration is: [cloudshell-30137]
Operation ID: operation-1784245853151-656c31c44e12b-6084eb8b-d6611419

A ativação das flags do banco de dados exige uma reinicialização da instância e leva alguns minutos. Quando concluído, o status da instância do AlloyDB será "Pronto".

7. Gerar embeddings de vetor

Depois de importar os dados, temos as seguintes tabelas: cymbal_products, que armazena informações sobre produtos, cymbal_inventory, que rastreia o estoque de itens em cada loja, e cymbal_stores, que é uma lista de lojas. Para realizar a pesquisa semântica nos nossos produtos, precisamos gerar embeddings de vetores das descrições de produtos com a função initialize_embeddings. Vamos usar a integração da Vertex AI para calcular dados de vetor com base nas descrições dos produtos e adicioná-los à tabela. Leia mais sobre a tecnologia usada na documentação.

Para usar a integração, conecte-se ao banco de dados com o AlloyDB Studio ou usando psql na sua 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.5.9
(1 row)

A versão padrão precisa ser 1.5.2 ou mais recente, mas se a instância mostrar uma versão mais antiga, ela provavelmente precisará ser atualizada. Verifique se a manutenção foi desativada para a instância.

Observação:a versão da extensão é gerenciada automaticamente no back-end. Você pode tentar atualizar a extensão executando o comando na sua sessão psql, como:

ALTER EXTENSION google_ml_integration UPDATE;

Se isso falhar, chame também um procedimento que ativa a versão de prévia do pacote (não use versões de prévia em produção).

CALL google_ml.upgrade_to_preview_version();

Instale a extensão de vetor e crie uma coluna para armazenar embeddings em cymbal_products

CREATE EXTENSION IF NOT EXISTS vector;
ALTER TABLE cymbal_products ADD COLUMN product_embedding vector(768);

Saída esperada do console:

quickstart_db=> CREATE EXTENSION IF NOT EXISTS vector;
ALTER TABLE cymbal_products ADD COLUMN product_embedding vector(768);
NOTICE:  extension "vector" already exists, skipping
CREATE EXTENSION
ALTER TABLE

Vamos usar a geração de embeddings em lote para melhorar a eficiência. Leia mais sobre as diferentes opções e técnicas de geração de incorporações no guia. Já ativamos a flag google_ml_integration.enable_faster_embedding_generation, que permite gerar incorporações em lote.

Por fim, também queremos que os embeddings sejam atualizados à medida que os valores das colunas são alterados. Para isso, incluímos o argumento incremental_refresh_mode na chamada de função. Isso introduz uma sobrecarga no nosso banco de dados, mas é uma troca que fazemos para manter automaticamente os embeddings sincronizados com o conteúdo. Se você quiser atualizar manualmente os embeddings, consulte as instruções na documentação.

Agora, juntando tudo e gerando embeddings, usamos a função initialize_embeddings e transmitimos batch_size de 50 como a dica de lote e definimos incremental_refresh_mode como transactional.

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'
);

Agora, se inserirmos uma nova linha na tabela com o valor NULL para a coluna product_embedding

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

Agora, quando consultarmos a linha que acabamos de inserir, vamos ver que a coluna product_embedding é atualizada automaticamente.

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

A saída será semelhante a esta:

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

8. Criar um índice vetorial

Para melhorar o desempenho da pesquisa vetorial, vamos adicionar um índice ScaNN.

Criar índice do ScaNN

Para criar o índice SCANN, precisamos ativar mais uma extensão. A extensão alloydb_scann oferece uma interface para trabalhar com o índice vetorial do tipo ANN usando o algoritmo ScaNN do Google.

CREATE EXTENSION IF NOT EXISTS alloydb_scann;

Saída esperada:

quickstart_db=> CREATE EXTENSION IF NOT EXISTS alloydb_scann;
CREATE EXTENSION

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 de manutenção. Leia em detalhes sobre todas as opções na documentação. No nosso caso, não temos linhas suficientes para criar o índice no modo AUTO. Por isso, vamos criá-lo como MANUAL e incluir parâmetros de ajuste. Leia sobre o ajuste de parâmetros de índice na documentação.

CREATE INDEX cymbal_products_embeddings_scann ON cymbal_products
  USING scann (product_embedding cosine)
  WITH (mode='MANUAL', num_leaves=31, max_num_levels = 2);

Saída esperada:

quickstart_db=> CREATE INDEX cymbal_products_embeddings_scann ON cymbal_products
  USING scann (product_embedding cosine)
  WITH (num_leaves=31, max_num_levels = 2);
CREATE INDEX
quickstart_db=>

Inspecionar o uso do índice

Agora podemos executar a consulta de pesquisa vetorial no modo EXPLAIN e verificar se o índice está sendo usado.

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.product_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=16.59..16.60 rows=1 width=32) (actual time=2.875..2.877 rows=1 loops=1)
-> Subquery Scan on trees (cost=8.42..16.59 rows=1 width=142) (actual time=2.860..2.862 rows=1 loops=1)
-> Limit (cost=8.42..16.58 rows=1 width=158) (actual time=2.855..2.856 rows=1 loops=1)
-> Nested Loop (cost=8.42..6489.19 rows=794 width=158) (actual time=2.854..2.855 rows=1 loops=1)
-> Nested Loop (cost=8.13..6466.99 rows=794 width=938) (actual time=2.742..2.743 rows=1 loops=1)
-> Index Scan using cymbal_products_embeddings_scann on cymbal_products cp (cost=7.71..111.99 rows=876 width=934) (actual time=2.724..2.724 rows=1 loops=1)
Order By: (embedding <=> '[0.008864171,0.03693164,-0.024245683,-0.00355923,0.0055611245,0.015985578,...<redacted>...5685,-0.03914233,-0.018452475,0.00826032,-0.07372604]'::vector)
...

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

9. Como criar uma instância do Solr

Vamos usar o Apache Solr para a parte de pesquisa de texto completo (FTS, na sigla em inglês) da pesquisa híbrida. Nesta etapa, você vai implantar uma instância independente do Solr na VM criada anteriormente.

Para proteger o acesso ao Solr, vamos ativar a autenticação básica. Para isso, vamos fornecer um arquivo de configuração security.json, fazer a montagem e iniciar o contêiner do Docker do Solr.

Conecte-se por SSH à VM e instale o Docker:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Agora você pode modificar o comando do Docker para ser executado pelo seu usuário:

sudo usermod -aG docker $USER
newgrp docker

Agora, crie o arquivo security.json para ativar a autenticação básica com o nome de usuário solr e a senha SolrRocks.

nano security.json

Cole o seguinte JSON no arquivo:

{
  "authentication": {
    "blockUnknown": true,
    "class": "solr.BasicAuthPlugin",
    "credentials": {
      "solr": "IV0EHq1OnNrj6gvRCwvFwTrZ1+z1oBbnQdiVC3otuq0= Ndd7LKvVBAaZIF0QAVi1ekCfAJXr1GGfLtRUXhgrF8c="
    }
  },
  "authorization": {
    "class": "solr.RuleBasedAuthorizationPlugin",
    "permissions": [
      { "name": "security-edit", "role": "admin" }
    ],
    "user-role": { "solr": "admin" }
  }
}

Salve e saia do nano (Ctrl + O, Enter, Ctrl + X).

Inicie o contêiner do Docker do Solr usando docker run e ative o arquivo security.json no contêiner:

docker run -d -p 8983:8983 --name solr --user root -v "$(pwd)/security.json:/var/solr/data/security.json" solr:9 -c -force

Verifique se o contêiner está em execução:

docker ps

Saída esperada:

student@instance-1:~$ docker ps
CONTAINER ID   IMAGE     COMMAND                  CREATED         STATUS         PORTS                                         NAMES
90db3c73835e   solr:9    "docker-entrypoint.s..."   7 seconds ago   Up 3 seconds   0.0.0.0:8983->8983/tcp, [::]:8983->8983/tcp   solr

Aguarde alguns segundos para o Solr inicializar e crie uma coleção chamada solrindexdemo acessando a API do Solr com suas credenciais de autenticação básica:

curl --user solr:SolrRocks -X POST "http://localhost:8983/solr/admin/collections?action=CREATE&name=solrindexdemo&numShards=1&replicationFactor=1"

Saída esperada:

student@instance-1:~$ curl --user solr:SolrRocks -X POST "http://localhost:8983/solr/admin/collections?action=CREATE&name=solrindexdemo&numShards=1&replicationFactor=1"
{
  "responseHeader":{
    "status":0,
    "QTime":3586
  },
  "success":{
    "172.17.0.2:8983_solr":{
      "responseHeader":{
        "status":0,
        "QTime":2405
      },
      "core":"solrindexdemo_shard1_replica_n1"
    }
  },
  "warning":"Using _default configset. Data driven schema functionality is enabled by default, which is NOT RECOMMENDED for production use. To turn it off: curl http://{host:port}/solr/solrindexdemo/config -d '{\"set-user-property\": {\"update.autoCreateFields\":\"false\"}}'"

Agora, vamos preencher a instância do Solr com descrições e nomes de produtos. Copie o CSV de produtos do Cloud Storage para a VM.

gcloud storage cp gs://cloud-training/gcc/gcc-tech-004/cymbal_products.csv .

Agora crie um script Python para extrair o CSV e formatar os dados em uma lista JSON para a atualização em massa.

nano convert.py

Cole o seguinte no arquivo:

import csv
import json

# Configuration
input_file = 'cymbal_products.csv'
output_file = 'products.json'

def convert():
    try:
        with open(input_file, mode='r', encoding='utf-8') as f_in, \
             open(output_file, mode='w', encoding='utf-8') as f_out:
            
            reader = csv.DictReader(f_in)
            
            products = []
            for row in reader:
                products.append({
                    "id": row['uniq_id'].strip(),
                    "product_name": row['product_name'].strip(),
                    "product_description": row['product_description'].strip()
                })
                
            json.dump(products, f_out, indent=2)
            print(f"Success: Processed {len(products)} products.")
            print(f"Output saved to: {output_file}")

    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == "__main__":
    convert()

Salve e execute o arquivo:

python3 convert.py

Saída esperada:

admin_gopalbhutada_altostrat_com@instance-1:~$ python3 convert.py
Success: Processed 941 products.
Output saved to: products.json

Agora envie os dados JSON para o Apache Solr usando o manipulador de atualização:

curl --user solr:SolrRocks -X POST -H 'Content-Type: application/json' \
  'http://localhost:8983/solr/solrindexdemo/update?commit=true' \
  --data-binary "@products.json"

Saída esperada:

admin_gopalbhutada_altostrat_com@instance-1:~$ curl --user solr:SolrRocks -X POST -H 'Content-Type: application/json' \
  'http://localhost:8983/solr/solrindexdemo/update?commit=true' \
  --data-binary "@products.json"
{
  "responseHeader":{
    "rf":1,
    "status":0,
    "QTime":3220
  }
}

Agora, precisamos criar um secret no Secret Manager para armazenar nossas credenciais do Solr. Como o AlloyDB se vincula a FDWs de pesquisa externa usando valores username:password codificados em base64 para autenticação básica, primeiro vamos receber a string codificada em base64 para solr:SolrRocks:

echo -n "solr:SolrRocks" | base64

Saída:

admin_gopalbhutada_altostrat_com@instance-1:~$ echo -n "solr:SolrRocks" | base64
c29scjpTb2xyUm9ja3M=

Crie um secret no Google Secret Manager usando essa credencial codificada em base64. No Cloud Shell, execute o seguinte:

echo -n "c29scjpTb2xyUm9ja3M=" | \
gcloud secrets create solr-credentials \
    --replication-policy="automatic" \
    --data-file=-

10. Como criar um invólucro de dados externos no AlloyDB

Duração: 10:00

Para consultar dados armazenados no Apache Solr do AlloyDB, é necessário criar um Foreign Data Wrapper (FDW) para o Solr e uma tabela externa. Antes, você armazenou as credenciais do Solr no Secret Manager. Para que o AlloyDB acesse o secret, conceda à conta de serviço a permissão necessária.

No Cloud Shell, conceda à conta de serviço acesso ao secret solr-credentials:

gcloud secrets add-iam-policy-binding solr-credentials \
    --member="serviceAccount:service-$(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)')@gcp-sa-alloydb.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"

Saída esperada:

admin_@cloudshell:~ (my-project-93954-gke)$ gcloud secrets add-iam-policy-binding solr-credentials \
    --member="serviceAccount:service-$(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)')@gcp-sa-alloydb.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"
Your active configuration is: [cloudshell-13031]
Updated IAM policy for secret [solr-credentials].
bindings:
- members:
  - serviceAccount:[e-mail]
  role: roles/secretmanager.secretAccessor
etag: BwZWyKlkx6Q=
version: 1

Conecte-se ao banco de dados com o AlloyDB Studio ou usando psql para se conectar da VM. Faça login no quickstart_db como usuário postgres.

Ative a extensão FDW:

CREATE EXTENSION IF NOT EXISTS external_search_fdw;

Saída esperada:

CREATE EXTENSION

Receber parâmetros de conexão

Antes de configurar o servidor de dados externo no AlloyDB, você precisa do endereço IP interno da VM (onde o Solr está sendo executado) e do caminho secreto.

Para imprimir o IP interno da VM, execute o seguinte no Cloud Shell:

gcloud compute instances describe instance-1 \
    --zone=us-central1-a \
    --format="value(networkInterfaces[0].networkIP)"

Saída esperada:

10.X.X.X

Para imprimir o caminho do recurso secreto no Secret Manager, execute:

gcloud secrets describe solr-credentials --format="value(name)"

Saída esperada:

projects/<project_id>/secrets/solr-credentials

Para acessar o Apache Solr, crie um servidor de dados externo. Substitua e na consulta abaixo pelos valores que você recuperou. Adicione /versions/latest ao caminho do secret para acessar a versão mais recente:

CREATE SERVER solr_demo_server
FOREIGN DATA WRAPPER external_search_fdw
OPTIONS(
    server 'http://<VM_INTERNAL_IP_ADDRESS>:8983',
    search_provider 'solr',
    auth_mode 'secret_manager',
    auth_method 'Basic',
    secret_path '<SECRET_PATH>/versions/latest'
);

Saída esperada:

CREATE SERVER

Em seguida, defina a tabela externa. Depois dos metadados, forneça a definição do esquema de campo do Solr para corresponder aos dados carregados anteriormente. Na tabela remota, especifique o nome da coleção do Solr.

CREATE FOREIGN TABLE solrindexdemo (
    metadata external_search_fdw_schema.OpaqueMetadata,
    id TEXT,
    product_name TEXT,
    product_description TEXT
)
SERVER solr_demo_server
OPTIONS(
    remote_table_name 'solrindexdemo'
);

Crie um mapeamento de usuário para o servidor:

CREATE USER MAPPING FOR CURRENT_USER SERVER solr_demo_server;

Agora você pode testar a tabela externa:

Atenção:se a consulta falhar, verifique se você tem uma regra de firewall de entrada que permita o TCP na porta 8983 para o intervalo de IP especificado para o PSA.

SELECT id, product_name
FROM solrindexdemo
ORDER BY metadata <@> 'product_description:cherry' DESC
limit 10;

Saída esperada:

"id","product_name"
"d536e9e823296a2eba198e52dd23e712","Cherry Tree"
"390cf08feac229e7b752709fd1f943b3","Woven Round Placemat, Set of Twelve, Grass"
"2c9aa7ac98c30abf78dd9c62a68a34e6","48 Scented Wax Melts Wax Cubes: Jelly Belly Jelly Beans Candy Bulk Soy Wax Melts For Candle Warmer, Wax Warmers, Wax Melt Warmers In 8 Pack Set"

11. Como usar a pesquisa híbrida

Duração: 10:00

Agora que tudo está configurado, podemos usar a função ai.hybrid_search() para combinar a pesquisa vetorial e a pesquisa de texto completo. Leia mais sobre a pesquisa híbrida na documentação. Ao usar a pesquisa híbrida, os resultados da consulta usam por padrão o algoritmo Fusão de classificação recíproca para ordenar os resultados de classificação de várias consultas. Primeiro, vamos testar a pesquisa vetorial e a pesquisa híbrida de forma independente para analisar as diferenças entre elas.

A consulta a seguir realiza uma pesquisa vetorial para encontrar produtos semelhantes a cereja. A matriz fornece uma lista de pesquisas a serem realizadas. Neste caso, usamos apenas a pesquisa vetorial, mas depois vamos fornecer vetores e FTS.

SELECT id, score, cymbal_products.product_name, cymbal_products.product_description
FROM ai.hybrid_search(
  ARRAY[
      '{
        "data_type": "vector",
        "table_name": "cymbal_products",
        "key_column": "uniq_id",
        "vec_column": "product_embedding",
        "distance_operator": "public.<=>",
        "limit": 3,
        "query_vector": "ai.embedding(''text-embedding-005'', ''cherry'')::vector"
      }'::JSONB
  ]
) JOIN cymbal_products ON id = cymbal_products.uniq_id;

Na saída, "cherry tree" é o primeiro resultado, mas observe que os dois seguintes também são árvores frutíferas. Isso acontece porque, quando usamos a pesquisa vetorial na coluna product_description, encontramos correspondências semânticas para nossa condição de pesquisa.

"id","score","product_name","product_description"
"d536e9e823296a2eba198e52dd23e712","0.01639344262295082","Cherry Tree","This is a beautiful cherry tree that will produce delicious cherries. It is an deciduous tree that grows to be about 15 feet tall. The leaves are dark green in the summer and turn a beautiful red in the fall. Cherry trees are known for their beauty and their ability to provide shade and privacy. Cherry trees prefer a cool, moist climate and sandy soil. They are best suited for USDA zones 4-9."
"b70c44b1a38c0a2329fa583c9109a80f","0.016129032258064516","Peach Tree","This is a beautiful peach tree that will produce delicious peaches. It is an evergreen tree that grows to be about 20 feet tall. The leaves are dark green in the summer and turn a beautiful yellow in the fall. Peach trees are known for their beauty and their ability to provide shade and privacy. Peach trees prefer a cool, moist climate and sandy soil. They are best suited for USDA zones 2-9."
"23e41a71d63d8bbc9bdfa1d118cfddc5","0.015873015873015872","Apple Tree","This is a beautiful apple tree that will produce delicious apples. It is a deciduous tree that grows to be about 30 feet tall. The leaves are dark green in the summer and turn a beautiful red, orange, and yellow in the fall. Apple trees are known for their strength and durability. They are also a popular choice for shade trees. Apple trees prefer a cool, moist climate and loamy soil. They are best suited for USDA zones 4-8."

Para realizar uma pesquisa de texto completo usando o FDW do Apache Solr, execute a seguinte consulta:

SELECT id, score, cymbal_products.product_name, cymbal_products.product_description
FROM ai.hybrid_search(
  ARRAY[
      '{
        "limit": 3,
        "data_type": "external_search_fdw",
        "table_name": "solrindexdemo",
        "key_column": "id",
        "query_text_input": "product_description:cherry"
      }'::JSONB
  ]
) JOIN cymbal_products ON id = cymbal_products.uniq_id;

Observe nos resultados que, como a pesquisa de texto completo usa a correspondência de tokens, os resultados retornam qualquer coisa que contenha a palavra "cherry" na descrição do produto.

"id","score","product_name","product_description"
"d536e9e823296a2eba198e52dd23e712","0.01639344262295082","Cherry Tree","This is a beautiful cherry tree that will produce delicious cherries. It is an deciduous tree that grows to be about 15 feet tall. The leaves are dark green in the summer and turn a beautiful red in the fall. Cherry trees are known for their beauty and their ability to provide shade and privacy. Cherry trees prefer a cool, moist climate and sandy soil. They are best suited for USDA zones 4-9."
"390cf08feac229e7b752709fd1f943b3","0.016129032258064516","Woven Round Placemat, Set of Twelve, Grass","...These placemats are great for special occasions and holidays, but are also perfect to accessorize your everyday place settings.|Measurements. 15-inch round diameter is the perfect size for most table sizes and shapes.|Pop Colors. Choose from 7 pop woven color placemats including: Black, Cherry, Grass, Taupe, Navy, Sun and Graphite."
"2c9aa7ac98c30abf78dd9c62a68a34e6","0.015873015873015872","48 Scented Wax Melts Wax Cubes: Jelly Belly Jelly Beans Candy Bulk Soy Wax Melts For Candle Warmer, Wax Warmers, Wax Melt Warmers In 8 Pack Set","...From These Flavors: Lemon Drop, Mixed Berry Smoothie, Sizzling Cinnamon, Crushed Pineapple, Juicy Pear, Cotton Candy, Toasted Marshmallow, French Vanilla, Watermelon, Red Apple, Very Cherry, Buttered Popcorn..."

Agora você pode combinar a pesquisa semântica e a FTS para ter resultados mais significativos. Vamos supor que queremos procurar uma árvore que possa crescer mais do que uma casa e que seja da Califórnia. Dividimos a consulta para aproveitar a intenção semântica em vez da correspondência literal. A pesquisa vetorial lida com a parte descritiva: "árvore que pode crescer mais do que uma casa", porque entende o conceito de escala sem precisar de palavras-chave exatas. Enquanto isso, a pesquisa de texto completo trata "Califórnia" como um filtro estrito para garantir que vamos receber uma correspondência geográfica exata, e não apenas algo conceitualmente semelhante.

SELECT id, score, cymbal_products.product_name, cymbal_products.product_description
FROM ai.hybrid_search(
  ARRAY[
    '{
        "data_type": "vector",
        "table_name": "cymbal_products",
        "key_column": "uniq_id",
        "vec_column": "product_embedding",
        "distance_operator": "public.<=>",
        "limit": 3,
        "query_vector": "ai.embedding(''text-embedding-005'', ''tree that can grow taller than a house'')::vector"
      }'::JSONB,
      '{
        "limit": 3,
        "data_type": "external_search_fdw",
        "table_name": "solrindexdemo",
        "key_column": "id",
        "query_text_input": "product_description:California"
      }'::JSONB
  ]
) JOIN cymbal_products ON id = cymbal_products.uniq_id;

Resultados esperados:

"id","score","product_name","product_description"
"a589fd36a8a20fd9472d2403d6ed692a","0.00819672631147241","California Redwood","This is a beautiful redwood tree that can grow to be over 300 feet tall. It is an evergreen tree that grows in the coastal forests of California. Redwoods are known for their beauty and their strength. They are best suited for USDA zones 7-10."
"ef9432802da24041594c2cf368dfb4d2","0.008064521129029258","Madrone","This is a beautiful madrona tree that can grow to be over 80 feet tall. It is an evergreen tree that grows in the coastal forests of California. Madronas are known for their beauty and their bark. They are best suited for USDA zones 7-10."
"1360d8642bc218e4ea28e9c32b2e1721","0.007936512936504936","California Sycamore","This is a beautiful sycamore tree that can grow to be over 100 feet tall. It is an deciduous tree that grows in the valleys and foothills of California. California sycamores are known for their beauty and their shade. They are best suited for USDA zones 7-10."

12. 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

Se você usou a versão de teste do AlloyDB. Não exclua o cluster de teste se você planeja testar outros laboratórios e recursos usando esse cluster. Não será possível criar outro cluster de teste no mesmo projeto.

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

No Cloud Shell, defina o projeto e as variáveis de ambiente se tiver ocorrido uma desconexão e todas as configurações anteriores forem perdidas:

gcloud config set project <your project id>

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

Exclua o cluster:

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

Observação: o comando leva de 3 a 5 minutos para ser executado.

Saída esperada do console:

admin_@cloudshell:~ (my-project-93954-gke)$ 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-1784270790060-656c8ea9fea06-1b93001f-846543e0
Deleting cluster...done.   

Excluir backups do AlloyDB

Exclua todos os backups do AlloyDB do cluster:

Observação: o comando vai destruir todos os backups de dados do cluster com o nome especificado na variável de ambiente.

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:

admin_@cloudshell:~ (my-project-93954-gke)$ 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-1784271231983-656c904f71e05-1389a145-f101ceee
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:

admin_@cloudshell:~ (my-project-93954-gke)$ export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet
Deleted

13. Parabéns

Parabéns por concluir o codelab!

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
• Gerar embeddings com a Vertex AI
• Como criar um índice vetorial do ScaNN para melhorar a pesquisa vetorial
• Como criar um Foreign Data Wrapper (FDW) para o Apache Solr
• Realize uma pesquisa híbrida combinando a pesquisa semântica no AlloyDB com a pesquisa de texto completo no Solr.

Próximas etapas

Confira mais codelabs do AlloyDB no site oficial (em inglês).