Como começar a usar o Spanner para aplicativos de IA generativa

Neste tutorial, mostramos como criar um aplicativo de IA generativa usando o Spanner e a Vertex AI.

Com esse aplicativo, você pode fazer pesquisas de similaridade semântica e encontrar produtos que correspondem a uma consulta em linguagem natural. Para isso, ela usa embeddings, que são representações numéricas de texto que capturam o significado e o contexto das palavras. Você vai usar um modelo da Vertex AI para gerar esses embeddings e, em seguida, armazenar e pesquisar os embeddings no Spanner. Essa abordagem é especialmente útil para casos de uso como a pesquisa de produtos, em que os usuários podem descrever o que querem em linguagem natural em vez de palavras-chave específicas.

Os tópicos a seguir ajudam você a aprender a:

  1. Criar um Google Cloud projeto
  2. Criar uma instância do Spanner
  3. Criar um banco de dados
  4. Criar um modelo de embedding
  5. Carregar dados no Spanner
  6. Gerar embeddings para dados
  7. Realizar pesquisa de similaridade de vetores KNN
  8. Escalonar a pesquisa vetorial com um índice vetorial
  9. Limpar recursos

Para saber mais sobre os preços do Spanner, consulte Preços do Spanner.

Para testar um codelab, consulte Começar a usar a pesquisa de vetor do Spanner.

Antes de começar

