Generare embedding con modelli Transformer in formato ONNX

In questo tutorial utilizzerai l'interfaccia a riga di comando Hugging Face Optimum per esportare il modello sentence-transformers/all-MiniLM-L6-v2 nel formato Open Neural Network Exchange (ONNX). Utilizza l'istruzione CREATE MODEL per importare il modello ONNX in BigQuery. Infine, utilizzi la funzione ML.PREDICT per generare embedding con il modello ONNX importato.

Questo tutorial utilizza il modello sentence-transformers/all-MiniLM-L6-v2. Questo modello di trasformatore di frasi è noto per le sue prestazioni rapide ed efficaci nella generazione di embedding di frasi. L'embedding delle frasi consente attività come la ricerca semantica, il clustering e la somiglianza delle frasi acquisendo il significato sottostante del testo.

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

  • Addestra un modello utilizzando il tuo framework preferito.
  • Converti il modello nel formato ONNX.
  • Importa il modello ONNX in BigQuery e genera previsioni utilizzando BigQuery ML.

Obiettivi

  • Esporta il modello sentence-transformers/all-MiniLM-L6-v2 in ONNX.
  • Importa il modello ONNX in BigQuery.
  • Utilizza la funzione ML.PREDICT per generare embedding con il modello ONNX importato.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Cloud de Confiance by S3NS:

Al termine delle attività descritte in questo documento, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato. Per saperne di più, consulta Esegui la pulizia.

Prima di iniziare

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

    Go to project selector

  2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud de Confiance .

  3. Attiva le API BigQuery e Cloud Storage, se non sono già attive.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilita le API

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

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare questo tutorial, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

  • Creare set di dati, tabelle e modelli ed eseguire job BigQuery: BigQuery Studio Admin (roles/bigquery.studioAdmin)
  • Creare un bucket Cloud Storage e creare oggetti di archiviazione (se converti manualmente i file del modello del trasformatore in ONNX): Storage Admin (roles/storage.admin)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

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

Per saperne di più sulle autorizzazioni IAM in BigQuery, consulta Autorizzazioni IAM.

(Facoltativo) Converti manualmente i file del modello Transformer in ONNX

Se stai convertendo manualmente il modello sentence-transformers/all-MiniLM-L6-v2 e il tokenizzatore in ONNX, segui i passaggi descritti nelle sezioni seguenti. In alternativa, puoi utilizzare i file di esempio nel bucket Cloud Storage gs://cloud-samples-data. I file in questo bucket sono già stati convertiti. Se utilizzi i file di esempio, vai a Crea un set di dati.

Se scegli di convertire manualmente i file, devi disporre di un ambiente a riga di comando locale in cui è installato Python. Per saperne di più sull'installazione di Python, consulta Download di Python.

Esporta il modello Transformer in ONNX

Utilizza l'interfaccia a riga di comando Hugging Face Optimum per esportare il modello sentence-transformers/all-MiniLM-L6-v2 in ONNX. Per saperne di più sull'esportazione dei modelli con l'interfaccia a riga di comando Optimum, consulta Esporta un modello in ONNX con optimum.exporters.onnx.

Per esportare il modello, apri un ambiente a riga di comando e segui questi passaggi:

  1. Installa l'interfaccia a riga di comando Optimum:

    pip install optimum[onnx]

  2. Esporta il modello:

    optimum-cli export onnx \
    --model sentence-transformers/all-MiniLM-L6-v2 \
    --task sentence-similarity \
    --opset 17 all-MiniLM-L6-v2/

    L'argomento --model specifica l'ID modello Hugging Face. L'argomento --opset specifica la versione della libreria ONNXRuntime ed è impostato su 17 per mantenere la compatibilità con la libreria ONNXRuntime supportata da BigQuery.

Il file del modello viene esportato nella directory all-MiniLM-L6-v2 come model.onnx.

Applica la quantizzazione al modello Transformer

Utilizza l'interfaccia a riga di comando Optimum per applicare la quantizzazione al modello di transformer esportato per ridurre le dimensioni del modello e velocizzare l'inferenza. Per saperne di più, consulta Quantizzazione.

