Fazer uma pesquisa de vetor

Neste tutorial, descrevemos como configurar e realizar uma pesquisa vetorial no AlloyDB para PostgreSQL usando o Google Cloud console. Os exemplos incluídos mostram os recursos de pesquisa vetorial e são apenas para fins de demonstração.

Para saber como usar a pesquisa vetorial filtrada para refinar suas pesquisas de similaridade, consulte Pesquisa vetorial filtrada no AlloyDB para PostgreSQL.

Para saber como realizar uma pesquisa vetorial com embeddings da Vertex AI, consulte Introdução às embedding de vetor com a IA do AlloyDB.

Objetivos

• Criar um cluster e uma instância principal do AlloyDB.
• Conectar-se ao banco de dados e instalar as extensões necessárias.
• Criar uma tabela product e product inventory.
• Inserir dados nas tabelas product e product inventory e realizar uma pesquisa vetorial básica.
• Criar um índice ScaNN na tabela de produtos.
• Realizar uma pesquisa vetorial básica.
• Realizar uma pesquisa vetorial complexa com um filtro e uma junção.

Custos

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

Para gerar uma estimativa de custo baseada na projeção de uso, use a calculadora de preços.

Novos Google Cloud usuários podem estar qualificados para um teste sem custo financeiro.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Para mais informações, consulte Limpeza.

Antes de começar

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

Ativar o faturamento e as APIs necessárias

1. Noconsole, acesse a página Clusters. Google Cloud

   Acessar o seletor de projetos

2. Verifique se o faturamento está ativado para seu 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 Avançar para confirmar o nome do projeto no qual você vai fazer alterações.

   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

**Observação**: algumas regiões disponíveis para o AlloyDB não estão disponíveis para modelos de embedding de texto da Vertex AI. Para saber quais recursos da Vertex AI estão disponíveis em cada região da Vertex AI, consulte Disponibilidade de recursos.

1. Noconsole, acesse a página Clusters. Google Cloud

   Acessar Clusters

2. Clique em Criar cluster.

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

4. Insira uma senha. Anote essa senha porque ela será usada 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 particular, continue 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 vários minutos para o AlloyDB criar o cluster e exibi-lo na página Visão geral do cluster principal.

11. Em Instâncias no cluster, expanda o painel Conectividade. Anote o URI de conexão porque ele será usado 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 embedding de texto da Vertex AI, adicione 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. Noconsole, acesse a página Clusters. Google Cloud

   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. Insira a senha criada em Criar um cluster e a instância principal dele.
   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 e alloydb_scann:

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

Inserir dados de produtos e inventário de produtos e realizar uma pesquisa vetorial 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 embedding para uma descrição 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 em dados atuais em uma tabela. Ela é mais adequada para a geração de embeddings 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, use o Análise de registros para visualizar registros e solucionar erros.

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 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 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 realização de uma pesquisa vetorial básica sem criar um índice usa a pesquisa de vizinho mais próximo exato (KNN), que oferece recall eficiente. Em escala, o uso do KNN pode afetar a performance. Para uma melhor performance de consulta, recomendamos que você use o índice ScaNN para a pesquisa de vizinho mais próximo aproximado (ANN), que oferece alto recall com baixa latência.

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

   Para saber mais sobre como usar o ScaNN em escala, consulte Introdução às embedding de vetor com a IA do AlloyDB.

Criar um índice ScaNN ajustado manualmente na tabela de produtos

Importante: os exemplos neste tutorial são apenas para fins de demonstração. Recomendamos que você crie índices ScaNN apenas em tabelas maiores que 10 mil.

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

CREATE INDEX product_index ON product
USING scann (embedding cosine)
WITH (mode='MANUAL', num_leaves=4);

Para mais informações sobre como criar um índice ScaNN, consulte Criar um índice ScaNN.

Realizar uma pesquisa vetorial

Execute a consulta de pesquisa vetorial a seguir que tenta encontrar produtos semelhantes à consulta de linguagem natural music. Mesmo que 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 pesquisados durante uma pesquisa de similaridade. Os valores de parâmetro num_leaves e scann.num_leaves_to_search ajudam a alcançar um equilíbrio de performance e recall.

