Realizar uma pesquisa de vetor

---

Este tutorial descreve como configurar e realizar uma pesquisa de vetor no AlloyDB para PostgreSQL usando o console do Google Cloud. Os exemplos são incluídos para mostrar os recursos de pesquisa vetorial e são destinados apenas para fins de demonstração.

Para saber como realizar uma pesquisa vetorial com embeddings da Vertex AI, consulte Começar a usar embeddings vetoriais com o AlloyDB AI.

Objetivos

• Crie um cluster e uma instância principal do AlloyDB.
• Conecte-se ao seu banco de dados e instale as extensões necessárias.
• Crie uma tabela product e product inventory.
• Insira dados nas tabelas product e product inventory e realize uma pesquisa de vetor básica.
• Crie um índice ScaNN na tabela de produtos.
• Faça uma pesquisa de vetor simples.
• Realize uma pesquisa vetorial complexa com um filtro e uma mesclagem.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

• AlloyDB for PostgreSQL
• Vertex AI

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Antes de começar

Observação: se você já realizou as etapas desta seção, prossiga diretamente para Inserir dados de produtos e inventário de produtos e realizar uma pesquisa de vetor básica e continue o tutorial.

Ativar o faturamento e as APIs necessárias

1. No console do Google Cloud, acesse a página Clusters.

   Acessar o seletor de projetos

2. Verifique se o faturamento está ativado para o projeto do Google Cloud .

3. Ative as APIs do Cloud necessárias para criar e se conectar ao AlloyDB para PostgreSQL.

   Ativar as APIs

   1. Na etapa Confirmar projeto, clique em Próxima para confirmar o nome do projeto em que você vai fazer mudanças.

   2. Na etapa Ativar APIs, clique em Ativar para ativar o seguinte:

      • API AlloyDB
      • API Compute Engine
      • API Service Networking
      • API Vertex AI

Criar um cluster e uma instância principal do AlloyDB

1. No console do Google Cloud, acesse a página Clusters.

   Acessar Clusters

2. Clique em Criar cluster.

3. Em ID do cluster, insira my-cluster.

4. Insira uma senha. Anote essa senha porque você vai usá-la neste tutorial.

5. Selecione uma região, por exemplo, us-central1 (Iowa).

6. Selecione a rede padrão.

   Se você tiver uma conexão de acesso privado, siga para a próxima etapa. Caso contrário, clique em Configurar conexão e siga estas etapas:

   1. Em Alocar um intervalo de IP, clique em Usar um intervalo de IP alocado automaticamente.
   2. Clique em Continuar e em Criar conexão.

7. Em Disponibilidade por zona, selecione Zona única.

8. Selecione o tipo de máquina 2 vCPU,16 GB.

9. Em Conectividade, selecione Ativar IP público.

10. Clique em Criar cluster. Pode levar alguns minutos para que o AlloyDB crie o cluster e o mostre na página Visão geral do cluster principal.

11. Em Instâncias no cluster, abra o painel Conectividade. Anote o URI da conexão, porque você vai usá-lo neste tutorial.

    O URI de conexão está no formato projects/<var>PROJECT_ID</var>/locations/<var>REGION_ID</var>/clusters/my-cluster/instances/my-cluster-primary.

Conceder permissão de usuário da Vertex AI ao agente de serviço do AlloyDB

Para permitir que o AlloyDB use modelos de incorporação de texto da Vertex AI, adicione as permissões de usuário da Vertex AI ao agente de serviço do AlloyDB para o projeto em que o cluster e a instância estão localizados.

Para mais informações sobre como adicionar as permissões, consulte Conceder permissão de usuário da Vertex AI ao agente de serviço do AlloyDB.

Conectar-se ao banco de dados usando um navegador da Web

1. No console do Google Cloud, acesse a página Clusters.

   Acessar Clusters

2. Na coluna Nome do recurso, clique no nome do cluster, my-cluster.

3. No painel de navegação, clique em AlloyDB Studio.

4. Na página Fazer login no AlloyDB Studio, siga estas etapas:

   1. Selecione o banco de dados postgres.
   2. Selecione o usuário postgres.
   3. Digite a senha criada em Criar um cluster e a instância principal.
   4. Clique em Autenticar. O painel Explorer mostra uma lista dos objetos no banco de dados postgres.

5. Abra uma nova guia clicando em + Nova guia do editor de SQL ou + Nova guia.

Instalar as extensões necessárias

Execute a consulta a seguir para instalar as extensões vector, alloydb_scann e google_ml_integration:

  CREATE EXTENSION IF NOT EXISTS vector;
  CREATE EXTENSION IF NOT EXISTS alloydb_scann;
  CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;

Inserir dados de produtos e de inventário de produtos e realizar uma pesquisa de vetor básica

