Effettuare previsioni con modelli PyTorch in formato ONNX

---

Open Neural Network Exchange (ONNX) fornisce un formato uniforme progettato per rappresentare qualsiasi framework di machine learning. Il supporto di BigQuery ML per ONNX ti consente di:

• Addestra un modello utilizzando il tuo framework preferito.
• Converti il modello in formato ONNX.
• Importa il modello ONNX in BigQuery ed esegui le previsioni utilizzando BigQuery ML.

Questo tutorial mostra come importare i modelli ONNX addestrati con PyTorch in un set di dati BigQuery e utilizzarli per fare previsioni da una query SQL.

Importante: per eseguire le previsioni utilizzando i modelli e le tabelle di oggetti importati, devi disporre di una prenotazione. Per ulteriori informazioni, consulta le limitazioni relative ai modelli ONNX importati.

Obiettivi

• Importa un modello preaddestrato utilizzando PyTorch.
• Converti il modello in formato ONNX utilizzando torch.onnx.
• Utilizza l'istruzione CREATE MODEL per importare il modello ONNX in BigQuery.
• Utilizza la funzione ML.PREDICT per fare previsioni con il modello ONNX importato.

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

• BigQuery
• BigQuery ML
• Cloud Storage

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi Google Cloud utenti potrebbero avere diritto a una prova gratuita.

Al termine delle attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la sezione Pulizia.

Prima di iniziare

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.

   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

3. 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

4. Make sure that billing is enabled for your Google Cloud project.

5. Enable the BigQuery, BigQuery Connection, and Cloud Storage APIs.

   Enable the APIs

6. Assicurati di disporre delle autorizzazioni necessarie per eseguire le attività descritte in questo documento.

Ruoli obbligatori

Se crei un nuovo progetto, sei il proprietario del progetto e ti vengono concesse tutte le autorizzazioni IAM (Identity and Access Management) necessarie per completare questo tutorial.

Se utilizzi un progetto esistente, procedi nel seguente modo.

Make sure that you have the following role or roles on the project:

• BigQuery Studio Admin (roles/bigquery.studioAdmin)
• BigQuery Connection Admin (roles/bigquery.connectionAdmin)
• Storage Admin (roles/storage.admin)

Check for the roles

1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.

3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

Grant the roles

1. In the Google Cloud console, go to the IAM page.

   Vai a IAM
2. Seleziona il progetto.
3. Fai clic su Concedi accesso.

4. Nel campo Nuovi principali, inserisci il tuo identificatore utente. In genere si tratta dell'indirizzo email di un Account Google.

5. Nell'elenco Seleziona un ruolo, seleziona un ruolo.
6. Per concedere altri ruoli, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo aggiuntivo.
7. Fai clic su Salva.

Per ulteriori informazioni sulle autorizzazioni IAM in BigQuery, consulta Autorizzazioni IAM.

(Facoltativo) Addestra un modello e convertilo in formato ONNX

I seguenti esempi di codice mostrano come importare un modello di classificazione preaddestrato in PyTorch e come convertire il modello risultante in formato ONNX. Questo tutorial utilizza un modello di esempio predefinito archiviato in gs://cloud-samples-data/bigquery/ml/onnx/resnet18.onnx. Non è necessario completare questi passaggi se utilizzi il modello di esempio.

Creare un modello di visione PyTorch per la classificazione delle immagini

Utilizza il seguente esempio di codice per importare un modello resnet18 preaddestrato di PyTorch che accetta i dati delle immagini decodificati restituiti dalle funzioni ML.DECODE_IMAGE e ML.RESIZE_IMAGE di BigQuery ML.

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()
)

Converti il modello in formato ONNX

Utilizza il seguente esempio per esportare il modello di visione PyTorch utilizzando torch.onnx. Il file ONNX esportato si chiama 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

Carica il modello ONNX in Cloud Storage

Dopo aver salvato il modello, svolgi le seguenti operazioni:

• Crea un bucket Cloud Storage per memorizzare il modello.
• Carica il modello ONNX nel tuo bucket Cloud Storage.

Crea un set di dati

Crea un set di dati BigQuery per archiviare il tuo modello ML.

Console

1. Nella console Google Cloud, vai alla pagina BigQuery.

   Vai alla pagina BigQuery

2. Nel riquadro Explorer, fai clic sul nome del progetto.

3. Fai clic su Visualizza azioni > Crea set di dati.

   

