Fazer uma pesquisa vetorial

---

Este tutorial descreve como configurar e realizar uma pesquisa vetorial no AlloyDB for PostgreSQL através da Google Cloud consola. Os exemplos são incluídos para mostrar as capacidades de pesquisa vetorial e destinam-se apenas a fins de demonstração.

Para obter informações sobre como usar a pesquisa vetorial filtrada para refinar as suas pesquisas de semelhanças, consulte o artigo Pesquisa vetorial filtrada no AlloyDB for PostgreSQL.

Para saber como realizar uma pesquisa vetorial com as incorporações do Vertex AI, consulte o artigo Introdução às incorporações vetoriais com a IA do AlloyDB.

Objetivos

• Crie um cluster e uma instância principal do AlloyDB.
• Associe à sua base de dados e instale as extensões necessárias.
• Crie uma tabela product e product inventory.
• Inserir dados nas tabelas product e product inventory e fazer uma pesquisa vetorial básica.
• Crie um índice ScaNN na tabela de produtos.
• Realizar uma pesquisa vetorial simples.
• Realize uma pesquisa vetorial complexa com um filtro e uma junção.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• AlloyDB for PostgreSQL
• Vertex AI

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Antes de começar

Nota: se já executou os passos nesta secção, avance diretamente para Inserir dados de produtos e inventário de produtos e fazer uma pesquisa vetorial básica e continue o tutorial.

Ative a faturação e as APIs necessárias

1. Na Google Cloud consola, aceda à página Clusters.

   Aceder ao seletor de projetos

2. Certifique-se de que a faturação está ativada para o seu Google Cloud projeto.

3. Ative as APIs Cloud necessárias para criar e estabelecer ligação ao AlloyDB para PostgreSQL.

   Ative as APIs

   1. No passo Confirmar projeto, clique em Seguinte para confirmar o nome do projeto ao qual vai fazer alterações.

   2. No passo Ativar APIs, clique em Ativar para ativar o seguinte:

      • API AlloyDB
      • API Compute Engine
      • API de rede de serviços
      • API Vertex AI

Crie um cluster e uma instância principal do AlloyDB

Nota: algumas regiões que estão disponíveis para o AlloyDB não estão disponíveis para os modelos de incorporação de texto da Vertex AI. Para saber que funcionalidades do Vertex AI estão disponíveis em cada região do Vertex AI, consulte o artigo Disponibilidade de funcionalidades.

1. Na Google Cloud consola, aceda à página Clusters.

   Aceda a Clusters

2. Clique em Criar cluster.

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

4. Introduza uma palavra-passe. Tome nota desta palavra-passe, pois vai usá-la neste tutorial.

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

6. Selecione a rede predefinida.

   Se tiver uma ligação de acesso privado, avance para o passo seguinte. Caso contrário, clique em Configurar associação e siga estes passos:

   1. Em Atribua um intervalo de IP, clique em Usar um intervalo de IP atribuído automaticamente.
   2. Clique em Continuar e, de seguida, em Criar associação.

7. Em Disponibilidade zonal, selecione Zona única.

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

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

10. Clique em Criar cluster. O AlloyDB pode demorar vários minutos a criar o cluster e a apresentá-lo na página Vista geral do cluster principal.

11. Em Instâncias no seu cluster, expanda o painel Conetividade. Tome nota do URI de ligação, uma vez que o usa neste tutorial.

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

Conceda autorização do utilizador da Vertex AI ao agente do serviço AlloyDB

Para permitir que o AlloyDB use modelos de incorporação de texto da Vertex AI, tem de adicionar autorizações de utilizador da Vertex AI ao agente de serviço do AlloyDB para o projeto onde o cluster e a instância estão localizados.

Para mais informações sobre como adicionar as autorizações, consulte o artigo Conceda autorização de utilizador da Vertex AI ao agente do serviço AlloyDB.

Associe à sua base de dados através de um navegador de Internet

