Prediksi batch untuk Cloud Storage

Halaman ini menjelaskan cara mendapatkan prediksi batch menggunakan Cloud Storage.

1. Menyiapkan input Anda

Model Batch untuk Gemini menerima satu file JSON Lines (JSONL) yang disimpan di Cloud Storage sebagai data input. Setiap baris dalam data input batch adalah permintaan ke model, mengikuti format yang sama untuk Gemini API.

Contoh:

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

Download file permintaan batch contoh

Setelah Anda menyiapkan data input dan menguploadnya ke Cloud Storage. Pastikan Agen Layanan AI Platform memiliki izin ke file Cloud Storage.

2. Mengirimkan tugas batch

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

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.5-flash; atau nama endpoint yang disesuaikan, misalnya, projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID, dengan MODEL_ID adalah ID model yang disesuaikan.
  • INPUT_URI: Lokasi Cloud Storage input prediksi batch JSONL Anda, seperti gs://bucketname/path/to/file.jsonl.
  • OUTPUT_FORMAT: 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-cloud-storage-batch-prediction-job",
  "model": "MODEL_PATH",
  "inputConfig": {
    "instancesFormat": "jsonl",
    "gcsSource": {
      "uris" : "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 = "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/%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 bucket Cloud Storage yang Anda tentukan saat membuat tugas. Untuk baris yang berhasil, respons model disimpan di kolom response. Jika tidak, detail error disimpan di kolom status untuk pemeriksaan lebih lanjut.

Selama tugas yang berjalan lama, prediksi yang telah selesai akan terus diekspor ke tujuan output yang ditentukan. Jika tugas prediksi batch dihentikan, semua baris yang selesai akan diekspor. Anda hanya dikenai biaya untuk prediksi yang selesai.

Contoh output

Contoh yang berhasil

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

Contoh gagal

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