Instruções e requisitos de configuração do laboratório
Proteja sua conta e seu progresso. Sempre use uma janela anônima do navegador e suas credenciais para realizar este laboratório.

Configuração da pesquisa vetorial no Spanner

Laboratório 15 minutos universal_currency_alt 5 créditos show_chart Introdutório
info Este laboratório pode incorporar ferramentas de IA para ajudar no seu aprendizado.
Este conteúdo ainda não foi otimizado para dispositivos móveis.
Para aproveitar a melhor experiência, acesse nosso site em um computador desktop usando o link enviado a você por e-mail.

GSP1288

Logotipo dos laboratórios autoguiados do Google Cloud

Visão geral

Imagine seus aplicativos pesquisando o banco de dados do Spanner e identificando rapidamente dados relacionados, mesmo que a fase de pesquisa fornecida não esteja incluída no texto armazenado. Agora isso é possível com os embeddings de texto da Vertex AI para fazer pesquisas vetoriais no Spanner.

O Spanner é um serviço de banco de dados totalmente gerenciado que oferece consistência transacional em escala global e replicação automática e síncrona para alta disponibilidade. Além disso, você pode usar a funcionalidade de inteligência artificial (IA) no Spanner se quiser realizar tarefas como criar aplicativos de IA generativa e acessar informações no banco de dados do Spanner com base na relevância para os termos de pesquisa específicos.

A pesquisa vetorial é uma metodologia útil para encontrar itens semelhantes com base no significado semântico, não na correspondência exata de palavra-chave. Ela pode ser aplicada a vários tipos de dados, incluindo áudio, imagens, vídeos e texto. No caso específico de texto, a pesquisa vetorial possibilita encontrar itens de texto semelhantes sem que o conteúdo deles corresponda exatamente à frase ou ao texto usados na busca.

Neste laboratório, vamos explicar as noções básicas de configuração da pesquisa vetorial no Spanner. Primeiro, você vai gerar e armazenar embeddings de texto (vetores que contêm representações numéricas do significado semântico do texto) e, depois, vai usar esses embeddings de texto para realizar pesquisas rápidas de similaridade. Este laboratório prático foi adaptado do codelab Introdução à pesquisa vetorial do Spanner e usa um conjunto de dados de produtos de bicicleta para destacar como a pesquisa vetorial pode ser usada no Spanner para encontrar os produtos mais relevantes para uma frase de pesquisa sem precisar de uma correspondência exata no texto.

Atividades deste laboratório

Neste laboratório, você vai aprender a:

  • Criar um modelo de embeddings no Spanner e configurá-lo para um endpoint de modelo da Vertex AI
  • Criar uma tabela e carregar dados no Spanner
  • Gerar e armazenar embeddings de texto no Spanner
  • Realizar a pesquisa vetorial no Spanner usando embeddings de texto

Configuração e requisitos

Antes de clicar no botão Começar o Laboratório

Leia estas instruções. Os laboratórios são cronometrados e não podem ser pausados. O timer é ativado quando você clica em Iniciar laboratório e mostra por quanto tempo os recursos do Google Cloud vão ficar disponíveis.

Este laboratório prático permite que você realize as atividades em um ambiente real de nuvem, e não em uma simulação ou demonstração. Você vai receber novas credenciais temporárias para fazer login e acessar o Google Cloud durante o laboratório.

Confira os requisitos para concluir o laboratório:

  • Acesso a um navegador de Internet padrão (recomendamos o Chrome).
Observação: para executar este laboratório, use o modo de navegação anônima (recomendado) ou uma janela anônima do navegador. Isso evita conflitos entre sua conta pessoal e de estudante, o que poderia causar cobranças extras na sua conta pessoal.
  • Tempo para concluir o laboratório: não se esqueça que, depois de começar, não será possível pausar o laboratório.
Observação: use apenas a conta de estudante neste laboratório. Se usar outra conta do Google Cloud, você poderá receber cobranças nela.