1. Na Google Cloud consola, aceda à página Clusters.

   Aceda a 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 Inicie sessão no AlloyDB Studio, siga estes passos:

   1. Selecione a base de dados postgres.
   2. Selecione o utilizador postgres.
   3. Introduza a palavra-passe que criou em Crie um cluster e a respetiva instância principal.
   4. Clique em Autenticar. O painel Explorador apresenta uma lista dos objetos na base de dados postgres.

5. Abra um novo separador clicando em + Novo separador do editor de SQL ou + Novo separador.

Instale as extensões necessárias

Execute a seguinte consulta para instalar as extensões vector e alloydb_scann:

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

Insira dados de produtos e de inventário de produtos e faça uma pesquisa vetorial básica

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

   • Armazena informações básicas sobre o produto.
   • Inclui uma coluna de vetor embedding que calcula e armazena um vetor de incorporação para uma descrição do produto de cada produto.
   Nota: se tiver mais de 100 mil linhas numa tabela, não recomendamos a utilização da função embedding() para gerar incorporações armazenadas em dados existentes numa tabela. É mais adequado para a geração de incorporações 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
     );
   

   Se necessário, pode usar o Explorador de registos para ver registos e resolver problemas.

2. Execute a seguinte consulta 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 vetorial complexas.

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

3. Execute a seguinte consulta 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 seguinte consulta para verificar se os dados são inseridos na tabela product:

   SELECT * FROM product;
   

5. Execute a seguinte consulta 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 seguinte consulta de pesquisa vetorial que tenta encontrar produtos semelhantes à palavra music. Isto significa que, embora 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 vetorial básica sem criar um índice usa a pesquisa do vizinho mais próximo exato (KNN), que oferece uma capacidade de memorização eficiente. À escala, a utilização do KNN pode afetar o desempenho. Para um melhor desempenho das consultas, recomendamos que use o índice ScaNN para a pesquisa de vizinhos mais próximos aproximados (ANN), que oferece uma elevada capacidade de memorização com baixas latências.

   Sem criar um índice, o AlloyDB usa por predefinição a pesquisa de vizinhos mais próximos (KNN) exata.

   Para saber como usar o ScaNN em grande escala, consulte o artigo Começar a usar as incorporações de vetores com a IA do AlloyDB.

Crie um índice ScaNN na tabela de produtos

Importante: os exemplos neste tutorial destinam-se apenas a fins de demonstração. Recomendamos que crie apenas índices ScaNN em tabelas com mais de 10 000 linhas.

Execute a seguinte consulta para criar um índice product_indexScaNN 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 folha com os quais o índice baseado em árvore cria o índice. Para mais informações sobre como ajustar este parâmetro, consulte o artigo Ajuste o desempenho das consultas vetoriais.

Fazer uma pesquisa vetorial

Execute a seguinte consulta de pesquisa vetorial 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 produtos 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 folha que são 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 o desempenho e a capacidade de memorização.

Realize uma pesquisa vetorial que use um filtro e uma junção

Pode executar consultas de pesquisa vetorial filtradas de forma eficiente, mesmo quando usa o índice ScaNN. Execute a seguinte consulta de pesquisa vetorial complexa, que devolve resultados relevantes que satisfazem as 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;

Acelere a pesquisa vetorial filtrada

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Pode usar o motor de colunas para melhorar o desempenho das pesquisas de similaridade vetorial, especificamente as pesquisas de K-Nearest Neighbor (KNN), quando combinadas com a filtragem de predicados altamente seletiva, por exemplo, usando LIKE, em bases de dados. Nesta secção, vai usar a extensão vector e a extensão google_columnar_engine do AlloyDB.

As melhorias de desempenho resultam da eficiência incorporada do motor de colunas na análise de grandes conjuntos de dados e na aplicação de filtros, como predicados LIKE, juntamente com a sua capacidade, através do suporte de vetores, de pré-filtrar linhas. Esta funcionalidade reduz o número de subconjuntos de dados necessários para os cálculos de distância vetorial KNN subsequentes e ajuda a otimizar consultas analíticas complexas que envolvem filtragem padrão e pesquisa vetorial.

