Inférence par lots pour BigQuery

Cette page explique comment obtenir des inférences par lot à l'aide de BigQuery.

1. Préparer les entrées

Entrée de stockage BigQuery

Votre compte de service doit disposer des autorisations BigQuery appropriées. Pour attribuer le rôle Utilisateur BigQuery au compte de service, utilisez la gcloud iam service-accounts add-iam-policy-binding commande comme suit :

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.s3ns.iam.gserviceaccount.com" \
        --role="roles/bigquery.user"

Remplacez les valeurs suivantes :

  • PROJECT_ID : ID du projet dans lequel votre compte de service a été créé.
  • SERVICE_ACCOUNT_ID : ID du compte de service.

Une colonne request est obligatoire et doit être au format JSON valide. Ces données JSON représentent votre entrée pour le modèle.

Le contenu de la colonne request doit correspondre à la structure de GenerateContentRequest.

Votre table d'entrée peut comporter des types de données de colonne autres que request. Ces colonnes peuvent avoir des types de données BigQuery, à l'exception des suivants : array, struct, range, datetime et geography. Ces colonnes sont ignorées pour la génération de contenu, mais sont incluses dans la table de sortie.

Exemple d'entrée (JSON) 
        
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Give me a recipe for banana bread."
        }
      ]
    }
  ],
  "system_instruction": {
    "parts": [
      {
        "text": "You are a chef."
      }
    ]
  }
}

2. Envoyer un job par lot

Vous pouvez créer un job par lot via la Cloud de Confiance console, le SDK Google Gen AI, ou l'API REST.

Le job et votre table doivent se trouver dans la même région.

Console

  1. Dans la section Agent Platform de la Cloud de Confiance console, accédez à la page Batch Inference (Inférence par lot).

    Accéder à l'inférence par lot

  2. Cliquez sur Créer.

REST

Pour créer un job d'inférence par lot, utilisez la projects.locations.batchPredictionJobs.create méthode.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • ENDPOINT_PREFIX : région de la ressource de modèle suivie de -. Par exemple, us-central1-. Si vous utilisez le point de terminaison global, laissez ce champ vide. Remarque : Le point de terminaison global n'est pas compatible avec l'inférence par lot à l'aide de modèles réglés.
  • LOCATION : région compatible avec les modèles Gemini. Si vous utilisez le point de terminaison global, saisissez global.
  • PROJECT_ID : ID de votre projet .
  • MODEL_PATH : nom du modèle d'éditeur, par exemple publishers/google/models/gemini-2.0-flash-001 ; ou nom du point de terminaison réglé, par exemple projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID, où MODEL_ID est l'ID du modèle réglé.
  • INPUT_URI : table BigQuery où se trouve votre entrée d'inférence par lot, par exemple bq://myproject.mydataset.input_table. L'ensemble de données doit se trouver dans la même région que le job d'inférence par lot. Les ensembles de données multirégionaux ne sont pas acceptés.
  • OUTPUT_FORMAT : pour générer une sortie dans une table BigQuery, spécifiez bigquery. Pour générer la sortie dans un bucket Cloud Storage, spécifiez jsonl.
  • DESTINATION : pour BigQuery, spécifiez bigqueryDestination. Pour Cloud Storage, spécifiez gcsDestination.
  • OUTPUT_URI_FIELD_NAME : pour BigQuery, spécifiez outputUri. Pour Cloud Storage, spécifiez outputUriPrefix.
  • OUTPUT_URI : pour BigQuery, spécifiez l'emplacement de la table, par exemple bq://myproject.mydataset.output_result. La région de l'ensemble de données BigQuery de sortie doit être identique à celle du job d'inférence par lot Agent Platform. Pour Cloud Storage, spécifiez l'emplacement du bucket et du répertoire, par exemple gs://mybucket/path/to/output.

Méthode HTTP et URL : 

POST https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs

Corps JSON de la requête : 

