Prediksi batch untuk BigQuery

Halaman ini menjelaskan cara mendapatkan prediksi batch menggunakan BigQuery.

1. Menyiapkan input Anda

Input penyimpanan BigQuery

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

Ganti nilai berikut:

*   <var>PROJECT_ID</var>: The project that your service account was
    created in.
*   <var>SERVICE_ACCOUNT_ID</var>: The ID for the service account.
  • Kolom request diperlukan, dan harus berupa JSON yang valid. Data JSON ini merepresentasikan input Anda untuk model.
  • Konten di kolom request harus sesuai dengan struktur GenerateContentRequest. + Tabel input Anda dapat memiliki jenis data kolom selain request. Kolom ini dapat memiliki jenis data BigQuery kecuali untuk jenis berikut: array, struct, rentang, datetime, dan geografi. Kolom ini diabaikan untuk pembuatan konten, tetapi disertakan dalam tabel output.
Contoh input (JSON) 
        
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Give me a recipe for banana bread."
        }
      ]
    }
  ],
  "system_instruction": {
    "parts": [
      {
        "text": "You are a chef."
      }
    ]
  }
}

2. Mengirimkan tugas batch

Anda dapat membuat tugas batch melalui konsol Google Cloud , Google Gen AI SDK, atau REST API.

Tugas dan tabel Anda harus berada di region yang sama.

Konsol

  1. Di bagian Vertex AI pada Google Cloud konsol, buka halaman Inferensi Batch.

    Buka Inferensi Batch

  2. Klik Buat.

REST

Untuk membuat tugas prediksi batch, gunakan metode projects.locations.batchPredictionJobs.create.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • LOCATION: Region yang mendukung model Gemini.
  • PROJECT_ID: Project ID Anda.
  • MODEL_PATH: nama model penayang, misalnya, publishers/google/models/gemini-2.0-flash-001; atau nama endpoint yang disesuaikan, misalnya, projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID, dengan MODEL_ID adalah ID model yang disesuaikan.
  • INPUT_URI: Tabel BigQuery tempat input prediksi batch Anda berada seperti bq://myproject.mydataset.input_table. Set data harus berada di region yang sama dengan tugas prediksi batch. Set data multi-region tidak didukung.
  • OUTPUT_FORMAT: Untuk menghasilkan output ke tabel BigQuery, tentukan bigquery. Untuk menghasilkan output ke bucket Cloud Storage, tentukan jsonl.
  • DESTINATION: Untuk BigQuery, tentukan bigqueryDestination. Untuk Cloud Storage, tentukan gcsDestination.
  • OUTPUT_URI_FIELD_NAME: Untuk BigQuery, tentukan outputUri. Untuk Cloud Storage, tentukan outputUriPrefix.
  • OUTPUT_URI: Untuk BigQuery, tentukan lokasi tabel seperti bq://myproject.mydataset.output_result. Region set data BigQuery output harus sama dengan tugas prediksi batch Vertex AI. Untuk Cloud Storage, tentukan lokasi bucket dan direktori seperti gs://mybucket/path/to/output.

Metode HTTP dan URL: 

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

Isi JSON permintaan: 

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

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

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

PowerShell

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs" | Select-Object -Expand Content

Anda akan melihat respons JSON yang mirip seperti berikut:

Responsnya menyertakan ID unik untuk tugas batch. Anda dapat melakukan polling untuk status tugas batch menggunakan BATCH_JOB_ID. Untuk mengetahui informasi selengkapnya, lihat Memantau status tugas. Catatan: Laporan akun Layanan Kustom, progres langsung, CMEK, dan VPCSC tidak didukung.

Python

Instal

pip install --upgrade google-genai

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Gen AI SDK dengan 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 = 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-2.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/%PROJECT_ID%/locations/us-central1/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. Memantau status dan progres tugas

Setelah tugas dikirimkan, Anda dapat memeriksa status tugas batch menggunakan API, SDK, dan Konsol Cloud.

Konsol

  1. Buka halaman Inferensi Batch.

    Buka Inferensi Batch

  2. Pilih tugas batch Anda untuk memantau progresnya.

REST

Untuk memantau tugas prediksi batch, gunakan metode projects.locations.batchPredictionJobs.get dan lihat kolom CompletionStats dalam respons.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • LOCATION: Region yang mendukung model Gemini.
  • PROJECT_ID: .
  • BATCH_JOB_ID: ID tugas batch Anda.

Metode HTTP dan URL: 

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

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Jalankan perintah berikut: 

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

PowerShell

Jalankan perintah berikut: 

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

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

Anda akan menerima respons JSON yang mirip dengan berikut ini.

Python

Instal

pip install --upgrade google-genai

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Gen AI SDK dengan 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/us-central1/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

Status tugas batch tertentu dapat berupa salah satu dari berikut:

  • JOB_STATE_PENDING: Antrean untuk kapasitas. Tugas dapat berada dalam status queue hingga 72 jam sebelum memasuki status running.
  • JOB_STATE_RUNNING: File input berhasil divalidasi dan batch sedang dijalankan.
  • JOB_STATE_SUCCEEDED: Batch telah selesai dan hasilnya sudah siap
  • JOB_STATE_FAILED: file input gagal dalam proses validasi, atau tidak dapat diselesaikan dalam jangka waktu 24 jam setelah memasuki status RUNNING.
  • JOB_STATE_CANCELLING: batch sedang dibatalkan
  • JOB_STATE_CANCELLED: batch dibatalkan

4. Mengambil output batch

Setelah tugas prediksi batch selesai, output akan disimpan di tabel BigQuery yang Anda tentukan dalam permintaan Anda.

Untuk baris yang berhasil, respons model disimpan di kolom response. Jika tidak, detail error akan disimpan di kolom status untuk pemeriksaan lebih lanjut.

Contoh output

Contoh yang berhasil

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

Contoh gagal

  • Permintaan

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

  • Tanggapan

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