Comece a usar o Spanner para aplicações de IA generativa

Este tutorial demonstra como criar uma aplicação de IA generativa usando o Spanner e a Vertex AI.

Esta aplicação permite-lhe realizar uma pesquisa de semelhança semântica, o que lhe permite encontrar produtos que correspondem a uma consulta de linguagem natural. Consegue fazê-lo através da utilização de incorporações, que são representações numéricas de texto que captam o significado e o contexto das palavras. Vai usar um modelo da Vertex AI para gerar estas incorporações e, em seguida, armazená-las e pesquisá-las no Spanner. Esta abordagem é particularmente útil para exemplos de utilização como a pesquisa de produtos, em que os utilizadores podem descrever o que querem em linguagem natural em vez de palavras-chave específicas.

Os seguintes tópicos ajudam a saber como:

  1. Crie um Google Cloud projeto
  2. Crie uma instância do Spanner
  3. Crie uma base de dados
  4. Crie um modelo de incorporação
  5. Carregue dados no Spanner
  6. Gere incorporações para dados
  7. Realize uma pesquisa de similaridade de vetores KNN
  8. Ajuste a escala da pesquisa vetorial com um índice vetorial
  9. Limpe recursos

Para saber mais sobre os detalhes dos preços do Spanner, consulte o artigo Preços do Spanner.

Para experimentar um codelab, consulte o artigo Introdução à pesquisa vetorial do Spanner.

Antes de começar