4. Nella pagina Crea set di dati:

   • In ID set di dati, inserisci bqml_tutorial.

   • Per Tipo di località, seleziona Più regioni e poi Stati Uniti (più regioni negli Stati Uniti).

   I set di dati pubblici sono archiviati nella US multiregione. Per semplicità, archivia il tuo set di dati nella stessa posizione.

   • Lascia invariate le restanti impostazioni predefinite e fai clic su Crea set di dati.

   

bq

Per creare un nuovo set di dati, utilizza il comando bq mk con il flag --location. Per un elenco completo dei possibili parametri, consulta la documentazione di riferimento del comando bq mk --dataset.

1. Crea un set di dati denominato bqml_tutorial con la posizione dei dati impostata su US e una descrizione di BigQuery ML tutorial dataset:

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

   Anziché utilizzare il flag --dataset, il comando utilizza la scorciatoia -d. Se ometti -d e --dataset, il comando crea per impostazione predefinita un set di dati.

2. Verifica che il set di dati sia stato creato:

   bq ls

API

Chiama il metodo datasets.insert con una risorsa set di dati definita.

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

Importa il modello ONNX in BigQuery

I passaggi riportati di seguito mostrano come importare il modello ONNX di esempio da Cloud Storage nel set di dati utilizzando un'istruzione CREATE MODEL.

Console

1. Nella console Google Cloud, vai alla pagina BigQuery Studio.

   Vai a BigQuery Studio

2. Nell'editor di query, inserisci il seguente statement CREATE MODEL.

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

   Sostituisci BUCKET_PATH con il percorso del modello che hai caricato su Cloud Storage. Se utilizzi il modello di esempio, sostituisci BUCKET_PATH con il seguente valore: gs://cloud-samples-data/bigquery/ml/onnx/resnet18.onnx.

   Al termine dell'operazione, viene visualizzato un messaggio simile al seguente: Successfully created model named imported_onnx_model.

   Il nuovo modello viene visualizzato nel riquadro Risorse. I modelli sono indicati dall'icona del modello: Se selezioni il nuovo modello nel riquadro Risorse, le informazioni sul modello vengono visualizzate accanto all'editor di query.

   

bq

1. Importa il modello ONNX da Cloud Storage inserendo la seguente dichiarazione 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')"

   Sostituisci BUCKET_PATH con il percorso del modello che hai caricato su Cloud Storage. Se utilizzi il modello di esempio, sostituisci BUCKET_PATH con questo valore: gs://cloud-samples-data/bigquery/ml/onnx/resnet18.onnx.

2. Dopo aver importato il modello, verifica che sia visualizzato nel set di dati.

   bq ls bqml_tutorial

   L'output è simile al seguente:

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

Per ulteriori informazioni sull'importazione dei modelli ONNX in BigQuery, inclusi i requisiti di formato e archiviazione, consulta L'istruzione CREATE MODEL per l'importazione dei modelli ONNX.

Creare una tabella di oggetti in BigQuery per analizzare i dati delle immagini

Una tabella di oggetti è una tabella di sola lettura per oggetti di dati non strutturati che si trovano in Cloud Storage. Le tabelle di oggetti ti consentono di analizzare i dati non strutturati da BigQuery.

In questo tutorial utilizzerai la funzione ML.PREDICT per visualizzare l'etichetta di classe prevista di un'immagine di input archiviata in un bucket Cloud Storage.

Per creare la tabella degli oggetti, devi:

• Crea un bucket Cloud Storage e carica un'immagine di un pesce rosso.
• Crea una connessione a una risorsa Cloud utilizzata per accedere alla tabella degli oggetti.
• Concedi l'accesso all'account di servizio della connessione della risorsa.

Crea un bucket e carica un'immagine

Segui questi passaggi per creare un bucket Cloud Storage e caricare un'immagine di un pesce rosso.

Console

Nota: quando crei un bucket utilizzando la console Google Cloud, devi solo impostare un nome univoco a livello globale per il bucket. Tutti gli altri passaggi sono facoltativi o hanno impostazioni predefinite.

1. Nella console Google Cloud, vai alla pagina Bucket in Cloud Storage.
   

   Vai a Bucket

2. Fai clic su Crea.

