Previsão em lote a partir do Cloud Storage

Esta página descreve como obter previsões em lote através do Cloud Storage.

1. Prepare as suas entradas

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

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

Transfira o ficheiro de pedido em lote de exemplo

Depois de preparar os dados de entrada e carregá-los para o Cloud Storage. Certifique-se de que o agente de serviço do AI Platform tem autorização para o ficheiro do Cloud Storage.

2. Envie uma tarefa de lote

Pode criar uma tarefa em lote através da Google Cloud consola, da API REST ou do SDK Google Gen AI.

Para ver um exemplo de utilização de previsões em lote, execute o bloco de notas "Introdução às previsões em lote com a API Gemini" num dos seguintes ambientes:

Abrir no Colab | Abrir no Colab Enterprise | Abrir no Vertex AI Workbench | Ver no GitHub

Consola

1. Na secção Vertex AI da Google Cloud consola, aceda à página Inferência em lote.

   Aceder à inferência em lote

2. Clique em Criar.

REST

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

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

• ENDPOINT_PREFIX: a região do recurso do modelo seguida de -. Por exemplo, us-central1-. Se usar o ponto final global, deixe em branco. Nota: o ponto final global não é suportado para a inferência em lote com modelos otimizados.
• LOCATION: Uma região que suporta modelos Gemini. Se usar o ponto final global, introduza global.
• PROJECT_ID: o ID do projeto.
• MODEL_PATH: o nome do modelo do publicador, por exemplo, publishers/google/models/gemini-2.5-flash; ou o nome do ponto final otimizado, por exemplo, projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID, em que MODEL_ID é o ID do modelo otimizado.
• INPUT_URI: a localização do Cloud Storage da entrada de previsão em lote JSONL, como gs://bucketname/path/to/file.jsonl.
• OUTPUT_FORMAT: Para enviar o resultado para um contentor 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 a localização da tabela, como bq://myproject.mydataset.output_result. A região do conjunto de dados do BigQuery de saída tem de ser igual à tarefa de previsão em lote do Vertex AI. Para o Cloud Storage, especifique o contentor e a localização 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 do pedido:

{
  "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 o seu pedido, escolha uma destas opções:

curl

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

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

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$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

Deve receber uma resposta JSON semelhante à seguinte.

Resposta

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

A resposta inclui um identificador exclusivo para a tarefa em lote. Pode sondar o estado da tarefa em lote através do comando BATCH_JOB_ID. Para mais informações, consulte o artigo Monitorize o estado da tarefa. Nota: as contas de serviço personalizadas e a CMEK não são suportadas.

Python

Instalação

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 gen com o 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. Monitorize o estado e o progresso da tarefa

Depois de enviar a tarefa, pode verificar o estado da tarefa em lote através da Google Cloud consola, da API REST ou do SDK de IA gen da Google.

Consola

1. Aceda à página Inferência em lote.

   Aceder à inferência em lote

2. Selecione a tarefa em lote para monitorizar o respetivo progresso.

REST

Para monitorizar uma tarefa de previsão em lote, use o método projects.locations.batchPredictionJobs.get e veja o campo CompletionStats na resposta.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

• ENDPOINT_PREFIX: a região do recurso do modelo seguida de -. Por exemplo, us-central1-. Se usar o ponto final global, deixe em branco. Nota: o ponto final global não é suportado para a inferência em lote com modelos otimizados.
• LOCATION: Uma região que suporta modelos Gemini. Se usar o ponto final global, introduza global.
• PROJECT_ID: o ID do seu projeto.
• BATCH_JOB_ID: o ID da tarefa 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 o seu pedido, escolha uma destas opções:

curl

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

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

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

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

Deve receber uma resposta JSON semelhante à seguinte.

Resposta

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

Instalação

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 gen com o 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 ver descrições dos estados de tarefas, consulte JobState.

4. Obtenha o resultado do lote

Quando uma tarefa de previsão em lote é concluída, o resultado é armazenado no contentor do Cloud Storage que especificou quando criou a tarefa. Para as linhas com êxito, 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 adicional.

Durante as tarefas de longa duração, as previsões concluídas são exportadas continuamente para o destino de saída especificado. Se a tarefa de previsão em lote for terminada, todas as linhas concluídas são exportadas. Só lhe são cobradas as previsões concluídas.

Aviso: a eliminação temporária está ativada nos contentores do Cloud Storage, que retêm conteúdo num estado eliminado, o que pode resultar em custos de armazenamento significativos. Recomendamos vivamente que desative a eliminação temporária para evitar custos inesperados.

Exemplos de resultados

Nota: os exemplos seguintes representam uma linha no ficheiro JSONL de saída. Foram formatados para facilitar a leitura.

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