Como iniciar seu laboratório e fazer login no console do Google Cloud

  1. Clique no botão Começar o laboratório. Se for preciso pagar por ele, uma caixa de diálogo vai aparecer para você selecionar a forma de pagamento. No painel Detalhes do Laboratório, à esquerda, você vai encontrar o seguinte:

    • O botão Abrir Console do Google Cloud
    • O tempo restante
    • As credenciais temporárias que você vai usar neste laboratório
    • Outras informações, se forem necessárias

  2. Se você estiver usando o navegador Chrome, clique em Abrir console do Google Cloud ou clique com o botão direito do mouse e selecione Abrir link em uma janela anônima.

    O laboratório ativa os recursos e depois abre a página Fazer Login em outra guia.

    Dica: coloque as guias em janelas separadas lado a lado.

    Observação: se aparecer a caixa de diálogo Escolher uma conta, clique em Usar outra conta.

  3. Se necessário, copie o Nome de usuário abaixo e cole na caixa de diálogo Fazer login.

    {{{user_0.username | "Username"}}}

    Você também encontra o nome de usuário no painel Detalhes do Laboratório.

  4. Clique em Próxima.

  5. Copie a Senha abaixo e cole na caixa de diálogo de Olá.

    {{{user_0.password | "Password"}}}

    Você também encontra a senha no painel Detalhes do Laboratório.

  6. Clique em Próxima.

    Importante: você precisa usar as credenciais fornecidas no laboratório, e não as da sua conta do Google Cloud. Observação: se você usar sua própria conta do Google Cloud neste laboratório, é possível que receba cobranças adicionais.

  7. Acesse as próximas páginas:

    • Aceite os Termos e Condições.
    • Não adicione opções de recuperação nem autenticação de dois fatores (porque essa é uma conta temporária).
    • Não se inscreva em testes gratuitos.

Depois de alguns instantes, o console do Google Cloud será aberto nesta guia.

Observação: para acessar os produtos e serviços do Google Cloud, clique no Menu de navegação ou digite o nome do serviço ou produto no campo Pesquisar. Ícone do menu de navegação e campo de pesquisa

Tarefa 1: Criar um modelo de embeddings no Spanner e configurá-lo para um endpoint de modelo da Vertex AI

Uma instância do Spanner chamada cymbal-retail e um banco de dados chamado cymbal-bicycles foram provisionados para você neste ambiente de laboratório.

Nesta tarefa, você vai iniciar o fluxo de trabalho geral no Spanner criando e configurando o modelo de embeddings usado para gerar os embeddings de texto, o que também inicia automaticamente a criação da conta de serviço do Spanner necessária para tarefas posteriores. Especificamente, você vai criar um modelo de embeddings chamado EmbeddingsModel e configurá-lo para um endpoint do modelo de embeddings de texto da Vertex AI chamado .

  1. No console do Google Cloud, clique no Menu de navegação (Ícone do menu de navegação) > Ver todos os produtos. Em Bancos de dados, clique em Spanner.

  2. Na página Instâncias, clique na instância chamada Cymbal Retail Spanner Instance para examinar os detalhes da instância.

  3. Em Bancos de dados, clique no banco de dados chamado cymbal-bicycles.

  4. No menu do Spanner, em Banco de dados, clique em Spanner Studio.

  5. Na página do Spanner Studio, clique em Nova guia do editor de SQL para abrir uma nova janela de consulta.

  6. Para criar e configurar o modelo de embeddings para um endpoint de modelo da Vertex AI, copie e cole a consulta a seguir na janela de consulta e clique em Executar.

CREATE MODEL EmbeddingsModel INPUT( content STRING(MAX), ) OUTPUT( embeddings STRUCT<statistics STRUCT<truncated BOOL, token_count FLOAT32>, values ARRAY<FLOAT32>>, ) REMOTE OPTIONS ( endpoint = '//aiplatform.googleapis.com/projects/{{{project_0.project_id |Project ID}}}/locations/{{{project_0.default_region |Region}}}/publishers/google/models/{{{project_0.startup_script.gemini_embedding_model_id | model_name | disablehighlight }}}' );

Clique em Verificar meu progresso para conferir o objetivo. Criar um modelo de embeddings e configurá-lo para um endpoint de modelo da Vertex AI.

Quando a consulta for concluída, a mensagem Atualização concluída vai aparecer.

Permaneça no Spanner Studio e prossiga para a próxima tarefa.

Tarefa 2: Criar uma tabela e carregar os dados de produtos

Agora que você criou e configurou o modelo de embeddings, precisa dos dados para os quais quer gerar os embeddings de texto para a pesquisa vetorial.

