Previsione batch

La previsione batch è una tecnica utile per applicare in modo efficiente i modelli di machine learning a set di dati di grandi dimensioni. Anziché elaborare singoli punti dati, puoi inviare un batch di dati a Gemini per la previsione, risparmiando tempo e risorse di calcolo. A differenza della previsione online, in cui hai un limite di un prompt di input alla volta, puoi inviare un numero elevato di prompt multimodali in una singola richiesta batch. Le risposte vengono poi completate in modo asincrono nella posizione di output dello spazio di archiviazione BigQuery o Cloud Storage.

Le richieste batch per i modelli Gemini sono scontate del 50% rispetto alle richieste standard. Per scoprire di più, consulta la pagina dei prezzi.

Caso d'uso di previsione batch

Prendiamo ad esempio una libreria online con migliaia di libri nel database. Anziché generare le descrizioni singolarmente per ogni libro, il che richiederebbe molto tempo, questo negozio può utilizzare la previsione batch di Gemini per elaborare tutte le informazioni sui libri contemporaneamente. Questo approccio migliora notevolmente l'efficienza riducendo il tempo di elaborazione complessivo e minimizzando le risorse di calcolo richieste.

Le previsioni in batch possono anche migliorare la coerenza con l'automazione. Elaborando tutte le descrizioni contemporaneamente, il modello mantiene un tono e uno stile uniformi nelle descrizioni dei libri, rafforzando l'identità del brand. Questa libreria può anche integrare la previsione batch nel proprio flusso di lavoro per generare automaticamente le descrizioni delle nuove voci di libri, eliminando il lavoro manuale e garantendo che il sito web rimanga aggiornato con un intervento umano minimo.

Modelli Gemini che supportano le previsioni batch

I seguenti modelli Gemini di base e ottimizzati supportano le previsioni collettive:

Limitazioni

Dopo l'invio, i job batch vengono convalidati e messi in coda in base alla capacità disponibile. Una volta avviato, un job ha un limite di esecuzione di 24 ore. Se non viene completata entro questo periodo di tempo, tutte le richieste completate verranno esportate e ti verrà addebitato solo il costo delle richieste completate. Il tempo massimo che un job batch può trascorrere in coda ed esecuzione è di 72 ore.

Input e output di previsione batch

Le richieste batch per i modelli Gemini accettano origini di archiviazione BigQuery e Cloud Storage. Puoi scegliere in modo indipendente di eseguire l'output delle previsioni in una tabella BigQuery o in un file JSONL in un bucket Cloud Storage.

Ti consigliamo di includere nella sorgente di input (tabella o file) almeno 25.000 richieste per job. Il sistema di previsione batch suddivide e esegue in parallelo i job il più rapidamente e in modo il più efficiente possibile con le risorse disponibili al momento. Non esiste un numero massimo di richieste per job.

Per le quote e i limiti per i job di previsione in batch, consulta Quote e limiti di sistema per l'IA generativa su Vertex AI.

Previsione batch per Cloud Storage

Prepara gli input

Input di Cloud Storage

  • Formato file: righe JSON (JSONL)
  • Si trova presso us-central1

  • Deve disporre delle autorizzazioni Cloud Storage appropriate per l'account di servizio. Per concedere all'account di servizio l'autorizzazione di lettura e scrittura su un bucket Cloud Storage, utilizza il comando gcloud iam service-accounts add-iam-policy-binding come segue:

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

    Sostituisci i seguenti valori:

    • PROJECT_ID: il progetto in cui è stato creato il tuo account di servizio.
    • SERVICE_ACCOUNT_ID: l'ID dell'account di servizio.