Per applicare la quantizzazione al modello, esegui questo comando:

optimum-cli onnxruntime quantize \
    --onnx_model all-MiniLM-L6-v2/ \
    --avx512_vnni -o all-MiniLM-L6-v2_quantized

Il file del modello quantizzato viene esportato nella directory all-MiniLM-L6-v2_quantized come model_quantized.onnx.

Converti il tokenizer in ONNX

Per generare embedding utilizzando un modello Transformer in formato ONNX, in genere utilizzi un tokenizer per produrre due input per il modello, input_ids e attention_mask.

Per produrre questi input, converti il tokenizer per il modello sentence-transformers/all-MiniLM-L6-v2 nel formato ONNX utilizzando la libreria onnxruntime-extensions. Dopo aver convertito il tokenizer, puoi eseguire la tokenizzazione direttamente sugli input di testo non elaborato per generare previsioni ONNX.

Per convertire il tokenizer, segui questi passaggi dalla riga di comando:

  1. Installa l'interfaccia a riga di comando Optimum:

    pip install optimum[onnx]

  2. Utilizzando l'editor di testo che preferisci, crea un file denominato convert-tokenizer.py. L'esempio seguente utilizza l'editor di testo nano:

    nano convert-tokenizer.py

  3. Copia e incolla il seguente script Python nel file convert-tokenizer.py:

    from onnxruntime_extensions import gen_processing_models

# Load the Huggingface tokenizer
tokenizer = AutoTokenizer.from_pretrained("sentence-transformers/all-MiniLM-L6-v2")

# Export the tokenizer to ONNX using gen_processing_models
onnx_tokenizer_path = "tokenizer.onnx"

# Generate the tokenizer ONNX model, and set the maximum token length.
# Ensure 'max_length' is set to a value less than the model's maximum sequence length, failing to do so will result in error during inference.
tokenizer_onnx_model = gen_processing_models(tokenizer, pre_kwargs={'max_length': 256})[0]

# Modify the tokenizer ONNX model signature.
# This is because certain tokenizers don't support batch inference.
tokenizer_onnx_model.graph.input[0].type.tensor_type.shape.dim[0].dim_value = 1

# Save the tokenizer ONNX model
with open(onnx_tokenizer_path, "wb") as f:
  f.write(tokenizer_onnx_model.SerializeToString())

  4. Salva il file convert-tokenizer.py.

  5. Per convertire il tokenizer, esegui lo script Python:

    python convert-tokenizer.py

Il tokenizer convertito viene esportato nella directory all-MiniLM-L6-v2_quantized come tokenizer.onnx.

Carica i file del modello convertito su Cloud Storage

Dopo aver convertito il modello Transformer e il tokenizer, segui questi passaggi:

Crea un set di dati

Per creare un set di dati BigQuery, seleziona una delle seguenti opzioni:

Console

  1. Nella console Cloud de Confiance , vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nel riquadro a sinistra, fai clic su Explorer:

    Pulsante evidenziato per il riquadro Spazio di esplorazione.

    Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro sinistro per aprirlo.

  3. In Explorer, espandi il progetto, quindi fai clic su Set di dati.

  4. Nella pagina Set di dati, fai clic su Crea set di dati.

  5. Nel riquadro Crea set di dati, segui questi passaggi:

    • In ID set di dati, inserisci bqml_tutorial.

    • Per Località dei dati, seleziona USA.

    Lascia invariate le altre impostazioni predefinite.

  6. Fai clic su Crea set di dati.

bq

Per creare un nuovo set di dati, utilizza il comando bq mk --dataset.

  1. Crea un set di dati denominato bqml_tutorial con la località dei dati impostata su US:

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

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

    bq ls

API

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

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

BigQuery DataFrames

Prima di provare questo esempio, segui le istruzioni di configurazione di BigQuery DataFrames nella guida rapida di BigQuery per l'utilizzo di BigQuery DataFrames. Per saperne di più, consulta la documentazione di riferimento di BigQuery DataFrames.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale. 

import google.cloud.bigquery

bqclient = google.cloud.bigquery.Client()
bqclient.create_dataset("bqml_tutorial", exists_ok=True)

