Predicción por lotes desde Cloud Storage

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

1. Prepara tus entradas

Los modelos de Gemini por lotes aceptan un archivo de líneas JSON (JSONL) almacenado en Cloud Storage como datos de entrada. Cada línea de los datos de entrada por lotes 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 muestra

Una vez que hayas preparado tus datos de entrada y los hayas 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. Envía un trabajo por lotes

Puedes crear un trabajo por lotes con la Google Cloud consola, la API de REST o el SDK de IA generativa de Google.

Para ver un ejemplo del uso de predicciones por lotes, ejecuta el notebook “Introducción a las predicciones por lotes con la API de Gemini” en uno de los siguientes entornos:

Abrir en Colab | Abrir en Colab Enterprise | Abrir en Vertex AI Workbench | Ver en GitHub

Console

1. En la sección Vertex AI de la consola de Google Cloud , ve a la página Batch Inference.

   Ir a Inferencia por lotes

2. Haz clic en Crear.

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: Es el nombre del modelo de publicador, por ejemplo, publishers/google/models/gemini-2.5-flash, 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 en formato JSONL, como gs://bucketname/path/to/file.jsonl.
• OUTPUT_FORMAT: Para generar el resultado en 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 el caso de Cloud Storage, especifica outputUriPrefix.
• OUTPUT_URI: En 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 salida de BigQuery debe ser la misma que la del trabajo de predicción por lotes de Vertex AI. En Cloud Storage, especifica la ubicación del bucket y el 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

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

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

Nota: En el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

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:

Respuesta

{
  "name": "projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID",
  "displayName": "my-cloud-storage-batch-prediction-job",
  "model": "publishers/google/models/gemini-2.5-flash",
  "inputConfig": {
    "instancesFormat": "jsonl",
    "gcsSource": {
      "uris": [
        "INPUT_URI"
      ]
    }
  },
  "outputConfig": {
    "predictionsFormat": "OUTPUT_FORMAT",
    "DESTINATION": {
      "OUTPUT_URI_FIELD_NAME": "OUTPUT_URI"
    }
  },
  "state": "JOB_STATE_PENDING",
  "createTime": "2024-10-16T19:33:59.153782Z",
  "updateTime": "2024-10-16T19:33:59.153782Z",
  "modelVersionId": "1"
}

La respuesta 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 Cómo supervisar 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 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. Supervisa el estado y el progreso del trabajo

Después de enviar el trabajo, puedes verificar su estado con la consola de Google Cloud , la API de REST o el SDK de Google Gen AI.

Console

1. Ve a la página Batch Inference.

   Ir a Inferencia por lotes

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

REST

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

• LOCATION: Es una región que admite modelos de Gemini.
• PROJECT_ID: .
• BATCH_JOB_ID: Es el ID de tu 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

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:

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

Nota: En el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:

$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 que se muestra a continuación:

Respuesta

{
  "name": "projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID",
  "displayName": "my-cloud-storage-batch-prediction-job",
  "model": "publishers/google/models/gemini-2.5-flash",
  ...
  "state": "JOB_STATE_PENDING",
  "completionStats": {
    "successfulCount": "10",
    "failedCount": "1"
  },
  "createTime": "2024-10-16T19:33:59.153782Z",
  "updateTime": "2024-10-16T19:33:59.153782Z",
  "modelVersionId": "1"
}

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 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 obtener descripciones de los estados de trabajo, consulta JobState.

4. Recuperar los resultados por lotes

Cuando se completa un trabajo de predicción por lotes, el resultado se almacena en el bucket de Cloud Storage que especificaste cuando creaste el trabajo. 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 su posterior inspección.

Durante los trabajos de larga duración, las predicciones completadas se exportan de forma continua al destino de salida especificado. Si se finaliza el trabajo de predicción por lotes, se exportarán todas las filas completadas. Solo se te cobra por las predicciones completadas.

Precaución: La eliminación no definitiva está habilitada en los buckets de Cloud Storage, que retienen el contenido en estado borrado, lo que puede generar costos de almacenamiento significativos. Te recomendamos que inhabilites el borrado temporal para evitar cargos inesperados.

Ejemplos de resultados

Nota: Los siguientes ejemplos representan una línea en el archivo JSONL de salida. Se les aplicó formato para facilitar la lectura.

Ejemplo sin errores

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

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