API di ottimizzazione

L'ottimizzazione del modello è un processo cruciale per adattare Gemini a svolgere attività specifiche con maggiore precisione e accuratezza. L'ottimizzazione fornisce al modello un set di dati di addestramento che contiene un insieme di esempi di attività downstream specifiche.

Utilizza l'API di ottimizzazione di Gemini per i seguenti casi d'uso:

Modelli supportati:

Puoi utilizzare il fine-tuning supervisionato sui seguenti modelli Gemini:

È supportato anche Translation LLM V2 (translation-llm-002).

Sintassi di esempio

Sintassi per ottimizzare un modello.

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \

https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs \
-d '{
  "baseModel": "...",
  "supervisedTuningSpec" : {
    ...
      "hyper_parameters": {
        ...
      },
  },
  "tunedModelDisplayName": "",
}'

Elenco dei parametri

Per informazioni dettagliate sull'implementazione, consulta gli esempi.

Corpo della richiesta

Il corpo della richiesta contiene dati con i seguenti parametri:

Parametri

source_model

(Facoltativo) string

Nome del foundation model che viene ottimizzato.

tunedModelDisplayName

string

Il nome visualizzato di TunedModel. Il nome può avere fino a 128 caratteri e può essere composto da qualsiasi carattere UTF-8.

supervisedTuningSpec

Parametri

training_dataset

string

URI Cloud Storage del set di dati di addestramento. Il set di dati deve essere formattato come file JSONL. Per ottenere risultati ottimali, fornisci almeno 100-500 esempi. Per saperne di più, consulta Informazioni sui set di dati di ottimizzazione supervisionata.

validation_dataset

(Facoltativo) string

URI Cloud Storage del set di dati di convalida. Il set di dati deve essere formattato come file JSONL. Un set di dati può contenere fino a 256 esempi. Se fornisci questo file, i dati vengono utilizzati per generare periodicamente metriche di convalida durante l'ottimizzazione. Per saperne di più, consulta Informazioni sui set di dati di ottimizzazione supervisionata .

epoch_count

(Facoltativo) int

Il numero di passaggi completi che il modello esegue sull'intero set di dati di addestramento durante l'addestramento. Vertex AI regola automaticamente il valore predefinito in base alle dimensioni del set di dati di addestramento. Questo valore si basa sui risultati del benchmarking per ottimizzare la qualità dell'output del modello.

learning_rate_multiplier

(Facoltativo) float

Moltiplicatore per la regolazione del tasso di apprendimento predefinito.

adapter_size

(Facoltativo) AdapterSize

Dimensioni dell'adattatore per l'ottimizzazione.

tuned_model_display_name

(Facoltativo) string

Nome visualizzato di TunedModel. Il nome può avere fino a 128 caratteri e può essere composto da qualsiasi carattere UTF-8.

AdapterSize

Dimensioni dell'adattatore per il job di ottimizzazione.

Parametri

ADAPTER_SIZE_UNSPECIFIED

Dimensioni dell'adattatore non specificate.

ADAPTER_SIZE_ONE

Dimensioni adattatore 1.

ADAPTER_SIZE_FOUR

Dimensioni adattatore 4.

ADAPTER_SIZE_EIGHT

Dimensioni adattatore 8.

ADAPTER_SIZE_SIXTEEN

Dimensioni adattatore 16.

Esempi

Crea un job di ottimizzazione supervisionata

Puoi creare un job di ottimizzazione del modello di testo supervisionato utilizzando l'SDK Vertex AI Python o inviando una richiesta POST.

Caso d'uso di base

Il caso d'uso di base imposta solo i valori per baseModel e training_dataset_uri. Tutti gli altri parametri utilizzano i valori predefiniti.

REST

Per creare un job di ottimizzazione del modello, invia una richiesta POST utilizzando il metodo tuningJobs.create. Tieni presente che alcuni parametri non sono supportati da tutti i modelli. Assicurati di includere solo i parametri applicabili per il modello che stai ottimizzando.

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

  • PROJECT_ID: il tuo ID progetto
  • TUNING_JOB_REGION: la regione in cui viene eseguito il job di ottimizzazione. Questa è anche la regione predefinita in cui viene caricato il modello ottimizzato.
  • BASE_MODEL: Nome del modello di base da ottimizzare.
  • TRAINING_DATASET_URI: l'URI Cloud Storage del set di dati di addestramento. Il set di dati deve essere formattato come file JSONL. Per ottenere risultati ottimali, fornisci almeno 100-500 esempi. Per saperne di più, consulta Informazioni sui set di dati di ottimizzazione supervisionata .

