Previsão em lote

A previsão em lote é uma técnica valiosa para aplicar modelos de machine learning a grandes conjuntos de dados de maneira eficiente. Em vez de processar pontos de dados individuais, você pode enviar um lote de dados ao Gemini para previsão, 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 comandos multimodais em uma única solicitação em lote. Então, suas respostas são preenchidas de maneira 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 de uma só vez. Essa abordagem melhora muito a eficiência, reduzindo o tempo geral de processamento 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 um estilo uniformes em todas as descrições de livros, 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 trabalho manual e garantindo que o site permaneça atualizado com intervenção humana mínima.

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

Os seguintes modelos básicos e ajustados do Gemini são compatíveis com previsões em lote:

Limitações

Após o envio, os jobs em lote são validados e enfileirados para a capacidade disponível. Depois que um job começa a ser executado, ele tem um limite de execução de 24 horas. Se ele não for concluído nesse período, todas as solicitações concluídas serão exportadas, e você só vai receber cobranças pelas solicitações concluídas. O tempo máximo que um job em lote pode passar na fila e em execução é de 72 horas.

Entradas e saídas de previsão em lote

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

Recomendamos que sua origem de entrada (tabela ou arquivo) inclua um mínimo de 25.000 solicitações por job. O sistema de previsão em lote divide e paraleliza os jobs o mais rápido e eficiente possível com os recursos disponíveis no momento. Não há um número máximo de solicitações por job.

Para cotas e limites em jobs de previsão em lote, consulte Cotas e limites do sistema da IA generativa na Vertex AI.

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

  • 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="roles/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.
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"}}]}], "generationConfig": {"temperature": 0.9, "topP": 1, "maxOutputTokens": 256}}}
{"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 do Gemini.
  • PROJECT_ID: o ID do projeto.
  • MODEL_PATH: o nome do modelo do editor, por exemplo, publishers/google/models/gemini-2.0-flash-001; 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 uma 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. 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 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

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.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 concluídas, as respostas do modelo são armazenadas na coluna response. Caso contrário, os detalhes do erro serão armazenados na coluna 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. 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 do BigQuery, o modelo e o local de saída. 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 é obrigatória e precisa ser um JSON válido. Esses dados JSON representam sua entrada para o modelo.

  • O conteúdo da 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 os seguintes: array, struct, range, datetime e geography. Essas colunas são ignoradas para geração de conteúdo, mas incluídas na tabela de saída.

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 do Gemini.
  • PROJECT_ID: o ID do projeto.
  • MODEL_PATH: o nome do modelo do editor, por exemplo, publishers/google/models/gemini-2.0-flash-001, 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: 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 uma 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. 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-bigquery-batch-prediction-job",
  "model": "MODEL_PATH",
  "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

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 = f"bq://your-project.your_dataset.your_table"

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.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 concluídas, as respostas do modelo são armazenadas na coluna response. Caso contrário, os detalhes do erro serão armazenados na coluna status para inspeção posterior.

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