Fazer previsões com modelos PyTorch no formato ONNX

O Open Neural Network Exchange (ONNX) fornece um formato uniforme projetado para representar qualquer framework de machine learning. O suporte do BigQuery ML para ONNX permite que você:

• Treine um modelo usando seu framework favorito.
• Converta o modelo no formato de modelo ONNX.
• Importe o modelo ONNX para o BigQuery e faça previsões usando o BigQuery ML.

Neste tutorial, mostramos como importar modelos ONNX treinados com PyTorch em um conjunto de dados do BigQuery e usá-los para fazer previsões a partir de uma consulta SQL.

Importante: você precisa ter uma reserva para executar previsões usando modelos importados e tabelas de objetos. Para mais informações, consulte as Limitações em modelos ONNX importados.

Objetivos

• Importe um modelo pré-treinado usando o PyTorch.
• Converta o modelo para o formato ONNX usando torch.onnx.
• Use a instrução CREATE MODEL para importar o modelo ONNX para o BigQuery.
• Use a função ML.PREDICT para fazer previsões com o modelo ONNX importado.

Custos

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

• BigQuery
• BigQuery ML
• Cloud Storage

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 sem custo financeiro.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Para mais informações, consulte Limpeza.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

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

2. Ative as APIs BigQuery, BigQuery Connection e Cloud Storage.

   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

3. Verifique se você tem as permissões necessárias para realizar as tarefas neste documento.

Funções exigidas

Se você criar um projeto, será o proprietário dele e terá todas as permissões necessárias do Identity and Access Management (IAM) para concluir este tutorial.

Se você estiver usando um projeto atual, faça o seguinte:

Verifique se você tem os seguintes papéis no projeto:

• Administrador do BigQuery Studio (roles/bigquery.studioAdmin)
• Administrador de conexão do BigQuery (roles/bigquery.connectionAdmin)
• Administrador do Storage (roles/storage.admin)

Verificar os papéis

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

   Acessar IAM
2. Selecione o projeto.

3. Na coluna Principal, encontre todas as linhas que identificam você ou um grupo no qual você está incluído. Para saber em quais grupos você está incluído, entre em contato com o administrador.

4. Em todas as linhas que especificam ou incluem você, verifique a coluna Papel para ver se a lista de papéis inclui os papéis necessários.

Conceder os papéis

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

   Acessar IAM
2. Selecione o projeto.
3. Clique em Conceder acesso.

4. No campo Novos principais, digite seu identificador de usuário. Normalmente, é o endereço de e-mail de uma Conta do Google.

5. Clique em Selecionar um papel e pesquise o papel.
6. Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
7. Clique em Salvar.

Para mais informações sobre as permissões do IAM no BigQuery, consulte Permissões do IAM.

Opcional: treinar um modelo e convertê-lo para o formato ONNX

Os exemplos de código a seguir mostram como importar um modelo de classificação pré-treinado para o PyTorch e como converter o modelo resultante no formato ONNX. Este tutorial usa um modelo de exemplo pré-criado armazenado em gs://cloud-samples-data/bigquery/ml/onnx/resnet18.onnx. Não é necessário concluir essas etapas se você estiver usando o modelo de amostra.

Criar um modelo de visão PyTorch para classificação de imagens

Use o exemplo de código a seguir para importar um modelo resnet18 pré-treinado do PyTorch que aceita dados de imagem decodificados retornados pelas funções do BigQuery ML ML.DECODE_IMAGE e ML.RESIZE_IMAGE.

import torch
import torch.nn as nn

# Define model input format to match the output format of
# ML.DECODE_IMAGE function: [height, width, channels]
dummy_input = torch.randn(1, 224, 224, 3, device="cpu")

# Load a pretrained pytorch model for image classification
model = torch.hub.load('pytorch/vision:v0.10.0', 'resnet18', pretrained=True)

# Reshape input format from [batch_size, height, width, channels]
# to [batch_size, channels, height, width]
class ReshapeLayer(nn.Module):
    def __init__(self):
        super().__init__()

    def forward(self, x):
        x = x.permute(0, 3, 1, 2)  # reorder dimensions
        return x

class ArgMaxLayer(nn.Module):
    def __init__(self):
        super().__init__()

    def forward(self, x):
       return torch.argmax(x, dim=1)

final_model = nn.Sequential(
    ReshapeLayer(),
    model,
    nn.Softmax(),
    ArgMaxLayer()
)

Converter o modelo no formato ONNX

Use o exemplo a seguir para exportar o modelo de visão PyTorch usando torch.onnx. O arquivo ONNX exportado é chamado de resnet18.onnx.

torch.onnx.export(final_model,            # model being run
                  dummy_input,            # model input
                  "resnet18.onnx",        # where to save the model
                  opset_version=10,       # the ONNX version to export the model to
                  input_names = ['input'],         # the model's input names
                  output_names = ['class_label'])  # the model's output names