Importa i modelli ONNX in BigQuery

Importa il tokenizer convertito e i modelli di trasformatori di frasi come modelli BigQuery ML.

Seleziona una delle seguenti opzioni:

Console

  1. Nella console Cloud de Confiance , vai alla pagina BigQuery Studio.

    Vai a Studio

  2. Nell'editor di query, esegui la seguente istruzione CREATE MODEL per creare il modello tokenizer:

     CREATE OR REPLACE MODEL `bqml_tutorial.tokenizer`
  OPTIONS (MODEL_TYPE='ONNX',
   MODEL_PATH='TOKENIZER_BUCKET_PATH');

    Sostituisci TOKENIZER_BUCKET_PATH con il percorso del modello che hai caricato su Cloud Storage. Se utilizzi il modello di esempio, sostituisci TOKENIZER_BUCKET_PATH con il seguente valore: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/tokenizer.onnx.

    Al termine dell'operazione, nel riquadro Risultati query viene visualizzato un messaggio simile al seguente: Successfully created model named tokenizer.

  3. Per aprire il riquadro Dettagli, fai clic su Vai al modello.

  4. Per visualizzare gli input e l'output del modello nella colonna etichetta, esamina la sezione Colonne di caratteristiche:

    Il riquadro **Dettagli** per il modello `tokenizer`

  5. Per creare il modello all-MiniLM-L6-v2, nell'editor di query, esegui la seguente istruzione CREATE MODEL:

     CREATE OR REPLACE MODEL `bqml_tutorial.all-MiniLM-L6-v2`
  OPTIONS (MODEL_TYPE='ONNX',
   MODEL_PATH='TRANSFORMER_BUCKET_PATH');

    Sostituisci TRANSFORMER_BUCKET_PATH con il percorso del modello che hai caricato su Cloud Storage. Se utilizzi il modello di esempio, sostituisci TRANSFORMER_BUCKET_PATH con il seguente valore: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/model_quantized.onnx.

    Al termine dell'operazione, nel riquadro Risultati query viene visualizzato un messaggio simile al seguente: Successfully created model named all-MiniLM-L6-v2.

  6. Per aprire il riquadro Dettagli, fai clic su Vai al modello.

  7. Per visualizzare gli input e gli output del modello nella colonna Etichetta, consulta la sezione Colonne di caratteristiche:

    Il riquadro **Dettagli** per il modello "all-MiniLM-L6-v2"

bq

Esegui l'istruzione CREATE MODEL utilizzando il comando query dello strumento a riga di comando bq.

  1. Crea il modello tokenizer:

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

    Sostituisci TOKENIZER_BUCKET_PATH con il percorso del modello che hai caricato su Cloud Storage. Se utilizzi il modello di esempio, sostituisci TOKENIZER_BUCKET_PATH con il seguente valore: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/tokenizer.onnx.

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

  2. Crea il modello all-MiniLM-L6-v2:

    bq query --use_legacy_sql=false \
"CREATE OR REPLACE MODEL
  `bqml_tutorial.all-MiniLM-L6-v2`
OPTIONS
  (MODEL_TYPE='ONNX',
    MODEL_PATH='TRANSFORMER_BUCKET_PATH')"

    Sostituisci TRANSFORMER_BUCKET_PATH con il percorso del modello che hai caricato su Cloud Storage. Se utilizzi il modello di esempio, sostituisci TRANSFORMER_BUCKET_PATH con il seguente valore: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/model_quantized.onnx.

    Al termine dell'operazione, viene visualizzato un messaggio simile al seguente: Successfully created model named all-MiniLM-L6-v2.

  3. Dopo aver importato i modelli, verifica che vengano visualizzati nel set di dati.

    bq ls -m bqml_tutorial

    L'output è simile al seguente:

    tableId            Type
------------------------
tokenizer          MODEL
all-MiniLM-L6-v2   MODEL

API

