Começar a usar a pesquisa de vetores do Spanner

1. Introdução

O Spanner é um serviço de banco de dados totalmente gerenciado, escalonável e distribuído globalmente, ideal para cargas de trabalho operacionais relacionais e não relacionais.

Com o lançamento da funcionalidade exata de vizinhos do K-mais próximo, o Spanner agora é um banco de dados de vetores altamente escalonável, permitindo realizar pesquisas semânticas ou por similaridade e implementar a geração aumentada de recuperação (RAG) em aplicativos de IA generativa em grande escala. As consultas de pesquisa vetorial do Spanner retornam dados em tempo real assim que as transações são confirmadas, assim como qualquer outra consulta nos seus dados operacionais.

Neste laboratório, você vai aprender a configurar os recursos básicos necessários para usar o Spanner na pesquisa vetorial e acessar modelos LLM e embeddings do jardim de modelos da Vertex AI usando SQL.

A arquitetura ficaria assim:

Observação:o foco deste laboratório é a parte certa do diagrama. Portanto, você vai implantar apenas uma instância do Spanner e as integrações da Vertex AI.

O que você vai criar

Como parte deste laboratório, você vai:

• Criar uma instância do Spanner
• Configurar o esquema de banco de dados do Spanner para integração com modelos de embedding e LLM na Vertex AI
• Carregar um conjunto de dados de varejo
• Emitir consultas de pesquisa por semelhança no conjunto de dados
• Forneça contexto ao modelo LLM para gerar recomendações específicas do produto.

Conteúdo

• Como configurar uma instância do Spanner
• Como fazer a integração com a Vertex AI
• Como usar o Spanner para realizar uma pesquisa vetorial para encontrar itens semelhantes em um conjunto de dados de varejo

O que é necessário

• Um projeto do Google Cloud conectado a uma conta de faturamento.
• Um navegador, como o Chrome ou o Firefox

2. Configuração e requisitos

Criar um projeto

Se você ainda não tem uma Conta do Google (Gmail ou Google Apps), crie uma. Faça login no console do Google Cloud Platform ( console.cloud.google.com) e crie um novo projeto.

Se você já tiver um projeto, clique no menu suspenso de seleção no canto superior esquerdo do console:

e clique no botão "NEW PROJECT" na caixa de diálogo exibida para criar um novo projeto:

Se você ainda não tiver um projeto, uma caixa de diálogo como esta será exibida para criar seu primeiro:

A caixa de diálogo de criação de projeto subsequente permite que você insira os detalhes do novo projeto:

Lembre-se do código do projeto, um nome exclusivo em todos os projetos do Google Cloud. O nome acima já foi escolhido e não servirá para você. Faremos referência a ele mais adiante neste codelab como PROJECT_ID.

Em seguida, você precisará ativar o faturamento no Developers Console para usar os recursos do Google Cloud e ativar a API Spanner, caso ainda não tenha feito isso.

A execução por meio deste codelab terá um custo baixo, mas poderá ser mais se você decidir usar mais recursos ou se deixá-los em execução. Consulte a seção "limpeza" no final deste documento. Os preços do Google Cloud Spanner estão documentados neste link.

Novos usuários do Google Cloud Platform estão qualificados para uma avaliação sem custo financeiro de US$ 300, o que torna este codelab totalmente sem custo financeiro.

Configuração do Google Cloud Shell

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

O Cloud Shell é uma máquina virtual com base em Debian que 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. Isso significa que tudo que você precisa para este codelab é um navegador (sim, funciona em um Chromebook).

1. Para ativar o Cloud Shell no Console do Cloud, basta clicar em Ativar o Cloud Shell . O provisionamento e a conexão ao ambiente devem levar apenas alguns instantes.

Após se conectar ao Cloud Shell, sua conta já está autenticada e o projeto está configurado com seu PROJECT_ID.

gcloud auth list

Resposta ao comando

