Inferência em lote do Cloud Storage

Nesta página, descrevemos como receber inferências em lote usando o Cloud Storage.

1. Preparar suas entradas

A inferência 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 ao modelo.

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

Baixar o arquivo de solicitação em lote de exemplo

Depois de preparar os dados de entrada e fazer upload deles para o Cloud Storage, verifique se o agente de serviço da plataforma de IA tem permissão para ler o arquivo do Cloud Storage.

2. Enviar um job em lote

É possível criar um job em lote usando o Cloud de Confiance console, a API REST, ou o SDK de IA Generativa do Google.

Console

  1. Na seção "Agent Platform" do Cloud de Confiance console, acesse a página Inferência em lote.

    Acessar a inferência em lote

  2. Clique em Criar.

REST

Para criar um job de inferência em lote, use o projects.locations.batchPredictionJobs.create método.

Antes de usar qualquer um dos dados da solicitação, faça as seguintes substituições:

  • 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 que oferece suporte a 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 do Cloud Storage da entrada de inferência em lote JSONL, como gs://bucketname/path/to/file.jsonl.
  • OUTPUT_FORMAT: para gerar a saída em um bucket do Cloud Storage, especifique jsonl.
  • DESTINATION: para o BigQuery, especifique bigqueryDestination. Para o 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 BigQuery precisa ser a mesma do job de inferência em lote da Agent Platform. 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-inference-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://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 o job em lote. É possível pesquisar o status do job em lote usando o BATCH_JOB_ID. Para mais informações, consulte Monitorar o status do job.

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 do Google 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_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. 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 Cloud de Confiance console, a API REST ou o SDK de IA Generativa do Google.

Console

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

    Acessar a inferência em lote

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

REST

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

Antes de usar qualquer um dos dados da solicitação, faça as seguintes substituições:

  • 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.
  • LOCATION: uma região que oferece suporte a 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 do Google 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_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

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

4. Recuperar saída em lote

Quando um job de inferência em lote é concluído, a saída é armazenada no bucket do Cloud Storage especificado ao criar o job. Para linhas bem-sucedidas, as respostas do modelo são armazenadas no campo response. Caso contrário, os detalhes do erro são armazenados no campo status para inspeção posterior.

Durante jobs de longa duração, as inferências concluídas são exportadas continuamente para o destino de saída especificado. Se o job de inferência em lote for encerrado, todas as linhas concluídas serão exportadas. Você só paga pelas inferências 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": {}
}

Retomar um job em lote incompleto

Se um job de inferência em lote falhar, for cancelado ou expirar, você poderá retomá-lo criando um novo job em lote. O novo job processa apenas as solicitações incompletas ou com falha do job anterior, mesclando os novos resultados com aqueles das solicitações concluídas anteriormente. Por exemplo, se o job em lote incompleto estiver 90% concluído, o novo job processará os 10% restantes das solicitações.

Para retomar um job em lote, crie um novo job em lote, fornecendo o arquivo do Cloud Storage como entrada para o novo job.