Nesta tarefa, você vai criar uma tabela com colunas descritivas para produtos (como nomes de produtos e contagem de inventário) para uma empresa fictícia chamada Cymbal Bicycles, além de outra coluna para os embeddings de vetor das descrições dos produtos, que será gerada na próxima tarefa. Por fim, você vai carregar uma amostra dos dados de produtos da Cymbal Bicycles na tabela do Spanner.

  1. No editor de consultas do Spanner Studio, clique em Limpar (na mesma barra de menus onde fica a opção Executar) para remover a consulta anterior.

  2. Para criar uma tabela chamada products, copie e cole a consulta abaixo na janela e clique em Executar.

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

A coluna chamada productDescriptionEmbedding é do tipo ARRAY<FLOAT32>, que oferece armazenamento dos valores de vetor que você vai criar na próxima tarefa.

Quando a consulta for concluída, a mensagem Atualização concluída vai aparecer.

  1. Clique em Limpar novamente (na mesma barra de menus que Executar) para remover a consulta anterior.

  2. Para carregar dados na tabela, copie e cole a consulta abaixo na janela e clique em Executar.

Essa consulta carrega uma pequena amostra de produtos, mas inclui todas as informações necessárias para cada um dos 10 produtos carregados na tabela.

INSERT INTO products (categoryId, productId, productName, productDescription, createTime, inventoryCount, priceInCents) VALUES (1, 1, "Capacete Cymbal Helios", "Segurança e estilo com o capacete infantil Cymbal. O design leve, a ventilação superior e o ajuste personalizável garantem conforto e proteção em todos os passeios. Mantenha a criança protegida do sol com o Cymbal Helios!", PENDING_COMMIT_TIMESTAMP(), 100, 10999), (1, 2, "Cymbal Sprout", "Uma jornada de ciclismo divertida começa com a Cymbal Sprout, a bicicleta de equilíbrio ideal para iniciantes de 2 a 4 anos. O quadro leve, a altura baixa do assento e os pneus à prova de furos promovem estabilidade e confiança enquanto as crianças aprendem a se equilibrar na bicicleta. As crianças vão se divertir com a Cymbal Sprout!", PENDING_COMMIT_TIMESTAMP(), 10, 13999), (1, 3, "Cymbal Spark Jr.", "Leve, vibrante e pronta para a aventura, a Spark Jr. é a primeira bicicleta perfeita para jovens ciclistas (de 5 a 8 anos). A estrutura resistente, os freios fáceis de usar e os pneus resistentes a furos inspiram confiança e diversão sem fim. Deixe a faísca do ciclismo acender com a Cymbal!", PENDING_COMMIT_TIMESTAMP(), 34, 13900), (1, 4, "Cymbal Summit", "A mountain bike Summit é perfeita para desbravar trilhas. O quadro de alumínio leve, a suspensão responsiva e os freios a disco potentes oferecem controle e conforto excepcionais para ciclistas experientes que enfrentam subidas rochosas ou descidas íngremes. Alcance novos patamares com a Cymbal Summit!", PENDING_COMMIT_TIMESTAMP(), 0, 79999), (1, 5, "Cymbal Breeze", "Passeie com estilo e pedale sem esforço com a bicicleta elétrica Breeze. O motor silencioso e a bateria de longa duração permitem que você conquiste subidas e distâncias com facilidade. Faça passeios, desloque-se ou trabalhe com mais confiança com a Cymbal Breeze!", PENDING_COMMIT_TIMESTAMP(), 72, 129999), (1, 6, "Mochila Cymbal Trailblazer", "Leve tudo o que você precisa com estilo com a mochila Trailblazer. O material resistente à água, os vários compartimentos e as alças confortáveis mantêm seus equipamentos organizados e acessíveis, permitindo que você se concentre na aventura. Desbrave novas trilhas com a Cymbal Trailblazer!", PENDING_COMMIT_TIMESTAMP(), 24, 7999), (1, 7, "Luzes Cymbal Phoenix", "Seja visto com as luzes de bicicleta Phoenix. LEDs potentes e vários modos de luz garantem visibilidade superior, aumentando sua segurança e diversão durante passeios diurnos ou noturnos. Ilumine sua jornada com a Cymbal Phoenix!", PENDING_COMMIT_TIMESTAMP(), 87, 3999), (1, 8, "Bomba Cymbal Windstar", "Os pneus vazios não têm vez com a bomba Windstar. O design compacto, a construção leve e a capacidade de alta pressão facilitam e agilizam o enchimento de pneus. Volte à estrada em pouco tempo com a Cymbal Windstar!", PENDING_COMMIT_TIMESTAMP(), 36, 24999), (1, 9,"Kit de ferramentas Cymbal Odyssey","Esteja preparado para tudo com o kit de ferramentas Odyssey. Esse gadget prático tem ferramentas essenciais como chaves de fenda, chaves Allen e alavancas de pneu, permitindo que você faça pequenos reparos e ajustes em qualquer lugar. Conquiste sua jornada com a Cymbal Odyssey!", PENDING_COMMIT_TIMESTAMP(), 52, 999), (1, 10,"Garrafa de água Cymbal Nomad","Mantenha-se hidratado em todos os passeios com a garrafa de água Nomad. Com design elegante, fabricada sem BPA e tampa com trava de segurança, ela é a companhia perfeita para manter a hidratação e a motivação durante suas aventuras. Hidrate-se e conheça lugares com a Cymbal Nomad!", PENDING_COMMIT_TIMESTAMP(), 42, 1299);