3. Nella pagina Crea un bucket, inserisci le informazioni del bucket.

   1. Nella sezione Inizia:

      1. Nella casella, inserisci bqml_images.

      2. Fai clic su Continua.

   2. Nella sezione Scegli dove archiviare i tuoi dati, segui questi passaggi:

      1. Per Tipo di località, seleziona Più regioni.

      2. Nel menu del tipo di località, seleziona US (più regioni negli Stati Uniti).

      3. Fai clic su Continua.

   3. Nella sezione Scegli una classe di archiviazione per i tuoi dati:

      1. Seleziona Imposta una classe predefinita.

      2. Seleziona Standard.

      3. Fai clic su Continua.

   4. Nelle sezioni rimanenti, lascia i valori predefiniti.

4. Fai clic su Crea.

Riga di comando

Inserisci questo comando gcloud storage buckets create:

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

Se la richiesta riesce, il comando restituisce il seguente messaggio:

Creating gs://bqml_images/...

Carica un'immagine nel bucket Cloud Storage

Una volta creato il bucket, scarica un'immagine di un pesce rosso e caricala nel bucket Cloud Storage.

Per caricare l'immagine, segui questi passaggi:

Console

1. Nella console Google Cloud, vai alla pagina Bucket in Cloud Storage.
   

   Vai a Bucket

2. Nell'elenco dei bucket, fai clic su bqml_images.

3. Nella scheda Objects (Oggetti) del bucket, esegui una delle seguenti operazioni:

   • Trascina il file dal desktop o dal gestore file al riquadro principale della console Google Cloud.

   • Fai clic su Carica > Carica file, seleziona il file immagine che vuoi caricare nella finestra di dialogo visualizzata e poi fai clic su Apri.

Riga di comando

Inserisci questo comando gcloud storage cp:

gcloud storage cp OBJECT_LOCATION gs://bqml_images/IMAGE_NAME

Sostituisci quanto segue:

• OBJECT_LOCATION: il percorso locale del file Immagine. Ad esempio, Desktop/goldfish.jpg.
• IMAGE_NAME: il nome dell'immagine. Ad esempio, goldfish.jpg.

In caso di esito positivo, la risposta è simile alla seguente:

Completed files 1/1 | 164.3kiB/164.3kiB

Creare una connessione a una risorsa cloud BigQuery

Devi disporre di una connessione alla risorsa Cloud per connetterti alla tabella degli oggetti che crei in un secondo momento in questo tutorial.

Le connessioni alle risorse cloud ti consentono di eseguire query sui dati archiviati al di fuori di BigQuery in Google Cloud servizi come Cloud Storage o Spanner oppure in origini di terze parti come AWS o Azure. Queste connessioni esterne utilizzano l'API BigQuery Connection.

Per creare la connessione alla risorsa Cloud, segui questi passaggi.

Console

1. Vai alla pagina BigQuery Studio.

   Vai a BigQuery Studio

2. Per creare una connessione, fai clic su Aggiungi e poi su Connessioni a origini dati esterne.

3. Nell'elenco Tipo di connessione, seleziona Modelli remoti di Vertex AI, funzioni remote e BigLake (risorsa Cloud).

4. Nel campo ID connessione, inserisci bqml_tutorial.

5. Verifica che sia selezionata l'opzione Più regioni - Stati Uniti.

6. Fai clic su Crea connessione.

7. Nella parte inferiore della finestra, fai clic su Vai alla connessione. In alternativa, nel riquadro Explorer, espandi Connessioni esterne e poi fai clic su us.bqml_tutorial.

8. Nel riquadro Informazioni sulla connessione, copia l'ID account di servizio. Ti occorre questo ID quando configuri le autorizzazioni per la connessione. Quando crei una risorsa di connessione, BigQuery crea un account di servizio di sistema univoco e lo associa alla connessione.

bq

1. Crea una connessione:

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

   Sostituisci PROJECT_ID con il tuo ID progetto Google Cloud. Il parametro --project_id sostituisce il progetto predefinito.

   Quando crei una risorsa di connessione, BigQuery crea un account di servizio di sistema unico e lo associa alla connessione.

   Risoluzione dei problemi: se ricevi il seguente errore di connessione, aggiorna Google Cloud SDK:

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

2. Recupera e copia l'ID account di servizio per utilizzarlo in un passaggio successivo:

   bq show --connection PROJECT_ID.us.bqml_tutorial

   L'output è simile al seguente:

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

Configurare l'accesso alla connessione

Concedi il ruolo Amministratore oggetti archiviazione all'account di servizio della connessione della risorsa Cloud. Devi concedere questo ruolo nello stesso progetto in cui hai creato l'endpoint del modello remoto.

