Processar erros de cota chamando ML.GENERATE_TEXT de forma iterativa

Este tutorial mostra como usar o procedimento armazenado público bqutil.procedure.bqml_generate_text do BigQuery para iterar chamadas para a função ML.GENERATE_TEXT. 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_text no GitHub, consulte bqml_generate_text.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 gemini-2.0-flash.
  • Iterar por chamadas para a função ML.GENERATE_TEXT, 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_text.

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).
  • Conceda 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.*
  • Defina a conexão padrão: bigquery.config.*
  • Defina as permissões da conta de serviço: resourcemanager.projects.getIamPolicy e resourcemanager.projects.setIamPolicy
  • Crie um modelo e execute 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 deste tutorial, use a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste gratuito.

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. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

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

  3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

    Enable the APIs

Criar um conjunto de dados

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

  1. No console do Google Cloud , 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 sample.

    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 texto

Crie um modelo remoto que represente um modelo gemini-2.0-flash da Vertex AI:

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

    Acessar o BigQuery

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

    CREATE OR REPLACE MODEL `sample.generate_text`
  REMOTE WITH CONNECTION DEFAULT
  OPTIONS (ENDPOINT = 'gemini-2.0-flash');

    A consulta leva alguns segundos para ser concluída. Depois disso, o modelo generate_text 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_text, que faz a iteração por chamadas para a função ML.GENERATE_TEXT usando o modelo sample.generate_text e a Tabela de dados públicos bigquery-public-data.bbc_news.fulltext:

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

    Acessar o BigQuery

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

    CALL `bqutil.procedure.bqml_generate_text`(
    "bigquery-public-data.bbc_news.fulltext",   -- source table
    "PROJECT_ID.sample.news_generated_text",  -- destination table
    "PROJECT_ID.sample.generate_text",        -- model
    "body",                                     -- content column
    ["filename"],                               -- key columns
    '{}'                                        -- optional arguments
);

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

    O procedimento armazenado cria uma tabela sample.news_generated_text para conter a saída da função ML.GENERATE_TEXT.

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

    SELECT *
FROM `sample.news_generated_text`
WHERE ml_generate_text_status LIKE '%A retryable error occurred%';

    A consulta retorna a mensagem No data to display.

Limpar

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.