Input di esempio (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"}}]}]}}

Richiedere un job di previsione batch

Specifica la tabella di input, il modello e la posizione di output di Cloud Storage.

REST

Per creare un job di previsione batch, utilizza il metodo projects.locations.batchPredictionJobs.create.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • LOCATION: una regione che supporta modelli Gemini.
  • PROJECT_ID: il tuo ID progetto.
  • MODEL_PATH: il nome del modello dell'editore, ad esempio publishers/google/models/gemini-2.0-flash-001; oppure il nome dell'endpoint ottimizzato, ad esempio projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID, dove MODEL_ID è l'ID del modello ottimizzato.
  • INPUT_URI: la posizione di Cloud Storage dell'input di previsione batch JSONL, ad esempio gs://bucketname/path/to/file.jsonl.
  • OUTPUT_FORMAT: per eseguire l'output in una tabella BigQuery, specifica bigquery. Per eseguire l'output in un bucket Cloud Storage, specifica jsonl.
  • DESTINATION: per BigQuery, specifica bigqueryDestination. Per Cloud Storage, specifica gcsDestination.
  • OUTPUT_URI_FIELD_NAME: Per BigQuery, specifica outputUri. Per Cloud Storage, specifica outputUriPrefix.
  • OUTPUT_URI: per BigQuery, specifica la posizione della tabella, ad esempio bq://myproject.mydataset.output_result. La regione del set di dati BigQuery di output deve essere la stessa del job di previsione in batch di Vertex AI. Per Cloud Storage, specifica la posizione del bucket e della directory, ad esempio gs://mybucket/path/to/output.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

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

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

$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

Dovresti ricevere una risposta JSON simile alla seguente.

La risposta include un identificatore univoco per il job batch. Puoi eseguire il polling dello stato del job batch utilizzando BATCH_JOB_ID finché il job state non è JOB_STATE_SUCCEEDED. Ad esempio:

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

Installa

pip install --upgrade google-genai

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK 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

Output di previsione batch

Al termine di un'attività di previsione batch, l'output viene archiviato nel bucket Cloud Storage o nella tabella BigQuery specificata nella richiesta. Per le righe riuscite, le risposte del modello vengono memorizzate nella colonna response. In caso contrario, i dettagli dell'errore vengono memorizzati nella colonna status per ulteriori accertamenti.

Durante i job di lunga durata, le previsioni completate vengono esportate continuamente nella destinazione di output specificata. Questa operazione inizia dopo 90 minuti. Se il job di previsione batch viene annullato o non va a buon fine, tutte le previsioni completate vengono esportate.

Esempio di output di 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
    }
  }
}

Previsione batch per BigQuery

Specifica la tabella di input, il modello e la posizione di output BigQuery. Il job di previsione batch e la tabella devono trovarsi nella stessa regione.

Prepara gli input

Input dello spazio di archiviazione BigQuery

  • Il tuo account di servizio deve disporre delle autorizzazioni BigQuery appropriate. Per concedere all'account di servizio il ruolo Utente BigQuery, utilizza il comando gcloud iam service-accounts add-iam-policy-binding come segue:

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

    Sostituisci i seguenti valori:

    • PROJECT_ID: il progetto in cui è stato creato il tuo account di servizio.
    • SERVICE_ACCOUNT_ID: l'ID dell'account di servizio.

  • È obbligatoria una colonna request, che deve essere in formato JSON valido. Questi dati JSON rappresentano il tuo input per il modello.

  • I contenuti della colonna request devono corrispondere alla struttura di un GenerateContentRequest.

  • La tabella di input può avere tipi di dati di colonna diversi da request. Queste colonne possono avere tipi di dati BigQuery, ad eccezione di array, struct, range, datetime e geography. Queste colonne vengono ignorate per la generazione dei contenuti, ma incluse nella tabella di output.

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

Richiedere un job di previsione batch

REST

Per creare un job di previsione batch, utilizza il metodo projects.locations.batchPredictionJobs.create.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • LOCATION: una regione che supporta modelli Gemini.
  • PROJECT_ID: il tuo ID progetto.
  • MODEL_PATH: il nome del modello dell'editore, ad esempio publishers/google/models/gemini-2.0-flash-001; oppure il nome dell'endpoint ottimizzato, ad esempio projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID, dove MODEL_ID è l'ID del modello ottimizzato.
  • INPUT_URI: la tabella BigQuery in cui si trova l'input di previsione batch, ad esempio bq://myproject.mydataset.input_table. I set di dati multiregione non sono supportati.
  • OUTPUT_FORMAT: per eseguire l'output in una tabella BigQuery, specifica bigquery. Per eseguire l'output in un bucket Cloud Storage, specifica jsonl.
  • DESTINATION: per BigQuery, specifica bigqueryDestination. Per Cloud Storage, specifica gcsDestination.
  • OUTPUT_URI_FIELD_NAME: Per BigQuery, specifica outputUri. Per Cloud Storage, specifica outputUriPrefix.
  • OUTPUT_URI: per BigQuery, specifica la posizione della tabella, ad esempio bq://myproject.mydataset.output_result. La regione del set di dati BigQuery di output deve essere la stessa del job di previsione in batch di Vertex AI. Per Cloud Storage, specifica la posizione del bucket e della directory, ad esempio gs://mybucket/path/to/output.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

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

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

$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

Dovresti ricevere una risposta JSON simile alla seguente.

La risposta include un identificatore univoco per il job batch. Puoi eseguire il polling dello stato del job batch utilizzando BATCH_JOB_ID finché il job state non è JOB_STATE_SUCCEEDED. Ad esempio:

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

Installa

pip install --upgrade google-genai

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK 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

Recuperare l'output batch

Al termine di un'attività di previsione batch, l'output viene archiviato nella tabella BigQuery specificata nella richiesta.

Per le righe riuscite, le risposte del modello vengono memorizzate nella colonna response. In caso contrario, i dettagli dell'errore vengono memorizzati nella colonna status per ulteriori accertamenti.

Esempio di output BigQuery

richiesta risposta stato 
{"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
  }
}

Passaggi successivi