Batch-Inferenz aus Cloud Storage

Auf dieser Seite wird beschrieben, wie Sie Batchinferenzen mit Cloud Storage erhalten.

1. Eingaben vorbereiten

Für die Batchinferenz für Gemini-Modelle wird eine JSON Lines-Datei (JSONL) verwendet, die in Cloud Storage gespeichert ist. Jede Zeile in den Batch-Eingabedaten ist eine Anfrage an das Modell.

Beispiel:

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

Laden Sie die Beispieldatei für Batchanfragen herunter

Nachdem Sie Ihre Eingabedaten vorbereitet und in Cloud Storage hochgeladen haben, prüfen Sie, ob der KI Platform-Dienst Agent die Berechtigung zum Lesen der Cloud Storage-Datei hat.

2. Batchjob senden

Sie können einen Batchjob mit der Cloud de Confiance Console, der REST API, oder dem Google Gen AI SDK erstellen.

Console

  1. Rufen Sie im Bereich **Agent Platform** der Cloud de Confiance Console die Seite Batchinferenz auf.

    Zu „Batchinferenz“

  2. Klicken Sie auf Erstellen.

REST

Verwenden Sie die projects.locations.batchPredictionJobs.create Methode, um einen Batchinferenzjob zu erstellen.

Ersetzen Sie folgende Werte in den Anfragedaten:

  • ENDPOINT_PREFIX: Die Region der Modellressource gefolgt von -. Beispiel: us-central1-. Wenn Sie den globalen Endpunkt verwenden, lassen Sie das Feld leer. Hinweis: Der globale End endpoint wird für die Batch Inferenz mit feinabgestimmten Modellen nicht unterstützt.
  • LOCATION: Eine Region, die Gemini-Modelle unterstützt. Wenn Sie den globalen Endpunkt verwenden, geben Sie global ein.
  • PROJECT_ID: Ihre Projekt-ID.
  • MODEL_PATH: Der Name des Publisher-Modells, z. B. publishers/google/models/gemini-2.5-flash, oder der Name des feinabgestimmten Endpunkts, z. B. projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID, wobei MODEL_ID die Modell-ID des feinabgestimmten Modells ist.
  • INPUT_URI: Der Cloud Storage-Speicherort Ihrer JSONL-Eingabe für die Batchinferenz, z. B. gs://bucketname/path/to/file.jsonl.
  • OUTPUT_FORMAT: Geben Sie jsonl an, um die Ausgabe in einen Cloud Storage-Bucket zu schreiben.
  • DESTINATION: Geben Sie für BigQuery bigqueryDestination an. Geben Sie für Cloud Storage gcsDestination an.
  • OUTPUT_URI_FIELD_NAME: Geben Sie für BigQuery outputUri an. Geben Sie für Cloud Storage outputUriPrefix an.
  • OUTPUT_URI: Geben Sie für BigQuery den Tabellenspeicherort an, z. B. bq://myproject.mydataset.output_result. Die Region des Ausgabe- BigQuery-Datasets muss mit der des Agent Platform-Batch- Inferenjobs übereinstimmen. Geben Sie für Cloud Storage den Bucket- und Verzeichnisspeicherort an, z. B. gs://mybucket/path/to/output.

HTTP-Methode und URL: 

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

JSON-Text der Anfrage: 

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

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

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

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

$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

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

Die Antwort enthält eine eindeutige Kennung für den Batchjob. Sie können den Status des Batchjobs mit der BATCH_JOB_ID abfragen. Weitere Informationen finden Sie unter Jobstatus überwachen.

Python

Installieren

pip install --upgrade google-genai

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Legen Sie Umgebungsvariablen fest, um das Google Gen AI SDK mit Vertex AI zu verwenden: 

# 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 = "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-3.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. Jobstatus und -fortschritt überwachen

Nachdem der Job gesendet wurde, können Sie den Status Ihres Batchjobs mit der Cloud de Confiance Console, der REST API oder dem Google Gen AI SDK prüfen.

Console

  1. Rufen Sie die Batchinferenz Seite auf.

    Zu „Batchinferenz“

  2. Wählen Sie Ihren Batchjob aus, um den Fortschritt zu überwachen.

REST

Verwenden Sie die projects.locations.batchPredictionJobs.get Methode und sehen Sie sich das CompletionStats Feld in der Antwort an, um einen Batchinferenzjob zu überwachen.

Ersetzen Sie folgende Werte in den Anfragedaten:

  • ENDPOINT_PREFIX: Die Region der Modellressource gefolgt von -. Beispiel: us-central1-. Wenn Sie den globalen Endpunkt verwenden, lassen Sie das Feld leer.
  • LOCATION: Eine Region, die Gemini-Modelle unterstützt. Wenn Sie den globalen Endpunkt verwenden, geben Sie global ein.
  • PROJECT_ID: Ihre Projekt-ID.
  • BATCH_JOB_ID: Ihre Batchjob-ID.

HTTP-Methode und URL: 

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

Senden Sie die Anfrage mithilfe einer der folgenden Optionen:

curl

Führen Sie folgenden Befehl aus: 

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

Führen Sie folgenden Befehl aus: 

$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

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

Python

Installieren

pip install --upgrade google-genai

Weitere Informationen finden Sie in der SDK-Referenzdokumentation.

Legen Sie Umgebungsvariablen fest, um das Google Gen AI SDK mit Vertex AI zu verwenden: 

# 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

Beschreibungen der Jobstatus finden Sie unter JobState.

4. Batchausgabe abrufen

Wenn ein Batchinferenzjob abgeschlossen ist, wird die Ausgabe in dem Cloud Storage-Bucket gespeichert, den Sie beim Erstellen des Jobs angegeben haben. Für erfolgreiche Zeilen werden die Modellantworten im Feld response gespeichert. Andernfalls werden Fehlerdetails zur weiteren Überprüfung im Feld status gespeichert.

Bei Jobs mit langer Ausführungszeit werden abgeschlossene Inferenzen kontinuierlich in das angegebene Ausgabeziel exportiert. Wenn der Batchinferenzjob beendet wird, werden alle abgeschlossenen Zeilen exportiert. Es werden nur abgeschlossene Inferenzen in Rechnung gestellt.

Ausgabebeispiele

Erfolgreiches Beispiel

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

Beispiel für Fehler

{
  "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": {}
}

Unvollständigen Batchjob fortsetzen

Wenn ein Batchinferenzjob fehlschlägt, abgebrochen wird oder abläuft, können Sie ihn fortsetzen, indem Sie einen neuen Batchjob erstellen. Der neue Job verarbeitet nur die unvollständigen oder fehlgeschlagenen Anfragen aus dem vorherigen Job und führt die neuen Ergebnisse mit denen aus den zuvor abgeschlossenen Anfragen zusammen. Wenn der unvollständige Batchjob beispielsweise zu 90 % abgeschlossen war, verarbeitet der neue Job die restlichen 10% der Anfragen.

Wenn Sie einen Batchjob fortsetzen möchten, erstellen Sie einen neuen Batchjob und geben Sie die Cloud Storage-Datei als Eingabe für den neuen Job an.