Cloud Storage 的批次預測

本頁說明如何使用 Cloud Storage 取得批次預測。

1. 準備輸入內容

Gemini 模型批次作業接受儲存在 Cloud Storage 中的一個 JSON Lines (JSONL) 檔案做為輸入資料。批次輸入資料中的每一行都是對模型的請求，格式與 Gemini API 相同。

例如：

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

下載範例批次要求檔案

準備好輸入資料並上傳至 Cloud Storage 後，確認 AI Platform 服務代理有權存取 Cloud Storage 檔案。

2. 提交批次工作

您可以透過 Google Cloud 控制台、Google Gen AI SDK 或 REST API 建立批次工作。

控制台

  1. 在 Google Cloud 控制台的 Vertex AI 專區中，前往「Batch Inference」頁面。

    前往「Batch Inference」(批次推論) 頁面

  2. 點選「建立」。

REST

如要建立批次預測工作，請使用 projects.locations.batchPredictionJobs.create 方法。

使用任何要求資料之前，請先替換以下項目：

  • LOCATION：支援 Gemini 模型的區域。
  • PROJECT_ID：您的專案 ID。
  • MODEL_PATH：發布者模型名稱，例如 publishers/google/models/gemini-2.5-flash；或微調端點名稱，例如 projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID，其中 MODEL_ID 是微調模型的模型 ID。
  • INPUT_URI：JSONL 批次預測輸入內容的 Cloud Storage 位置，例如 gs://bucketname/path/to/file.jsonl。
  • OUTPUT_FORMAT：如要輸出至 Cloud Storage bucket，請指定 jsonl。
  • DESTINATION：如果是 BigQuery，請指定 bigqueryDestination。如果是 Cloud Storage，請指定 gcsDestination。
  • OUTPUT_URI_FIELD_NAME： 如果是 BigQuery，請指定 outputUri。如果是 Cloud Storage，請指定 outputUriPrefix。
  • OUTPUT_URI：如果是 BigQuery，請指定資料表位置，例如 bq://myproject.mydataset.output_result。輸出 BigQuery 資料集的區域必須與 Vertex AI 批次預測工作相同。如果是 Cloud Storage，請指定值區和目錄位置，例如 gs://mybucket/path/to/output。

HTTP 方法和網址：

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

JSON 要求主體：

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

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$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

您應該會收到類似如下的 JSON 回應。

回應會包含批次作業的專屬 ID。 您可以使用 BATCH_JOB_ID 輪詢批次作業的狀態。詳情請參閱「監控工作狀態」。 注意：系統不支援自訂服務帳戶、即時進度、CMEK 和 VPCSC 報表。

Python

安裝

pip install --upgrade google-genai

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK： 

# 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. 監控工作狀態和進度

提交工作後，您可以使用 API、SDK 和 Cloud Console 檢查批次工作狀態

控制台

  1. 前往「Batch Inference」(批次推論) 頁面。

    前往「Batch Inference」(批次推論) 頁面

  2. 選取批次工作，即可監控進度。

REST

如要監控批次預測工作，請使用 projects.locations.batchPredictionJobs.get 方法，並查看回應中的 CompletionStats 欄位。

使用任何要求資料之前，請先替換以下項目：

  • LOCATION：支援 Gemini 模型的區域。
  • PROJECT_ID：。
  • BATCH_JOB_ID：批次作業 ID。

HTTP 方法和網址：

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

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令：

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

執行下列指令：

$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

您應該會收到類似如下的 JSON 回應。

Python

安裝

pip install --upgrade google-genai

詳情請參閱 SDK 參考說明文件。

設定環境變數，透過 Vertex AI 使用 Gen AI SDK： 

# 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

特定批次工作的狀態可以是下列任一項：

  • JOB_STATE_PENDING：等待取得容量。工作最多可能在 72 小時內處於 queue 狀態，然後進入 running 狀態。
  • JOB_STATE_RUNNING：輸入檔案已通過驗證，目前正在執行批次作業。
  • JOB_STATE_SUCCEEDED：批次作業已完成，結果已準備就緒
  • JOB_STATE_FAILED：輸入檔案未通過驗證程序，或在進入 RUNNING 狀態後的 24 小時內未完成。
  • JOB_STATE_CANCELLING：批次作業正在取消
  • JOB_STATE_CANCELLED：批次作業已取消

4. 擷取批次輸出內容

批次預測工作完成後，輸出內容會儲存在您建立工作時指定的 Cloud Storage bucket。如果是成功列，模型回覆會儲存在 response 欄位。否則，錯誤詳細資料會儲存在 status 欄位中，以供進一步檢查。

在長時間執行的工作中，系統會持續將完成的預測結果匯出至指定的輸出目的地。如果批次預測工作終止，系統會匯出所有已完成的資料列。系統只會針對完成的預測向您收費。

輸出範例

成功示例

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

失敗範例

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