Previsão em lote para o BigQuery

Nesta página, descrevemos como receber previsões em lote usando o BigQuery.

1. Preparar 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 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."
      }
    ]
  }
}

2. Enviar um job em lote

É possível criar um job em lote usando o console do Google Cloud , o SDK do Google Gen AI ou a API REST.

O job e a tabela precisam estar na mesma região.

Console

  1. Na seção "Vertex AI" do console Google Cloud , acesse a página Inferência em lote.

    Acessar "Inferência em lote"

  2. Clique em Criar.

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. O conjunto de dados precisa estar na mesma região que o job de previsão em lote. 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 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 abaixo: 

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 job em lote. É possível pesquisar o status da job em lote usando BATCH_JOB_ID. Para mais informações, consulte Monitorar o status do job. Observação: não há suporte para os relatórios de conta de serviço personalizada, andamento em tempo real, CMEK e VPCSC.

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.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. Monitorar o status e o progresso do job

Depois que o job for enviado, verifique o status dele usando a API, o SDK e o console do Cloud.

Console

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

    Acessar "Inferência em lote"

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

REST

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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • ENDPOINT_PREFIX: a região do recurso do modelo seguida por -. Por exemplo, us-central1-. Se 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 compatível com 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 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
 

    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 status de um determinado job em lote pode ser um dos seguintes:

  • JOB_STATE_PENDING: fila para capacidade. O job pode ficar no estado queue por até 72 horas antes de entrar no estado running.
  • JOB_STATE_RUNNING: o arquivo de entrada foi validado e o lote está sendo executado.
  • JOB_STATE_SUCCEEDED: o lote foi concluído e os resultados estão prontos.
  • JOB_STATE_FAILED: o arquivo de entrada falhou no processo de validação ou não pôde ser concluído dentro do período de 24 horas após entrar no estado RUNNING.
  • JOB_STATE_CANCELLING: o lote está sendo cancelado.
  • JOB_STATE_CANCELLED: o lote foi cancelado

4. 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 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

  • Solicitação

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