Inferenza batch da Cloud Storage

Questa pagina descrive come ottenere inferenze batch utilizzando Cloud Storage.

1. Preparare gli input

L'inferenza batch per i modelli Gemini accetta un file JSON Lines (JSONL) archiviato in Cloud Storage come dati di input. Ogni riga dei dati di input batch è una richiesta al modello, che segue lo stesso formato dell'API Gemini.

Ad esempio:

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

Scarica il file di richiesta batch di esempio.

Una volta preparati i dati di input e caricati su Cloud Storage. Assicurati che l'agente di servizio AI Platform disponga dell'autorizzazione per il file Cloud Storage.

2. Invia un job batch

Puoi creare un job batch utilizzando la console Google Cloud , l'API REST o Google Gen AI SDK.

Per vedere un esempio di utilizzo dell'inferenza batch, esegui il notebook "Intro to Batch Predictions with the Gemini API" in uno dei seguenti ambienti:

Apri in Colab | Apri in Colab Enterprise | Apri in Vertex AI Workbench | Visualizza su GitHub

Console

1. Nella sezione Vertex AI della console Google Cloud , vai alla pagina Inferenza batch.

   Vai a Inferenza batch

2. Fai clic su Crea.

REST

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

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

• ENDPOINT_PREFIX: la regione della risorsa modello seguita da -. Ad esempio: us-central1-. Se utilizzi l'endpoint globale, lascia vuoto il campo. Nota:l'endpoint globale non è supportato per l'inferenza batch utilizzando modelli ottimizzati.
• LOCATION: una regione che supporta i modelli Gemini. Se utilizzi l'endpoint globale, inserisci global.
• PROJECT_ID: il tuo ID progetto.
• MODEL_PATH: il nome del modello dell'editore, ad esempio publishers/google/models/gemini-2.5-flash; o il nome dell'endpoint ottimizzato, ad esempio projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID, dove MODEL_ID è l'ID modello del modello ottimizzato.
• INPUT_URI: il percorso di Cloud Storage dell'input di inferenza batch JSONL, ad esempio gs://bucketname/path/to/file.jsonl.
• OUTPUT_FORMAT: Per 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 inferenza batch 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://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs

Corpo JSON della richiesta:

{
  "displayName": "my-cloud-storage-batch-inference-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

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

PowerShell

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

Dovresti ricevere una risposta JSON simile alla seguente.

Risposta

{
  "name": "projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID",
  "displayName": "my-cloud-storage-batch-inference-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 risposta include un identificatore univoco per il job batch. Puoi eseguire il polling dello stato del job batch utilizzando BATCH_JOB_ID. Per saperne di più, vedi Monitorare lo stato del job. Nota: i service account personalizzati e CMEK non sono supportati.

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.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/.../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. Monitorare lo stato e l'avanzamento del job

Dopo l'invio del job, puoi controllare lo stato del job batch utilizzando la console Google Cloud , l'API REST o l'SDK Google Gen AI.

Console

1. Vai alla pagina Inferenza batch.

   Vai a Inferenza batch

2. Seleziona il job batch per monitorarne l'avanzamento.

REST

Per monitorare un job di inferenza batch, utilizza il metodo projects.locations.batchPredictionJobs.get e visualizza il campo CompletionStats nella risposta.

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

• ENDPOINT_PREFIX: la regione della risorsa modello seguita da -. Ad esempio: us-central1-. Se utilizzi l'endpoint globale, lascia vuoto questo campo. Nota:l'endpoint globale non è supportato per l'inferenza batch utilizzando modelli ottimizzati.
• LOCATION: una regione che supporta i modelli Gemini. Se utilizzi l'endpoint globale, inserisci global.
• PROJECT_ID: il tuo ID progetto.
• BATCH_JOB_ID: l'ID del job batch.

Metodo HTTP e URL:

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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

Dovresti ricevere una risposta JSON simile alla seguente.

Risposta

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

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

    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

Per le descrizioni degli stati dei job, vedi JobState.

4. Recuperare l'output batch

Al termine di un job di inferenza batch, l'output viene archiviato nel bucket Cloud Storage specificato al momento della creazione del job. Per le righe riuscire, le risposte del modello vengono archiviate nel campo response. In caso contrario, i dettagli dell'errore vengono memorizzati nel campo status per un'ulteriore ispezione.

Durante i job a esecuzione prolungata, le inferenze completate vengono esportate continuamente nella destinazione di output specificata. Se il job di inferenza batch viene terminato, tutte le righe completate vengono esportate. Ti vengono addebitati solo i crediti utilizzati.

Attenzione: l'eliminazione temporanea è abilitata nei bucket Cloud Storage, che conservano i contenuti in uno stato eliminato, con conseguenti costi di archiviazione potenzialmente elevati. Ti consigliamo vivamente di disattivare l'eliminazione temporanea per evitare addebiti imprevisti.

Esempi di output

Nota :gli esempi seguenti rappresentano una riga nel file JSONL di output. Sono formattati per una maggiore leggibilità.

Esempio riuscito

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

Esempio di operazione non riuscita

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