Générer du texte à l'aide d'un modèle Gemini et de la fonction AI.GENERATE_TEXT

Ce tutoriel explique comment créer un modèle distant basé sur le modèle gemini-2.5-flash et comment utiliser ce modèle avec la fonction AI.GENERATE_TEXT pour extraire des mots clés et effectuer une analyse des sentiments sur les avis de films à partir de la table publique bigquery-public-data.imdb.reviews.

Rôles requis

Pour exécuter ce tutoriel, vous devez disposer des rôles IAM (Identity and Access Management) suivants :

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

Ces rôles prédéfinis contiennent les autorisations requises pour effectuer les tâches décrites dans ce document. Pour afficher les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

• Créez 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 et 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.

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.
• Vertex AI: You incur costs for calls to the Vertex AI service that's represented by the remote model.

Vous pouvez obtenir 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 sur les tarifs de BigQuery, consultez la page Tarifs de BigQuery dans la documentation BigQuery.

Pour en savoir plus sur les tarifs de Vertex AI, consultez la page Tarifs de Vertex AI.

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. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

Créer un ensemble de données

Créez un ensemble de données BigQuery pour stocker votre modèle de ML.

Console

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

   Accéder à la page "BigQuery"

2. Dans le volet Explorateur, cliquez sur le nom de votre projet.

3. Cliquez sur Afficher les actions > Créer un ensemble de données.

4. Sur la page 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 Type d'emplacement, sélectionnez Multirégional, puis sélectionnez US (plusieurs régions aux États-Unis).

   • Conservez les autres paramètres par défaut, puis cliquez sur Créer un ensemble de données.

bq

Pour créer un ensemble de données, exécutez la commande bq mk en spécifiant l'option --location. Pour obtenir la liste complète des paramètres possibles, consultez la documentation de référence sur 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 et la description BigQuery ML tutorial dataset :

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

   Au lieu d'utiliser l'option --dataset, la commande utilise le raccourci -d. Si vous omettez -d et --dataset, la commande crée un ensemble de données par défaut.

2. Vérifiez que l'ensemble de données a é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"
  }
}

BigQuery DataFrames

Avant d'essayer cet exemple, suivez les instructions de configuration pour BigQuery DataFrames du guide de démarrage rapide de BigQuery DataFrames. Pour en savoir plus, consultez la documentation de référence sur BigQuery DataFrames.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer les ADC pour un environnement de développement local.

import google.cloud.bigquery

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

Créer une connexion

Créez une connexion de ressource cloud et obtenez le compte de service de la connexion. Créez la connexion dans le même emplacement que l'ensemble de données que vous avez créé à l'étape précédente.

Vous pouvez ignorer cette étape si vous avez configuré une connexion par défaut ou si vous disposez du rôle Administrateur BigQuery.

Sélectionnez l'une des options suivantes :

Console

1. Accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le panneau de gauche, cliquez sur Explorer :

   

   Si le panneau de gauche n'apparaît pas, cliquez sur Développer le panneau de gauche pour l'ouvrir.

3. Dans le volet Explorateur, développez le nom de votre projet, puis cliquez sur Connexions.

4. Sur la page Connexions, cliquez sur Créer une connexion.

5. Pour Type de connexion, sélectionnez Modèles distants Vertex AI, fonctions à distance, BigLake et Spanner (ressource Cloud).

6. Dans le champ ID de connexion, saisissez un nom pour votre connexion.

7. Pour Type d'emplacement, sélectionnez un emplacement pour votre connexion. La connexion doit être colocalisée avec vos autres ressources, telles que les ensembles de données.

8. Cliquez sur Créer une connexion.

9. Cliquez sur Accéder à la connexion.

10. Dans le volet Informations de connexion, copiez l'ID du compte de service à utiliser à l'étape suivante.

bq

1. Dans un environnement de ligne de commande, créez une connexion :

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   Le paramètre --project_id remplace le projet par défaut.

   Remplacez les éléments suivants :

   • REGION : votre région de connexion
   • PROJECT_ID : ID de votre projet Google Cloud
   • CONNECTION_ID : ID de votre connexion

   Lorsque vous créez une ressource de connexion, BigQuery crée un compte de service système unique et l'associe à la connexion.

   Dépannage : Si vous obtenez l'erreur de connexion suivante, mettez à jour le Google Cloud SDK :

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

2. Récupérez et copiez l'ID du compte de service pour l'utiliser lors d'une prochaine étape :

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   Le résultat ressemble à ce qui suit :

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

Terraform

Utilisez la ressource google_bigquery_connection.

Remarque : Pour créer des objets BigQuery à l'aide de Terraform, vous devez activer l'API Cloud Resource Manager.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant crée une connexion de ressources cloud nommée my_cloud_resource_connection dans la région US :

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Pour appliquer votre configuration Terraform dans un projet Google Cloud , suivez les procédures des sections suivantes.

Préparer Cloud Shell

1. Lancez Cloud Shell.

2. Définissez le projet Google Cloud par défaut dans lequel vous souhaitez appliquer vos configurations Terraform.

   Vous n'avez besoin d'exécuter cette commande qu'une seule fois par projet et vous pouvez l'exécuter dans n'importe quel répertoire.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Les variables d'environnement sont remplacées si vous définissez des valeurs explicites dans le fichier de configuration Terraform.

Préparer le répertoire

Chaque fichier de configuration Terraform doit avoir son propre répertoire (également appelé module racine).

1. Dans Cloud Shell, créez un répertoire et un nouveau fichier dans ce répertoire. Le nom du fichier doit comporter l'extension .tf, par exemple main.tf. Dans ce tutoriel, le fichier est appelé main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Si vous suivez un tutoriel, vous pouvez copier l'exemple de code dans chaque section ou étape.

   Copiez l'exemple de code dans le fichier main.tf que vous venez de créer.

   Vous pouvez également copier le code depuis GitHub. Cela est recommandé lorsque l'extrait Terraform fait partie d'une solution de bout en bout.

