Predicción por lotes para BigQuery

En esta página se describe cómo obtener predicciones por lotes con BigQuery.

1. Prepara las entradas

Entrada de almacenamiento de BigQuery

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

Sustituye los siguientes valores:

*   <var>PROJECT_ID</var>: The project that your service account was
    created in.
*   <var>SERVICE_ACCOUNT_ID</var>: The ID for the service account.
  • Se necesita una columna request, que debe ser un JSON válido. Estos datos JSON representan la entrada del modelo.
  • El contenido de la columna request debe coincidir con la estructura de un GenerateContentRequest. + La tabla de entrada puede tener tipos de datos de columna distintos de request. Estas columnas pueden tener tipos de datos de BigQuery, excepto los siguientes: array, struct, range, datetime y geography. Estas columnas se ignoran para la generación de contenido, pero se incluyen en la tabla de resultados.
Ejemplo 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 una tarea por lotes

Puedes crear un trabajo por lotes a través de la Google Cloud consola, el SDK de Gen AI de Google o la API REST.

El trabajo y la tabla deben estar en la misma región.

Consola

  1. En la sección Vertex AI de la Google Cloud consola, ve a la página Inferencia por lotes.

    Ir a Inferencia por lotes

  2. Haz clic en Crear.

REST

Para crear una tarea de predicción por lotes, usa el método projects.locations.batchPredictionJobs.create.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • LOCATION: una región que admita modelos de Gemini.
  • PROJECT_ID: tu ID de proyecto.
  • MODEL_PATH: el nombre del modelo de editor, por ejemplo, publishers/google/models/gemini-2.0-flash-001; o el nombre del endpoint ajustado, por ejemplo, projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID, donde MODEL_ID es el ID del modelo ajustado.
  • INPUT_URI: la tabla de BigQuery en la que se encuentra la entrada de la predicción por lotes, como bq://myproject.mydataset.input_table. El conjunto de datos debe estar ubicado en la misma región que el trabajo de predicción por lotes. No se admiten los conjuntos de datos multirregionales.
  • OUTPUT_FORMAT: para enviar los datos a una tabla de BigQuery, especifica bigquery. Para enviar los datos a un segmento de Cloud Storage, especifica jsonl.
  • DESTINATION: en BigQuery, especifica bigqueryDestination. En el caso de Cloud Storage, especifica gcsDestination.
  • OUTPUT_URI_FIELD_NAME: En BigQuery, especifica outputUri. En el caso de Cloud Storage, especifica outputUriPrefix.
  • OUTPUT_URI: en BigQuery, especifica la ubicación de la tabla, como bq://myproject.mydataset.output_result. La región del conjunto de datos de BigQuery de salida debe ser la misma que la del trabajo de predicción por lotes de Vertex AI. En Cloud Storage, especifica la ubicación del segmento y del directorio, como gs://mybucket/path/to/output.

Método HTTP y URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs

Cuerpo JSON de la solicitud: 

{
  "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 tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Deberías recibir una respuesta JSON similar a la siguiente.

La respuesta incluye un identificador único del trabajo por lotes. Puedes sondear el estado de la tarea por lotes con BATCH_JOB_ID. Para obtener más información, consulta Monitorizar el estado de los trabajos. Nota: No se admiten los informes de cuentas de servicio personalizadas, progreso en tiempo real, CMEK ni VPCSC.

Python

Instalar

pip install --upgrade google-genai

Para obtener más información, consulta la documentación de referencia del SDK.

Define variables de entorno para usar el SDK de IA generativa con 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/%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

3. Monitorizar el estado y el progreso del trabajo

Una vez que se haya enviado el trabajo, puedes consultar su estado mediante la API, el SDK y la consola de Cloud.

Consola

  1. Ve a la página Inferencia por lotes.

    Ir a Inferencia por lotes

  2. Selecciona el trabajo por lotes para monitorizar su progreso.

REST

Para monitorizar un trabajo de predicción por lotes, usa el método projects.locations.batchPredictionJobs.get y consulta el campo CompletionStats de la respuesta.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • LOCATION: una región que admita modelos de Gemini.
  • PROJECT_ID: .
  • BATCH_JOB_ID: el ID del trabajo por lotes.

Método HTTP y URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el comando siguiente: 

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

PowerShell

Ejecuta el comando siguiente: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la siguiente.

Python

Instalar

pip install --upgrade google-genai

Para obtener más información, consulta la documentación de referencia del SDK.

Define variables de entorno para usar el SDK de IA generativa con 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/us-central1/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

El estado de un trabajo por lotes puede ser cualquiera de los siguientes:

  • JOB_STATE_PENDING: cola de capacidad. El trabajo puede estar en estado queue hasta 72 horas antes de pasar al estado running.
  • JOB_STATE_RUNNING: el archivo de entrada se ha validado correctamente y el lote se está ejecutando.
  • JOB_STATE_SUCCEEDED: el lote se ha completado y los resultados están listos.
  • JOB_STATE_FAILED: el archivo de entrada no ha superado el proceso de validación o no se ha podido completar en un plazo de 24 horas después de pasar al estado RUNNING.
  • JOB_STATE_CANCELLING: se está cancelando el lote
  • JOB_STATE_CANCELLED: se ha cancelado el lote

4. Recuperar la salida de un lote

Cuando se completa una tarea de predicción por lotes, la salida se almacena en la tabla de BigQuery que hayas especificado en tu solicitud.

En las filas correctas, las respuestas del modelo se almacenan en la columna response. De lo contrario, los detalles del error se almacenarán en la columna status para que se puedan examinar más adelante.

Ejemplo de salida

Ejemplo de operación correcta

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

Ejemplo fallido

  • Solicitud

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

  • Respuesta

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