Realizar uma pesquisa vetorial que usa um filtro e uma junção

É possível executar consultas de pesquisa vetorial filtradas com eficiência, mesmo ao usar o índice ScaNN. Execute a consulta de pesquisa vetorial complexa a seguir, 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;

Acelerar a pesquisa vetorial filtrada

É possível usar o repositório de conteúdo do mecanismo colunar para melhorar o desempenho de pesquisas de similaridade vetorial, especificamente pesquisas de vizinho mais próximo (KNN), quando combinadas com a filtragem de predicados altamente seletiva, por exemplo, usando LIKE, em bancos de dados. Nesta seção, você usa a extensão vector e a extensão google_columnar_engine do AlloyDB. Para mais informações sobre como o mecanismo colunar funciona, consulte Sobre o mecanismo colunar do AlloyDB.

As melhorias de performance vêm da eficiência integrada do mecanismo colunar na verificação de grandes conjuntos de dados e na aplicação de filtros, como predicados LIKE, juntamente com a capacidade, usando o suporte vetorial, de pré-filtrar linhas. Essa funcionalidade reduz o número de subconjuntos de dados necessários para cálculos de distância vetorial KNN subsequentes e ajuda a otimizar consultas analíticas complexas que envolvem filtragem padrão e pesquisa vetorial.

O armazenamento colunar oferece duas opções para gerenciar o conteúdo:

• Gerenciar automaticamente o conteúdo do armazenamento de colunas: novas instâncias do AlloyDB usam a columnarização automática por padrão. Como alternativa, é possível executar manualmente a funcionalidade de columnarização automática.
• Gerenciar o conteúdo do armazenamento de colunas manualmente: se você precisar gerenciar manualmente as colunas no armazenamento de colunas para sua carga de trabalho, você pode desativar a columnarização automática.

Para comparar o tempo de execução de uma pesquisa vetorial KNN filtrada por um predicado LIKE antes e depois de ativar o mecanismo colunar, siga estas etapas:

1. Ative a extensão vector para oferecer suporte a tipos e operações de dados vetoriais. Execute as instruções a seguir para criar uma tabela de exemplo (itens) com um ID, uma descrição de texto e uma coluna de embedding de vetor 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 instruções a seguir para inserir 1 milhão de linhas na tabela de exemplo items.

   -- 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 a performance de referência da pesquisa de similaridade vetorial sem o mecanismo colunar.

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

4. Ative o mecanismo colunar e o suporte vetorial executando o comando a seguir na Google Cloud CLI. Para usar a CLI gcloud, você 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

   Substitua:

   • INSTANCE_ID: o ID da instância.
   • CLUSTER_ID: o ID do cluster.
   • REGION_ID: a região em que o cluster está localizado.
   • PROJECT_ID: o ID do projeto em que o cluster está localizado.

5. Adicione a tabela items ao mecanismo colunar:

   SELECT google_columnar_engine_add('items');
   

6. Meça a performance da pesquisa de similaridade vetorial usando o mecanismo colunar. Execute novamente a consulta que você executou anteriormente para medir a performance de referência.

   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 mecanismo colunar, execute o comando a seguir:

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

Limpar

1. Noconsole, acesse a página Clusters. Google Cloud

   Acessar Clusters

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

3. Clique em Excluir cluster.

4. Em Excluir cluster my-cluster, insira 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 Google Cloud Redes doconsole e clique em Excluir rede VPC.

A seguir

• Conheça casos de uso reais para pesquisa vetorial.
• Comece a usar embeddings de vetor com a IA do AlloyDB.
• Aprenda a criar aplicativos de IA generativa usando a IA do AlloyDB.
• Criar um índice ScaNN.
• Ajustar os índices ScaNN.
• Aprenda a criar um assistente de compras inteligente com o AlloyDB, o pgvector e o gerenciamento de endpoints de modelo.
• Acelerar a pesquisa vetorial com o mecanismo colunar.