Crie um projeto Google Cloud conectado a uma conta de faturamento.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. A API Spanner será ativada automaticamente. Se não estiver, ative manualmente:

    Ativar a API Spanner
  7. A API Vertex AI será ativada automaticamente. Se não estiver, ative manualmente:

    Ative a API Vertex AI

    1. Para receber as permissões necessárias para criar instâncias e bancos de dados, peça ao administrador para conceder a você o papel do IAM de Administrador do Cloud Spanner (roles/spanner.admin) no seu projeto.

    1. Para ter as permissões necessárias para consultar gráficos do Spanner se você não tiver o papel de administrador do Cloud Spanner, peça ao administrador para conceder a você o papel do IAM de Leitor de banco de dados do Cloud Spanner (roles/spanner.databaseReader) no seu projeto.

    Criar uma instância

    Ao usar o Spanner pela primeira vez, é necessário criar uma instância, que é uma alocação de recursos usados pelos bancos de dados do Spanner. Esta seção mostra como criar uma instância usando o console Google Cloud .

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

      Acessar o Spanner

    2. Selecione ou crie um Google Cloud projeto, caso ainda não tenha feito isso.

    3. Escolha uma destas opções:

      1. Se você nunca criou uma instância do Spanner, na página Bem-vindo ao Spanner, clique em Criar uma instância provisionada.
      2. Se você já criou uma instância do Spanner, na página Instâncias, clique em Criar instância.

    4. Na página Selecionar uma edição, escolha Enterprise Plus ou Enterprise.

      A pesquisa vetorial do Spanner está disponível apenas nas edições Enterprise e Enterprise Plus. Para comparar as diferentes edições, clique em Comparar edições. Para mais informações, consulte a visão geral das edições do Spanner.

    5. Clique em Continuar.

    6. Em Nome da instância, insira um nome, por exemplo, test-instance.

    7. Em ID da instância, mantenha ou mude o ID da instância. O ID da instância é o mesmo que o nome dela por padrão, mas você pode mudar isso. O nome e o ID da instância podem ser iguais ou diferentes.

    8. Clique em Continuar.

    9. Em Escolher uma configuração, faça o seguinte:

      1. Mantenha a opção Regional selecionada.
      2. Em Selecionar uma configuração, escolha uma região. A região selecionada é onde as instâncias são armazenadas e replicadas.
      3. Clique em Continuar.

    10. Em Configurar capacidade de computação, faça o seguinte:

      1. Em Selecionar unidade, escolha Unidades de processamento (PUs).
      2. Em Escolher um modo de escalonamento, mantenha Alocação manual selecionada e, em Quantidade, mantenha 1.000 unidades de processamento.

    11. Clique em Criar. O console do Google Cloud mostra a página Visão geral da instância criada.

    Criar um banco de dados

    Depois que a instância começar a ser executada, você poderá criar seu banco de dados. Você define o esquema no banco de dados .

    1. No console Google Cloud , acesse a página Instâncias do Spanner.

      Acessar as instâncias do Spanner

    2. Clique na instância que você criou, por exemplo, test-instance.

    3. Em Visão geral, abaixo do nome da instância, clique em Criar banco de dados.

    4. Em Nome do banco de dados, insira um nome. Por exemplo, example-db.

    5. Em Selecionar dialeto do banco de dados, escolha SQL padrão do Google.

      A pesquisa vetorial do Spanner não está disponível no dialeto PostgreSQL.

    6. Copie e cole o seguinte esquema na guia do editor Modelos de DDL. O esquema define uma tabela Products.

        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);

    7. Não faça mudanças em Mostrar opções de criptografia.

    8. Clique em Criar.O console Google Cloud mostra a página Visão geral do banco de dados que você criou.

    Criar um modelo de embedding

    Ao usar a instrução DDL CREATE MODEL no Spanner, você registra uma referência ao endpoint do modelo da Vertex AI no seu banco de dados. Depois de registrar o modelo, use a função ML.PREDICT para acessar o modelo nas consultas.

    O exemplo a seguir demonstra como registrar um modelo de embedding de texto da Vertex AI, que é usado para realizar uma pesquisa de similaridade e encontrar produtos semelhantes em um banco de dados.

    1. Na página Visão geral do banco de dados, clique em Spanner Studio.
    2. Na página Spanner Studio, clique em Nova guia ou use a guia do editor vazia.

    3. Insira o seguinte:

      CREATE MODEL EmbeddingsModel INPUT(
content STRING(MAX),
) OUTPUT(
embeddings STRUCT<values ARRAY<FLOAT32>>,
) REMOTE OPTIONS (
endpoint = '//aiplatform.googleapis.com/projects/PROJECT_ID/locations/us-central1/publishers/google/models/TEXT_EMBEDDING_MODEL'
);

      Substitua:

      • PROJECT_ID: um identificador permanente exclusivo para seu projetoGoogle Cloud .
      • TEXT_EMBEDDING_MODEL: o nome do modelo de embedding de texto. Para conferir uma lista dos modelos de embedding de texto da Vertex AI, consulte Modelos compatíveis.

    4. Clique em Executar para criar o modelo.

      Depois que o modelo for adicionado, ele vai aparecer no painel Explorer.

    Carregar dados

    Para carregar os dados de amostra do Cymbal na tabela products, faça o seguinte:

    1. Em uma nova guia do Spanner Studio, copie e cole a seguinte instrução INSERT:

      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);

    2. Clique em Executar para inserir os dados.

    Gerar embeddings de vetor

    Depois de registrar um modelo e carregar dados no Spanner, você pode gerar embeddings de vetores com as descrições de produtos dos seus dados. Os embeddings de vetor transformam dados de texto em um valor numérico que captura o significado e o contexto das palavras. Essa transformação é crucial para realizar uma pesquisa semântica.

    Nesta etapa, você vai preencher a coluna productDescriptionEmbedding gerando embeddings da coluna productDescription usando ML.PREDICT. Isso permite que você faça uma pesquisa de similaridade vetorial na próxima etapa.

    1. Em uma nova guia do Spanner Studio, copie e cole a seguinte instrução de atualização:

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

    2. Clique em Executar para gerar os embeddings.

    No exemplo a seguir, você faz uma solicitação de pesquisa em linguagem natural usando uma consulta SQL. A consulta SQL realiza uma pesquisa de similaridade de vetor usando os embeddings de vetor gerados anteriormente. A consulta realiza a pesquisa fazendo o seguinte:

    • Usa ML.PREDICT para gerar um embedding para a consulta de pesquisa especificada ("Quero comprar uma bicicleta infantil para uma criança de 3 anos").
    • Calcula a COSINE_DISTANCE entre a incorporação de consulta e o productDescriptionEmbedding de cada produto na tabela de produtos para encontrar resultados semelhantes na sua loja Cymbal.
    • Filtra os resultados para incluir apenas produtos com um inventoryCount maior que 0.
    • Ordena os resultados pela distância calculada e retorna as cinco correspondências mais próximas, além de productName, productDescription e inventoryCount.

    1. Em uma nova guia do Spanner Studio, copie e cole a seguinte consulta:

      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;

    2. Clique em Executar para retornar os produtos que melhor correspondem ao texto da pesquisa.

      Exemplo de saída:

      /*-----------------+--------------------+----------------+--------------------*
| productName      | productDescription | inventoryCount | distance           |
+------------------+--------------------+----------------+--------------------+
| Cymbal Sprout    | Let their cycling  | 10             | 0.3094387191860244 |
|                  | journey begin with |                |                    |
|                  | the Cymbal Sprout, |                |                    |
|                  | the ideal balance  |                |                    |
|                  | bike for beginning |                |                    |
|                  | riders ages 2-4    |                |                    |
|                  | years...           |                |                    |
| Cymbal Spark Jr  | Light, vibrant,    | 34             | 0.3412342902117166 |
|                  | and ready for      |                |                    |
|                  | adventure, the     |                |                    |
|                  | Spark Jr. is the   |                |                    |
|                  | perfect first bike |                |                    |
|                  | for young riders   |                |                    |
|                  | (ages 5-8)...      |                |                    |
| Cymbal Helios    | Safety meets style | 100            | 0.4197863319656684 |
| Helmet           | with the Cymbal    |                |                    |
|                  | children's bike    |                |                    |
|                  | helmet...          |                |                    |
| Cymbal Breeze    | Cruise in style and| 72             | 0.485231776523978  |
|                  | embrace effortless |                |                    |
|                  | pedaling with the  |                |                    |
|                  | Breeze electric    |                |                    |
|                  | bike...            |                |                    |
| Cymbal Phoenix   | See and be seen    | 87             | 0.525101413779242  |
| Lights           | with the Phoenix   |                |                    |
|                  | bike lights...     |                |                    |
*------------------+--------------------+----------------+--------------------*/

    O exemplo anterior de pesquisa de vetor usa a pesquisa de vetor de vizinhos k-mais próximos (KNN). As funções de distância de vetor KNN (distância do cosseno, distância euclidiana e produto escalar) são úteis quando você pode consultar um subconjunto específico dos dados do Spanner. Como a pesquisa KNN calcula a distância exata entre um vetor de consulta e todos os vetores no banco de dados, ela é eficiente quando você pode particionar os dados. Se a consulta precisar comparar o vetor de consulta com todos os vetores no banco de dados sem filtros específicos e não for possível dividir a consulta em subconsultas independentes, você poderá ter gargalos de desempenho se usar o KNN. A pesquisa de vetores de vizinhos aproximados mais próximos (ANN) é útil nessas situações. Para mais informações, consulte Encontrar vizinhos mais próximos aproximados.

    Se as cargas de trabalho não puderem ser particionadas e você tiver uma grande quantidade de dados, use a pesquisa vetorial de ANN para aumentar a performance da consulta em conjuntos de dados maiores.

    Para escalonar e usar a pesquisa vetorial ANN no Spanner, faça o seguinte:

    Criar um índice vetorial

    O Spanner acelera as pesquisas de vetores ANN usando um índice vetorial especializado que aproveita o vizinho mais próximo escalonável (ScaNN) do Google Research.

    Para criar um índice de vetor no conjunto de dados, modifique a coluna productDescriptionEmbeddings para definir uma anotação vector_length. A anotação vector_length indica a dimensão de cada vetor. As instruções DDL a seguir descartam a coluna productDescriptionEmbedding e a recriam com o vector_length. O comprimento máximo (dimensão) do vetor varia de acordo com o modelo de embedding escolhido.

    1. Em uma nova guia do Spanner Studio, copie e cole a seguinte instrução DDL para recriar a coluna productDescriptionEmbedding:

      ALTER TABLE products DROP COLUMN productDescriptionEmbedding;
