Inferência em lote para o BigQuery

Nesta página, descrevemos como receber inferências em lote usando o BigQuery.

1. 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 ID do 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 a entrada do 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 pelo Google Cloud console, pelo SDK de IA Generativa do Google, ou pela API REST.

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

Console

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

    Acessar a inferência em lote

  2. Clique em Criar.

REST

Para criar um job de inferência em lote, use o projects.locations.batchPredictionJobs.create método.

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

  • ENDPOINT_PREFIX: a região do recurso do modelo seguida por -. Por exemplo, us-central1-. Se você 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 Gemini. Se você estiver usando o endpoint global, insira global.
  • 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 inferência em lote está localizada, como bq://myproject.mydataset.input_table. O conjunto de dados precisa estar na mesma região que o job de inferência em lote. Não há suporte para conjuntos de dados multirregionais.
  • OUTPUT_FORMAT: para gerar a saída em uma tabela do BigQuery, especifique bigquery. Para gerar a 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 BigQuery precisa ser a mesma do job de inferência em lote da Agent Platform. 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://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs

Corpo JSON da solicitação: 

{
  "displayName": "my-bigquery-batch-inference-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://ENDPOINT_PREFIXaiplatform.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://ENDPOINT_PREFIXaiplatform.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 sondar o status do job em lote usando o 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 do Google 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_ENTERPRISE=True
 

import time

from google import genai
from google.genai.types import CreateBatchJobConfig, HttpOptions, JobState

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-3.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, você poderá verificar o status do job em lote usando a API, o SDK e o Google Cloud console.

Console

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

    Acessar a inferência em lote

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

REST

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

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

  • ENDPOINT_PREFIX: a região do recurso do modelo seguida por -. Por exemplo, us-central1-. Se você estiver usando o endpoint global, deixe em branco.
  • LOCATION: uma região compatível com modelos 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 do Google 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_ENTERPRISE=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 de 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 na janela 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 inferência em lote é concluída, a saída é armazenada na tabela do BigQuery especificada na solicitação.

Para linhas bem-sucedidas, as respostas do modelo são armazenadas na coluna response. Caso contrário, os detalhes do erro 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

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

Retomar um job em lote incompleto

Se um job de inferência em lote falhar, for cancelado ou expirar, você poderá retomá-lo criando um novo job em lote. O novo job processa apenas as solicitações incompletas ou com falha do job anterior, mesclando os novos resultados com aqueles das solicitações concluídas anteriormente. Por exemplo, se o job em lote incompleto estiver 90% concluído, o novo job processará os 10% restantes das solicitações.

Para retomar um job em lote, crie um novo job em lote, fornecendo a saída da tabela do BigQuery como entrada para o novo job.