Credentialed accounts:
 - <myaccount>@<mydomain>.com (active)

Observação:a ferramenta de linha de comando gcloud vem pré-instalada no Cloud Shell. Para mais informações, consulte a visão geral da ferramenta de linha de comando gcloud.

gcloud config list project

Resposta ao comando

[core]
project = <PROJECT_ID>

Se, por algum motivo, o projeto não estiver definido, basta emitir o seguinte comando:

gcloud config set project <PROJECT_ID>

Quer encontrar seu PROJECT_ID? Veja qual ID você usou nas etapas de configuração ou procure-o no painel do Console do Cloud:

O Cloud Shell também define algumas variáveis de ambiente por padrão, o que pode ser útil ao executar comandos futuros.

echo $GOOGLE_CLOUD_PROJECT

Resposta ao comando

<PROJECT_ID>

Observação:ao executar a gcloud na sua máquina, as definições de configuração são mantidas em todas as sessões. No Cloud Shell, você precisará configurá-lo para cada nova sessão ou reconexão.

Ativar a API Spanner

gcloud services enable spanner.googleapis.com

Resumo

Nesta etapa, você configurou seu projeto, se ainda não tinha um, ativou o Cloud Shell e as APIs necessárias.

A seguir

Em seguida, configure a instância e o banco de dados do Spanner.

3. Criar uma instância e um banco de dados do Spanner

Criar a instância do Spanner

Nesta etapa, vamos configurar a instância do Spanner para o codelab. Para fazer isso, abra o Cloud Shell e execute este comando:

export SPANNER_INSTANCE_ID=retail-demo
gcloud spanner instances create $SPANNER_INSTANCE_ID \
--config=regional-us-central1 \
--description="spanner AI retail demo" \
--nodes=1

Observação:a criação da instância pode levar alguns instantes.

Observação:esse comando usa regional-us-central1 como a região. Selecione uma região diferente com base nas configurações de região disponíveis para o Spanner que correspondam às regiões de endpoints da Vertex AI que estão localizados.

Resposta ao comando:

$ gcloud spanner instances create $SPANNER_INSTANCE_ID \
--config=regional-us-central1 \
--description="spanner AI retail demo" \
--nodes=1
Creating instance...done.  

Crie o banco de dados

Quando sua instância estiver em execução, você poderá criar o banco de dados. O Spanner permite vários bancos de dados em uma única instância.

O banco de dados é onde você define o esquema. Você também pode controlar quem tem acesso ao banco de dados, definir criptografia personalizada, configurar o otimizador e definir o período de armazenamento.

Para criar o banco de dados, use novamente a ferramenta de linha de comando gcloud:

export SPANNER_DATABASE=cymbal-bikes
gcloud spanner databases create $SPANNER_DATABASE \
 --instance=$SPANNER_INSTANCE_ID

Resposta ao comando:

$ gcloud spanner databases create $SPANNER_DATABASE \
 --instance=$SPANNER_INSTANCE_ID
Creating database...done.

Resumo

Nesta etapa, você criou a instância e o banco de dados do Spanner.

A seguir

Em seguida, configure o esquema e os dados do Spanner.

4. Carregar esquema e dados da Cymbal

Criar o esquema da Cymbal

Para configurar o esquema, navegue até o Spanner Studio:

Observação:para acessar o Spanner Studio, clique na instância retail-demo do Spanner e no banco de dados cymbal-bikes.

O esquema tem duas partes. Primeiro, você quer adicionar a tabela products. Copie e cole esta instrução na guia vazia.

Para o esquema, copie e cole esse DDL na caixa:

CREATE TABLE products (
categoryId INT64 NOT NULL,
productId INT64 NOT NULL,
productName STRING(MAX) NOT NULL,
productDescription STRING(MAX) NOT NULL,
productDescriptionEmbedding ARRAY<FLOAT64>,
createTime TIMESTAMP NOT NULL OPTIONS (
allow_commit_timestamp = true
),
inventoryCount INT64 NOT NULL,
priceInCents INT64,
) PRIMARY KEY(categoryId, productId);