ALTER TABLE products
  ADD COLUMN productDescriptionEmbedding ARRAY<FLOAT32>(vector_length=>VECTOR_LENGTH_VALUE);

      Substitua VECTOR_LENGTH_VALUE pelas dimensões máximas de saída do modelo de incorporação escolhido.

    2. Clique em Executar.

    3. Copie e cole a seguinte instrução de inserção para regenerar as incorporações de vetor:

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

    4. Clique em Executar.

    5. Copie e cole a seguinte instrução DDL para criar o índice de vetor:

      CREATE VECTOR INDEX ProductDescriptionEmbeddingIndex
    ON products(productDescriptionEmbedding)
    WHERE productDescriptionEmbedding IS NOT NULL
OPTIONS (
distance_type = 'COSINE'
);

    6. Clique em Executar.

    Usar a função de distância do vetor ANN

    Para usar a pesquisa vetorial ANN no Spanner, modifique o seguinte na sua consulta SQL:

    • Gere o embedding de comando separadamente, em vez de dentro da consulta SQL.
    • Copie os resultados dos embeddings na consulta.
    • Use a dica FORCE_INDEX para referenciar o novo índice de vetores: @{force_index=ProductDescriptionEmbeddingIndex}
    • Use a função de distância de vetor APPROX_COSINE_DISTANCE em vez de COSINE_DISTANCE. A opção JSON '{"num_leaves_to_search": num_leaves}' é obrigatória.

    1. Em uma nova guia do Spanner Studio, copie e cole a consulta a seguir para gerar a incorporação de comandos:

      -- Generate the prompt embedding
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)
  );

    2. Clique em Executar.

    3. Copie o resultado do embeddings.values.

    4. Substitua embedding na consulta a seguir pelo resultado do embedding que você copiou na etapa anterior.

      -- Update embedding query using the vector index
