Previsão em lote

A predição em lote é uma técnica valiosa para aplicar modelos de aprendizado de máquina a conjuntos de dados grandes de maneira eficiente. Em vez de processar pontos de dados individuais, você pode enviar um lote de dados para a previsão do Gemini, economizando tempo e recursos computacionais. Ao contrário da previsão on-line, em que você está limitado a um comando de entrada por vez, é possível enviar um grande número de solicitações multimodais em um único comando em lote. Em seguida, suas respostas são preenchidas de forma assíncrona no local de saída do armazenamento do BigQuery ou do Cloud Storage.

As solicitações em lote para modelos do Gemini têm desconto de 50% em relação a solicitações padrão. Para saber mais, consulte a página de preços.

Caso de uso de previsão em lote

Considere uma livraria on-line com milhares de livros no banco de dados. Em vez de gerar descrições individualmente para cada livro, o que seria demorado, essa loja pode usar a previsão em lote do Gemini para processar todas as informações do livro de uma vez. Essa abordagem melhora drasticamente a eficiência, reduzindo o tempo de processamento geral e minimizando os recursos computacionais necessários.

A predição em lote também pode melhorar a consistência com a automação. Ao processar todas as descrições simultaneamente, o modelo mantém um tom e estilo uniforme nas descrições do livro, reforçando a identidade da marca. Essa livraria também pode integrar a previsão em lote ao fluxo de trabalho para gerar automaticamente descrições de novas entradas de livros, eliminando o esforço manual e garantindo que o site permaneça atualizado com a intervenção humana mínima.

Modelos do Gemini compatíveis com previsões em lote

Os seguintes modelos do Gemini são compatíveis com previsões em lote:

As solicitações em lote para modelos do Gemini aceitam origens de armazenamento do BigQuery e do Cloud Storage. Você pode escolher se quer gerar previsões em uma tabela do BigQuery ou em um arquivo JSONL em um bucket do Cloud Storage.

Predição em lote para o Cloud Storage

Preparar suas entradas

Entrada do Cloud Storage

  • Formato do arquivo: linhas JSON (JSONL)
  • Localizado em us-central1

  • Precisa ter as permissões adequadas do Cloud Storage para a conta de serviço. Para conceder à conta de serviço permissão de leitura e gravação em um bucket do Cloud Storage, use o comando gcloud iam service-accounts add-iam-policy-binding da seguinte maneira:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
    --role="storage.objectUser"

    Substitua os seguintes valores:

    • PROJECT_ID: o projeto em que a conta de serviço foi criada.
    • SERVICE_ACCOUNT_ID: o ID da conta de serviço.

  • Os seguintes modelos do Gemini são compatíveis com fileData:

    • gemini-2.0-flash-001
    • gemini-2.0-flash-lite-001
Exemplo de entrada (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"}}]}]}}
{"request":{"contents": [{"role": "user", "parts": [{"text": "Describe what is happening in this video."}, {"fileData": {"fileUri": "gs://cloud-samples-data/generative-ai/video/another_video.mov", "mimeType": "video/mov"}}]}]}}

Solicitar um job de previsão em lote

Especifique a tabela de entrada, o modelo e o local de saída do Cloud Storage.

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 Gemini.
  • PROJECT_ID: o ID do projeto.
  • INPUT_URI: o local do Cloud Storage da entrada de previsão em lote JSONL, como gs://bucketname/path/to/file.jsonl.
  • OUTPUT_FORMAT: para gerar saída em uma tabela do BigQuery, especifique bigquery. Para gerar 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 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": "publishers/google/models/gemini-2.0-flash-001",
  "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 tarefa em lote. É possível pesquisar o status da tarefa em lote usando BATCH_JOB_ID até que o job state seja JOB_STATE_SUCCEEDED. Exemplo:

curl \
  -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/batchPredictionJobs/BATCH_JOB_ID

Gen AI SDK for 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 da 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=us-central1
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(
    model="gemini-2.0-flash-001",
    # 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

Saída da previsão em lote

Quando uma tarefa de previsão em lote é concluída, a saída é armazenada no bucket do Cloud Storage ou na tabela do BigQuery especificada na solicitação. Para linhas com sucesso, as respostas do modelo são armazenadas na coluna response. Caso contrário, os detalhes do erro são armazenados na coluna status para uma inspeção mais detalhada.

Durante jobs de longa duração, as previsões concluídas são exportadas continuamente para o destino de saída especificado. Isso começa após 90 minutos. Se o job de previsão em lote for cancelado ou falhar, todas as previsões concluídas serão exportadas.

Exemplo de saída do Cloud Storage

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

Previsão em lote para o BigQuery

Especifique a tabela de entrada, o modelo e o local de saída do BigQuery. O job de previsão em lote e a tabela precisam estar na mesma região.

Preparar suas entradas

Entrada de armazenamento do BigQuery

  • Sua conta de serviço precisa ter as permissões adequadas do BigQuery. Para conceder à conta de serviço o papel de Usuário do BigQuery, use o comando gcloud iam service-accounts add-iam-policy-binding da seguinte maneira:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/bigquery.user"

    Substitua os seguintes valores:

    • PROJECT_ID: o projeto em que a conta de serviço foi criada.
    • SERVICE_ACCOUNT_ID: o ID da conta de serviço.

  • Uma coluna request é necessária e precisa ser um JSON válido. Esses dados JSON representam sua entrada para o modelo.

  • O conteúdo na coluna request precisa corresponder à estrutura de um GenerateContentRequest.

  • A tabela de entrada pode ter tipos de dados de coluna diferentes de request. Essas colunas podem ter tipos de dados do BigQuery, exceto: matriz, struct, intervalo, data e hora e geografia. Essas colunas são ignoradas para geração de conteúdo, mas incluídas na tabela de saída. O sistema reserva dois nomes de colunas para a saída: response e status. Eles são usados para fornecer informações sobre o resultado do job de previsão em lote.

  • Os seguintes modelos do Gemini são compatíveis com fileData:

    • gemini-2.0-flash-001
    • gemini-2.0-flash-lite-001
Exemplo de entrada (JSON) 
        
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Give me a recipe for banana bread."
        }
      ]
    }
  ],
  "system_instruction": {
    "parts": [
      {
        "text": "You are a chef."
      }
    ]
  }
}

Solicitar um job de previsão em lote

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 Gemini.
  • PROJECT_ID: o ID do projeto.
  • INPUT_URI: a tabela do BigQuery em que a entrada de previsão em lote está localizada, como bq://myproject.mydataset.input_table. Não há suporte para conjuntos de dados multirregionais.
  • OUTPUT_FORMAT: para gerar saída em uma tabela do BigQuery, especifique bigquery. Para gerar 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 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-bigquery-batch-prediction-job",
  "model": "publishers/google/models/gemini-2.0-flash-001",
  "inputConfig": {
    "instancesFormat": "bigquery",
    "bigquerySource":{
      "inputUri" : "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 tarefa em lote. É possível pesquisar o status da tarefa em lote usando BATCH_JOB_ID até que o job state seja JOB_STATE_SUCCEEDED. Exemplo:

curl \
  -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/batchPredictionJobs/BATCH_JOB_ID

Gen AI SDK for 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 da 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=us-central1
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 = f"bq://your-project.your_dataset.your_table"

job = client.batches.create(
    model="gemini-2.0-flash-001",
    src="bq://storage-samples.generative_ai.batch_requests_for_multimodal_input",
    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

Recuperar saída em lote

Quando uma tarefa de previsão em lote é concluída, a saída é armazenada na tabela do BigQuery especificada na solicitação.

Para linhas com sucesso, as respostas do modelo são armazenadas na coluna response. Caso contrário, os detalhes do erro são armazenados na coluna status para uma inspeção mais detalhada.

Exemplo de uma saída do BigQuery

solicitação resposta status 
{"content":[{...}]}
 
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "In a medium bowl, whisk together the flour, baking soda, baking powder."
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.14057204,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.14270912
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 8,
    "candidatesTokenCount": 396,
    "totalTokenCount": 404
  }
}

A seguir