Previsão em lote para o BigQuery

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

1. Prepare as suas entradas

Entrada de armazenamento do BigQuery

    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 no qual a sua conta de serviço foi criada.
  • SERVICE_ACCOUNT_ID: o ID da conta de serviço.
  • É necessária uma coluna request e tem de ser um JSON válido. Estes dados JSON representam a sua entrada para o modelo.
  • O conteúdo na coluna request tem de corresponder à estrutura de um GenerateContentRequest. + A tabela de entrada pode ter tipos de dados de coluna diferentes de request. Estas colunas podem ter tipos de dados do BigQuery, exceto os seguintes: matriz, struct, intervalo, data/hora e geografia. Estas colunas são ignoradas para a geração de conteúdo, mas são 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."
      }
    ]
  }
}

2. Envie uma tarefa de lote

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

A tarefa e a tabela têm de estar na mesma região.

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:

  • LOCATION: Uma região que suporta modelos Gemini.
  • PROJECT_ID: o seu ID do projeto.
  • MODEL_PATH: o nome do modelo do publicador, por exemplo, publishers/google/models/gemini-2.0-flash-001; 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 tabela do BigQuery onde se encontra a entrada de previsão em lote, como bq://myproject.mydataset.input_table. O conjunto de dados tem de estar localizado na mesma região que a tarefa de previsão em lote. Os conjuntos de dados de várias regiões não são suportados.
  • OUTPUT_FORMAT: para gerar resultados numa tabela do BigQuery, especifique bigquery. Para gerar resultados num 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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs

Corpo JSON do pedido: 

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

curl

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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs"

PowerShell

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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs" | Select-Object -Expand Content

Deve receber uma resposta JSON semelhante à seguinte.

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: não são suportados relatórios de conta de serviço personalizada, progresso em direto, CMEK e VPCSC.

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 = 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.5-flash",
    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/.../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 API, do SDK e da Cloud Console.

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

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

Deve receber uma resposta JSON semelhante à seguinte.

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

O estado de uma determinada tarefa em lote pode ser qualquer um dos seguintes:

  • JOB_STATE_PENDING: fila para capacidade. A tarefa pode estar no estado queue até 72 horas antes de entrar no estado running.
  • JOB_STATE_RUNNING: o ficheiro de entrada foi validado com êxito e o lote está atualmente em execução.
  • JOB_STATE_SUCCEEDED: o lote foi concluído e os resultados estão prontos
  • JOB_STATE_FAILED: o ficheiro de entrada falhou no processo de validação ou não foi possível concluí-lo no período de 24 horas após a entrada no estado RUNNING.
  • JOB_STATE_CANCELLING: o lote está a ser cancelado
  • JOB_STATE_CANCELLED: o lote foi cancelado

4. Obtenha o resultado do lote

Quando uma tarefa de previsão em lote é concluída, o resultado é armazenado na tabela do BigQuery que especificou no seu pedido.

Para as linhas com êxito, as respostas do modelo são armazenadas na coluna response. Caso contrário, os detalhes dos erros são armazenados na coluna status para inspeção adicional.

Exemplo de saída

Exemplo bem-sucedido

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

Exemplo com falha

  • Pedido

    {"contents":[{"parts":{"text":"Explain how AI works in a few words."},"role":"tester"}]}

  • Resposta

    Bad Request: {"error": {"code": 400, "message": "Please use a valid role: user, model.", "status": "INVALID_ARGUMENT"}}