Faça o upload do modelo ONNX para o Cloud Storage.

Depois de salvar o modelo, faça o seguinte:

• Crie um bucket do Cloud Storage para armazenar o modelo.
• Faça upload do modelo ONNX para seu bucket do Cloud Storage.

crie um conjunto de dados

Crie um conjunto de dados do BigQuery para armazenar seu modelo de ML.

Console

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:

   • Para o código do conjunto de dados, insira bqml_tutorial.

   • Em Tipo de local, selecione Multirregião e EUA.

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

bq

Para criar um conjunto de dados, use o comando bq mk --dataset.

1. Crie um conjunto de dados chamado bqml_tutorial com o local dos dados definido como US.

   bq mk --dataset \
     --location=US \
     --description "BigQuery ML tutorial dataset." \
     bqml_tutorial

2. Confirme se o conjunto de dados foi criado:

   bq ls

API

Chame o método datasets.insert com um recurso de conjunto de dados definido.

{
  "datasetReference": {
     "datasetId": "bqml_tutorial"
  }
}

Importar o modelo ONNX para o BigQuery

As etapas a seguir mostram como importar o modelo ONNX de exemplo do Cloud Storage para seu conjunto de dados usando uma instrução CREATE MODEL.

Console

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

   Acessar o BigQuery Studio

2. No editor de consultas, insira a seguinte instrução CREATE MODEL.

   CREATE OR REPLACE MODEL `bqml_tutorial.imported_onnx_model`
    OPTIONS (MODEL_TYPE='ONNX',
     MODEL_PATH='BUCKET_PATH')

   Substitua BUCKET_PATH pelo caminho para o modelo que você fez upload para o Cloud Storage. Se você estiver usando o modelo de exemplo, substitua BUCKET_PATH pelo seguinte valor: gs://cloud-samples-data/bigquery/ml/onnx/resnet18.onnx.

   Quando a operação for concluída, uma mensagem semelhante a esta será exibida: Successfully created model named imported_onnx_model.

   Seu novo modelo vai aparecer no painel Recursos. Os modelos são indicados pelo ícone: Se você selecionar o novo modelo no painel Recursos, as informações sobre o modelo vão aparecer ao lado do Editor de consultas.

   

bq

1. Importe o modelo ONNX do Cloud Storage inserindo a seguinte instrução CREATE MODEL.

   bq query --use_legacy_sql=false \
   "CREATE OR REPLACE MODEL
     `bqml_tutorial.imported_onnx_model`
   OPTIONS
     (MODEL_TYPE='ONNX',
      MODEL_PATH='BUCKET_PATH')"

   Substitua BUCKET_PATH pelo caminho para o modelo que você fez upload para o Cloud Storage. Se você estiver usando o modelo de exemplo, substitua BUCKET_PATH por este valor: gs://cloud-samples-data/bigquery/ml/onnx/resnet18.onnx.

2. Depois de importar o modelo, verifique se ele aparece no conjunto de dados.

   bq ls -m bqml_tutorial

   O resultado será o seguinte:

   tableId               Type
   --------------------- -------
   imported_onnx_model  MODEL

Para mais informações sobre como importar modelos ONNX para o BigQuery, incluindo requisitos de formato e armazenamento, consulte A instrução CREATE MODEL para importar modelos ONNX.

Criar uma tabela de objetos no BigQuery para analisar dados de imagem

Uma tabela de objetos é uma tabela somente leitura sobre objetos de dados não estruturados que residem no Cloud Storage. Com as tabelas de objetos, é possível analisar dados não estruturados do BigQuery.

Neste tutorial, você vai usar a função ML.PREDICT para gerar o rótulo de classe previsto de uma imagem de entrada armazenada em um bucket do Cloud Storage.

Para criar a tabela de objetos, faça o seguinte:

• Crie um bucket do Cloud Storage e faça upload de uma imagem de um peixe dourado.
• Crie uma conexão a recursos do Cloud usada para acessar a tabela de objetos.
• Conceda acesso à conta de serviço da conexão de recursos.

Criar um bucket e fazer upload de uma imagem

Siga estas etapas para criar um bucket do Cloud Storage e fazer upload de uma imagem de um peixe dourado.

Console

Observação: ao criar um bucket usando o console Google Cloud , você só precisa definir um nome globalmente exclusivo para o bucket. Todas as outras etapas são opcionais ou têm configurações padrão.

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

   Acesse Buckets

2. Clique em Criar.

3. Na página Criar um bucket, insira as informações do seu bucket.

   1. Na seção Começar, faça o seguinte:

      1. Na caixa, digite bqml_images.

      2. Clique em Continuar.

   2. Na seção Escolha onde armazenar seus dados, faça o seguinte:

      1. Em Tipo de local, selecione Multirregional.

      2. No menu do tipo de local, selecione EUA (várias regiões nos Estados Unidos).

      3. Clique em Continuar.

   3. Na seção Escolher uma classe de armazenamento para os dados:

      1. Selecione Definir uma classe padrão.

      2. Selecione Standard.

      3. Clique em Continuar.

   4. Nas outras seções, deixe os valores padrão.

4. Clique em Criar.

Linha de comando

Digite este comando gcloud storage buckets create:

gcloud storage buckets create gs://bqml_images --location=us

Se a solicitação for bem-sucedida, o comando retornará a seguinte mensagem:

Creating gs://bqml_images/...

Fazer upload de uma imagem para o bucket do Cloud Storage

Depois que o bucket for criado, faça o download de uma imagem de um peixe dourado e faça upload dela para o bucket do Cloud Storage.

Siga estas etapas para fazer upload da imagem:

Console

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

   Acessar buckets

2. Na lista de buckets, clique em bqml_images.

3. Na guia Objetos do bucket, faça o seguinte:

   • Arraste o arquivo da área de trabalho ou do gerenciador de arquivos para o painel principal no console do Google Cloud .

   • Clique em Fazer upload > Fazer upload de arquivos, selecione o arquivo de imagem que você quer enviar na caixa de diálogo exibida e clique em Abrir.

Linha de comando

Digite este comando gcloud storage cp:

gcloud storage cp OBJECT_LOCATION gs://bqml_images/IMAGE_NAME

Substitua:

• OBJECT_LOCATION: o caminho local para o arquivo de imagem. Por exemplo, Desktop/goldfish.jpg.
• IMAGE_NAME: o nome da imagem. Por exemplo, goldfish.jpg.

Se a operação for bem-sucedida, a resposta será semelhante a esta:

Completed files 1/1 | 164.3kiB/164.3kiB

Criar uma conexão a recursos do Cloud do BigQuery

Você precisa ter uma conexão a recursos do Cloud para se conectar à tabela de objetos que será criada mais adiante neste tutorial.

Com as conexões de recursos do Google Cloud, é possível consultar dados armazenados fora do BigQuery em serviços do Google Cloud, como Cloud Storage ou Spanner, ou em fontes de terceiros, como AWS ou Azure. Google Cloud Essas conexões externas usam a API BigQuery Connection.

Siga estas etapas para criar sua conexão a recursos do Cloud.

Console

1. Acesse a página do BigQuery Studio.

   Acessar o BigQuery Studio

2. No painel à esquerda, clique em Explorer:

   

   Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

3. No painel Explorer, clique em Adicionar dados.

   A caixa de diálogo Adicionar dados é aberta.

4. No painel Filtrar por, na seção Tipo de fonte de dados, selecione Bancos de dados.

   Como alternativa, no campo Pesquisar fontes de dados, insira Vertex AI.

5. Na seção Fontes de dados em destaque, clique em Vertex AI.

6. Clique no card da solução Modelos da Vertex AI: federação do BigQuery.

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

8. No campo ID da conexão, insira bqml_tutorial.

9. Verifique se a opção Multirregião — EUA está selecionada.

10. Clique em Criar conexão.

11. Na parte de baixo da janela, clique em Acessar a conexão. Outra opção é clicar em Conexões no painel Explorador e depois em us.bqml_tutorial.

12. No painel Informações da conexão, copie o ID da conta de serviço. Você precisa desse ID ao configurar as permissões da 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.

bq

1. Criar uma conexão

   bq mk --connection --location=US --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE bqml_tutorial

   Substitua PROJECT_ID pelo ID do projetoGoogle Cloud . O parâmetro --project_id substitui o projeto padrã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.us.bqml_tutorial

   O resultado será o seguinte:

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

Configurar o acesso à conexão

Conceda o papel de administrador de objetos do Storage à conta de serviço da conexão a recursos do Cloud. Conceda essa função no mesmo projeto em que você fez upload dos arquivos de imagem.

Observação: se a conexão estiver em um projeto diferente, este erro será retornado: [e-mail] does not have the permission to access resource.

Para conceder o papel, siga estas etapas:

1. Acessar a página AM e administrador

   Acessar IAM e administrador

2. Clique em Conceder acesso.

3. No campo Novos principais, insira o ID da conta de serviço da conexão de recurso do Cloud que você copiou anteriormente.

4. No campo Selecionar um papel, escolha Cloud Storage e selecione Administrador de objetos do Storage.

5. Clique em Salvar.

Criar a tabela de objetos

Siga estas etapas para criar uma tabela de objetos chamada goldfish_image_table usando a imagem dourada que você enviou ao Cloud Storage.

Console

1. Acesse a página do BigQuery Studio.

   Acessar o BigQuery Studio

2. No editor de consultas, insira esta consulta para criar a tabela de objetos.

   CREATE EXTERNAL TABLE `bqml_tutorial.goldfish_image_table`
   WITH CONNECTION `us.bqml_tutorial`
   OPTIONS(
   object_metadata = 'SIMPLE',
   uris = ['gs://bqml_images/IMAGE_NAME'],
   max_staleness = INTERVAL 1 DAY,
   metadata_cache_mode = 'AUTOMATIC');

   Substitua IMAGE_NAME pelo nome do arquivo de imagem, por exemplo, goldfish.jpg.

   Quando a operação for concluída, você vai receber uma mensagem como This statement created a new table named goldfish_image_table.

bq

1. Crie a tabela de objetos inserindo a seguinte instrução CREATE EXTERNAL TABLE.

   bq query --use_legacy_sql=false \
   "CREATE EXTERNAL TABLE `bqml_tutorial.goldfish_image_table`
   WITH CONNECTION `us.bqml_tutorial`
   OPTIONS(
   object_metadata = 'SIMPLE',
   uris = ['gs://bqml_images/IMAGE_NAME'],
   max_staleness = INTERVAL 1 DAY,
   metadata_cache_mode = 'AUTOMATIC')"

   Substitua IMAGE_NAME pelo nome do arquivo de imagem, por exemplo, goldfish.jpg.

2. Depois de criar a tabela de objetos, verifique se ela aparece no conjunto de dados.

   bq ls bqml_tutorial

   O resultado será o seguinte:

   tableId               Type
   --------------------- --------
   goldfish_image_table  EXTERNAL

Para mais informações, consulte Criar tabelas de objetos.

Fazer previsões com o modelo ONNX importado

Importante:é necessário ter uma reserva para executar previsões usando modelos importados e tabelas de objetos. Para mais informações, consulte as limitações dos modelos ONNX importados.

Se você não tiver uma reserva, executar uma consulta usando ML.PREDICT vai gerar este erro: BigQuery ML inference using imported models and object tables requires a reservation, but no reservations were assigned for job type `QUERY`...`.

Use a consulta a seguir, que contém a função ML.PREDICT, para fazer previsões com base em dados de imagem na tabela de objetos de entrada goldfish_image_table. Essa consulta gera o rótulo de classe previsto da imagem de entrada com base no dicionário de rótulos do ImageNet.

Na consulta, a função ML.DECODE_IMAGE é necessária para decodificar os dados da imagem para que ela possa ser interpretada por ML.PREDICT. A função ML.RESIZE_IMAGE é chamada para redimensionar a imagem para se ajustar ao tamanho da entrada do modelo (224*224).

Para mais informações sobre como executar a inferência em tabelas de objetos de imagem, consulte Executar inferência em tabelas de objetos de imagem.

Para fazer previsões com base nos dados de imagem, faça o seguinte:

Console

1. Acesse a página do BigQuery Studio.

   Acessar o BigQuery Studio

2. No editor de consultas, insira a seguinte consulta ML.PREDICT.

    SELECT
      class_label
    FROM
      ML.PREDICT(MODEL bqml_tutorial.imported_onnx_model,
        (
        SELECT
          ML.RESIZE_IMAGE(ML.DECODE_IMAGE(DATA),
            224,
            224,
            FALSE) AS input
        FROM
          bqml_tutorial.goldfish_image_table))
    

   Os resultados da consulta são semelhantes a estes:

   

bq

Digite este comando bq query:

bq query --use_legacy_sql=false \
'SELECT
  class_label
FROM
  ML.PREDICT(MODEL `bqml_tutorial.imported_onnx_model`,
    (
    SELECT
      ML.RESIZE_IMAGE(ML.DECODE_IMAGE(DATA),
        224,
        224,
        FALSE) AS input
    FROM
      bqml_tutorial.goldfish_image_table))'

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Excluir o projeto

Console

Cuidado: excluir 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 console Google Cloud , 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.

gcloud

Cuidado: excluir 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.

Excluir um projeto do Google Cloud :

gcloud projects delete PROJECT_ID

Excluir recursos individuais

Como alternativa, para remover os recursos individuais usados neste tutorial, faça o seguinte:

1. Exclua o modelo importado.

2. (Opcional) Exclua o conjunto de dados.

3. Exclua a conexão a recursos do Cloud.

4. Exclua o bucket do Cloud Storage.

A seguir

• Para mais informações sobre como importar modelos ONNX, consulte A instrução CREATE MODEL para modelos ONNX.
• Para mais informações sobre conversores e tutoriais ONNX disponíveis, consulte Como converter para o formato ONNX.
• Para uma visão geral do BigQuery ML, consulte Introdução ao BigQuery ML.
• Para começar a usar o BigQuery ML, consulte Criar modelos de machine learning no BigQuery ML.