Utilizza il metodo jobs.insert per importare i modelli. Compila il parametro query della risorsa QueryRequest nel corpo della richiesta con l'istruzione CREATE MODEL.

  1. Per creare il modello tokenizer, utilizza il seguente parametro query:

    {
  "query": "CREATE MODEL `PROJECT_ID :bqml_tutorial.tokenizer` OPTIONS(MODEL_TYPE='ONNX' MODEL_PATH='TOKENIZER_BUCKET_PATH')"
}

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto.
    • TOKENIZER_BUCKET_PATH: il percorso del modello che hai caricato su Cloud Storage. Se utilizzi il modello di esempio, sostituisci TOKENIZER_BUCKET_PATH con il seguente valore: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/tokenizer.onnx.

  2. Per creare il modello all-MiniLM-L6-v2, utilizza il seguente valore parametro query:

    {
  "query": "CREATE MODEL `PROJECT_ID :bqml_tutorial.all-MiniLM-L6-v2` OPTIONS(MODEL_TYPE='ONNX' MODEL_PATH='TRANSFORMER_BUCKET_PATH')"
}

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto.
    • TRANSFORMER_BUCKET_PATH: il percorso del modello che hai caricato su Cloud Storage. Se utilizzi il modello di esempio, sostituisci TRANSFORMER_BUCKET_PATH con il seguente valore: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/model_quantized.onnx.

BigQuery DataFrames

Prima di provare questo esempio, segui le istruzioni di configurazione di BigQuery DataFrames nella guida rapida di BigQuery per l'utilizzo di BigQuery DataFrames. Per saperne di più, consulta la documentazione di riferimento di BigQuery DataFrames.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale.

Importa i modelli di tokenizer e SentenceTransformer utilizzando l'oggetto ONNXModel.

import bigframes
from bigframes.ml.imported import ONNXModel

bigframes.options.bigquery.project = PROJECT_ID

bigframes.options.bigquery.location = "US"

tokenizer = ONNXModel(
  model_path= "TOKENIZER_BUCKET_PATH"
)
imported_onnx_model = ONNXModel(
  model_path="TRANSFORMER_BUCKET_PATH"
)

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto.
  • TOKENIZER_BUCKET_PATH: il percorso del modello che hai caricato su Cloud Storage. Se utilizzi il modello di esempio, sostituisci TOKENIZER_BUCKET_PATH con il seguente valore: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/tokenizer.onnx.
  • TRANSFORMER_BUCKET_PATH: il percorso del modello che hai caricato su Cloud Storage. Se utilizzi il modello di esempio, sostituisci TRANSFORMER_BUCKET_PATH con il seguente valore: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/model_quantized.onnx.

Genera embedding con i modelli ONNX importati

Utilizza il tokenizer importato e i modelli di transformer di frasi per generare embedding basati sui dati del set di dati pubblico bigquery-public-data.imdb.reviews.

Seleziona una delle seguenti opzioni:

Console

Utilizza la funzione ML.PREDICT per generare embedding con i modelli.

La query utilizza una chiamata ML.PREDICT nidificata per elaborare il testo non elaborato direttamente tramite il tokenizer e il modello di embedding come segue:

  • Tokenizzazione (query interna): la chiamata ML.PREDICT interna utilizza il modello bqml_tutorial.tokenizer. Prende la colonna title dal set di dati pubblico bigquery-public-data.imdb.reviews come input text. Il modello tokenizer converte le stringhe di testo non elaborate negli input di token numerici richiesti dal modello principale, inclusi gli input input_ids e attention_mask.
  • Generazione di embedding (query esterna): la chiamata ML.PREDICT esterna utilizza il modello bqml_tutorial.all-MiniLM-L6-v2. La query prende come input le colonne input_ids e attention_mask dall'output della query interna.

L'istruzione SELECT recupera la colonna sentence_embedding, che è un array di valori FLOAT che rappresentano l'embedding semantico del testo.

Per generare gli embedding, segui questi passaggi:

  1. Nella console Cloud de Confiance , vai alla pagina BigQuery Studio.

    Vai a Studio

  2. Nell'editor di query, esegui la query seguente.

    SELECT