1. Execute a instrução a seguir para criar uma tabela product que faça o seguinte:

   • Armazena informações básicas do produto.
   • Inclui uma coluna de vetor embedding que calcula e armazena um vetor de embeddings para uma descrição de produto de cada produto.
   Observação: se você tiver mais de 100 mil linhas em uma tabela, não recomendamos usar a função embedding() para gerar embeddings armazenados nos dados existentes em uma tabela. É mais adequado para a geração de incorporação inline.

     CREATE TABLE product (
       id INT PRIMARY KEY,
       name VARCHAR(255) NOT NULL,
       description TEXT,
       category VARCHAR(255),
       color VARCHAR(255),
       embedding vector(768) GENERATED ALWAYS AS (embedding('text-embedding-005', description)) STORED
     );
   

2. Execute a consulta a seguir para criar uma tabela product_inventory que armazene informações sobre o inventário disponível e os preços correspondentes. As tabelas product_inventory e product são usadas neste tutorial para executar consultas de pesquisa de vetor complexas.

   CREATE TABLE product_inventory (
     id INT PRIMARY KEY,
     product_id INT REFERENCES product(id),
     inventory INT,
     price DECIMAL(10,2)
   );
   

3. Execute a consulta a seguir para inserir dados de produtos na tabela product:

   INSERT INTO product (id, name, description,category, color) VALUES
   (1, 'Stuffed Elephant', 'Soft plush elephant with floppy ears.', 'Plush Toys', 'Gray'),
   (2, 'Remote Control Airplane', 'Easy-to-fly remote control airplane.', 'Vehicles', 'Red'),
   (3, 'Wooden Train Set', 'Classic wooden train set with tracks and trains.', 'Vehicles', 'Multicolor'),
   (4, 'Kids Tool Set', 'Toy tool set with realistic tools.', 'Pretend Play', 'Multicolor'),
   (5, 'Play Food Set', 'Set of realistic play food items.', 'Pretend Play', 'Multicolor'),
   (6, 'Magnetic Tiles', 'Set of colorful magnetic tiles for building.', 'Construction Toys', 'Multicolor'),
   (7, 'Kids Microscope', 'Microscope for kids with different magnification levels.', 'Educational Toys', 'White'),
   (8, 'Telescope for Kids', 'Telescope designed for kids to explore the night sky.', 'Educational Toys', 'Blue'),
   (9, 'Coding Robot', 'Robot that teaches kids basic coding concepts.', 'Educational Toys', 'White'),
   (10, 'Kids Camera', 'Durable camera for kids to take pictures and videos.', 'Electronics', 'Pink'),
   (11, 'Walkie Talkies', 'Set of walkie talkies for kids to communicate.', 'Electronics', 'Blue'),
   (12, 'Karaoke Machine', 'Karaoke machine with built-in microphone and speaker.', 'Electronics', 'Black'),
   (13, 'Kids Drum Set', 'Drum set designed for kids with adjustable height.', 'Musical Instruments', 'Blue'),
   (14, 'Kids Guitar', 'Acoustic guitar for kids with nylon strings.', 'Musical Instruments', 'Brown'),
   (15, 'Kids Keyboard', 'Electronic keyboard with different instrument sounds.', 'Musical Instruments', 'Black'),
   (16, 'Art Easel', 'Double-sided art easel with chalkboard and whiteboard.', 'Arts & Crafts', 'White'),
   (17, 'Finger Paints', 'Set of non-toxic finger paints for kids.', 'Arts & Crafts', 'Multicolor'),
   (18, 'Modeling Clay', 'Set of colorful modeling clay.', 'Arts & Crafts', 'Multicolor'),
   (19, 'Watercolor Paint Set', 'Watercolor paint set with brushes and palette.', 'Arts & Crafts', 'Multicolor'),
   (20, 'Beading Kit', 'Kit for making bracelets and necklaces with beads.', 'Arts & Crafts', 'Multicolor'),
   (21, '3D Puzzle', '3D puzzle of a famous landmark.', 'Puzzles', 'Multicolor'),
   (22, 'Race Car Track Set', 'Race car track set with cars and accessories.', 'Vehicles', 'Multicolor'),
   (23, 'RC Monster Truck', 'Remote control monster truck with oversized tires.', 'Vehicles', 'Green'),
   (24, 'Train Track Expansion Set', 'Expansion set for wooden train tracks.', 'Vehicles', 'Multicolor');
   

4. Opcional: execute a consulta a seguir para verificar se os dados foram inseridos na tabela product:

   SELECT * FROM product;
   

