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

Cloud Storage からのバッチ予測

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

1. 入力を準備する

Gemini モデルのバッチ予測は、Cloud Storage に保存されている 1 つの 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 コンソール、REST API、または Google 生成 AI SDK を使用して作成できます。

コンソール

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

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

REST

バッチ予測ジョブを作成するには、projects.locations.batchPredictionJobs.create メソッドを使用します。

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

ENDPOINT_PREFIX: モデルリソースのリージョンと -（例: us-central1-）。グローバルエンドポイントを使用する場合は、空白のままにします。注: チューニング済みモデルを使用するバッチ推論では、グローバルエンドポイントはサポートされていません。
LOCATION: Gemini モデルをサポートするリージョン。グローバルエンドポイントを使用する場合は、「global」と入力します。
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 バケットに出力するには、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://ENDPOINT_PREFIXaiplatform.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

注: 次のコマンドは、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://ENDPOINT_PREFIXaiplatform.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://ENDPOINT_PREFIXaiplatform.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-cloud-storage-batch-prediction-job",
  "model": "publishers/google/models/gemini-2.5-flash",
  "inputConfig": {
    "instancesFormat": "jsonl",
    "gcsSource": {
      "uris": [
        "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 はサポートされていません。

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/.../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. ジョブのステータスと進行状況をモニタリングする

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

コンソール

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

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

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

ジョブの状態ステータスの説明については、JobState をご覧ください。

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

バッチ予測ジョブが完了すると、ジョブの作成時に指定した Cloud Storage バケットに出力が保存されます。成功した行の場合、モデルのレスポンスは 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": {}
}