Inférence par lot depuis Cloud Storage

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

1. Préparer les entrées

L'inférence par lot pour les modèles Gemini accepte un fichier JSON Lines (JSONL) stocké dans Cloud Storage comme données d'entrée. Chaque ligne des données d'entrée par lot est une requête adressée au modèle, suivant le même format que pour l'API Gemini.

Exemple :

{"request":{"contents": [{"role": "user", "parts": [{"text": "What is the relation between the following video and image samples?"}, {"fileData": {"fileUri": "gs://cloud-samples-data/generative-ai/video/animals.mp4", "mimeType": "video/mp4"}}, {"fileData": {"fileUri": "gs://cloud-samples-data/generative-ai/image/cricket.jpeg", "mimeType": "image/jpeg"}}]}], "generationConfig": {"temperature": 0.9, "topP": 1, "maxOutputTokens": 256}}}

Téléchargez l'exemple de fichier de requête par lot.

Une fois que vous avez préparé vos données d'entrée et que vous les avez importées dans Cloud Storage. Assurez-vous que l'agent de service AI Platform est autorisé à accéder au fichier Cloud Storage.

2. Envoyer un job par lot

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

Console

  1. Dans la section Vertex AI de la console Google Cloud , accédez à la page 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 méthode projects.locations.batchPredictionJobs.create.

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 mondial, laissez ce champ vide. Remarque : Le point de terminaison global n'est pas compatible avec l'inférence par lots à l'aide de modèles réglés.
  • LOCATION : région compatible avec les modèles Gemini. Si vous utilisez le point de terminaison mondial, saisissez global.
  • PROJECT_ID : ID de votre projet.
  • MODEL_PATH : nom du modèle d'éditeur (par exemple, publishers/google/models/gemini-2.5-flash) ou nom du point de terminaison réglé (par exemple, projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID), où MODEL_ID correspond à l'ID du modèle réglé.
  • INPUT_URI : emplacement Cloud Storage de votre entrée d'inférence par lots JSONL, par exemple gs://bucketname/path/to/file.jsonl.
  • OUTPUT_FORMAT : pour générer un fichier de 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 lots Vertex AI. 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-cloud-storage-batch-inference-job",
  "model": "MODEL_PATH",
  "inputConfig": {
    "instancesFormat": "jsonl",
    "gcsSource": {
      "uris" : "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, puis 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, puis 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 de la job par lot à l'aide de BATCH_JOB_ID. Pour en savoir plus, consultez Surveiller l'état du job. Remarque : Les comptes de service personnalisés et les clés CMEK ne sont pas acceptés.

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 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_VERTEXAI=True
 

import time

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

client = genai.Client(http_options=HttpOptions(api_version="v1"))
# TODO(developer): Update and un-comment below line
# output_uri = "gs://your-bucket/your-prefix"

# See the documentation: https://googleapis.github.io/python-genai/genai.html#genai.batches.Batches.create
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-2.5-flash",
    # Source link: https://storage.cloud.google.com/cloud-samples-data/batch/prompt_for_batch_gemini_predict.jsonl
    src="gs://cloud-samples-data/batch/prompt_for_batch_gemini_predict.jsonl",
    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 la tâche envoyée, vous pouvez vérifier son état à job par lot;aide de la console Google Cloud , de l'API REST ou du SDK Google Gen AI.

Console

  1. Accédez à la page Inférence par lot.

    Accéder à l'inférence par lot

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

REST

Pour surveiller un job d'inférence par lot, utilisez la méthode projects.locations.batchPredictionJobs.get et affichez le champ CompletionStats 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 mondial, laissez ce champ vide. Remarque : Le point de terminaison global n'est pas compatible avec l'inférence par lots à l'aide de modèles réglés.
  • LOCATION : région compatible avec les modèles Gemini. Si vous utilisez le point de terminaison mondial, 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 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_VERTEXAI=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

Pour obtenir la description des états des jobs, consultez JobState.

4. Récupérer une sortie par lot

Lorsqu'une tâche d'inférence par lot est terminée, le résultat est stocké dans le bucket Cloud Storage que vous avez spécifié lors de la création de la tâche. Pour les lignes réussies, les réponses du modèle sont stockées dans le champ response. Sinon, les détails de l'erreur sont stockés dans le champ status en vue d'une inspection plus approfondie.

Pendant les jobs de longue durée, les inférences terminées sont exportées en continu vers la destination de sortie spécifiée. Si le job d'inférence par lot est arrêté, toutes les lignes traitées sont exportées. Vous n'êtes facturé que pour les inférences terminées.

Exemples de résultats

Exemple de réussite

{
  "status": "",
  "processed_time": "2024-11-01T18:13:16.826+00:00",
  "request": {
    "contents": [
      {
        "parts": [
          {
            "fileData": null,
            "text": "What is the relation between the following video and image samples?"
          },
          {
            "fileData": {
              "fileUri": "gs://cloud-samples-data/generative-ai/video/animals.mp4",
              "mimeType": "video/mp4"
            },
            "text": null
          },
          {
            "fileData": {
              "fileUri": "gs://cloud-samples-data/generative-ai/image/cricket.jpeg",
              "mimeType": "image/jpeg"
            },
            "text": null
          }
        ],
        "role": "user"
      }
    ]
  },
  "response": {
    "candidates": [
      {
        "avgLogprobs": -0.5782725546095107,
        "content": {
          "parts": [
            {
              "text": "This video shows a Google Photos marketing campaign where animals at the Los Angeles Zoo take self-portraits using a modified Google phone housed in a protective case. The image is unrelated."
            }
          ],
          "role": "model"
        },
        "finishReason": "STOP"
      }
    ],
    "modelVersion": "gemini-2.0-flash-001@default",
    "usageMetadata": {
      "candidatesTokenCount": 36,
      "promptTokenCount": 29180,
      "totalTokenCount": 29216
    }
  }
}

Exemple d'échec

{
  "status": "Bad Request: {\"error\": {\"code\": 400, \"message\": \"Please use a valid role: user, model.\", \"status\": \"INVALID_ARGUMENT\"}}",
  "processed_time": "2025-07-09T19:57:43.558+00:00",
  "request": {
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ],
        "role": "tester"
      }
    ]
  },
  "response": {}
}