sentence_embedding
FROM
ML.PREDICT (MODEL `bqml_tutorial.all-MiniLM-L6-v2`,
  (
  SELECT
    input_ids, attention_mask
  FROM
    ML.PREDICT(MODEL `bqml_tutorial.tokenizer`,
      (
      SELECT
        title AS text
      FROM
        `bigquery-public-data.imdb.reviews` limit 10))));

    Il risultato è simile al seguente:

    +-----------------------+
| sentence_embedding    |
+-----------------------+
| -0.02361682802438736  |
| 0.02025664784014225   |
| 0.005168713629245758  |
| -0.026361213997006416 |
| 0.0655381828546524    |
| ...                   |
+-----------------------+

bq

Utilizza il comando query dello strumento a riga di comando bq per eseguire una query. La query utilizza la funzione ML.PREDICT per generare embedding con i modelli.

La query utilizza una chiamata ML.PREDICT nidificata per elaborare il testo non elaborato direttamente tramite il tokenizer e il modello di embedding come segue:

  • Tokenizzazione (query interna): la chiamata ML.PREDICT interna utilizza il modello bqml_tutorial.tokenizer. Prende la colonna title dal set di dati pubblico bigquery-public-data.imdb.reviews come input text. Il modello tokenizer converte le stringhe di testo non elaborate negli input di token numerici richiesti dal modello principale, inclusi gli input input_ids e attention_mask.
  • Generazione di embedding (query esterna): la chiamata ML.PREDICT esterna utilizza il modello bqml_tutorial.all-MiniLM-L6-v2. La query prende come input le colonne input_ids e attention_mask dall'output della query interna.

L'istruzione SELECT recupera la colonna sentence_embedding, che è un array di valori FLOAT che rappresentano l'embedding semantico del testo.

Nella riga di comando, esegui questo comando per eseguire la query.

bq query --use_legacy_sql=false \
'SELECT
sentence_embedding
FROM
ML.PREDICT (MODEL `bqml_tutorial.all-MiniLM-L6-v2`,
  (
  SELECT
    input_ids, attention_mask
  FROM
    ML.PREDICT(MODEL `bqml_tutorial.tokenizer`,
      (
      SELECT
        title AS text
      FROM
        `bigquery-public-data.imdb.reviews` limit 10))))'

Il risultato è simile al seguente:

+-----------------------+
| sentence_embedding    |
+-----------------------+
| -0.02361682802438736  |
| 0.02025664784014225   |
| 0.005168713629245758  |
| -0.026361213997006416 |
| 0.0655381828546524    |
| ...                   |
+-----------------------+

BigQuery DataFrames

Prima di provare questo esempio, segui le istruzioni di configurazione di BigQuery DataFrames nella guida rapida di BigQuery per l'utilizzo di BigQuery DataFrames. Per saperne di più, consulta la documentazione di riferimento di BigQuery DataFrames.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale.

Utilizza il metodo predict per generare embedding utilizzando i modelli ONNX.

import bigframes.pandas as bpd

df = bpd.read_gbq("bigquery-public-data.imdb.reviews", max_results=10)
df_pred = df.rename(columns={"title": "text"})
tokens = tokenizer.predict(df_pred)
predictions = imported_onnx_model.predict(tokens)
predictions.peek(5)

L'output è simile al seguente:

Output del modello Transformer.

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

  1. Nella console Cloud de Confiance , vai alla pagina Gestisci risorse.

    Vai a Gestisci risorse

  2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
  3. Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.

gcloud

    Elimina un progetto Cloud de Confiance :

    gcloud projects delete PROJECT_ID

Elimina singole risorse

In alternativa, per conservare il progetto ed eliminare le risorse utilizzate in questo tutorial, segui questi passaggi:

  1. Nella console Cloud de Confiance , vai alla pagina BigQuery Studio.

    Vai a Studio

  2. Nel riquadro a sinistra, espandi il progetto e fai clic su Set di dati.

  3. Per il set di dati bqml_tutorial, fai clic su Apri azioni > Elimina.

  4. Nella finestra di dialogo Elimina set di dati, fai clic su Elimina per confermare.

  5. Se hai seguito i passaggi per convertire manualmente i file del modello di transformer in ONNX, elimina il bucket Cloud Storage.

Passaggi successivi