Inferensi batch dari Cloud Storage

Halaman ini menjelaskan cara mendapatkan inferensi batch menggunakan Cloud Storage.

1. Menyiapkan input Anda

Inferensi batch untuk model 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 menggunakan konsol Google Cloud , REST API, atau Google Gen AI SDK.

Konsol

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

    Buka Inferensi Batch

  2. Klik Buat.

REST

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

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • ENDPOINT_PREFIX: Region resource model yang diikuti dengan -. Misalnya, us-central1-. Jika menggunakan endpoint global, biarkan kosong. Catatan: Endpoint global tidak didukung untuk inferensi batch menggunakan model yang disesuaikan.
  • LOCATION: Region yang mendukung model Gemini. Jika menggunakan endpoint global, masukkan global.
  • 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 untuk input inferensi 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 inferensi batch Vertex AI. Untuk Cloud Storage, tentukan lokasi bucket dan direktori seperti gs://mybucket/path/to/output.

Metode HTTP dan URL: 

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

Meminta isi JSON: 

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

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://ENDPOINT_PREFIXaiplatform.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://ENDPOINT_PREFIXaiplatform.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: Akun layanan kustom dan CMEK 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/.../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. Memantau status dan progres tugas

Setelah tugas dikirimkan, Anda dapat memeriksa status tugas batch menggunakan konsol Google Cloud , REST API, atau Google Gen AI SDK.

Konsol

  1. Buka halaman Inferensi Batch.

    Buka Inferensi Batch

  2. Pilih tugas batch Anda untuk memantau progresnya.

REST

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

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • ENDPOINT_PREFIX: Region resource model yang diikuti dengan -. Misalnya, us-central1-. Jika menggunakan endpoint global, biarkan kosong. Catatan: Endpoint global tidak didukung untuk inferensi batch menggunakan model yang disesuaikan.
  • LOCATION: Region yang mendukung model Gemini. Jika menggunakan endpoint global, masukkan global.
  • PROJECT_ID: Project ID Anda.
  • BATCH_JOB_ID: ID tugas batch Anda.

Metode HTTP dan URL: 

GET https://ENDPOINT_PREFIXaiplatform.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://ENDPOINT_PREFIXaiplatform.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://ENDPOINT_PREFIXaiplatform.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/.../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

Untuk deskripsi status status tugas, lihat JobState.

4. Mengambil output batch

Setelah tugas inferensi 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, inferensi yang telah selesai diekspor secara berkelanjutan ke tujuan output yang ditentukan. Jika tugas inferensi batch dihentikan, semua baris yang selesai akan diekspor. Anda hanya dikenai biaya untuk inferensi 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": {}
}