Para comparar o tempo de execução de uma pesquisa de vetores KNN filtrada por um predicado antes e depois de ativar o motor colunar, siga estes passos:LIKE

1. Ative a extensão vector para suportar tipos de dados vetoriais e operações. Execute as seguintes declarações para criar uma tabela de exemplo (itens) com um ID, uma descrição de texto e uma coluna de incorporação de vetores de 512 dimensões.

   CREATE EXTENSION IF NOT EXISTS vector;
   
   CREATE TABLE items (
       id SERIAL PRIMARY KEY,
       description TEXT,
       embedding VECTOR(512)
   );
   

2. Preencha os dados executando as seguintes declarações para inserir 1 milhão de linhas na tabela items de exemplo.

   -- Simplified example of inserting matching (~0.1%) and non-matching data
   INSERT INTO items (description, embedding)
   SELECT
       CASE WHEN g % 1000 = 0 THEN 'product_' || md5(random()::text) || '_common' -- ~0.1% match
       ELSE 'generic_item_' || g || '_' || md5(random()::text)    -- ~99.9% don't match
       END,
       random_vector(512) -- Assumes random_vector function exists
   FROM generate_series(1, 999999) g;
   

3. Meça o desempenho de base da pesquisa de similaridade vetorial sem o motor colunar.

   SELECT id, description, embedding <-> '[...]' AS distance
   FROM items
   WHERE description LIKE '%product_%_common%'
   ORDER BY embedding <-> '[...]'
   LIMIT 100;
   

4. Ative o motor de colunas e o suporte de vetores executando o seguinte comando na CLI Google Cloud. Para usar a CLI gcloud, pode instalar e inicializar a CLI gcloud.

   gcloud beta alloydb instances update INSTANCE_ID \
       --cluster=CLUSTER_ID \
       --region=REGION_ID \
       --project=PROJECT_ID \
       --database-flags=google_columnar_engine.enabled=on,google_columnar_engine.enable_vector_support=on

5. Adicione a tabela items ao motor de colunas:

   SELECT google_columnar_engine_add('items');
   

6. Meça o desempenho da pesquisa de similaridade vetorial através do motor colunar. Executa novamente a consulta que executou anteriormente para medir o desempenho de base.

   SELECT id, description, embedding <-> '[...]' AS distance
   FROM items
   WHERE description LIKE '%product_%_common%'
   ORDER BY embedding <-> '[...]'
   LIMIT 100;
   

7. Para verificar se a consulta foi executada com o motor de colunas, execute o seguinte comando:

   explain (analyze) SELECT id, description, embedding <-> '[...]' AS distance
   FROM items
   WHERE description LIKE '%product_%_common%'
   ORDER BY embedding <-> '[...]'
   LIMIT 100;
   

Limpar

1. Na Google Cloud consola, aceda à página Clusters.

   Aceda a Clusters

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

3. Clique em Eliminar cluster.

4. Em Delete cluster my-cluster, introduza my-cluster para confirmar que quer eliminar o cluster.

5. Clique em Eliminar.

6. Se criou uma ligação privada quando criou um cluster, aceda à Google Cloud página de rede da consola e clique em Eliminar rede VPC.

O que se segue?

• Saiba mais sobre os exemplos de utilização reais da pesquisa vetorial.
• Comece a usar as incorporações vetoriais com a IA do AlloyDB.
• Saiba como criar aplicações de IA generativa com o AlloyDB AI.
• Crie um índice ScaNN.
• Otimize os seus índices ScaNN.
• Saiba como criar um assistente de compras inteligente com o AlloyDB, o pgvector e a gestão de pontos finais de modelos.
• Resolva problemas de erros com o Explorador de registos.