Metodo HTTP e URL: 

POST https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs

Corpo JSON della richiesta: 

{
  "baseModel": "BASE_MODEL",
  "supervisedTuningSpec" : {
      "training_dataset_uri": "TRAINING_DATASET_URI"
  },
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, ed esegui questo 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://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente.

Python 


import time

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

sft_tuning_job = sft.train(
    source_model="gemini-2.0-flash-001",
    # 1.5 and 2.0 models use the same JSONL format
    train_dataset="gs://cloud-samples-data/ai-platform/generative_ai/gemini-1_5/text/sft_train_data.jsonl",
)

# Polling for job completion
while not sft_tuning_job.has_ended:
    time.sleep(60)
    sft_tuning_job.refresh()

print(sft_tuning_job.tuned_model_name)
print(sft_tuning_job.tuned_model_endpoint_name)
print(sft_tuning_job.experiment)
# Example response:
# projects/123456789012/locations/us-central1/models/1234567890@1
# projects/123456789012/locations/us-central1/endpoints/123456789012345
# <google.cloud.aiplatform.metadata.experiment_resources.Experiment object at 0x7b5b4ae07af0>

Caso d'uso avanzato

Il caso d'uso avanzato si basa su quello di base, ma imposta anche valori per hyper_parameters facoltativi, come epoch_count, learning_rate_multiplier e adapter_size.

REST

Per creare un job di ottimizzazione del modello, invia una richiesta POST utilizzando il metodo tuningJobs.create. Tieni presente che alcuni parametri non sono supportati da tutti i modelli. Assicurati di includere solo i parametri applicabili per il modello che stai ottimizzando.

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

  • PROJECT_ID: il tuo ID progetto.
  • TUNING_JOB_REGION: la regione in cui viene eseguito il job di ottimizzazione. Questa è anche la regione predefinita in cui viene caricato il modello ottimizzato.
  • BASE_MODEL: Nome del modello di base da ottimizzare.
  • TRAINING_DATASET_URI: l'URI Cloud Storage del set di dati di addestramento. Il set di dati deve essere formattato come file JSONL. Per ottenere risultati ottimali, fornisci almeno 100-500 esempi. Per saperne di più, consulta Informazioni sui set di dati di ottimizzazione supervisionata .
  • VALIDATION_DATASET_URI(Facoltativo) L'URI Cloud Storage del file del set di dati di convalida.
  • EPOCH_COUNT(Facoltativo) Il numero di passaggi completi che il modello esegue sull'intero set di dati di addestramento durante l'addestramento. Lascia il campo vuoto per utilizzare il valore consigliato precompilato.
  • ADAPTER_SIZE(Facoltativo) Le dimensioni dell'adattatore da utilizzare per il job di ottimizzazione. Le dimensioni dell'adattatore influiscono sul numero di parametri addestrabili per il job di ottimizzazione. Un adattatore più grande implica che il modello può apprendere attività più complesse, ma richiede un set di dati di addestramento più grande e tempi di addestramento più lunghi.
  • LEARNING_RATE_MULTIPLIER: facoltativo: un moltiplicatore da applicare al tasso di apprendimento suggerito. Lascia il campo vuoto per utilizzare il valore consigliato.
  • EXPORT_LAST_CHECKPOINT_ONLY(Facoltativo) Imposta true per utilizzare solo l'ultimo checkpoint.
  • METRIC_SPEC(Facoltativo) Una o più specifiche delle metriche che utilizzi per eseguire una valutazione utilizzando il servizio di valutazione dell'AI generativa. Puoi utilizzare le seguenti specifiche delle metriche: "pointwise_metric_spec", "pairwise_metric_spec".
  • METRIC_SPEC_FIELD_NAME(Facoltativo) I campi obbligatori per la specifica della metrica scelta. Ad esempio, "metric_prompt_template"
  • METRIC_SPEC_FIELD_NAME_CONTENT(Facoltativo) Il campo contenuto per la specifica della metrica scelta. Ad esempio, puoi utilizzare il seguente contenuto del campo per una valutazione punto per punto: "Evaluate the fluency of this sentence: {response}. Give score from 0 to 1. 0 - not fluent at all. 1 - very fluent."
  • CLOUD_STORAGE_BUCKET(Facoltativo) Il bucket Cloud Storage in cui archiviare i risultati di un'esecuzione di valutazione da parte del servizio Gen AI evaluation service.
  • TUNED_MODEL_DISPLAYNAME(Facoltativo) Un nome visualizzato per il modello ottimizzato. Se non viene impostato, viene generato un nome casuale.
  • KMS_KEY_NAME(Facoltativo) L'identificatore della risorsa Cloud KMS della chiave di crittografia gestita dal cliente utilizzata per proteggere una risorsa. La chiave ha il formato: projects/my-project/locations/my-region/keyRings/my-kr/cryptoKeys/my-key. La chiave deve trovarsi nella stessa regione in cui viene creata la risorsa di computing. Per saperne di più, consulta Chiavi di crittografia gestite dal cliente (CMEK).
  • SERVICE_ACCOUNT(Facoltativo) Il account di servizio con cui viene eseguito il carico di lavoro tuningJob. Se non specificato, viene utilizzato l'agente di servizio Vertex AI Secure Fine-Tuning nel progetto. Consulta la sezione Agente di servizio di ottimizzazione. Se prevedi di utilizzare un service account gestito dal cliente, devi concedere il ruolo roles/aiplatform.tuningServiceAgent al account di servizio. Concedi anche il ruolo Agente di servizio di ottimizzazione roles/iam.serviceAccountTokenCreator al service account gestito dal cliente.

Metodo HTTP e URL: 

POST https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs

Corpo JSON della richiesta: 

{
  "baseModel": "BASE_MODEL",
  "supervisedTuningSpec" : {
      "trainingDatasetUri": "TRAINING_DATASET_URI",
      "validationDatasetUri": "VALIDATION_DATASET_URI",
      "hyperParameters": {
          "epochCount": "EPOCH_COUNT",
          "adapterSize": "ADAPTER_SIZE",
          "learningRateMultiplier": "LEARNING_RATE_MULTIPLIER"
      },
      "exportLastCheckpointOnly": EXPORT_LAST_CHECKPOINT_ONLY,
      "evaluationConfig": {
          "metrics": [
              {
                  "aggregation_metrics": ["AVERAGE", "STANDARD_DEVIATION"],
                  "METRIC_SPEC": {
                      "METRIC_SPEC_FIELD_NAME":
                          METRIC_SPEC_FIELD_CONTENT
                  }
              },
          ],
          "outputConfig": {
              "gcs_destination": {
                  "output_uri_prefix": "CLOUD_STORAGE_BUCKET"
              }
          },
      },
  },
  "tunedModelDisplayName": "TUNED_MODEL_DISPLAYNAME",
  "encryptionSpec": {
    "kmsKeyName": "KMS_KEY_NAME"
  },
  "serviceAccount": "SERVICE_ACCOUNT"
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, ed esegui questo 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://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente.

Python 


import time

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Initialize Vertex AI with your service account for BYOSA (Bring Your Own Service Account).
# Uncomment the following and replace "your-service-account"
# vertexai.init(service_account="your-service-account")

# Initialize Vertex AI with your CMEK (Customer-Managed Encryption Key).
# Un-comment the following line and replace "your-kms-key"
# vertexai.init(encryption_spec_key_name="your-kms-key")

sft_tuning_job = sft.train(
    source_model="gemini-2.0-flash-001",
    # 1.5 and 2.0 models use the same JSONL format
    train_dataset="gs://cloud-samples-data/ai-platform/generative_ai/gemini-1_5/text/sft_train_data.jsonl",
    # The following parameters are optional
    validation_dataset="gs://cloud-samples-data/ai-platform/generative_ai/gemini-1_5/text/sft_validation_data.jsonl",
    tuned_model_display_name="tuned_gemini_2_0_flash",
    # Advanced use only below. It is recommended to use auto-selection and leave them unset
    # epochs=4,
    # adapter_size=4,
    # learning_rate_multiplier=1.0,
)

# Polling for job completion
while not sft_tuning_job.has_ended:
    time.sleep(60)
    sft_tuning_job.refresh()

print(sft_tuning_job.tuned_model_name)
print(sft_tuning_job.tuned_model_endpoint_name)
print(sft_tuning_job.experiment)
# Example response:
# projects/123456789012/locations/us-central1/models/1234567890@1
# projects/123456789012/locations/us-central1/endpoints/123456789012345
# <google.cloud.aiplatform.metadata.experiment_resources.Experiment object at 0x7b5b4ae07af0>

Elenco job di ottimizzazione

Puoi visualizzare un elenco dei job di ottimizzazione nel tuo progetto attuale utilizzando l'SDK Vertex AI per Python o inviando una richiesta GET.

REST

Per creare un job di ottimizzazione del modello, invia una richiesta POST utilizzando il metodo tuningJobs.create. Tieni presente che alcuni parametri non sono supportati da tutti i modelli. Assicurati di includere solo i parametri applicabili per il modello che stai ottimizzando.

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

  • PROJECT_ID: .
  • TUNING_JOB_REGION: la regione in cui viene eseguito il job di ottimizzazione. Questa è anche la regione predefinita in cui viene caricato il modello ottimizzato.

Metodo HTTP e URL: 

GET https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs

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://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs"

PowerShell

Esegui questo comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente.

Python 

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

responses = sft.SupervisedTuningJob.list()

for response in responses:
    print(response)
# Example response:
# <vertexai.tuning._supervised_tuning.SupervisedTuningJob object at 0x7c85287b2680>
# resource name: projects/12345678/locations/us-central1/tuningJobs/123456789012345

Visualizzare i dettagli di un job di ottimizzazione

Puoi ottenere i dettagli di un job di ottimizzazione utilizzando l'SDK Vertex AI per Python o inviando una richiesta GET.

REST

Per visualizzare un elenco dei job di ottimizzazione del modello, invia una richiesta GET utilizzando il metodo tuningJobs.get e specifica TuningJob_ID.

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

  • PROJECT_ID: .
  • TUNING_JOB_REGION: la regione in cui viene eseguito il job di ottimizzazione. Questa è anche la regione predefinita in cui viene caricato il modello ottimizzato.
  • TUNING_JOB_ID: l'ID del job di ottimizzazione.

Metodo HTTP e URL: 

GET https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs/TUNING_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://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs/TUNING_JOB_ID"

PowerShell

Esegui questo comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs/TUNING_JOB_ID" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente.

Python 

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# LOCATION = "us-central1"
vertexai.init(project=PROJECT_ID, location=LOCATION)

tuning_job_id = "4982013113894174720"
response = sft.SupervisedTuningJob(
    f"projects/{PROJECT_ID}/locations/{LOCATION}/tuningJobs/{tuning_job_id}"
)

print(response)
# Example response:
# <vertexai.tuning._supervised_tuning.SupervisedTuningJob object at 0x7cc4bb20baf0>
# resource name: projects/1234567890/locations/us-central1/tuningJobs/4982013113894174720

Annullamento di un job di ottimizzazione

Puoi annullare un job di ottimizzazione utilizzando l'SDK Vertex AI per Python o inviando una richiesta POST.

REST

Per visualizzare un elenco dei job di ottimizzazione del modello, invia una richiesta GET utilizzando il metodo tuningJobs.cancel e specifica TuningJob_ID.

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

  • PROJECT_ID: .
  • TUNING_JOB_REGION: la regione in cui viene eseguito il job di ottimizzazione. Questa è anche la regione predefinita in cui viene caricato il modello ottimizzato.
  • TUNING_JOB_ID: l'ID del job di ottimizzazione.

Metodo HTTP e URL: 

POST https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs/TUNING_JOB_ID:cancel

Per inviare la richiesta, scegli una di queste opzioni:

curl

Esegui questo comando: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs/TUNING_JOB_ID:cancel"

PowerShell

Esegui questo comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs/TUNING_JOB_ID:cancel" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente.

Python 

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# LOCATION = "us-central1"
vertexai.init(project=PROJECT_ID, location=LOCATION)

tuning_job_id = "4982013113894174720"
job = sft.SupervisedTuningJob(
    f"projects/{PROJECT_ID}/locations/{LOCATION}/tuningJobs/{tuning_job_id}"
)
job.cancel()

Passaggi successivi

Per la documentazione dettagliata, consulta quanto segue: