Previsioni batch

Le previsioni in batch ti consentono di inviare in modo efficiente più prompt di solo testo che non sono sensibili alla latenza a un modello. Rispetto alle previsioni online, in cui invii un prompt di input per ogni richiesta, puoi raggruppare un numero elevato di prompt di input in una singola richiesta.

Modelli supportati

Gemini Enterprise Agent Platform supporta le previsioni in batch per i seguenti modelli.

Llama:

OpenAI gpt-oss:

Qwen:

DeepSeek:

Modelli di embedding:

Preparare l'input

Prima di iniziare, prepara gli input in una tabella BigQuery o come file JSONL in Cloud Storage. L'input per entrambe le origini deve seguire il formato JSONL dello schema dell'API OpenAI, come mostrato negli esempi seguenti.

Modelli linguistici di grandi dimensioni:

{"custom_id": "test-request-0", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "MODEL_ID", "messages": [{"role": "user", "content": "Give me a recipe for banana bread"}], "max_tokens": 1000}}

Modelli di embedding:

{"custom_id": "test-request-0", "method": "POST", "url": "/v1/embeddings", "body": {"model": "MODEL_ID", "input": "Hello World"}}

BigQuery

La tabella di input BigQuery deve rispettare lo schema seguente:

Nome colonna Descrizione
custom_id Un ID per ogni richiesta per abbinare l'input all'output.
method Il metodo di richiesta.
url L'endpoint della richiesta.
body(JSON) Il prompt di input.
  • La tabella di input può avere altre colonne, che vengono ignorate dal job batch e passate direttamente alla tabella di output.
  • I job di previsione in batch riservano due nomi di colonna per l'output della previsione in batch: response(JSON) e id. Non utilizzare queste colonne nella tabella di input.
  • Le colonne method e url vengono eliminate e non incluse nella tabella di output.

Cloud Storage

Per Cloud Storage, il file di input deve essere un file JSONL che si trova in un bucket Cloud Storage.

Richiedere una previsione in batch

Esegui una previsione in batch su un modello utilizzando l'input di BigQuery o Cloud Storage. Puoi scegliere in modo indipendente di generare l'output delle previsioni in una tabella BigQuery o in un file JSONL in un bucket Cloud Storage.

BigQuery

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

REST

Dopo aver configurato l'ambiente, puoi utilizzare REST per testare un prompt di testo. L'esempio seguente invia una richiesta all'endpoint del modello del publisher.

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

  • LOCATION: una regione che supporta il modello.
  • PROJECT_ID: il tuo [ID progetto](/resource-manager/docs/creating-managing-projects#identifiers). .
  • MODEL: il nome del modello da ottimizzare.
  • INPUT_URI: la tabella BigQuery in cui si trova l'input della previsione in batch, ad esempio myproject.mydataset.input_table.
  • OUTPUT_FORMAT: per generare l'output in una tabella BigQuery, specifica bigquery. Per generare 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 località della tabella, ad esempio myproject.mydataset.output_result. Per Cloud Storage, specifica la località del bucket e della cartella, ad esempio gs://mybucket/path/to/outputfile.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

'{
  "displayName": "JOB_NAME",
  "model": "publishers/PUBLISHER/models/MODEL_ID",
  "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, e 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.

Cloud Storage

Specifica la località di Cloud Storage del file JSONL, il modello e la località di output.

REST

Dopo aver configurato l'ambiente, puoi utilizzare REST per testare un prompt di testo. L'esempio seguente invia una richiesta all'endpoint del modello del publisher.

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

  • LOCATION: una regione che supporta il modello.
  • PROJECT_ID: il tuo [ID progetto](/resource-manager/docs/creating-managing-projects#identifiers). .
  • MODEL: il nome del modello da ottimizzare.
  • INPUT_URI: la località di Cloud Storage dell'input della previsione in batch JSONL, ad esempio gs://bucketname/path/to/jsonl.
  • OUTPUT_FORMAT: per generare l'output in una tabella BigQuery, specifica bigquery. Per generare 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 località della tabella, ad esempio myproject.mydataset.output_result. Per Cloud Storage, specifica la località del bucket e della cartella, ad esempio gs://mybucket/path/to/outputfile.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

'{
  "displayName": "JOB_NAME",
  "model": "publishers/PUBLISHER/models/MODEL_ID",
  "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, e 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.

Ottenere lo stato di un job di previsione in batch

Ottieni lo stato del job di previsione in batch per verificare se è stato completato correttamente. La durata del job dipende dal numero di elementi di input che hai inviato.

REST

Dopo aver configurato l'ambiente, puoi utilizzare REST per testare un prompt di testo. L'esempio seguente invia una richiesta all'endpoint del modello del publisher.

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

  • PROJECT_ID: il tuo [ID progetto](/resource-manager/docs/creating-managing-projects#identifiers). .
  • LOCATION: la regione in cui si trova il job batch.
  • JOB_ID: l'ID del job batch restituito quando hai creato il job.

Metodo HTTP e URL: 

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Esegui questo comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/JOB_ID"

PowerShell

Esegui questo 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/JOB_ID" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente.

Recuperare l'output

Al termine di un job di previsione in batch, recupera l'output dalla località che hai specificato. Per BigQuery, l'output si trova nella colonna response(JSON) della tabella BigQuery di destinazione. Per Cloud Storage, l'output viene salvato come file JSONL nella località di output di Cloud Storage.

Passaggi successivi