Cloud Storage からのバッチ推論

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

1. 入力を準備する

Gemini モデルのバッチ推論は、Cloud Storage に保存されている 1 つの JSON Lines（JSONL）ファイルを入力データとして受け入れます。バッチ入力データの各行は、モデルへのリクエストです。

次に例を示します。

{"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. バッチジョブを送信する

バッチジョブは、 Cloud de Confiance コンソール、REST API、 または Google 生成 AI SDK を使用して作成できます。

Console

  1. コンソールの [Agent Platform] セクションで、 Cloud de Confiance [**バッチ推論**] ページに移動します。

    [バッチ推論] に移動

  2. [作成] をクリックします。

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 の出力データセットのリージョンは、Agent Platform バッチ推論ジョブのリージョンと同じである必要があります。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-inference-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://ENDPOINT_PREFIXaiplatform.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://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs" | Select-Object -Expand Content

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

レスポンスには、バッチジョブの固有識別子が含まれます。BATCH_JOB_ID を使用して、バッチジョブのステータスをポーリングできます。詳細については、 ジョブのステータスをモニタリングするをご覧ください。

Python

インストール

pip install --upgrade google-genai

詳しくは、 SDK リファレンス ドキュメントをご覧ください。

Vertex AI で Google 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_ENTERPRISE=True
 

import time

from google import genai
from google.genai.types import CreateBatchJobConfig, HttpOptions, JobState

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

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

コンソール

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

    [バッチ推論] に移動

  2. バッチジョブを選択して進行状況をモニタリングします。

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 レスポンスが返されます。

Python

インストール

pip install --upgrade google-genai

詳しくは、 SDK リファレンス ドキュメントをご覧ください。

Vertex AI で Google 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_ENTERPRISE=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": {}
}

未完了のバッチジョブを再開する

バッチ推論ジョブが失敗、キャンセル、または期限切れになった場合は、新しいバッチジョブを作成して再開できます。新しいジョブは、前のジョブの未完了リクエストまたは失敗したリクエストのみを処理し、新しい結果を以前に完了したリクエストの結果と統合します。たとえば、未完了のバッチジョブが 90% 完了している場合、新しいジョブは残りの 10% のリクエストを処理します。

バッチジョブを再開するには、新しいバッチジョブを作成し、新しいジョブの入力として Cloud Storage ファイルを指定します。