SELECT productName, productDescription, inventoryCount,
  (APPROX_COSINE_DISTANCE(productDescriptionEmbedding,
  array<float32>[embedding],
  options => JSON '{\"num_leaves_to_search\": 10}')) as distance
FROM products @{force_index=ProductDescriptionEmbeddingIndex}
WHERE productDescriptionEmbedding IS NOT NULL AND inventoryCount > 0
ORDER BY distance
LIMIT 5;

      A nova consulta SQL é semelhante a esta:

      SELECT productName, productDescription, count,
  (APPROX_COSINE_DISTANCE(productDescriptionEmbedding,
    array<float32>[-0.00457216799,-0.0771846101,-0.0319350846,0.0352052487,-0.0457422845,0.0183265656...],
    options => JSON '{\"num_leaves_to_search\": 10}')) as distance
FROM products @{force_index=ProductDescriptionEmbeddingIndex}
WHERE productDescriptionEmbedding IS NOT NULL AND inventoryCount > 0
ORDER BY distance
LIMIT 5;

      Exemplo de saída:

      /*-----------------+--------------------+----------------+--------------------*
| productName      | productDescription | inventoryCount | distance           |
+------------------+--------------------+----------------+--------------------+
| Cymbal Sprout    | Let their cycling  | 10             | 0.30935457151661594|
|                  | journey begin with |                |                    |
|                  | the Cymbal Sprout, |                |                    |
|                  | the ideal balance  |                |                    |
|                  | bike for beginning |                |                    |
|                  | riders ages 2-4    |                |                    |
|                  | years...           |                |                    |
| Cymbal Spark Jr  | Light, vibrant,    | 34             | 0.34116496551593656|
|                  | and ready for      |                |                    |
|                  | adventure, the     |                |                    |
|                  | Spark Jr. is the   |                |                    |
|                  | perfect first bike |                |                    |
|                  | for young riders   |                |                    |
|                  | (ages 5-8)...      |                |                    |
| Cymbal Helios    | Safety meets style | 100            | 0.4198014303921187 |
| Helmet           | with the Cymbal    |                |                    |
|                  | children's bike    |                |                    |
|                  | helmet...          |                |                    |
| Cymbal Breeze    | Cruise in style and| 72             | 0.4850674854267337 |
|                  | embrace effortless |                |                    |
|                  | pedaling with the  |                |                    |
|                  | Breeze electric    |                |                    |
|                  | bike...            |                |                    |
| Cymbal Phoenix   | See and be seen    | 87             | 0.525101413779242  |
| Lights           | with the Phoenix   |                |                    |
|                  | bike lights...     |                |                    |
*------------------+--------------------+----------------+--------------------*/

      O Cymbal Sprout, com um APPROX_COSINE_DISTANCE de 0,30935457151661594, tem o maior grau de similaridade com a consulta original.

      Para mais informações sobre como interpretar a relação entre funções de vetor e similaridade, consulte Escolher entre funções de distância de vetor para medir a similaridade de embeddings de vetor.

    Limpar

    Nesta seção, mostramos como usar o console Google Cloud para limpar seus recursos. Para evitar cobranças adicionais na sua conta do Cloud Billing, exclua o banco de dados e a instância que você criou durante a configuração. A exclusão de uma instância exclui todos os bancos de dados criados nela.

    Excluir o banco de dados

    1. No console Google Cloud , acesse a página Instâncias do Spanner.

      Acessar as instâncias do Spanner

    2. Clique no nome da instância que tem o banco de dados que você quer excluir, por exemplo, test-instance.

    3. Clique no nome do banco de dados que você quer excluir, por exemplo, example-db.

    4. Na página Visão geral do banco de dados, clique em excluir Excluir banco de dados.

    5. Confirme que você quer excluir o banco de dados digitando o nome dele e clicando em Excluir.

    Excluir a instância

    1. No console Google Cloud , acesse a página Instâncias do Spanner.

      Acessar as instâncias do Spanner

    2. Clique no nome da instância que você quer excluir, por exemplo, test-instance.

    3. Clique em Excluir instância.

    4. Confirme que você quer excluir a instância digitando o nome dela e clicando em Excluir.

    A seguir