3. Examinez et modifiez les exemples de paramètres à appliquer à votre environnement.
4. Enregistrez les modifications.
5. Initialisez Terraform. Cette opération n'est à effectuer qu'une seule fois par répertoire.

   terraform init

   Vous pouvez également utiliser la dernière version du fournisseur Google en incluant l'option -upgrade :

   terraform init -upgrade

Appliquer les modifications

1. Examinez la configuration et vérifiez que les ressources que Terraform va créer ou mettre à jour correspondent à vos attentes :

   terraform plan

   Corrigez les modifications de la configuration si nécessaire.

2. Appliquez la configuration Terraform en exécutant la commande suivante et en saisissant yes lorsque vous y êtes invité :

   terraform apply

   Attendez que Terraform affiche le message "Apply completed!" (Application terminée).

3. Ouvrez votre projet Google Cloud pour afficher les résultats. Dans la console Google Cloud , accédez à vos ressources dans l'interface utilisateur pour vous assurer que Terraform les a créées ou mises à jour.

Remarque : Les exemples Terraform partent généralement du principe que les API requises sont activées dans votre projet Google Cloud .

Accorder des autorisations au compte de service de la connexion

Attribuez le rôle d'utilisateur Vertex AI au compte de service de la connexion. Vous devez accorder ce rôle dans le projet que vous avez créé ou sélectionné dans la section Avant de commencer. L'attribution du rôle dans un autre projet génère l'erreur [e-mail] does not have the permission to access resource.

Pour accorder le rôle, procédez comme suit :

1. Accédez à la page IAM et administration.

   Accéder à IAM et administration

2. Cliquez sur Accorder l'accès.

3. Dans le champ Nouveaux comptes principaux, saisissez l'ID du compte de service que vous avez copié précédemment.

4. Dans le champ Sélectionner un rôle, sélectionnez Vertex AI, puis le rôle Utilisateur Vertex AI.

5. Cliquez sur Enregistrer.

Créer le modèle distant

Créez un modèle distant représentant un modèle Vertex AI 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.gemini_model`
  REMOTE WITH CONNECTION `LOCATION.CONNECTION_ID`
  OPTIONS (ENDPOINT = 'gemini-2.5-flash');

Remplacez les éléments suivants :

• LOCATION : emplacement de la connexion
• CONNECTION_ID : ID de votre connexion BigQuery.

  Lorsque vous affichez les détails de la connexion dans la console Google Cloud , il s'agit de la valeur de la dernière section de l'ID de connexion complet affiché dans ID de connexion (par exemple, projects/myproject/locations/connection_location/connections/myconnection).

L'exécution de la requête prend plusieurs secondes, après quoi le modèle gemini_model apparaît dans l'ensemble de données bqml_tutorial. É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.

Effectuer une extraction de mots clés

Effectuez une extraction de mots clés sur des avis de films IMDB à l'aide du modèle distant et de la fonction AI.GENERATE_TEXT :

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

   Accéder à BigQuery

2. Dans l'éditeur de requête, saisissez l'instruction suivante pour effectuer l'extraction de mots clés sur cinq avis de films :

   SELECT
     title, result, review
   FROM
     AI.GENERATE_TEXT(
       MODEL `bqml_tutorial.gemini_model`,
       (
         SELECT
           CONCAT(
             """Extract a list of only 3 key words from this review.
               List only the key words, nothing else. Review: """,
               review) AS prompt,
           *
         FROM
           `bigquery-public-data.imdb.reviews`
         LIMIT 5
       ),
       STRUCT(
         0.2 AS temperature,
         100 AS max_output_tokens));

   Le résultat ressemble à ce qui suit :

   +--------------+------------------+----------------------------------------+
   | title        | result           | review                                 |
   +--------------+------------------+----------------------------------------+
   | The Guardian | * Costner        | Once again Mr. Costner has dragged out |
   |              | * Kutcher        | a movie for far longer than necessary. |
   |              | * Rescue         | Aside from the terrific sea rescue...  |
   |              |                  |                                        |
   | Trespass     | * Generic        | This is an example of why the majority |
   |              | * Waste          | of action films are the same. Generic  |
   |              | * Cinematography | and boring, there's really nothing...  |
   | ...          | ...              | ...                                    |
   +--------------+------------------+----------------------------------------+
   

Effectuer une analyse des sentiments

Effectuez une analyse des sentiments sur des avis de films IMDB à l'aide du modèle distant et de la fonction AI.GENERATE_TEXT :

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 pour effectuer une analyse des sentiments sur des avis de films :

   SELECT
     title, result, review
   FROM
     AI.GENERATE_TEXT(
       MODEL `bqml_tutorial.gemini_model`,
       (
         SELECT
           CONCAT(
             """Perform sentiment analysis on the following text and
                return one the following categories: positive, negative: """,
             review) AS prompt,
           *
         FROM
           `bigquery-public-data.imdb.reviews`
         LIMIT 5
       ),
       STRUCT(
         0.2 AS temperature,
         100 AS max_output_tokens));

   Le résultat ressemble à ce qui suit :

   +----------+----------+------------------------------------------------+
   | title    | result   | review                                         |
   +----------+----------+------------------------------------------------+
   | Quitting | Positive | This movie is amazing because the fact that... |
   | Trespass | Negative | This is an example of why the majority of ...  |
   | ...      | ...      | ...                                            |
   +----------+----------+------------------------------------------------+
   

Effectuer un nettoyage

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.

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.