5. Execute a consulta a seguir para inserir dados de inventário na tabela product_inventory:

   INSERT INTO product_inventory (id, product_id, inventory, price) VALUES
   (1, 1, 9, 13.09),
   (2, 2, 40, 79.82),
   (3, 3, 34, 52.49),
   (4, 4, 9, 12.03),
   (5, 5, 36, 71.29),
   (6, 6, 10, 51.49),
   (7, 7, 7, 37.35),
   (8, 8, 6, 10.87),
   (9, 9, 7, 42.47),
   (10, 10, 3, 24.35),
   (11, 11, 4, 10.20),
   (12, 12, 47, 74.57),
   (13, 13, 5, 28.54),
   (14, 14, 11, 25.58),
   (15, 15, 21, 69.84),
   (16, 16, 6, 47.73),
   (17, 17, 26, 81.00),
   (18, 18, 11, 91.60),
   (19, 19, 8, 78.53),
   (20, 20, 43, 84.33),
   (21, 21, 46, 90.01),
   (22, 22, 6, 49.82),
   (23, 23, 37, 50.20),
   (24, 24, 27, 99.27);
   

6. Execute a consulta de pesquisa vetorial a seguir, que tenta encontrar produtos semelhantes à palavra music. Isso significa que, mesmo que a palavra music não seja mencionada explicitamente na descrição do produto, o resultado mostra produtos relevantes para a consulta:

   SELECT * FROM product
   ORDER BY embedding <=> embedding('text-embedding-005', 'music')::vector
   LIMIT 3;
   

   O resultado da consulta é o seguinte:

   A execução de uma pesquisa de vetor básica sem criar um índice usa a pesquisa de vizinho exato mais próximo (KNN, na sigla em inglês), que fornece recall eficiente. Em grande escala, o uso de KNN pode afetar o desempenho. Para melhorar a performance da consulta, recomendamos o uso do índice ScaNN para a pesquisa de vizinho mais próximo aproximado (ANN, na sigla em inglês), que oferece alta recuperação com baixa latência.

   Sem a criação de um índice, o AlloyDB usa por padrão a pesquisa exata de vizinho mais próximo (KNN).

   Para saber mais sobre o uso do ScaNN em grande escala, consulte Começar a usar embeddings vetoriais com o AlloyDB AI.

Criar um índice ScaNN na tabela de produtos

Importante: os exemplos deste tutorial são destinados apenas a fins de demonstração. Recomendamos que você crie índices ScaNN apenas em tabelas com mais de 10.000 itens.

Execute a consulta a seguir para criar um índice ScaNN product_index na tabela product:

  CREATE INDEX product_index ON product
  USING scann (embedding cosine)
  WITH (num_leaves=5);

O parâmetro num_leaves indica o número de nós de folha com que o índice baseado em árvore é criado. Para mais informações sobre como ajustar esse parâmetro, consulte Ajustar o desempenho da consulta de vetor.

Realizar uma pesquisa de vetor

Execute a consulta de pesquisa vetorial a seguir, que tenta encontrar produtos semelhantes à consulta de linguagem natural music. Embora a palavra music não esteja incluída na descrição do produto, o resultado mostra itens relevantes para a consulta:

SET LOCAL scann.num_leaves_to_search = 2;

SELECT * FROM product
ORDER BY embedding <=> embedding('text-embedding-005', 'music')::vector
  LIMIT 3;

Os resultados da consulta são os seguintes:

O parâmetro de consulta scann.num_leaves_to_search controla o número de nós de folha pesquisados durante uma pesquisa de similaridade. Os valores dos parâmetros num_leaves e scann.num_leaves_to_search ajudam a alcançar um equilíbrio entre performance e recuperação.

Realizar uma pesquisa vetorial que usa um filtro e uma mesclagem

É possível executar consultas de pesquisa de vetor filtrado de forma eficiente, mesmo quando você usa o índice ScaNN. Execute a consulta de pesquisa vetorial complexa abaixo, que retorna resultados relevantes que atendem às condições da consulta, mesmo com filtros:

SET LOCAL scann.num_leaves_to_search = 2;

SELECT * FROM product p
JOIN product_inventory pi ON p.id = pi.product_id
WHERE pi.price < 80.00
ORDER BY embedding <=> embedding('text-embedding-005', 'music')::vector
LIMIT 3;

Limpar

1. No console do Google Cloud, acesse a página Clusters.

   Acessar Clusters

2. Clique no nome do cluster, my-cluster, na coluna Nome do recurso.

3. Clique em Excluir cluster.

4. Em Delete cluster my-cluster, digite my-cluster para confirmar que você quer excluir o cluster.

5. Clique em Excluir.

6. Se você criou uma conexão particular ao criar um cluster, acesse a página de rede do console do Google Cloud e clique em Excluir rede VPC.

A seguir

• Comece a usar embeddings vetoriais com o AlloyDB AI.
• Aprenda a criar aplicativos de IA generativa usando a AlloyDB AI.
• Crie um índice ScaNN.
• Ajuste os índices do ScaNN.
• Aprenda a criar um assistente de compras inteligentes com o AlloyDB, o pgvector e o gerenciamento de endpoints do modelo.