Processar erros de cota chamando ML.GENERATE_EMBEDDING de maneira iterativa

Este tutorial mostra como usar o procedimento armazenado público bqutil.procedure.bqml_generate_embeddings do BigQuery para iterar chamadas para a função ML.GENERATE_EMBEDDING. Chamar a função de forma iterativa permite resolver erros que podem ser repetidos devido ao excesso de cotas e limites aplicáveis à a função.

Para revisar o código-fonte da procedura armazenada bqutil.procedure.bqml_generate_embeddings no GitHub, consulte bqml_generate_embeddings.sqlx. Para mais informações sobre o uso e os parâmetros de procedimentos armazenados, consulte a Arquivo README.

Este tutorial vai orientar você nas tarefas a seguir:

• Criar um modelo remoto em um modelo text-embedding-005.
• Iterar por chamadas para a função ML.GENERATE_EMBEDDING, usando o modelo remoto e a tabela de dados públicos bigquery-public-data.bbc_news.fulltext com o procedimento armazenado bqutil.procedure.bqml_generate_embeddings.

Permissões necessárias

Para seguir este tutorial, você precisa dos seguintes papéis do Identity and Access Management (IAM):

• Criar e usar conjuntos de dados, conexões e modelos do BigQuery: administrador do BigQuery (roles/bigquery.admin).
• Conceder permissões à conta de serviço da conexão: administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin).

Esses papéis predefinidos contêm as permissões necessárias para executar as tarefas neste documento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

• Criar um conjunto de dados: bigquery.datasets.create
• Criar, delegar e usar uma conexão: bigquery.connections.*
• Definir a conexão padrão: bigquery.config.*
• Definir permissões da conta de serviço: resourcemanager.projects.getIamPolicy e resourcemanager.projects.setIamPolicy
• Criar um modelo e executar a inferência:
  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Custos

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

• BigQuery ML: You incur costs for the data that you process in BigQuery.
• Vertex AI: You incur costs for calls to the Vertex AI model.

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.

Para mais informações sobre os preços do BigQuery, consulte Preços do BigQuery.

Para mais informações sobre os preços da Vertex AI, consulte Preços da Vertex AI.

Antes de começar

1. No Google Cloud console do, na página do seletor de projetos, escolha ou crie um Google Cloud projeto do.

   Papéis necessários para selecionar ou criar um projeto

   • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
   • Criar um projeto: para criar um projeto, você precisa do papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.
   Observação: se você não planeja manter os recursos criados neste procedimento, crie um projeto em vez de selecionar um projeto atual. Depois de concluir essas etapas, você poderá excluir o projeto, removendo todos os recursos associados a ele.

   Acessar o seletor de projetos

2. Verifique se o faturamento está ativado para o Google Cloud projeto.

3. Ative as APIs BigQuery, BigQuery Connection e Vertex AI.

   Funções necessárias para ativar APIs

   Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

   Ativar as APIs

crie um conjunto de dados

Crie um conjunto de dados do BigQuery para armazenar modelos e dados de amostra:

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

   Acessar a página do BigQuery

2. No painel Explorer, clique no nome do seu projeto.

3. Clique em Conferir ações > Criar conjunto de dados.

4. Na página Criar conjunto de dados, faça o seguinte:

   1. Para o código do conjunto de dados, insira target_dataset.

   2. Em Tipo de local, selecione Multirregião e EUA (várias regiões nos Estados Unidos).

   3. Mantenha as configurações padrão restantes e clique em Criar conjunto de dados.

Criar o modelo de geração de embedding de texto

Crie um modelo remoto que represente um modelo da Vertex AI text-embedding-005:

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

   Acessar o BigQuery

2. No editor de consultas, execute a seguinte instrução:

   CREATE OR REPLACE MODEL `target_dataset.embedding_model`
     REMOTE WITH CONNECTION DEFAULT
     OPTIONS (ENDPOINT = 'text-embedding-005');

   A consulta leva alguns segundos para ser concluída. Depois disso, o modelo embedding aparece no conjunto de dados sample no painel Explorer. Como a consulta usa uma instrução CREATE MODEL para criar um modelo, não há resultados de consulta.

Execute o procedimento armazenado

Execute o procedimento armazenado bqutil.procedure.bqml_generate_embeddings, que itera por chamadas para a função ML.GENERATE_EMBEDDING usando o modelo target_dataset.embedding_model e a tabela de dados públicos bigquery-public-data.bbc_news.fulltext:

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

   Acessar o BigQuery

2. No editor de consultas, execute a seguinte instrução:

   CALL `bqutil.procedure.bqml_generate_embeddings`(
       "bigquery-public-data.bbc_news.fulltext",            -- source table
       "PROJECT_ID.target_dataset.news_body_embeddings",  -- destination table
       "PROJECT_ID.target_dataset.embedding_model",       -- model
       "body",                                              -- content column
       ["filename"],                                        -- key columns
       '{}'                                                 -- optional arguments encoded as a JSON string
   );

   Substitua PROJECT_ID pelo ID do projeto do que você está usando neste tutorial.

   O procedimento armazenado cria uma tabela target_dataset.news_body_embeddings para conter a saída da função ML.GENERATE_EMBEDDING.

3. Quando a execução da consulta terminar, verifique se não há linhas na tabela target_dataset.news_body_embeddings que contêm um erro que permite uma nova tentativa. No editor de consultas, execute a seguinte instrução:

   SELECT *
   FROM `target_dataset.news_body_embeddings`
   WHERE ml_generate_embedding_status LIKE '%A retryable error occurred%';

   A consulta retorna a mensagem No data to display.

Liberar espaço

Atenção: a exclusão de um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

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

   Acessar "Gerenciar recursos"

2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir.
3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.