Quando a consulta for concluída, a mensagem Esta instrução inseriu 10 linhas e não retornou nenhuma vai aparecer.

Clique em Verificar meu progresso para conferir o objetivo. Crie uma tabela e carregue os dados dos produtos.

Tarefa 3: Gerar e armazenar embeddings de texto para os dados de produtos

Com a criação do modelo de embeddings na Tarefa 1, você também iniciou a criação da conta de serviço do Spanner usada para acessar o modelo de embeddings pelo endpoint do modelo da Vertex AI.

Nesta tarefa, você vai começar verificando se essa conta de serviço tem o papel necessário para acessar o endpoint da Vertex AI. Em seguida, você executa uma consulta para gerar os embeddings das descrições dos produtos e os armazena na tabela products.

Conceder o papel de agente de serviço da API Cloud Spanner à conta de serviço do Spanner

  1. No console do Google Cloud, em Menu de navegação (Ícone do menu de navegação), selecione IAM e administrador > IAM.

  2. Clique em Conceder acesso.

  3. Em Novos principais, insira o ID da conta de serviço do Spanner: service-@gcp-sa-spanner.iam.gserviceaccount.com

Observação : se você não vir essa conta de serviço, pode ser que ela ainda não tenha sido provisionada após a Tarefa 1. Feche esta janela e aguarde 3 minutos antes de repetir as etapas 2 e 3.

  1. Em Selecionar um papel, pesquise Agente de serviço da API Cloud Spanner usando o filtro e selecione essa opção para preencher a caixa Papel.

  2. Clique em Salvar.

Observação: se você receber a mensagem Nenhuma alteração: o principal já existe na política, você pode prosseguir para a próxima seção sem tentar conceder o papel novamente.

Atualizar a coluna productDescriptionEmbedding para armazenar os embeddings de texto gerados

Agora que você verificou se a conta de serviço do Spanner tem o papel apropriado, é possível gerar os embeddings de texto para as descrições dos produtos e adicioná-los à tabela products.

  1. Volte ao Spanner Studio seguindo as etapas 1 a 4 da Tarefa 1.

  2. Copie e cole a consulta abaixo na janela para atualizar a coluna productDescriptionEmbedding com os embeddings gerados e clique em Executar.

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; Observação: se você receber uma mensagem de erro semelhante a Permissão negada no recurso, aguarde alguns minutos para que as permissões atribuídas nas etapas anteriores sejam totalmente propagadas e execute a consulta novamente.

Quando a consulta for concluída, a mensagem 10 linhas atualizadas pela sua consulta vai aparecer.

Clique em Verificar meu progresso para conferir o objetivo. Gere e armazene os embeddings de texto para os dados de produtos.

Permaneça no Spanner Studio e prossiga para a próxima tarefa.

Tarefa 4: Realizar a pesquisa vetorial usando embeddings de texto no Spanner

Depois de gerar e armazenar os embeddings de texto para as descrições de produtos, seus dados estarão prontos para a primeira pesquisa vetorial em tempo real.

Nesta tarefa, você vai executar uma consulta para realizar uma pesquisa de similaridade com base na frase Quero comprar uma bicicleta para iniciantes para meu filho de 3 anos, retornando os 5 produtos mais relevantes, mesmo que não haja uma correspondência exata para o texto em questão nos dados do produto.

  1. No editor de consultas do Spanner Studio, clique em Limpar (na mesma barra de menus onde fica a opção Executar) para remover a consulta anterior.

  2. Para realizar uma pesquisa vetorial usando embeddings de texto, copie e cole a consulta abaixo na janela e clique em Executar.