Nota: se la connessione si trova in un progetto diverso, viene restituito questo errore: [e-mail] does not have the permission to access resource.

Per concedere il ruolo, segui questi passaggi:

1. Vai alla pagina IAM e amministrazione.

   Vai a IAM e amministrazione

2. Fai clic su Concedi accesso.

3. Nel campo Nuove entità, inserisci l'ID account di servizio della connessione della risorsa cloud che hai copiato in precedenza.

4. Nel campo Seleziona un ruolo, scegli Cloud Storage e poi Amministratore oggetti Storage.

5. Fai clic su Salva.

Crea la tabella degli oggetti

Segui questi passaggi per creare una tabella di oggetti denominata goldfish_image_table utilizzando l'immagine del pesce rosso che hai caricato su Cloud Storage.

Console

1. Vai alla pagina BigQuery Studio.

   Vai a BigQuery Studio

2. Nell'editor delle query, inserisci questa query per creare la tabella degli oggetti.

   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');

   Sostituisci IMAGE_NAME con il nome del file immagine, ad esempio goldfish.jpg.

   Al termine dell'operazione, viene visualizzato un messaggio simile aThis statement created a new table named goldfish_image_table.

bq

1. Crea la tabella degli oggetti inserendo il seguente statement 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')"

   Sostituisci IMAGE_NAME con il nome del file immagine, ad esempio goldfish.jpg.

2. Dopo aver creato la tabella degli oggetti, verifica che sia visualizzata nel set di dati.

   bq ls bqml_tutorial

   L'output è simile al seguente:

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

Per ulteriori informazioni, vedi Creare tabelle di oggetti.

Fai previsioni con il modello ONNX importato

Importante:per eseguire le previsioni utilizzando i modelli e le tabelle di oggetti importati, devi disporre di una prenotazione. Per ulteriori informazioni, consulta le limitazioni dei modelli ONNX importati.

Se non hai una prenotazione, l'esecuzione di una query utilizzando ML.PREDICT genera questo errore: BigQuery ML inference using imported models and object tables requires a reservation, but no reservations were assigned for job type `QUERY`...`.

Utilizza la seguente query contenente la funzione ML.PREDICT per fare previsioni dai dati immagine nella tabella degli oggetti di inputgoldfish_image_table. Questa query restituisce l'etichetta della classe prevista dell'immagine di input in base al dizionario delle etichette ImageNet.

Nella query, la funzione ML.DECODE_IMAGE è obbligatoria per decodificare i dati dell'immagine in modo che possano essere interpretati da ML.PREDICT. La funzione ML.RESIZE_IMAGE viene chiamata per ridimensionare l'immagine in base alle dimensioni dell'input del modello (224 x 224).

Per ulteriori informazioni sull'esecuzione dell'inferenza sulle tabelle degli oggetti immagine, consulta Eseguire l'inferenza sulle tabelle degli oggetti immagine.

Per fare previsioni dai dati delle immagini:

Console

1. Vai alla pagina BigQuery Studio.

   Vai a BigQuery Studio

2. Nell'editor di query, inserisci la seguente query 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))
    

   I risultati della query sono simili ai seguenti:

   

bq

Inserisci questo 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))'

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina il progetto

Console

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività descritte in questo documento, quando lo elimini elimini anche tutto il lavoro svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, il riuso dei progetti può aiutarti a non superare i limiti di quota.

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.

gcloud

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività descritte in questo documento, quando lo elimini elimini anche tutto il lavoro svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, il riuso dei progetti può aiutarti a non superare i limiti di quota.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Elimina singole risorse

In alternativa, per rimuovere le singole risorse utilizzate in questo tutorial:

1. Elimina il modello importato.

2. (Facoltativo) Elimina il set di dati.

3. Elimina il collegamento alla risorsa Cloud.

4. Elimina il bucket Cloud Storage.

Passaggi successivi

• Per ulteriori informazioni sull'importazione dei modelli ONNX, consulta L'istruzione CREATE MODEL per i modelli ONNX.
• Per ulteriori informazioni sui convertitori e sui tutorial ONNX disponibili, consulta Conversione in formato ONNX.
• Per una panoramica di BigQuery ML, consulta Introduzione a BigQuery ML.
• Per iniziare a utilizzare BigQuery ML, consulta Creare modelli di machine learning in BigQuery ML.