Em seguida, clique no botão run e aguarde alguns segundos para que o esquema seja criado.

Em seguida, você vai criar os dois modelos e configurá-los para os endpoints de modelo da Vertex AI.

O primeiro é um modelo de embedding usado para gerar embeddings de texto, e o segundo é um modelo LLM usado para gerar respostas com base nos dados no Spanner.

Cole o esquema a seguir em uma nova guia do Spanner Studio:

Aviso:mude o <PROJECT_ID> nas duas instruções para o ID do projeto que você criou no início do codelab.

Observação:o esquema abaixo usa o endpoint us-central1 da Vertex AI. Mude isso nas definições de EmbeddingsModel e LLMModel se você escolher uma região diferente do Spanner ao criar a instância.

CREATE MODEL EmbeddingsModel INPUT(
content STRING(MAX),
) OUTPUT(
embeddings STRUCT<statistics STRUCT<truncated BOOL, token_count FLOAT64>, values ARRAY<FLOAT64>>,
) REMOTE OPTIONS (
endpoint = '//aiplatform.googleapis.com/projects/<PROJECT_ID>/locations/us-central1/publishers/google/models/textembedding-gecko@003'
);

CREATE MODEL LLMModel INPUT(
prompt STRING(MAX),
) OUTPUT(
content STRING(MAX),
) REMOTE OPTIONS (
endpoint = '//aiplatform.googleapis.com/projects/<PROJECT_ID>/locations/us-central1/publishers/google/models/text-bison@001',
default_batch_size = 1
);

Em seguida, clique no botão run e aguarde alguns segundos para que os modelos sejam criados.

No painel esquerdo do Spanner Studio, você verá as seguintes tabelas e modelos:

Carregue os dados

Agora, você vai querer inserir alguns produtos em seu banco de dados. Abra uma nova guia no Spanner Studio e depois copie e cole as seguintes instruções de inserção:

INSERT INTO products (categoryId, productId, productName, productDescription, createTime, inventoryCount, priceInCents)
VALUES (1, 1, "Cymbal Helios Helmet", "Safety meets style with the Cymbal children's bike helmet. Its lightweight design, superior ventilation, and adjustable fit ensure comfort and protection on every ride. Stay bright and keep your child safe under the sun with Cymbal Helios!", PENDING_COMMIT_TIMESTAMP(), 100, 10999),
(1, 2, "Cymbal Sprout", "Let their cycling journey begin with the Cymbal Sprout, the ideal balance bike for beginning riders ages 2-4 years. Its lightweight frame, low seat height, and puncture-proof tires promote stability and confidence as little ones learn to balance and steer. Watch them sprout into cycling enthusiasts with Cymbal Sprout!", PENDING_COMMIT_TIMESTAMP(), 10, 13999),
(1, 3, "Cymbal Spark Jr.", "Light, vibrant, and ready for adventure, the Spark Jr. is the perfect first bike for young riders (ages 5-8). Its sturdy frame, easy-to-use brakes, and puncture-resistant tires inspire confidence and endless playtime. Let the spark of cycling ignite with Cymbal!", PENDING_COMMIT_TIMESTAMP(), 34, 13900),
(1, 4, "Cymbal Summit", "Conquering trails is a breeze with the Summit mountain bike. Its lightweight aluminum frame, responsive suspension, and powerful disc brakes provide exceptional control and comfort for experienced bikers navigating rocky climbs or shredding downhill. Reach new heights with Cymbal Summit!", PENDING_COMMIT_TIMESTAMP(), 0, 79999),
(1, 5, "Cymbal Breeze", "Cruise in style and embrace effortless pedaling with the Breeze electric bike. Its whisper-quiet motor and long-lasting battery let you conquer hills and distances with ease. Enjoy scenic rides, commutes, or errands with a boost of confidence from Cymbal Breeze!", PENDING_COMMIT_TIMESTAMP(), 72, 129999),
(1, 6, "Cymbal Trailblazer Backpack", "Carry all your essentials in style with the Trailblazer backpack. Its water-resistant material, multiple compartments, and comfortable straps keep your gear organized and accessible, allowing you to focus on the adventure. Blaze new trails with Cymbal Trailblazer!", PENDING_COMMIT_TIMESTAMP(), 24, 7999),
(1, 7, "Cymbal Phoenix Lights", "See and be seen with the Phoenix bike lights. Powerful LEDs and multiple light modes ensure superior visibility, enhancing your safety and enjoyment during day or night rides. Light up your journey with Cymbal Phoenix!", PENDING_COMMIT_TIMESTAMP(), 87, 3999),
(1, 8, "Cymbal Windstar Pump", "Flat tires are no match for the Windstar pump. Its compact design, lightweight construction, and high-pressure capacity make inflating tires quick and effortless. Get back on the road in no time with Cymbal Windstar!", PENDING_COMMIT_TIMESTAMP(), 36, 24999),
(1, 9,"Cymbal Odyssey Multi-Tool","Be prepared for anything with the Odyssey multi-tool. This handy gadget features essential tools like screwdrivers, hex wrenches, and tire levers, keeping you ready for minor repairs and adjustments on the go. Conquer your journey with Cymbal Odyssey!", PENDING_COMMIT_TIMESTAMP(), 52, 999),
(1, 10,"Cymbal Nomad Water Bottle","Stay hydrated on every ride with the Nomad water bottle. Its sleek design, BPA-free construction, and secure lock lid make it the perfect companion for staying refreshed and motivated throughout your adventures. Hydrate and explore with Cymbal Nomad!", PENDING_COMMIT_TIMESTAMP(), 42, 1299);

Clique no botão run para inserir os dados.

Resumo

Nesta etapa, você criou o esquema e carregou alguns dados básicos no banco de dados cymbal-bikes.

A seguir

Em seguida, você vai fazer a integração com o modelo de embedding para gerar embeddings para as descrições de produtos, além de converter uma solicitação de pesquisa textual em um embedding para pesquisar produtos relevantes.

5. Trabalhar com embeddings

Gerar embeddings de vetores para descrições de produtos

Para que a pesquisa por similaridade funcione nos produtos, você precisa gerar embeddings para as descrições deles.

Com o EmbeddingsModel criado no esquema, essa é uma instrução DML UPDATE simples.

UPDATE products p1
SET productDescriptionEmbedding =
(SELECT embeddings.values from ML.PREDICT(MODEL EmbeddingsModel,
(SELECT productDescription as content FROM products p2 where p2.productId=p1.productId)))
WHERE categoryId=1;

Clique no botão run para atualizar as descrições dos produtos.

Observação:para cargas de trabalho mais sensíveis ao desempenho, é melhor gerar os embeddings usando ML.PREDICT em uma transação somente leitura e depois gravá-los no Spanner usando uma transação de leitura e gravação.

Como usar a pesquisa de vetores

Neste exemplo, você vai fornecer uma solicitação de pesquisa em linguagem natural usando uma consulta SQL. Essa consulta transforma a solicitação de pesquisa em um embedding e pesquisa resultados semelhantes com base nos embeddings armazenados das descrições do produto que foram gerados na etapa anterior.

-- Use Spanner's vector search, and integration with embedding and LLM models to
-- return items that are semantically relevant and available in inventory based on
-- real-time data.


SELECT productName, productDescription, inventoryCount, COSINE_DISTANCE(
productDescriptionEmbedding,
(   SELECT embeddings.values
FROM ML.PREDICT(
MODEL EmbeddingsModel,
(SELECT "I'd like to buy a starter bike for my 3 year old child" as content)
)
)
) as distance
FROM products
WHERE inventoryCount > 0
ORDER BY distance
LIMIT 5;

