このページは Cloud Translation API によって翻訳されました。

BigQuery のバッチ予測

このページでは、BigQuery を使用してバッチ予測を取得する方法について説明します。

1. 入力を準備する

BigQuery ストレージ入力

サービスアカウントに適切な BigQuery 権限が付与されている必要があります。サービスアカウントに BigQuery ユーザーのロールを付与するには、次のように gcloud iam service-accounts add-iam-policy-binding コマンドを使用します。

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

次の値を置き換えます。

PROJECT_ID: サービスアカウントが作成されたプロジェクト。
SERVICE_ACCOUNT_ID: サービスアカウントの ID。
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 を使用して作成できます。

ジョブとテーブルは同じリージョンに存在する必要があります。

コンソール

Google Cloud コンソールの [Vertex AI] セクションで、[バッチ推論] ページに移動します。

[バッチ推論] に移動
[作成] をクリックします。

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 メソッドと URL:

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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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 レスポンスが返されます。

レスポンス

{
  "name": "projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID",
  "displayName": "my-bigquery-batch-prediction-job",
  "model": "publishers/google/models/gemini-2.5-flash",
  "inputConfig": {
    "instancesFormat": "bigquery",
    "bigquerySource": {
      "inputUri" : "INPUT_URI"
    }
  },
  "outputConfig": {
    "predictionsFormat": "OUTPUT_FORMAT",
    "DESTINATION": {
      "OUTPUT_URI_FIELD_NAME": "OUTPUT_URI"
    }
  },
  "state": "JOB_STATE_PENDING",
  "createTime": "2024-10-16T19:33:59.153782Z",
  "updateTime": "2024-10-16T19:33:59.153782Z",
  "modelVersionId": "1"
}

レスポンスには、バッチジョブの固有識別子が含まれます。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/.../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. ジョブのステータスと進行状況をモニタリングする

ジョブを送信したら、API、SDK、Cloud コンソールを使用してバッチジョブのステータスを確認できます。

コンソール

[バッチ推論] ページに移動します。

[バッチ推論] に移動
バッチジョブを選択して進行状況をモニタリングします。

REST

バッチ予測ジョブをモニタリングするには、projects.locations.batchPredictionJobs.get メソッドを使用して、レスポンスの CompletionStats フィールドを表示します。

リクエストのデータを使用する前に、次のように置き換えます。

ENDPOINT_PREFIX: モデルリソースのリージョンと -（例: us-central1-）。グローバルエンドポイントを使用する場合は、空白のままにします。注: チューニング済みモデルを使用するバッチ推論では、グローバルエンドポイントはサポートされていません。
LOCATION: Gemini モデルをサポートするリージョン。グローバルエンドポイントを使用する場合は、「global」と入力します。
PROJECT_ID: プロジェクト ID。
BATCH_JOB_ID: 実際のバッチジョブ ID。

HTTP メソッドと URL:

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

次のような JSON レスポンスが返されます。

レスポンス

{
  "name": "projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID",
  "displayName": "my-cloud-storage-batch-prediction-job",
  "model": "publishers/google/models/gemini-2.5-flash",
  ...
  "state": "JOB_STATE_PENDING",
  "completionStats": {
    "successfulCount": "10",
    "failedCount": "1"
  },
  "createTime": "2024-10-16T19:33:59.153782Z",
  "updateTime": "2024-10-16T19:33:59.153782Z",
  "modelVersionId": "1"
}

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/.../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: 容量のキュー。ジョブは、running 状態になるまで最大 72 時間 queue 状態になることがあります。
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"}}

BigQuery のバッチ予測 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

1. 入力を準備する

BigQuery ストレージ入力

2. バッチジョブを送信する

コンソール

REST

curl

PowerShell

レスポンス

Python

インストール

3. ジョブのステータスと進行状況をモニタリングする

コンソール

REST

curl

PowerShell

レスポンス

Python

インストール

4. バッチ出力を取得する

出力の例

BigQuery のバッチ予測