Predicción por lotes

La predicción por lotes es una técnica valiosa para aplicar modelos de aprendizaje automático a conjuntos de datos grandes de manera eficiente. En lugar de procesar datos individuales, puedes enviar un lote de datos a Gemini para la predicción, lo que ahorra tiempo y recursos de procesamiento. A diferencia de la predicción en línea, en la que estás limitado a una instrucción de entrada a la vez, puedes enviar una gran cantidad de instrucciones multimodales en una sola solicitud por lotes. Luego, tus respuestas se propagan de forma asíncrona en tu ubicación de salida de almacenamiento de BigQuery o Cloud Storage.

Las solicitudes por lotes para los modelos de Gemini tienen un 50% de descuento en comparación con las solicitudes estándar. Para obtener más información, consulta la página de precios.

Caso de uso de la predicción por lotes

Considera una librería en línea con miles de libros en su base de datos. En lugar de generar descripciones de forma individual para cada libro, lo que llevaría tiempo, esta tienda puede usar la predicción por lotes de Gemini para procesar toda la información de los libros a la vez. Este enfoque mejora de forma significativa la eficiencia, ya que reduce el tiempo de procesamiento general y minimiza los recursos de procesamiento necesarios.

La predicción por lotes también puede mejorar la coherencia con la automatización. Cuando se procesan todas las descripciones de forma simultánea, el modelo mantiene un tono y un estilo uniformes en las descripciones de los libros, lo que refuerza la identidad de marca. Esta librería también puede integrar la predicción por lotes en su flujo de trabajo para generar automáticamente descripciones de entradas de libros nuevas, lo que elimina el esfuerzo manual y garantiza que su sitio web permanezca actualizado con una intervención humana mínima.

Modelos de Gemini que admiten predicciones por lotes

Los siguientes modelos de Gemini base y ajustados admiten predicciones por lotes:

Limitaciones

Después del envío, los trabajos por lotes se validan y se ponen en cola para la capacidad disponible. Una vez que se inicia un trabajo, tiene un límite de ejecución de 24 horas. Si no se completa dentro de ese plazo, se exportarán todas las solicitudes completadas y solo se te cobrará por las que se hayan completado. El tiempo máximo que una trabajo por lotes puede pasar en la cola y en ejecución es de 72 horas.

Entradas y salidas de la predicción por lotes

Las solicitudes por lotes para modelos de Gemini aceptan fuentes de almacenamiento de BigQuery y de Cloud Storage. Puedes elegir de forma independiente si deseas generar predicciones en una tabla de BigQuery o en un archivo JSONL en un bucket de Cloud Storage.

Te recomendamos que tu fuente de entrada (tabla o archivo) incluya un mínimo de 25,000 solicitudes por trabajo. El sistema de predicción por lotes divide y paraleliza las tareas lo más rápido y eficientemente posible con los recursos disponibles en ese momento. No hay una cantidad máxima de solicitudes por trabajo.

Para conocer las cuotas y los límites de los trabajos de predicción por lotes, consulta Cuotas y límites del sistema de IA generativa en Vertex AI.

Predicción por lotes para Cloud Storage

Prepara tus entradas

Entrada de Cloud Storage

  • Formato de archivo: Líneas JSON (JSONL)
  • Ubicado en us-central1

  • Debe tener los permisos de Cloud Storage adecuados para la cuenta de servicio. Para otorgarle a la cuenta de servicio permiso de lectura y escritura en un bucket de Cloud Storage, 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.iam.gserviceaccount.com" \
    --role="roles/storage.objectUser"

    Reemplaza los siguientes valores:

    • PROJECT_ID es el proyecto en el que se creó tu cuenta de servicio.
    • SERVICE_ACCOUNT_ID: El ID para la cuenta de servicio.
Ejemplo de entrada (JSONL) 

{"request":{"contents": [{"role": "user", "parts": [{"text": "What is the relation between the following video and image samples?"}, {"fileData": {"fileUri": "gs://cloud-samples-data/generative-ai/video/animals.mp4", "mimeType": "video/mp4"}}, {"fileData": {"fileUri": "gs://cloud-samples-data/generative-ai/image/cricket.jpeg", "mimeType": "image/jpeg"}}]}]}}
{"request":{"contents": [{"role": "user", "parts": [{"text": "Describe what is happening in this video."}, {"fileData": {"fileUri": "gs://cloud-samples-data/generative-ai/video/another_video.mov", "mimeType": "video/mov"}}]}]}}

Solicita un trabajo de predicción por lotes

Especifica la tabla de entrada, el modelo y la ubicación de salida de Cloud Storage.

REST

