Inferencia por lotes para BigQuery

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

1. Prepara tus entradas

Entrada de almacenamiento de BigQuery

Tu cuenta de servicio debe tener los permisos de BigQuery adecuados. Para otorgar a la cuenta de servicio el rol de Usuario de BigQuery, usa el comando gcloud iam service-accounts add-iam-policy-binding de la siguiente manera:

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

Reemplaza los siguientes valores:

  • PROJECT_ID: Es el ID del proyecto en el que se creó tu cuenta de servicio.
  • SERVICE_ACCOUNT_ID: El ID para la cuenta de servicio.

Se requiere una columna request, que debe ser un JSON válido. Estos datos JSON representan tu entrada para el 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 que no sean 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.

Entrada de ejemplo (JSON) 
        
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Give me a recipe for banana bread."
        }
      ]
    }
  ],
  "system_instruction": {
    "parts": [
      {
        "text": "You are a chef."
      }
    ]
  }
}

2. Envía un trabajo por lotes

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

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

Console

  1. En la sección Agent Platform de la consola de Cloud de Confiance , ve a la página Inferencia por lotes.

    Ir a Inferencia por lotes

  2. Haz clic en Crear.

REST

Para crear un trabajo de inferencia por lotes, usa el método projects.locations.batchPredictionJobs.create.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • ENDPOINT_PREFIX: Es la región del recurso de modelo seguida de -. Por ejemplo, us-central1-. Si usas el extremo global, deja este campo en blanco. Nota: El extremo global no es compatible con la inferencia por lotes con modelos ajustados.
  • LOCATION: Es una región que admite modelos de Gemini. Si usas el extremo global, ingresa global.
  • PROJECT_ID: Es el ID del proyecto.
  • MODEL_PATH: Es el nombre del modelo del publicador, por ejemplo, publishers/google/models/gemini-2.0-flash-001, o el nombre del extremo ajustado, por ejemplo, projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID, en el que MODEL_ID es el ID del modelo ajustado.
  • INPUT_URI: Es la tabla de BigQuery en la que se encuentra la entrada de inferencia por lotes, como bq://myproject.mydataset.input_table. El conjunto de datos debe estar ubicado en la misma región que el trabajo de inferencia por lotes. No se admiten los conjuntos de datos multirregionales.
  • OUTPUT_FORMAT: Para enviar el resultado a una tabla de BigQuery, especifica bigquery. Para enviar el resultado a un bucket de Cloud Storage, especifica jsonl.
  • DESTINATION: Para BigQuery, especifica bigqueryDestination. En Cloud Storage, especifica gcsDestination.
  • OUTPUT_URI_FIELD_NAME: Para BigQuery, especifica outputUri. En Cloud Storage, especifica outputUriPrefix.
  • OUTPUT_URIEn el caso de 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 inferencia por lotes de Agent Platform. Para Cloud Storage, especifica la ubicación del bucket y del directorio, como gs://mybucket/path/to/output.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

En la respuesta, se incluye un identificador único para el trabajo por lotes. Puedes consultar el estado del trabajo por lotes con BATCH_JOB_ID. Para obtener más información, consulta Supervisa el estado del trabajo. Nota: No se admiten los informes personalizados de cuenta de servicio, progreso en vivo, CMEK ni VPCSC.

Python

Instalar

pip install --upgrade google-genai

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

Establece variables de entorno para usar el SDK de IA generativa de Google 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_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. Supervisa el estado y el progreso del trabajo

Después de enviar el trabajo por lotes, puedes verificar su estado con la API, el SDK y la consola de Cloud de Confiance .

Console

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

    Ir a Inferencia por lotes

  2. Selecciona tu trabajo por lotes para supervisar su progreso.

REST

Para supervisar un trabajo de inferencia por lotes, usa el método projects.locations.batchPredictionJobs.get y consulta el campo CompletionStats en la respuesta.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • ENDPOINT_PREFIX: Es la región del recurso de modelo seguida de -. Por ejemplo, us-central1-. Si usas el extremo global, deja este campo en blanco.
  • LOCATION: Es una región que admite modelos de Gemini. Si usas el extremo global, ingresa global.
  • PROJECT_ID: Es el ID del proyecto.
  • BATCH_JOB_ID: Es el ID de tu trabajo por lotes.

Método HTTP y URL: 

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente 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

Ejecuta el siguiente 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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

Python

Instalar

pip install --upgrade google-genai

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

Establece variables de entorno para usar el SDK de IA generativa de Google 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_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

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

  • JOB_STATE_PENDING: Se pone en cola para obtener capacidad. El trabajo puede estar en estado queue hasta 72 horas antes de ingresar al estado running.
  • JOB_STATE_RUNNING: El archivo de entrada se validó correctamente y se está ejecutando el lote.
  • JOB_STATE_SUCCEEDED: El lote se completó y los resultados están listos
  • JOB_STATE_FAILED: El archivo de entrada no pasó el proceso de validación o no se pudo completar en el plazo de 24 horas después de ingresar al estado RUNNING.
  • JOB_STATE_CANCELLING: Se está cancelando el lote.
  • JOB_STATE_CANCELLED: Se canceló el lote.

4. Recuperar los resultados por lotes

Cuando se completa una tarea de inferencia por lotes, el resultado se almacena en la tabla de BigQuery que especificaste en la solicitud.

En el caso de las filas que se procesaron correctamente, las respuestas del modelo se almacenan en la columna response. De lo contrario, los detalles del error se almacenan en la columna status para su posterior inspección.

Ejemplo de resultado

Ejemplo sin errores

{
  "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 con errores

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

Reanuda un trabajo por lotes incompleto

Si un trabajo de inferencia por lotes falla, se cancela o vence, puedes reanudarlo creando un trabajo por lotes nuevo. El trabajo nuevo solo procesa las solicitudes incompletas o con errores del trabajo anterior y combina los resultados nuevos con los de las solicitudes completadas con anterioridad. Por ejemplo, si el trabajo por lotes incompleto se completó en un 90%, el trabajo nuevo procesa el 10% restante de las solicitudes.

Para reanudar un trabajo por lotes, crea uno nuevo y proporciona el archivo de Cloud Storage o el resultado de la tabla de BigQuery como entrada para el trabajo nuevo.