Générer des données structurées à l'aide de la fonction AI.GENERATE_TABLE

Ce document vous explique comment générer des données structurées à l'aide d'un modèle Gemini, puis comment mettre en forme la réponse du modèle à l'aide d'un schéma SQL.

Pour ce faire, effectuez les tâches suivantes :

• Créer un modèle distant BigQuery ML sur l'un des modèles Gemini disponibles de manière générale ou en preview.
• Utiliser le modèle avec la fonction AI.GENERATE_TABLE pour générer des données structurées à partir des données des tables standards.

Rôles requis

Pour créer un modèle distant et utiliser la fonction AI.GENERATE_TABLE, vous avez besoin des rôles IAM (Identity and Access Management) suivants :

• Créer et utiliser des ensembles de données, des tables et des modèles BigQuery : Éditeur de données BigQuery (roles/bigquery.dataEditor) sur votre projet.

• Créer, déléguer et utiliser des connexions BigQuery : administrateur de connexion BigQuery (roles/bigquery.connectionsAdmin) sur votre projet.

  Si vous n'avez pas configuré de connexion par défaut, vous pouvez en créer une et la définir lors de l'exécution de l'instruction CREATE MODEL. Pour ce faire, vous devez disposer du rôle Administrateur BigQuery (roles/bigquery.admin) dans votre projet. Pour en savoir plus, consultez Configurer la connexion par défaut.

• Accordez des autorisations au compte de service de la connexion : Administrateur IAM du projet (roles/resourcemanager.projectIamAdmin) sur le projet contenant le point de terminaison Vertex AI. Il s'agit du projet actuel pour les modèles distants que vous créez en spécifiant le nom du modèle comme point de terminaison. Il s'agit du projet identifié dans l'URL des modèles distants que vous créez en spécifiant une URL comme point de terminaison.

• Créer des jobs BigQuery : rôle Utilisateur de job BigQuery (roles/bigquery.jobUser) sur votre projet.

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 :

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

Avant de commencer

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

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

3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

   Enable the APIs

Créer un ensemble de données

Créez un ensemble de données BigQuery pour contenir vos ressources :

Créer une connexion

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

Créez une connexion de ressource cloud pour que le modèle distant puisse l'utiliser, 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.

Sélectionnez l'une des options suivantes :

# 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 {}
}

Accorder l'accès au compte de service

Attribuez le rôle d'utilisateur Vertex AI au compte de service de la connexion.

Si vous envisagez de spécifier le point de terminaison en tant qu'URL lors de la création du modèle distant (par exemple, endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/gemini-2.5-flash'), accordez ce rôle dans le projet que vous spécifiez dans l'URL.

Si vous envisagez de spécifier le point de terminaison à l'aide du nom du modèle lors de la création du modèle distant (par exemple endpoint = 'gemini-2.5-flash'), accordez ce rôle dans le projet dans lequel vous prévoyez de créer le modèle distant.

L'attribution du rôle dans un autre projet génère l'erreur bqcx-1234567890-wxyz@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.

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

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None

Créer un modèle distant BigQuery ML

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

   Accéder à BigQuery

2. À l'aide de l'éditeur SQL, créez un modèle distant :

   CREATE OR REPLACE MODEL
   `PROJECT_ID.DATASET_ID.MODEL_NAME`
   REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
   OPTIONS (ENDPOINT = 'ENDPOINT');

   Remplacez les éléments suivants :

   • PROJECT_ID : ID de votre projet.
   • DATASET_ID : ID de l'ensemble de données pour contenir le modèle. Cet ensemble de données doit se trouver dans le même emplacement que la connexion que vous utilisez.
   • MODEL_NAME : nom du modèle
   • REGION : région utilisée par 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).

   • ENDPOINT : nom du modèle Gemini à utiliser. Pour en savoir plus, consultez ENDPOINT.

Générer des données structurées

Générez des données structurées à l'aide de la fonction AI.GENERATE_TABLE avec un modèle distant et à l'aide des données d'invite d'une colonne de table :