Para crear un trabajo de predicción 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:

  • LOCATION: Es una región que admite modelos de Gemini.
  • PROJECT_ID: El ID del proyecto.
  • MODEL_PATH: 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, donde MODEL_ID es el ID del modelo ajustado.
  • INPUT_URI: Es la ubicación de Cloud Storage de tu entrada de predicción por lotes JSONL, como gs://bucketname/path/to/file.jsonl.
  • OUTPUT_FORMAT: Para generar una salida en una tabla de BigQuery, especifica bigquery. Para generar 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_URI: Para 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 el bucket y la ubicación 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-cloud-storage-batch-prediction-job",
  "model": "MODEL_PATH",
  "inputConfig": {
    "instancesFormat": "jsonl",
    "gcsSource": {
      "uris" : "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 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 mediante BATCH_JOB_ID hasta que el state sea JOB_STATE_SUCCEEDED. Por ejemplo:

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

Gen AI SDK for 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 Gen AI 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 = "gs://your-bucket/your-prefix"

# See the documentation: https://googleapis.github.io/python-genai/genai.html#genai.batches.Batches.create
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.0-flash-001",
    # Source link: https://storage.cloud.google.com/cloud-samples-data/batch/prompt_for_batch_gemini_predict.jsonl
    src="gs://cloud-samples-data/batch/prompt_for_batch_gemini_predict.jsonl",
    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

Salida de la predicción por lotes

Cuando se completa una tarea de predicción por lotes, el resultado se almacena en el bucket de Cloud Storage o 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 una inspección más detallada.

Durante los trabajos de larga duración, las predicciones completadas se exportan de forma continua al destino de salida especificado. Esto comienza después de 90 minutos. Si se cancela o falla el trabajo de predicción por lotes, se exportan todas las predicciones completadas.

Ejemplo de salida de Cloud Storage

{
  "status": "",
  "processed_time": "2024-11-01T18:13:16.826+00:00",
  "request": {
    "contents": [
      {
        "parts": [
          {
            "fileData": null,
            "text": "What is the relation between the following video and image samples?"
          },
          {
            "fileData": {
              "fileUri": "gs://cloud-samples-data/generative-ai/video/animals.mp4",
              "mimeType": "video/mp4"
            },
            "text": null
          },
          {
            "fileData": {
              "fileUri": "gs://cloud-samples-data/generative-ai/image/cricket.jpeg",
              "mimeType": "image/jpeg"
            },
            "text": null
          }
        ],
        "role": "user"
      }
    ]
  },
  "response": {
    "candidates": [
      {
        "avgLogprobs": -0.5782725546095107,
        "content": {
          "parts": [
            {
              "text": "This video shows a Google Photos marketing campaign where animals at the Los Angeles Zoo take self-portraits using a modified Google phone housed in a protective case. The image is unrelated."
            }
          ],
          "role": "model"
        },
        "finishReason": "STOP"
      }
    ],
    "modelVersion": "gemini-2.0-flash-001@default",
    "usageMetadata": {
      "candidatesTokenCount": 36,
      "promptTokenCount": 29180,
      "totalTokenCount": 29216
    }
  }
}

Predicción por lotes para BigQuery

Especifica la tabla de entrada, el modelo y la ubicación de salida de BigQuery. El trabajo de predicción por lotes y tu tabla deben estar en la misma región.

Prepara tus entradas

Entrada de almacenamiento de BigQuery

  • Tu cuenta de servicio debe tener los permisos de BigQuery adecuados. Para otorgarle 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.iam.gserviceaccount.com" \
    --role="roles/bigquery.user"

    Reemplaza los siguientes valores:

    • PROJECT_ID es el 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 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.

  • Tu 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, rango, fecha y hora, y geografía. 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."
      }
    ]
  }
}

Solicita un trabajo de predicción por lotes

REST

Para crear un trabajo de predicción 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:

  • LOCATION: Es una región que admite modelos de Gemini.
  • PROJECT_ID: El ID del proyecto.
  • MODEL_PATH: 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, donde MODEL_ID es el ID del modelo ajustado.
  • INPUT_URI: Es la tabla de BigQuery en la que se encuentra la entrada de tu predicción por lotes, como bq://myproject.mydataset.input_table. No se admiten conjuntos de datos de varias regiones.
  • OUTPUT_FORMAT: Para generar una salida en una tabla de BigQuery, especifica bigquery. Para generar 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_URI: Para 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 el bucket y la ubicación 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 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 mediante BATCH_JOB_ID hasta que el state sea JOB_STATE_SUCCEEDED. Por ejemplo:

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

Gen AI SDK for 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 Gen AI 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.0-flash-001",
    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

Recuperar los resultados por lotes

Cuando se completa una tarea de predicción 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 una inspección más detallada.

Ejemplo de salida de BigQuery

solicitud respuesta estado 
{"content":[{...}]}
 
{
  "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
  }
}

¿Qué sigue?