Gestire gli errori di quota chiamando ML.GENERATE_TEXT in modo iterativo

La stored procedure pubblica bqutil.procedure.bqml_generate_text di BigQuery ti consente di eseguire l'iterazione delle chiamate batch alla funzione ML.GENERATE_TEXT in modo da poter elaborare set di dati di grandi dimensioni senza superare le quote e i limiti dell'endpoint. Poiché i job di query BigQuery vengono completati anche se la funzione non riesce su singole righe, volumi di richieste elevati possono lasciare RESOURCE EXHAUSTED errori ripetibili nella tabella di output. In questo tutorial, creerai un modello remoto ed eseguirai la stored procedure per riprovare in modo iterativo le righe non riuscite fino a quando non verranno elaborati tutti i record di un set di dati di notizie pubblico.

Per esaminare il codice sorgente della stored procedure in GitHub, consulta bqml_generate_text.sqlx. Per saperne di più sui parametri e sull'utilizzo della stored procedure, consulta il file README.

Obiettivi

  • Creare un set di dati BigQuery.
  • Crea un modello remoto BigQuery ML su un modello gemini-3.5-flash-lite.
  • Esegui la stored procedure bqutil.procedure.bqml_generate_text per generare in modo iterativo il testo dal set di dati pubblico bigquery-public-data.bbc_news.fulltext.
  • Verifica i risultati del testo generato e conferma che non rimangano errori di quota ripetibili.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

  • BigQuery ML: You incur costs for the data that you process in BigQuery.
  • Gemini Enterprise Agent Platform: You incur costs for calls to the Agent Platform model.

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi.

I nuovi utenti di Google Cloud potrebbero avere diritto a una prova senza costi.

Per saperne di più, consulta la pagina relativa ai prezzi di BigQuery e ai prezzi di Agent Platform.

Prima di iniziare

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

    Go to project selector

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

  3. Abilita le API BigQuery, BigQuery Connection e Agent Platform, se non sono già abilitate.

    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

Ruoli obbligatori

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

  • Creare e utilizzare set di dati, connessioni e modelli BigQuery: Amministratore BigQuery (roles/bigquery.admin) sul tuo progetto
  • Concedi le autorizzazioni al account di servizio della connessione: Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin) sul tuo progetto

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

Questi ruoli predefiniti contengono le autorizzazioni necessarie per completare questo tutorial. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per completare questo tutorial sono necessarie le seguenti autorizzazioni:

  • Crea un set di dati: bigquery.datasets.create
  • Crea, delega e utilizza una connessione: bigquery.connections.*
  • Imposta la connessione predefinita: bigquery.config.*
  • Imposta le autorizzazioni del account di servizio:
    • resourcemanager.projects.getIamPolicy
    • resourcemanager.projects.setIamPolicy
  • Crea un modello ed esegui l'inferenza:
    • bigquery.jobs.create
    • bigquery.models.create
    • bigquery.models.getData
    • bigquery.models.updateData
    • bigquery.models.updateMetadata

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Crea un set di dati

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

Console

  1. Nella console Google Cloud , 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"
  }
}

Crea il modello remoto

Utilizza l'istruzione CREATE MODEL per creare un modello remoto che rappresenta un modello Agent Platform gemini-3.5-flash-lite ospitato:

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

    Vai a BigQuery

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

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

    Il completamento della query richiede alcuni secondi, dopodiché il modello generate_text viene visualizzato nel set di dati bqml_tutorial nel riquadro Explorer. Poiché la query utilizza un'istruzione CREATE MODEL per creare un modello, non sono presenti risultati della query.

Esegui la stored procedure

Utilizza l'istruzione CALL per eseguire la stored procedure bqutil.procedure.bqml_generate_text. Questa stored procedure esegue l'iterazione delle chiamate alla funzione ML.GENERATE_TEXT utilizzando il modello bqml_tutorial.generate_text e la tabella pubblica bigquery-public-data.bbc_news.fulltext:

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

    Vai a BigQuery

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

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

    Sostituisci PROJECT_ID con l'ID progetto.

    La stored procedure crea la tabella bqml_tutorial.news_generated_text per contenere l'output della funzione ML.GENERATE_TEXT.

  3. Al termine dell'esecuzione della query, verifica che nella tabella bqml_tutorial.news_generated_text non siano presenti righe contenenti un errore ritentabile. Nell'editor di query, esegui la seguente istruzione:

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

    La query restituisce il messaggio There is no data to display.

  4. Nell'editor di query, esegui la seguente istruzione per esaminare un campione dei risultati del testo generato:

    SELECT
  filename,
  prompt,
  ml_generate_text_llm_result,
  ml_generate_text_status
FROM `bqml_tutorial.news_generated_text`
LIMIT 3;

    L'output è simile al seguente:

    +------------------------+------------------------------------------+-----------------------------------------------------------+-------------------------+
| filename               | prompt                                   | ml_generate_text_llm_result                               | ml_generate_text_status |
+------------------------+------------------------------------------+-----------------------------------------------------------+-------------------------+
| bbc/tech/209.txt       | A 20-year-old US man is selling...       | It looks like you shared a news article about Andrew...   |                         |
| bbc/business/375.txt   | South Korea's largest credit card...     | It looks like you shared a news article about the 2004... |                         |
| bbc/sport/139.txt      | A brave defensive display, led by...     | It looks like you have shared a match report from a...    |                         |
+------------------------+------------------------------------------+-----------------------------------------------------------+-------------------------+

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

    Elimina un progetto Google Cloud :

    gcloud projects delete PROJECT_ID

Elimina singole risorse

Se vuoi riutilizzare il progetto, elimina le risorse che hai creato per questo tutorial:

Console

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

    Vai a BigQuery

  2. Elimina il set di dati bqml_tutorial. L'eliminazione del set di dati comporta anche l'eliminazione del modello remoto e della tabella di output:

    1. Nel riquadro Explorer, espandi il progetto e fai clic su Set di dati.

    2. Nell'elenco Set di dati, fai clic sul set di dati bqml_tutorial.

    3. Nel riquadro dei dettagli, fai clic su Elimina.

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

bq

Elimina il set di dati bqml_tutorial, il modello remoto e la tabella di output:

bq rm --dataset --recursive bqml_tutorial

Passaggi successivi