Clique no botão run para encontrar produtos semelhantes. Os resultados vão ficar assim:

Outros filtros são usados na consulta, por exemplo, ter interesse apenas em produtos que estão em estoque (inventoryCount > 0).

Resumo

Nesta etapa, você criou embeddings de descrições de produtos e um embedding de solicitações de pesquisa usando SQL, aproveitando a integração do Spanner com modelos na Vertex AI. Você também realizou uma pesquisa de vetor para encontrar produtos semelhantes que correspondam à solicitação de pesquisa.

Próximas etapas

Em seguida, vamos usar os resultados da pesquisa para alimentar um LLM e gerar uma resposta personalizada para cada produto.

6. Trabalhar com um LLM

O Spanner facilita a integração com modelos LLM fornecidos pela Vertex AI. Isso permite que os desenvolvedores usem SQL para interagir diretamente com LLMs, em vez de exigir que o aplicativo execute a lógica.

Por exemplo, temos os resultados da consulta SQL anterior do usuário "I'd like to buy a starter bike for my 3 year old child"..

O desenvolvedor quer fornecer uma resposta para cada resultado indicando se o produto é adequado para o usuário, usando o seguinte comando:

"Answer with ‘Yes' or ‘No' and explain why: Is this a good fit for me? I'd like to buy a starter bike for my 3 year old child"

Você pode usar esta consulta:

-- Use an LLM to analyze this list and provide a recommendation on whether each
-- product is a good fit for the user. We use the vector search and real time
-- inventory data to first filter the products to reduce the size of the prompt to
-- the LLM.
SELECT productName, productDescription, inventoryCount, content AS LLMResponse
FROM ML.PREDICT(
MODEL LLMModel,
(   SELECT
inventoryCount,
productName,
productDescription,
CONCAT(
"Answer with ‘Yes' or ‘No' and explain why: Is this a good fit for me?",
"I'd like to buy a starter bike for my 3 year old child \n",
"Product Name: ", productName, "\n",
"Product Description:", productDescription) AS prompt,
FROM products
WHERE inventoryCount > 0
ORDER by COSINE_DISTANCE(
productDescriptionEmbedding,
(   SELECT embeddings.values
FROM ML.PREDICT(
MODEL EmbeddingsModel,
( SELECT "I'd like to buy a starter bike for my 3 year old child" as content)
)
)
) LIMIT 5
),
STRUCT(256 AS maxOutputTokens)
);

Observação:fornecemos a mesma consulta da etapa anterior para o modelo LLM para gerar a lista de produtos para os quais queremos uma resposta.

Clique no botão run para emitir a consulta. Os resultados vão ficar assim:

O primeiro produto é adequado para crianças de 3 anos devido à faixa etária na descrição (de 2 a 4 anos). Os outros produtos não são adequados.

Resumo

Próximas etapas

A seguir, é hora de fazer a limpeza!

7. Limpeza (opcional)

Para fazer a limpeza, acesse a seção Cloud Spanner do console do Cloud e exclua a instância 'retail-demo' criada no codelab.

8. Parabéns!

Parabéns! Você realizou uma pesquisa por similaridade usando a pesquisa de vetores integrada do Spanner. Além disso, você viu como é fácil trabalhar com modelos LLM e embedding para fornecer funcionalidades de IA generativa diretamente usando SQL.

Qual é a próxima etapa?

Saiba mais sobre o recurso de vizinho mais próximo exato (pesquisa de vetor KNN) do Spanner aqui: https://cloud.google.com/spanner/docs/find-k-nearest-neighbors

Também é possível ler mais sobre como realizar previsões on-line com SQL usando a integração da Vertex AI do Spanner aqui: https://cloud.google.com/spanner/docs/ml