Tem de criar um Google Cloud projeto associado a uma conta de faturação.

  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.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    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.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

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

  6. A API Spanner deve ser ativada automaticamente. Caso contrário, ative-o manualmente:

    Ative a API Spanner
  7. A API Vertex AI deve ser ativada automaticamente. Caso contrário, ative-o manualmente:

    Ative a API Vertex AI

    1. Para receber as autorizações de que precisa para criar instâncias e bases de dados, peça ao seu administrador para lhe conceder a função de IAM de administrador do Cloud Spanner (roles/spanner.admin) no seu projeto.

    1. Para receber as autorizações de que precisa para consultar gráficos do Spanner se não lhe for atribuída a função de administrador do Cloud Spanner, peça ao seu administrador para lhe atribuir a função do IAM Leitor da base de dados do Cloud Spanner (roles/spanner.databaseReader) no seu projeto.

    Crie uma instância

    Quando usa o Spanner pela primeira vez, tem de criar uma instância, que é uma atribuição de recursos usados pelas bases de dados do Spanner. Esta secção mostra como criar uma instância através da consola. Google Cloud

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

      Aceda ao Spanner

    2. Selecione ou crie um Google Cloud projeto, se ainda não o tiver feito.

    3. Efetue um dos seguintes passos:

      1. Se nunca criou uma instância do Spanner, na página Bem-vindo ao Spanner, clique em Criar uma instância aprovisionada.
      2. Se criou uma instância do Spanner, na página Instances, clique em Create instance.

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

      A pesquisa vetorial do Spanner só está disponível na edição Enterprise ou Enterprise Plus. Para comparar as diferentes edições, clique em Comparar edições. Para mais informações, consulte a Vista geral das edições do Spanner.

    5. Clique em Continuar.

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

    7. Em ID da instância, mantenha ou altere o ID da instância. O ID da instância é predefinido para o nome da instância, mas pode alterá-lo. O nome da instância e o ID da instância podem ser iguais ou diferentes.

    8. Clique em Continuar.

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

      1. Mantenha a opção Regional selecionada.
      2. Em Selecionar uma configuração, selecione uma região. A região que selecionar é onde as suas 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, selecione Unidades de processamento (PUs).
      2. Em Escolha um modo de dimensionamento, mantenha a opção Atribuição manual selecionada e, em Quantidade, mantenha 1000 unidades de processamento.

    11. Clique em Criar. A Google Cloud consola apresenta a página Vista geral da instância que criou.

    Crie uma base de dados

    Depois de a instância começar a ser executada, pode criar a base de dados. Define o esquema na base de dados .

    1. Na Google Cloud consola, aceda à página Instâncias do Spanner.

      Aceda às instâncias do Spanner

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

    3. Em Vista geral, abaixo do nome da instância, clique em Criar base de dados.

    4. Em Nome da base de dados, introduza um nome da base de dados. Por exemplo, example-db.

    5. Em Selecionar dialeto da base de dados, escolha SQL padrão da Google.

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

    6. Copie e cole o seguinte esquema no separador do editor Modelos 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 alterações em Mostrar opções de encriptação.

    8. Clique em Criar. Google Cloud A consola apresenta a página Vista geral da base de dados que criou.

    Crie um modelo de incorporação

    Quando usa a declaração DDL CREATE MODEL no Spanner, está a registar uma referência ao ponto final do modelo do Vertex AI a partir da sua base de dados. Depois de registar o modelo, pode usar a função ML.PREDICT para aceder ao modelo nas suas consultas.

    O exemplo seguinte demonstra como registar um modelo de incorporação de texto da Vertex AI, que é usado para realizar uma pesquisa de semelhanças para encontrar produtos semelhantes numa base de dados.

    1. Na página Vista geral da base de dados, clique em Spanner Studio.
    2. Na página Spanner Studio, clique em Novo separador ou use o separador do editor vazio.

    3. Introduza:

      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 o seguinte:

      • PROJECT_ID: um identificador permanente exclusivo do seu projeto Google Cloud .
      • TEXT_EMBEDDING_MODEL: o nome do modelo de incorporação de texto. Para ver uma lista dos modelos de incorporação de texto do Vertex AI, consulte o artigo Modelos suportados.

    4. Clique em Executar para criar o modelo.

      Depois de adicionar o modelo com êxito, este é apresentado no painel Explorador.

    Carregue dados

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

    1. Num novo separador no Spanner Studio, copie e cole a seguinte declaração 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);

    2. Clique em Executar para inserir os dados.

    Gere incorporações vetoriais

    Depois de registar um modelo e carregar dados para o Spanner, pode gerar incorporações de vetores com as descrições dos produtos dos seus dados. As incorporações vetoriais transformam dados de texto num valor numérico que capta o significado e o contexto das palavras. Esta transformação é fundamental para realizar uma pesquisa semântica.

    Neste passo, vai preencher a coluna productDescriptionEmbedding gerando incorporações a partir da coluna productDescription através da função ML.PREDICT. Isto permite-lhe fazer uma pesquisa de similaridade vetorial no passo seguinte.

    1. Num novo separador do Spanner Studio, copie e cole a seguinte declaraçã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 as incorporações.

    No exemplo seguinte, fornece um pedido de pesquisa em linguagem natural através de uma consulta SQL. A consulta SQL executa uma pesquisa de semelhança vetorial usando as incorporações de vetores que gerou anteriormente. A consulta realiza a pesquisa da seguinte forma:

    • Usa ML.PREDICT para gerar uma incorporação para a consulta de pesquisa fornecida ("Quero comprar uma bicicleta para principiantes para a minha criança de 3 anos").
    • Calcula a COSINE_DISTANCE entre esta 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 superior a 0.
    • Ordena os resultados pela distância calculada e devolve os cinco resultados mais próximos, juntamente com productName, productDescription e inventoryCount.

    1. Num novo separador 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 devolver os produtos que melhor correspondem ao texto de 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 de pesquisa vetorial anterior usa a pesquisa vetorial de K-vizinhos mais próximos (KNN) exata. As funções de distância vetorial KNN (distância de cossenos, distância euclidiana e produto escalar) são úteis quando pode consultar um subconjunto específico dos seus dados do Spanner. Uma vez que a pesquisa KNN calcula a distância exata entre um vetor de consulta e todos os vetores na base de dados, é eficiente quando pode particionar os dados. Se a sua consulta precisar de comparar o vetor de consulta com todos os vetores na sua base de dados sem filtros específicos e não conseguir dividir a consulta em subconsultas independentes, pode ter problemas de desempenho se usar o KNN. A pesquisa vetorial de vizinhos mais próximos aproximados (ANN) torna-se útil nestas situações. Para mais informações, consulte o artigo Encontre os vizinhos mais próximos aproximados.

    Se as suas cargas de trabalho não forem divisíveis em partições e tiver uma grande quantidade de dados, pode usar a pesquisa de vetores de ANN para aumentar o desempenho das consultas para conjuntos de dados maiores.

    Para dimensionar e usar a pesquisa vetorial de RNA em Spanner, faça o seguinte:

    Crie um índice vetorial

    O Spanner acelera as pesquisas de vetores de ANN através de um índice de vetores especializado que tira partido do Scalable Nearest Neighbor (ScaNN) da Google Research.

    Para criar um índice vetorial no conjunto de dados, tem de modificar a coluna productDescriptionEmbeddings para definir uma anotação vector_length. A anotação vector_length indica a dimensão de cada vetor. As seguintes declarações DDL eliminam a coluna productDescriptionEmbedding e recriam-na com a coluna vector_length. O comprimento máximo (dimensão) do vetor varia consoante o modelo de incorporação escolhido.

    1. Num novo separador no Spanner Studio, copie e cole a seguinte declaraçã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 de saída máximas do modelo de incorporação que escolheu.

    2. Clique em Executar.

    3. Copie e cole a seguinte declaração de inserção para voltar a gerar as incorporações de vetores:

      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 declaração DDL para criar o índice vetorial:

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

    6. Clique em Executar.

    Use a função de distância vetorial da ANN

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

    • Gere a incorporação do comando separadamente, em vez de na consulta SQL.
    • Copie os resultados das incorporações para a consulta.
    • Use a sugestão FORCE_INDEX para fazer referência ao novo índice vetorial: @{force_index=ProductDescriptionEmbeddingIndex}
    • Use a função de distância vetorial APPROX_COSINE_DISTANCE em vez de COSINE_DISTANCE. A opção JSON '{"num_leaves_to_search": num_leaves}' é obrigatória.

    1. Num novo separador do Spanner Studio, copie e cole a seguinte consulta para gerar a incorporação do comando:

      -- 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 embeddings.values.

    4. Substitua embedding na seguinte consulta pelo resultado da incorporação que copiou no passo 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 tem um aspeto semelhante ao seguinte:

      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 o seu APPROX_COSINE_DISTANCE de 0,30935457151661594, tem o grau de semelhança mais elevado com a consulta original.

      Para mais informações sobre a interpretação da relação entre as funções de vetor e a semelhança, consulte o artigo Escolha entre funções de distância vetorial para medir a semelhança de incorporações de vetores.

    Limpar

    Esta secção mostra-lhe como usar a Google Cloud consola para limpar os seus recursos. Para evitar cobranças adicionais na sua conta do Cloud Billing, elimine a base de dados e a instância que criou durante a configuração. A eliminação de uma instância elimina todas as bases de dados criadas na instância.

    Elimine a base de dados

    1. Na Google Cloud consola, aceda à página Instâncias do Spanner.

      Aceda às instâncias do Spanner

    2. Clique no nome da instância que tem a base de dados que quer eliminar, por exemplo, test-instance.

    3. Clique no nome da base de dados que quer eliminar, por exemplo, example-db.

    4. Na página Vista geral da base de dados, clique em Eliminar Eliminar base de dados.

    5. Confirme que quer eliminar a base de dados introduzindo o nome da base de dados e clicando em Eliminar.

    Elimine a instância

    1. Na Google Cloud consola, aceda à página Instâncias do Spanner.

      Aceda às instâncias do Spanner

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

    3. Clique em Eliminar instância.

    4. Confirme que quer eliminar a instância introduzindo o nome da instância e clicando em Eliminar.

    O que se segue?