Predicción por lotes desde Cloud Storage

En esta página se describe cómo obtener predicciones por lotes mediante Cloud Storage.

1. Prepara las entradas

Los modelos de Gemini por lotes aceptan un archivo JSON Lines (JSONL) almacenado en Cloud Storage como datos de entrada. Cada línea de los datos de entrada del lote es una solicitud al modelo, que sigue el mismo formato que la API de Gemini.

Por ejemplo:

{"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"}}]}], "generationConfig": {"temperature": 0.9, "topP": 1, "maxOutputTokens": 256}}}

Descarga el archivo de solicitud por lotes de ejemplo.

Una vez que haya preparado los datos de entrada y los haya subido a Cloud Storage. Asegúrate de que el agente de servicio de AI Platform tenga permiso para acceder al archivo de Cloud Storage.

2. Enviar una tarea por lotes

Puedes crear una tarea por lotes mediante la consola, la API REST o el SDK de IA generativa de Google. Google Cloud

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.5-flash; 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 ubicación de Cloud Storage de la entrada de predicción por lotes JSONL, como gs://bucketname/path/to/file.jsonl.
  • OUTPUT_FORMAT: para enviar la salida 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-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 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 = "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.5-flash",
    # 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

3. Monitorizar el estado y el progreso del trabajo

Una vez que se haya enviado el trabajo, puedes consultar su estado mediante la consola Google Cloud , la API REST o el SDK de IA generativa de Google.

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

Para ver las descripciones de los estados de las tareas, consulta JobState.

4. Recuperar la salida de un lote

Cuando se completa una tarea de predicción por lotes, la salida se almacena en el segmento de Cloud Storage que especificaste al crear la tarea. En el caso de las filas correctas, las respuestas del modelo se almacenan en el campo response. De lo contrario, los detalles del error se almacenan en el campo status para que se puedan examinar más a fondo.

Durante las tareas de larga duración, las predicciones completadas se exportan continuamente al destino de salida especificado. Si se termina la tarea de predicción por lotes, se exportarán todas las filas completadas. Solo se te cobrarán las predicciones completadas.

Ejemplos de salida

Ejemplo de operación correcta

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

Ejemplo fallido

{
  "status": "Bad Request: {\"error\": {\"code\": 400, \"message\": \"Please use a valid role: user, model.\", \"status\": \"INVALID_ARGUMENT\"}}",
  "processed_time": "2025-07-09T19:57:43.558+00:00",
  "request": {
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ],
        "role": "tester"
      }
    ]
  },
  "response": {}
}