BigQuery 的批次預測

本頁說明如何使用 BigQuery 取得批次預測結果。

1. 準備輸入內容

BigQuery 儲存空間輸入

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

替換下列值：

*   <var>PROJECT_ID</var>: The project that your service account was
    created in.
*   <var>SERVICE_ACCOUNT_ID</var>: The ID for the service account.
  • 必須提供 request 資料欄，且必須是有效的 JSON。這項 JSON 資料代表模型的輸入內容。
  • 「request」欄中的內容必須符合 GenerateContentRequest 的結構。+ 輸入資料表可以有 request 以外的資料欄資料類型。這些資料欄可以有 BigQuery 資料類型，但下列類型除外：陣列、結構體、範圍、日期時間和地理位置。系統會忽略這些資料欄，但會將其納入輸出表格。
輸入範例 (JSON) 
        
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Give me a recipe for banana bread."
        }
      ]
    }
  ],
  "system_instruction": {
    "parts": [
      {
        "text": "You are a chef."
      }
    ]
  }
}

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.0-flash-001；或微調端點名稱，例如 projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID，其中 MODEL_ID 是微調模型的模型 ID。
  • INPUT_URI：批次預測輸入內容所在的 BigQuery 資料表，例如 bq://myproject.mydataset.input_table。資料集必須與批次預測作業位於同一區域。不支援多區域資料集。
  • OUTPUT_FORMAT：如要輸出至 BigQuery 資料表，請指定 bigquery。如要輸出至 Cloud Storage 值區，請指定 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-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"
    }
  }
}

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

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

提交工作後，您可以使用 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. 擷取批次輸出內容

批次預測工作完成後，系統會根據您的要求，將輸出內容儲存在指定的 BigQuery 表格。

如果資料列成功處理，模型回應會儲存在 response 欄中。 否則，錯誤詳細資料會儲存在 status 欄中，以供進一步檢查。

輸出範例

成功示例

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

失敗範例

  • 要求

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

  • 回應

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