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-004.
• 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 criar o conjunto de dados, você precisa da permissão bigquery.datasets.create do Identity and Access Management (IAM).

• Para criar o recurso de conexão, você precisa das seguintes permissões do IAM:

  • bigquery.connections.create
  • bigquery.connections.get

• Para conceder permissões à conta de serviço da conexão, você precisa da seguinte permissão:

  • resourcemanager.projects.setIamPolicy

• Para criar o modelo, você precisa das seguintes permissões:

  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.connections.delegate

• Para executar a inferência, você precisa das seguintes permissões:

  • bigquery.models.getData
  • bigquery.jobs.create

Custos

Neste documento, você 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 uma avaliação gratuita.

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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Make sure 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 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.

Crie uma conexão

Crie uma Conexão de recursos do Cloud e tenha acesso ao ID da conta de serviço da conexão. Crie a conexão no mesmo local do conjunto de dados criado na etapa anterior.

Selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. Para criar uma conexão, clique em Adicionar e em Conexões com fontes de dados externas.

3. Na lista Tipo de conexão, selecione Modelos remotos da Vertex AI, funções remotas e BigLake (Cloud Resource).

4. No campo ID da conexão, insira um nome para a conexão.

5. Clique em Criar conexão.

6. Clique em Ir para conexão.

7. No painel Informações da conexão, copie o ID da conta de serviço para uso em uma etapa posterior.

bq

1. Em um ambiente de linha de comando, crie uma conexão:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   O parâmetro --project_id substitui o projeto padrão.

   Substitua:

   • REGION: sua região de conexão
   • PROJECT_ID: o ID do projeto do Google Cloud
   • CONNECTION_ID: um ID para sua conexão

   Quando você cria um recurso de conexão, o BigQuery cria uma conta de serviço do sistema exclusiva e a associa à conexão.

   Solução de problemas: se você receber o seguinte erro de conexão, atualize o SDK Google Cloud:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Recupere e copie o ID da conta de serviço para uso em uma etapa posterior:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   O resultado será assim:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

Anexe a seguinte seção ao seu arquivo main.tf.

 ## This creates a cloud resource connection.
 ## Note: The cloud resource nested object has only one output only field - serviceAccountId.
 resource "google_bigquery_connection" "connection" {
    connection_id = "CONNECTION_ID"
    project = "PROJECT_ID"
    location = "REGION"
    cloud_resource {}
}        

Substitua:

• CONNECTION_ID: um ID para sua conexão
• PROJECT_ID: o ID do projeto do Google Cloud
• REGION: sua região de conexão

Conceder permissões para a conta de serviço do portal

Para conceder à conta de serviço da conexão os papéis apropriados para acessar os serviços do Cloud Storage e da Vertex AI, siga estas etapas:

1. Acesse a página IAM e administrador.

   Acessar IAM e administrador

2. Clique em CONCEDER ACESSO.

3. No campo Novos principais, digite o ID da conta de serviço que você copiou anteriormente.

4. No menu Selecionar papel, escolha Vertex AI > Usuário da Vertex AI.

5. Clique em Salvar.

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

Crie um modelo remoto que represente um modelo text-embedding-004 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 `target_dataset.embedding_model`
     REMOTE WITH CONNECTION `LOCATION.CONNECTION_ID`
     OPTIONS (ENDPOINT = 'text-embedding-004');

   Substitua:

   • LOCATION: o local da conexão.
   • CONNECTION_ID: o ID da sua conexão do BigQuery.

     Quando você visualiza os detalhes da conexão no console do Google Cloud, esse é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo projects/myproject/locations/connection_location/connections/myconnection.

   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 faz a iteração 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 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_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.

Limpar

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código 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 passar por várias arquiteturas, tutoriais ou guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

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.