{
  "displayName": "my-bigquery-batch-inference-job",
  "model": "MODEL_PATH",
  "inputConfig": {
    "instancesFormat": "bigquery",
    "bigquerySource":{
      "inputUri" : "INPUT_URI"
    }
  },
  "outputConfig": {
    "predictionsFormat": "OUTPUT_FORMAT",
    "DESTINATION": {
      "OUTPUT_URI_FIELD_NAME": "OUTPUT_URI"
    }
  }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, et exécutez la commande suivante : 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs"

PowerShell

Enregistrez le corps de la requête dans un fichier nommé request.json, et exécutez la commande suivante : 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON semblable à la suivante.

La réponse inclut un identifiant unique pour le job par lot. Vous pouvez interroger l'état du job par lot à l'aide de the BATCH_JOB_ID. Pour en savoir plus, consultez la section Surveiller l'état du job. Remarque : Les rapports sur le compte de service personnalisé, la progression en temps réel, les clés CMEK et les rapports VPCSC ne sont pas pris en charge.

Python

Installer

pip install --upgrade google-genai

Pour en savoir plus, consultez la documentation de référence du SDK.

Définissez des variables d'environnement pour utiliser le SDK Google Gen AI avec Vertex AI : 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

import time

from google import genai
from google.genai.types import CreateBatchJobConfig, HttpOptions, JobState

client = genai.Client(http_options=HttpOptions(api_version="v1"))

# TODO(developer): Update and un-comment below line
# output_uri = f"bq://your-project.your_dataset.your_table"

job = client.batches.create(
    # To use a tuned model, set the model param to your tuned model using the following format:
    # model="projects/{PROJECT_ID}/locations/{LOCATION}/models/{MODEL_ID}
    model="gemini-3.5-flash",
    src="bq://storage-samples.generative_ai.batch_requests_for_multimodal_input",
    config=CreateBatchJobConfig(dest=output_uri),
)
print(f"Job name: {job.name}")
print(f"Job state: {job.state}")
# Example response:
# Job name: projects/.../locations/.../batchPredictionJobs/9876453210000000000
# Job state: JOB_STATE_PENDING

# See the documentation: https://googleapis.github.io/python-genai/genai.html#genai.types.BatchJob
completed_states = {
    JobState.JOB_STATE_SUCCEEDED,
    JobState.JOB_STATE_FAILED,
    JobState.JOB_STATE_CANCELLED,
    JobState.JOB_STATE_PAUSED,
}

while job.state not in completed_states:
    time.sleep(30)
    job = client.batches.get(name=job.name)
    print(f"Job state: {job.state}")
# Example response:
# Job state: JOB_STATE_PENDING
# Job state: JOB_STATE_RUNNING
# Job state: JOB_STATE_RUNNING
# ...
# Job state: JOB_STATE_SUCCEEDED

3. Surveiller l'état et la progression du job

Une fois le job par lot envoyé, vous pouvez vérifier son état à l'aide de l'API, du SDK et de la Cloud de Confiance console.

Console

  1. Accédez à la page Batch Inference (Inférence par lot).

    Accéder à l'inférence par lot

  2. Sélectionnez votre job par lot pour surveiller sa progression.

REST

Pour surveiller un job d'inférence par lot, utilisez la projects.locations.batchPredictionJobs.get méthode et affichez le CompletionStats champ dans la réponse.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • ENDPOINT_PREFIX : région de la ressource de modèle suivie de -. Par exemple, us-central1-. Si vous utilisez le point de terminaison global, laissez ce champ vide.
  • LOCATION : région compatible avec les modèles Gemini. Si vous utilisez le point de terminaison global, saisissez global.
  • PROJECT_ID : ID de votre projet.
  • BATCH_JOB_ID : ID de votre job par lot.

Méthode HTTP et URL : 

GET https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante : 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID"

PowerShell

Exécutez la commande suivante : 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON semblable à la suivante.

Python

Installer

pip install --upgrade google-genai

Pour en savoir plus, consultez la documentation de référence du SDK.

Définissez des variables d'environnement pour utiliser le SDK Google Gen AI avec Vertex AI : 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

    from google import genai
    from google.genai.types import HttpOptions

    client = genai.Client(http_options=HttpOptions(api_version="v1"))

    # Get the batch job
# Eg. batch_job_name = "projects/123456789012/locations/.../batchPredictionJobs/1234567890123456789"
    batch_job = client.batches.get(name=batch_job_name)

    print(f"Job state: {batch_job.state}")
    # Example response:
    # Job state: JOB_STATE_PENDING
    # Job state: JOB_STATE_RUNNING
    # Job state: JOB_STATE_SUCCEEDED

L'état d'un job par lot donné peut être l'un des suivants :

  • JOB_STATE_PENDING : file d'attente pour la capacité. Le job peut être à l'état queue jusqu'à 72 heures avant de passer à l'état running.
  • JOB_STATE_RUNNING: le fichier d'entrée a été validé et le lot est en cours d'exécution.
  • JOB_STATE_SUCCEEDED: le lot a été terminé et les résultats sont prêts.
  • JOB_STATE_FAILED: le fichier d'entrée n'a pas réussi le processus de validation ou n'a pas pu être terminé dans la fenêtre de 24 heures après être passé à l'état RUNNING.
  • JOB_STATE_CANCELLING : le lot est en cours d'annulation.
  • JOB_STATE_CANCELLED : le lot a été annulé.

4. Récupérer une sortie par lot

Une fois la tâche d'inférence par lot terminée, le résultat est stocké dans la table BigQuery que vous avez spécifiée dans votre requête.

Pour les lignes réussies, les réponses du modèle sont stockées dans la colonne response. Sinon, les détails de l'erreur sont stockés dans la colonne status en vue d'une inspection plus approfondie.

Exemple de résultat

Exemple de réussite

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "In a medium bowl, whisk together the flour, baking soda, baking powder."
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.14057204,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.14270912
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 8,
    "candidatesTokenCount": 396,
    "totalTokenCount": 404
  }
}

Exemple d'échec

  • Requête

    {"contents":[{"parts":{"text":"Explain how AI works in a few words."},"role":"tester"}]}

  • Réponse

    Bad Request: {"error": {"code": 400, "message": "Please use a valid role: user, model.", "status": "INVALID_ARGUMENT"}}

Reprendre un job par lot incomplet

Si un job d'inférence par lot échoue, est annulé ou expire, vous pouvez le reprendre en créant un job par lot. Le nouveau job ne traite que les requêtes incomplètes ou ayant échoué du job précédent, en fusionnant les nouveaux résultats avec ceux des requêtes précédemment terminées. Par exemple, si le job par lot incomplet était terminé à 90 %, le nouveau job traite les 10% restants des requêtes.

Pour reprendre un job par lot, créez un job par lot et fournissez le fichier Cloud Storage ou la table BigQuery en entrée du nouveau job.