SELECT productName, productDescription, inventoryCount, COSINE_DISTANCE( productDescriptionEmbedding, ( SELECT embeddings.values FROM ML.PREDICT( MODEL EmbeddingsModel, (SELECT "Quero comprar uma bicicleta para iniciantes para meu filho de 3 anos" as content) ) ) ) as distance FROM products WHERE inventoryCount > 0 ORDER BY distance LIMIT 5;

Essa consulta usa os valores na coluna productDescriptionEmbedding para encontrar as 5 linhas de banco de dados mais semelhantes à frase de pesquisa Quero comprar uma bicicleta para iniciantes para meu filho de 3 anos do ponto de vista semântico.

O embedding para a fase de pesquisa é gerado dinamicamente na consulta. Fique à vontade para explorar melhor essa consulta substituindo Quero comprar uma bicicleta para iniciantes para meu filho de 3 anos no código acima por um novo termo de pesquisa.

A saída será assim:

productName productDescription inventoryCount distance
Cymbal Sprout Uma jornada de ciclismo divertida começa com a Cymbal Sprout, a bicicleta de equilíbrio ideal para iniciantes de 2 a 4 anos. 10 0.3094387191860244
Cymbal Spark Jr. Leve, vibrante e pronta para a aventura, a Spark Jr. é a primeira bicicleta perfeita para jovens ciclistas (de 5 a 8 anos). 34 0.3412342902117166
Capacete Cymbal Helios Segurança e estilo com o capacete infantil Cymbal. 100 0.4197863319656684
Cymbal Breeze Passeie com estilo e pedale sem esforço com a bicicleta elétrica Breeze. 72 0.485231776523978
Luzes Cymbal Phoenix Seja visto com as luzes de bicicleta Phoenix. 87 0.5251486508206732

Clique em Verificar meu progresso para conferir o objetivo. Realizar a pesquisa vetorial usando embeddings de texto no Spanner.

Parabéns!

Neste laboratório, você aprendeu a criar um modelo de embeddings no Spanner e a configurá-lo para um endpoint de modelo da Vertex AI, gerar e armazenar embeddings de texto em uma tabela do Spanner e realizar pesquisas vetoriais no Spanner usando os embeddings de texto armazenados.

Próximas etapas / Saiba mais

Treinamento e certificação do Google Cloud

Esses treinamentos ajudam você a aproveitar as tecnologias do Google Cloud ao máximo. Nossas aulas incluem habilidades técnicas e práticas recomendadas para ajudar você a alcançar rapidamente o nível esperado e continuar sua jornada de aprendizado. Oferecemos treinamentos que vão do nível básico ao avançado, com opções de aulas virtuais, sob demanda e por meio de transmissões ao vivo para que você possa encaixá-las na correria do seu dia a dia. As certificações validam sua experiência e comprovam suas habilidades com as tecnologias do Google Cloud.

Manual atualizado em 28 de outubro de 2025

Laboratório testado em 28 de outubro de 2025

Copyright 2026 Google LLC. Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de produtos e empresas podem ser marcas registradas das respectivas empresas a que estão associados.

Antes de começar

  1. Os laboratórios criam um projeto e recursos do Google Cloud por um período fixo
  2. Os laboratórios têm um limite de tempo e não têm o recurso de pausa. Se você encerrar o laboratório, vai precisar recomeçar do início.
  3. No canto superior esquerdo da tela, clique em Começar o laboratório

Usar a navegação anônima

  1. Copie o nome de usuário e a senha fornecidos para o laboratório
  2. Clique em Abrir console no modo anônimo

Fazer login no console

  1. Faça login usando suas credenciais do laboratório. Usar outras credenciais pode causar erros ou gerar cobranças.
  2. Aceite os termos e pule a página de recursos de recuperação
  3. Não clique em Terminar o laboratório a menos que você tenha concluído ou queira recomeçar, porque isso vai apagar seu trabalho e remover o projeto

Este conteúdo não está disponível no momento

Você vai receber uma notificação por e-mail quando ele estiver disponível

Ótimo!

Vamos entrar em contato por e-mail se ele ficar disponível

Um laboratório por vez

Confirme para encerrar todos os laboratórios atuais e iniciar este

Use a navegação anônima para executar o laboratório

A melhor maneira de executar este laboratório é usando uma janela de navegação anônima ou privada. Isso evita conflitos entre sua conta pessoal e a conta de estudante, o que poderia causar cobranças extras na sua conta pessoal.