Batch-Inferenz für BigQuery

Auf dieser Seite wird beschrieben, wie Sie Batchvorhersagen mit BigQuery erhalten.

1. Eingaben vorbereiten

BigQuery-Speichereingabe

Ihr Dienstkonto muss die entsprechenden BigQuery-Berechtigungen haben. Verwenden Sie den Befehl gcloud iam service-accounts add-iam-policy-binding, um dem Dienstkonto die Rolle BigQuery-Nutzer zuzuweisen:

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

Ersetzen Sie die folgenden Werte:

  • PROJECT_ID: Die ID des Projekts, in dem Ihr Dienstkonto erstellt wurde.
  • SERVICE_ACCOUNT_ID: Die ID des Dienstkontos.

Eine request-Spalte ist erforderlich und muss gültiges JSON-Format sein. Diese JSON-Daten stellen Ihre Eingabe für das Modell dar.

Der Inhalt in der request Spalte muss mit der Struktur einer GenerateContentRequest übereinstimmen.

Ihre Eingabetabelle kann andere Spaltendatentypen als request haben. Diese Spalten können BigQuery-Datentypen haben, mit Ausnahme der folgenden: Array, Struct, Range, Datetime und Geography. Diese Spalten werden bei der Contentgenerierung ignoriert, sind aber in der Ausgabetabelle enthalten.

Beispieleingabe (JSON) 
        
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Give me a recipe for banana bread."
        }
      ]
    }
  ],
  "system_instruction": {
    "parts": [
      {
        "text": "You are a chef."
      }
    ]
  }
}

2. Batchjob senden

Sie können einen Batchjob über die Google Cloud Console, das Google Gen AI SDK, oder die REST API erstellen.

Der Job und die Tabelle müssen sich in derselben Region befinden.

Console

  1. Rufen Sie im Abschnitt „Agent Platform“ der Google Cloud Console die Seite Batchvorhersage auf.

    Zur Batchvorhersage

  2. Klicken Sie auf Erstellen.

REST

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

Ersetzen Sie vor der Verwendung der Anfragedaten Folgendes:

  • 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 Endpunkt wird für Batch Vorhersagen 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.0-flash-001, 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: Die BigQuery-Tabelle, in der sich Ihre Batchvorhersageeingabe befindet, z. B. bq://myproject.mydataset.input_table. Das Dataset muss sich in derselben Region wie der Batchvorhersagejob befinden. Datasets mit mehreren Regionen werden nicht unterstützt.
  • OUTPUT_FORMAT: Geben Sie bigquery an, um die Ausgabe in einer BigQuery-Tabelle zu speichern. Geben Sie jsonl an, um die Ausgabe in einem Cloud Storage-Bucket zu speichern.
  • 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 Batchvorhersagejobs der Agent Platform ü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-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"
    }
  }
}

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. Hinweis: Benutzerdefiniertes Dienstkonto, Live-Fortschritts-, CMEK- und VPCSC-Berichte werden nicht unterstützt.

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

Nachdem der Job gesendet wurde, können Sie den Status Ihres Batchjobs über die API, das SDK und die Google Cloud Console prüfen.

Console

  1. Rufen Sie die Batchvorhersage Seite auf.

    Zur Batchvorhersage

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

REST

Verwenden Sie die projects.locations.batchPredictionJobs.get Methode, um einen Batchvorhersagejob zu überwachen, und rufen Sie das CompletionStats Feld in der Antwort auf.

Ersetzen Sie vor der Verwendung der Anfragedaten Folgendes:

  • 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

Der Status eines bestimmten Batchjobs kann einer der folgenden sein:

  • JOB_STATE_PENDING: In der Warteschlange für Kapazität. Der Job kann bis zu 72 Stunden lang den Status queue haben, bevor er den Status running erhält.
  • JOB_STATE_RUNNING: Die Eingabedatei wurde erfolgreich validiert und der Batch wird ausgeführt.
  • JOB_STATE_SUCCEEDED: Der Batch wurde abgeschlossen und die Ergebnisse sind verfügbar.
  • JOB_STATE_FAILED: Die Eingabedatei hat den Validierungsprozess nicht bestanden oder konnte nicht innerhalb von 24 Stunden nach dem Status RUNNING abgeschlossen werden.
  • JOB_STATE_CANCELLING: Der Batch wird abgebrochen.
  • JOB_STATE_CANCELLED: Der Batch wurde abgebrochen.

4. Batchausgabe abrufen

Wenn eine Batchvorhersage abgeschlossen ist, wird die Ausgabe in der BigQuery-Tabelle gespeichert, die Sie in der Anfrage angegeben haben.

Für erfolgreiche Zeilen werden die Modellantworten in der Spalte response gespeichert. Andernfalls werden Fehlerdetails zur weiteren Überprüfung in der Spalte status gespeichert.

Ausgabebeispiel

Erfolgreiches Beispiel

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

Beispiel für Fehler

  • Anfrage

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

  • Antwort

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

Unvollständigen Batchjob fortsetzen

Wenn ein Batchvorhersagejob 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 oder die BigQuery-Tabellenausgabe als Eingabe für den neuen Job an.