Predição em lote do Cloud Storage

Nesta página, descrevemos como fazer previsões em lote usando o Cloud Storage.

1. Preparar suas entradas

A previsão em lote para modelos do Gemini aceita um arquivo JSON Lines (JSONL) armazenado no Cloud Storage como dados de entrada. Cada linha nos dados de entrada em lote é uma solicitação para o modelo, seguindo o mesmo formato da API Gemini.

Exemplo:

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

Baixe o arquivo de solicitação em lote de amostra.

Depois de preparar e fazer upload dos dados de entrada para o Cloud Storage. Confira se o agente de serviço do AI Platform tem permissão para o arquivo do Cloud Storage.

2. Enviar um job em lote

É possível criar um job em lote usando o console do Google Cloud , a API REST ou o SDK do Google Gen AI.

Console

  1. Na seção "Vertex AI" do console Google Cloud , acesse a página Inferência em lote.

    Acessar "Inferência em lote"

  2. Clique em Criar.

REST

Para criar um job de previsão em lote, use o método projects.locations.batchPredictionJobs.create.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • ENDPOINT_PREFIX: a região do recurso do modelo seguida por -. Por exemplo, us-central1-. Se você estiver usando o endpoint global, deixe em branco. Observação:o endpoint global não é compatível com a inferência em lote usando modelos ajustados.
  • LOCATION: uma região compatível com modelos do Gemini. Se você estiver usando o endpoint global, insira global.
  • PROJECT_ID: o ID do projeto.
  • MODEL_PATH: o nome do modelo do editor, por exemplo, publishers/google/models/gemini-2.5-flash; ou o nome do endpoint ajustado, por exemplo, projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID, em que MODEL_ID é o ID do modelo ajustado.
  • INPUT_URI: o local no Cloud Storage da entrada de previsão em lote JSONL, como gs://bucketname/path/to/file.jsonl.
  • OUTPUT_FORMAT: para gerar saída em um bucket do Cloud Storage, especifique jsonl.
  • DESTINATION: para o BigQuery, especifique bigqueryDestination. No Cloud Storage, especifique gcsDestination.
  • OUTPUT_URI_FIELD_NAME: Para o BigQuery, especifique outputUri. Para o Cloud Storage, especifique outputUriPrefix.
  • OUTPUT_URI: para o BigQuery, especifique o local da tabela, como bq://myproject.mydataset.output_result. A região do conjunto de dados de saída do BigQuery precisa ser a mesma do job de previsão em lote da Vertex AI. Para o Cloud Storage, especifique o bucket e o local do diretório, como gs://mybucket/path/to/output.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$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

Você receberá uma resposta JSON semelhante a seguinte.

A resposta inclui um identificador exclusivo para a job em lote. É possível pesquisar o status da job em lote usando BATCH_JOB_ID. Para mais informações, consulte Monitorar o status do job. Observação: não há suporte para contas de serviço personalizadas e CMEK.

Python

Instalar

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI: 

# 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. Monitorar o status e o progresso do job

Depois que o job for enviado, você poderá verificar o status do job em lote usando o console Google Cloud , a API REST ou o SDK do Google Gen AI.

Console

  1. Acesse a página Inferência em lote.

    Acessar "Inferência em lote"

  2. Selecione o job em lote para monitorar o progresso.

REST

Para monitorar um job de previsão em lote, use o método projects.locations.batchPredictionJobs.get e confira o campo CompletionStats na resposta.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • ENDPOINT_PREFIX: a região do recurso do modelo seguida por -. Por exemplo, us-central1-. Se estiver usando o endpoint global, deixe em branco. Observação:o endpoint global não é compatível com a inferência em lote usando modelos ajustados.
  • LOCATION: uma região compatível com modelos do Gemini. Se você estiver usando o endpoint global, insira global.
  • PROJECT_ID: o ID do projeto.
  • BATCH_JOB_ID: o ID do job em lote.

Método HTTP e URL: 

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

Para enviar a solicitação, escolha uma destas opções:

curl

Execute o seguinte comando:

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

execute o seguinte comando: 

$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

Você receberá uma resposta JSON semelhante a seguinte.

Python

Instalar

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI: 

# 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

Para descrições dos status de estado do job, consulte JobState.

4. Recuperar saída em lote

Quando um job de predição em lote é concluído, a saída é armazenada no bucket do Cloud Storage especificado na criação do job. Para linhas concluídas, as respostas do modelo são armazenadas no campo response. Caso contrário, os detalhes do erro serão armazenados no campo status para inspeção posterior.

Durante jobs de longa duração, as previsões concluídas são exportadas continuamente para o destino de saída especificado. Se o job de previsão em lote for encerrado, todas as linhas concluídas serão exportadas. Você só paga pelas previsões concluídas.

Exemplos de saída

Exemplo bem-sucedido

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

Exemplo com falha

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