Predição em lote para o Cloud Storage

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

1. Preparar suas entradas

O 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 acessar o arquivo do Cloud Storage.

2. Enviar um job em lote

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

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:

  • LOCATION: uma região compatível com modelos do Gemini.
  • 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://LOCATION-aiplatform.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 a seguir: 

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

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://LOCATION-aiplatform.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 os relatórios de conta de serviço personalizada, andamento em tempo real, CMEK e VPCSC.

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

Depois que o job for enviado, verifique o status dele usando a API, o SDK e o console do Cloud.

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:

  • LOCATION: uma região compatível com modelos do Gemini.
  • PROJECT_ID: .
  • BATCH_JOB_ID: o ID do job em lote.

Método HTTP e URL: 

GET https://LOCATION-aiplatform.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://LOCATION-aiplatform.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://LOCATION-aiplatform.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/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

O status de um determinado job em lote pode ser um dos seguintes:

  • JOB_STATE_PENDING: fila para capacidade. O job pode ficar no estado queue por até 72 horas antes de entrar no estado running.
  • JOB_STATE_RUNNING: o arquivo de entrada foi validado e o lote está sendo executado.
  • JOB_STATE_SUCCEEDED: o lote foi concluído e os resultados estão prontos.
  • JOB_STATE_FAILED: o arquivo de entrada falhou no processo de validação ou não pôde ser concluído dentro do período de 24 horas após entrar no estado RUNNING.
  • JOB_STATE_CANCELLING: o lote está sendo cancelado.
  • JOB_STATE_CANCELLED: o lote foi cancelado

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