SELECT *
FROM AI.GENERATE_TABLE(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  [TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME` / (PROMPT_QUERY)],
  STRUCT(TOKENS AS max_output_tokens, TEMPERATURE AS temperature,
  TOP_P AS top_p, STOP_SEQUENCES AS stop_sequences,
  SAFETY_SETTINGS AS safety_settings,
  OUTPUT_SCHEMA AS output_schema)
);

Remplacez l'élément suivant :

• PROJECT_ID : ID de votre projet.
• DATASET_ID : ID de l'ensemble de données contenant le modèle.
• MODEL_NAME : nom du modèle
• TABLE_NAME : nom de la table contenant la requête. Cette table doit avoir une colonne nommée prompt. Vous pouvez également utiliser un alias pour utiliser une colonne portant un nom différent.
• PROMPT_QUERY : requête GoogleSQL qui génère les données de la requête. La valeur d'invite elle-même peut être extraite d'une colonne, ou vous pouvez la spécifier en tant que valeur structurée avec un nombre arbitraire de sous-champs de nom de colonne et de chaîne. Par exemple : SELECT ('Analyze the sentiment in ', feedback_column, 'using the following categories: positive, negative, neutral') AS prompt.
• TOKENS : valeur INT64 qui définit le nombre maximal de jetons pouvant être générés dans la réponse. Cette valeur doit être comprise dans la plage [1,8192]. Spécifiez une valeur inférieure pour obtenir des réponses plus courtes et une valeur supérieure pour des réponses plus longues. La valeur par défaut est 128.
• TEMPERATURE : valeur FLOAT64 comprise dans la plage [0.0,2.0] qui contrôle le degré de randomisation dans la sélection des jetons. La valeur par défaut est 1.0.

  Des valeurs inférieures pour temperature conviennent aux requêtes qui nécessitent une réponse plus déterministe et moins ouverte ou créative, tandis que des valeurs plus élevées pour temperature peuvent entraîner des résultats plus diversifiés ou créatifs. Une valeur 0 pour temperature est déterministe, ce qui signifie que la réponse dont la probabilité est la plus élevée est toujours sélectionnée.

• TOP_P : une valeur FLOAT64 comprise dans la plage [0.0,1.0] permet de déterminer la probabilité de sélection des jetons. Spécifiez une valeur inférieure pour obtenir des réponses moins aléatoires et une valeur supérieure pour des réponses plus aléatoires. La valeur par défaut est 0.95.
• STOP_SEQUENCES : valeur ARRAY<STRING> qui supprime les chaînes spécifiées si elles sont incluses dans les réponses du modèle. Les chaînes correspondent exactement, y compris la casse. La valeur par défaut est un tableau vide.
• SAFETY_SETTINGS : valeur ARRAY<STRUCT<STRING AS category, STRING AS threshold>> qui configure les seuils de sécurité du contenu pour filtrer les réponses. Le premier élément de la structure spécifie une catégorie de préjudice, et le second élément de la structure spécifie un seuil de blocage correspondant. Le modèle filtre les contenus qui ne respectent pas ces paramètres. Vous ne pouvez spécifier chaque catégorie qu'une seule fois. Par exemple, vous ne pouvez pas spécifier à la fois STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_MEDIUM_AND_ABOVE' AS threshold) et STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_ONLY_HIGH' AS threshold). S'il n'existe aucun paramètre de sécurité pour une catégorie donnée, le paramètre de sécurité BLOCK_MEDIUM_AND_ABOVE est utilisé.

  Voici les catégories acceptées :

  • HARM_CATEGORY_HATE_SPEECH
  • HARM_CATEGORY_DANGEROUS_CONTENT
  • HARM_CATEGORY_HARASSMENT
  • HARM_CATEGORY_SEXUALLY_EXPLICIT

  Les seuils acceptés sont les suivants :

  • BLOCK_NONE (Limité)
  • BLOCK_LOW_AND_ABOVE
  • BLOCK_MEDIUM_AND_ABOVE (par défaut)
  • BLOCK_ONLY_HIGH
  • HARM_BLOCK_THRESHOLD_UNSPECIFIED

  Pour en savoir plus, consultez Catégories de préjudices et Configurer des filtres de contenu.

• OUTPUT_SCHEMA : valeur STRING spécifiant le format de la réponse du modèle. La valeur output_schema doit être une définition de schéma SQL, semblable à celle utilisée dans l'instruction CREATE TABLE. Les types de données suivants sont acceptés :
  • INT64
  • FLOAT64
  • BOOL
  • STRING
  • ARRAY
  • STRUCT

  Pour les modèles Gemini 1.5, ne spécifiez un type de données FLOAT64 que si vous êtes certain que la valeur renvoyée ne sera pas un nombre entier. Ces modèles peuvent parfois renvoyer des valeurs INT64 au lieu de valeurs FLOAT64 pour les nombres entiers (par exemple, 2 au lieu de 2.0), ce qui peut entraîner une erreur d'analyse dans la requête.

  Lorsque vous utilisez l'argument output_schema pour générer des données structurées à partir d'invites d'un tableau, il est important de comprendre les données d'invites afin de spécifier un schéma approprié.

  Par exemple, supposons que vous analysiez le contenu des critiques de films à partir d'un tableau comportant les champs suivants :

  • movie_id
  • review
  • requête

  Vous pouvez ensuite créer un texte d'invite en exécutant une requête semblable à la suivante :

  UPDATE mydataset.movie_review
  SET prompt = CONCAT('Extract the key words and key sentiment from the text below: ', review)
  WHERE review IS NOT NULL;

  Vous pouvez également spécifier une valeur output_schema semblable à "keywords ARRAY<STRING>, sentiment STRING" AS output_schema.

Exemples

L'exemple suivant montre une requête qui extrait les données d'invite d'une table et fournit un schéma SQL pour mettre en forme la réponse du modèle :

SELECT
*
FROM
AI.GENERATE_TABLE( MODEL `mydataset.gemini_model`,
  TABLE `mydataset.mytable`,
  STRUCT("keywords ARRAY<STRING>, sentiment STRING" AS output_schema));

L'exemple suivant montre une requête qui extrait les données d'invite d'une requête et fournit un schéma SQL pour mettre en forme la réponse du modèle :

SELECT *
FROM
  AI.GENERATE_TABLE(
    MODEL `mydataset.gemini_model`,
    (
      SELECT
        'John Smith is a 20-year old single man living at 1234 NW 45th St, Kirkland WA, 98033. He has two phone numbers 123-123-1234, and 234-234-2345. He is 200.5 pounds.'
          AS prompt
    ),
    STRUCT("address STRUCT<street_address STRING, city STRING, state STRING, zip_code STRING>, age INT64, is_married BOOL, name STRING, phone_number ARRAY<STRING>, weight_in_pounds FLOAT64"
        AS output_schema, 8192 AS max_output_tokens));