Gérer les erreurs de quota en appelant ML.GENERATE_TEXT de manière itérative

La procédure stockée publique BigQuery bqutil.procedure.bqml_generate_text vous permet d'itérer des appels par lot à la fonction ML.GENERATE_TEXT afin de traiter de grands ensembles de données sans dépasser les quotas et limites du point de terminaison. Étant donné que les jobs de requête BigQuery se terminent même lorsque la fonction échoue sur des lignes individuelles, des volumes de requêtes élevés peuvent laisser des erreurs RESOURCE EXHAUSTED pouvant être relancées dans votre table de sortie. Dans ce tutoriel, vous allez créer un modèle distant et exécuter la procédure stockée pour relancer de manière itérative les lignes ayant échoué jusqu'à ce que tous les enregistrements d'un ensemble de données d'actualités public soient traités.

Pour examiner le code source de la procédure stockée dans GitHub, consultez bqml_generate_text.sqlx. Pour en savoir plus sur les paramètres et l'utilisation de la procédure stockée, consultez le fichier README.

Objectifs

• Créez un ensemble de données BigQuery.
• Créez un modèle distant BigQuery ML sur un modèle gemini-3.5-flash-lite.
• Exécutez la procédure stockée bqutil.procedure.bqml_generate_text pour générer de manière itérative du texte à partir de l'ensemble de données public bigquery-public-data.bbc_news.fulltext.
• Vérifiez les résultats du texte généré et confirmez qu'il ne reste aucune erreur de quota pouvant être relancée.

Coûts

Dans ce document, vous utilisez les composants facturables de Google Cloudsuivants :

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

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût.

Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai sans frais.

Pour en savoir plus, consultez les tarifs de BigQuery et les tarifs d'Agent Platform.

Avant de commencer

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.
   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. Verify that billing is enabled for your Google Cloud project.

3. Activez les API BigQuery, BigQuery Connection et Agent Platform, si elles ne le sont pas déjà.

   Rôles requis pour activer les API

   Pour activer des API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

   Activer les API

Rôles requis

Pour obtenir les autorisations nécessaires pour suivre ce tutoriel, demandez à votre administrateur de vous accorder les rôles IAM suivants :

• Créer et utiliser des ensembles de données, des connexions et des modèles BigQuery : Administrateur BigQuery (roles/bigquery.admin) sur votre projet
• Accordez des autorisations au compte de service de la connexion : Administrateur IAM du projet (roles/resourcemanager.projectIamAdmin) sur votre projet.

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour suivre ce tutoriel. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour suivre ce tutoriel :

• Créer un ensemble de données : bigquery.datasets.create
• Créer, déléguer et utiliser une connexion : bigquery.connections.*
• Définissez la connexion par défaut : bigquery.config.*
• Définissez les autorisations du compte de service :
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.setIamPolicy
• Créez un modèle et exécutez l'inférence :
  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Créer un ensemble de données

Pour créer un ensemble de données BigQuery, sélectionnez l'une des options suivantes :

Console

1. Dans la console Google Cloud , accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet de gauche, cliquez sur Explorateur :

   

   Si le volet de gauche ne s'affiche pas, cliquez sur Développer le volet de gauche pour l'ouvrir.

3. Dans Explorateur, développez votre projet, puis cliquez sur Ensembles de données.

4. Sur la page Ensembles de données, cliquez sur Créer un ensemble de données.

5. Dans le volet Créer un ensemble de données, procédez comme suit :

   • Dans le champ ID de l'ensemble de données, saisissez bqml_tutorial.

   • Pour Emplacement des données, sélectionnez US.

   Ne modifiez pas les autres paramètres par défaut.

6. Cliquez sur Créer un ensemble de données.

bq

Pour créer un ensemble de données, utilisez la commande bq mk --dataset.

1. Créez un ensemble de données nommé bqml_tutorial avec l'emplacement des données défini sur US :

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

2. Vérifiez que l'ensemble de données a bien été créé :

   bq ls

API

Appelez la méthode datasets.insert avec une ressource d'ensemble de données définie :

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

Créer le modèle distant

Utilisez l'instruction CREATE MODEL pour créer un modèle distant représentant un modèle gemini-3.5-flash-lite Agent Platform hébergé :

1. Dans la console Google Cloud , accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans l'éditeur de requête, exécutez l'instruction suivante :

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

   L'exécution de la requête prend plusieurs secondes, après quoi le modèle generate_text apparaît dans l'ensemble de données bqml_tutorial dans le volet Explorateur. Étant donné que la requête utilise une instruction CREATE MODEL pour créer un modèle, il n'y a aucun résultat de requête.

Exécuter la procédure stockée

Utilisez l'instruction CALL pour exécuter la procédure stockée bqutil.procedure.bqml_generate_text. Cette procédure stockée effectue une itération par le biais d'appels à la fonction ML.GENERATE_TEXT à l'aide du modèle bqml_tutorial.generate_text et de la table publique bigquery-public-data.bbc_news.fulltext :

1. Dans la console Google Cloud , accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans l'éditeur de requête, exécutez l'instruction suivante :

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

   Remplacez PROJECT_ID par l'ID du projet.

   La procédure stockée crée la table bqml_tutorial.news_generated_text pour contenir le résultat de la fonction ML.GENERATE_TEXT.

3. Une fois l'exécution de la requête terminée, vérifiez qu'aucune ligne de la table bqml_tutorial.news_generated_text ne contient d'erreur pouvant faire l'objet d'une nouvelle tentative. Dans l'éditeur de requête, exécutez l'instruction suivante :

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

   La requête renvoie le message There is no data to display.

4. Dans l'éditeur de requête, exécutez l'instruction suivante pour inspecter un échantillon des résultats de texte générés :

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

   Le résultat ressemble à ce qui suit :

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

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.

Supprimer le projet

Attention : La suppression d'un projet entraîne les effets décrits ci-dessous :

• Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
• Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

Supprimer un projet Google Cloud  :

gcloud projects delete PROJECT_ID

Supprimer des ressources individuelles

Si vous souhaitez réutiliser le projet, supprimez les ressources que vous avez créées pour ce tutoriel :

Console

1. Dans la console Google Cloud , accédez à la page BigQuery.

   Accéder à BigQuery

2. Supprimer l'ensemble de données bqml_tutorial La suppression de l'ensemble de données supprime également le modèle distant et la table de sortie :

   1. Dans le volet Explorateur, développez votre projet et cliquez sur Ensembles de données.

   2. Dans la liste Ensembles de données, cliquez sur l'ensemble de données bqml_tutorial.

   3. Dans le volet Détails, cliquez sur Supprimer.

   4. Dans la boîte de dialogue Supprimer l'ensemble de données, cliquez sur Supprimer.

bq

Supprimez l'ensemble de données bqml_tutorial, le modèle distant et la table de sortie :

bq rm --dataset --recursive bqml_tutorial

Étapes suivantes

• En savoir plus sur la fonction ML.GENERATE_TEXT et la fonction AI.GENERATE_TEXT.
• En savoir plus sur l'IA générative dans BigQuery
• Découvrez comment choisir une fonction de génération de texte.