Creazione di un job di ottimizzazione iperparametri

Gli iperparametri sono le variabili che regolano il processo di addestramento di un modello, ad esempio la dimensione del batch o il numero di strati nascosti in una rete neurale profonda. L'ottimizzazione degli iperparametri cerca la migliore combinazione di valori degli iperparametri ottimizzando i valori delle metriche in una serie di prove. Le metriche sono riepiloghi scalari che aggiungi al tuo trainer, ad esempio l'accuratezza del modello.

Scopri di più sull'ottimizzazione degli iperparametri su Vertex AI. Per un esempio passo passo, consulta il codelab Vertex AI: Hyperparameter Tuning.

Questa pagina illustra come:

Preparare l'applicazione di addestramento

In un job di ottimizzazione degli iperparametri, Vertex AI crea prove del job di addestramento con diversi insiemi di iperparametri e valuta l'efficacia di una prova utilizzando le metriche specificate. Vertex AI trasmette i valori degli iperparametri all'applicazione di addestramento come argomenti della riga di comando. Affinché Vertex AI possa valutare l'efficacia di un esperimento, la tua applicazione di addestramento deve segnalare le metriche a Vertex AI.

Le sezioni seguenti descrivono:

  • In che modo Vertex AI passa gli iperparametri all'applicazione di addestramento.
  • Opzioni per trasmettere le metriche dall'applicazione di addestramento a Vertex AI.

Per scoprire di più sui requisiti per le applicazioni di addestramento personalizzato eseguite su Vertex AI, consulta la sezione Requisiti del codice di addestramento.

Gestire gli argomenti della riga di comando per gli iperparametri da ottimizzare

Vertex AI imposta gli argomenti della riga di comando quando chiama l'applicazione di addestramento. Utilizza gli argomenti della riga di comando nel codice:

  1. Definisci un nome per ogni argomento dell'iperparametro e analizzalo utilizzando il parser di argomenti che preferisci, ad esempio argparse. Utilizza gli stessi nomi degli argomenti quando configuri il job di addestramento degli iperparametri.

    Ad esempio, se l'applicazione di addestramento è un modulo Python denominato my_trainer e stai ottimizzando un iperparametro denominato learning_rate, Vertex AI avvia ogni prova con un comando come il seguente:

    python3 -m my_trainer --learning_rate learning-rate-in-this-trial

    Vertex AI determina il valore learning-rate-in-this-trial e lo passa utilizzando l'argomento learning_rate.

  2. Assegna i valori degli argomenti della riga di comando agli iperparametri nel codice di addestramento.

Scopri di più sui requisiti per l'analisi sintattica degli argomenti della riga di comando.

Segnalare le metriche a Vertex AI

Per segnalare le metriche a Vertex AI, utilizza il cloudml-hypertune pacchetto Python. Questa libreria fornisce funzioni di supporto per la generazione di report sulle metriche in Vertex AI.

Scopri di più sulle metriche degli iperparametri dei report.

Creazione di un job di ottimizzazione iperparametri

A seconda dello strumento che vuoi utilizzare per creare un HyperparameterTuningJob, seleziona una delle seguenti schede:

Console

Nella console Google Cloud non puoi creare direttamente una risorsa HyperparameterTuningJob. Tuttavia, puoi creare una risorsa TrainingPipeline che crea un HyperparameterTuningJob.

Le istruzioni riportate di seguito descrivono come creare un TrainingPipeline che crea un HyperparameterTuningJob e non fa altro. Se vuoi utilizzare altre funzionalità di TrainingPipeline, ad esempio l'addestramento con un set di dati gestito, leggi la sezione Creare pipeline di addestramento.

  1. Nella console Google Cloud, nella sezione Vertex AI, vai alla pagina Pipeline di addestramento.

    Vai a Pipeline di addestramento

  2. Fai clic su Crea per aprire il riquadro Addestra nuovo modello.

  3. Nel passaggio Metodo di addestramento, specifica le seguenti impostazioni:

    1. Nell'elenco a discesa Set di dati, seleziona Nessun set di dati gestito.

    2. Seleziona Addestramento personalizzato (avanzato).

    Fai clic su Continua.

  4. Nel passaggio Dettagli modello, scegli Addestra nuovo modello o Addestra nuova versione. Se selezioni Addestra nuovo modello, inserisci un nome a tua scelta,MODEL_NAME, per il modello. Fai clic su Continua.

  5. Nel passaggio Container di addestramento, specifica le seguenti impostazioni:

    1. Seleziona se utilizzare un container predefinito o un contenuto personalizzato per l'addestramento.

    2. A seconda della tua scelta, esegui una delle seguenti operazioni:

    3. Nel campo Directory di output del modello, puoi specificare l'URI Cloud Storage di una directory in un bucket a cui hai accesso. La directory non deve ancora esistere.

      Questo valore viene passato a Vertex AI nel campo baseOutputDirectory API, che imposta diverse variabili di ambiente a cui l'applicazione di addestramento può accedere quando viene eseguita.

    4. Facoltativo: nel campo Argomenti, puoi specificare gli argomenti da utilizzare da parte di Vertex AI quando inizia a eseguire il codice di addestramento. La lunghezza massima per tutti gli argomenti combinati è di 100.000 caratteri. Il comportamento di questi argomenti varia a seconda del tipo di contenitore utilizzato:

    Fai clic su Continua.

  6. Nel passaggio Ottimizzazione degli iperparametri, seleziona la casella di controllo Abilita ottimizzazione degli iperparametri e specifica le seguenti impostazioni:

    1. Nella sezione Nuovo iperparametro, specifica il nome parametro e il tipo di un iperparametro da ottimizzare. A seconda del tipo specificato, configura le impostazioni degli iperparametri aggiuntivi visualizzate.

      Scopri di più sui tipi di iperparametri e sulle relative configurazioni.

    2. Se vuoi ottimizzare più di un iperparametro, fai clic su Aggiungi nuovo parametro e ripeti il passaggio precedente nella nuova sezione visualizzata.

      Ripeti questa operazione per ogni iperparametro che vuoi ottimizzare.

    3. Nel campo Metrica da ottimizzare e nell'elenco a discesa Obiettivo, specifica il nome e l'obiettivo della metrica che vuoi ottimizzare.

    4. Nel campo Numero massimo di prove, specifica il numero massimo di prove che vuoi che Vertex AI esegua per il tuo job di ottimizzazione degli iperparametri.

    5. Nel campo Numero massimo di prove parallele, specifica il numero massimo di prove da eseguire contemporaneamente.

    6. Nell'elenco a discesa Algoritmo di ricerca, specifica un algoritmo di ricerca da utilizzare per Vertex AI.

    7. Ignora l'opzione di attivazione/disattivazione Abilita l'interruzione anticipata, che non ha alcun effetto.

    Fai clic su Continua.

  7. Nel passaggio Computing e prezzi, specifica le seguenti impostazioni:

    1. Nell'elenco a discesa Regione, seleziona una "regione che supporta l'addestramento personalizzato".

    2. Nella sezione Pool di worker 0, specifica le risorse di calcolo da utilizzare per l'addestramento.

      Se specifichi gli acceleratori, assicurati che il tipo di acceleratore scelto sia disponibile nella regione selezionata.

      Se vuoi eseguire l'addestramento distribuito, fai clic su Aggiungi altri pool di worker e specifica un altro insieme di risorse di calcolo per ogni altro pool di worker che vuoi.

    Fai clic su Continua.

  8. Nel passaggio Contenitore di previsione, seleziona Nessun contenitore di previsione.

  9. Fai clic su Inizia addestramento per avviare la pipeline di addestramento personalizzato.

gcloud

I passaggi che seguono mostrano come utilizzare Google Cloud CLI per creare un HyperparameterTuningJob con una configurazione relativamente minima. Per scoprire tutte le opzioni di configurazione che puoi utilizzare per questa operazione, consulta la documentazione di riferimento del comando gcloud ai hp-tuning-jobs create e la risorsa API HyperparameterTuningJob.

  1. Crea un file YAML denominato config.yaml con alcuni campi dell'API che vuoi specificare per il nuovo HyerparameterTuningJob:

    config.yaml
    studySpec:
  metrics:
  - metricId: METRIC_ID
    goal: METRIC_GOAL
  parameters:
  - parameterId: HYPERPARAMETER_ID
    doubleValueSpec:
      minValue: DOUBLE_MIN_VALUE
      maxValue: DOUBLE_MAX_VALUE
trialJobSpec:
  workerPoolSpecs:
    - machineSpec:
        machineType: MACHINE_TYPE
      replicaCount: 1
      containerSpec:
        imageUri: CUSTOM_CONTAINER_IMAGE_URI

    Sostituisci quanto segue:

  2. Nella stessa directory del file config.yaml, esegui il seguente comando shell:

    gcloud ai hp-tuning-jobs create \
    --region=LOCATION \
    --display-name=DISPLAY_NAME \
    --max-trial-count=MAX_TRIAL_COUNT \
    --parallel-trial-count=PARALLEL_TRIAL_COUNT \
    --config=config.yaml

    Sostituisci quanto segue:

REST

Utilizza il seguente esempio di codice per creare un job di ottimizzazione degli iperparametri utilizzando il metodo create della risorsa hyperparameterTuningJob.

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

  • LOCATION: la regione in cui vuoi creare il HyperparameterTuningJob. Utilizza una regione che supporta l'addestramento personalizzato.
  • PROJECT: il tuo ID progetto.
  • DISPLAY_NAME: un nome visualizzato facile da ricordare scelto da te per il HyperparameterTuningJob. Scopri di più sui requisiti dei nomi delle risorse.
  • Specifica le metriche:
  • Specifica gli iperparametri:
    • HYPERPARAMETER_ID: il nome di un iperparametro da ottimizzare. Il codice di addestramento deve analizzare un flag a riga di comando con questo nome.
    • PARAMETER_SCALE: (facoltativo) La modalità di applicazione della scala al parametro. Lascia vuoto per i parametri CATEGORICAL. Può essere UNIT_LINEAR_SCALE, UNIT_LOG_SCALE, UNIT_REVERSE_LOG_SCALE o SCALE_TYPE_UNSPECIFIED
    • Se il tipo di questo iperparametro è DOUBLE, specifica i valori minimo (DOUBLE_MIN_VALUE) e massimo (DOUBLE_MAX_VALUE) per questo iperparametro.
    • Se il tipo di questo iperparametro è INTEGER, specifica i valori minimo (INTEGER_MIN_VALUE) e massimo (INTEGER_MAX_VALUE) per questo iperparametro.
    • Se il tipo di questo iperparametro è CATEGORICO, specifica i valori accettabili (CATEGORICAL_VALUES) come array di stringhe.
    • Se il tipo di questo iperparametro è DISCRETE, specifica i valori accettabili (DISCRETE_VALUES) come array di numeri.
    • Specifica gli iperparametri condizionali. Gli iperparametri condizionali vengono aggiunti a una prova quando il valore dell'iperparametro principale corrisponde alla condizione specificata. Scopri di più sugli iperparametri condizionali.
      • CONDITIONAL_PARAMETER: il ParameterSpec del parametro condizionale. Questa specifica include il nome, la scala, l'intervallo di valori del parametro e tutti i parametri condizionali che dipendono da questo iperparametro.
      • Se il tipo dell'iperparametro principale è INTEGER, specifica un elenco di numeri interi come INTEGERS_TO_MATCH. Se il valore dell'iperparametro principale corrisponde a uno dei valori specificati, questo parametro condizionale viene aggiunto alla prova.
      • Se il tipo dell'iperparametro principale è CATEGORICAL, specifica un elenco di categorie come CATEGORIES_TO_MATCH. Se il valore dell'iperparametro principale corrisponde a uno dei valori specificati, questo parametro condizionale viene aggiunto alla prova.
      • Se il tipo dell'iperparametro principale è DISCRETE, specifica un elenco di numeri interi come DISCRETE_VALUES_TO_MATCH. Se il valore dell'iperparametro principale corrisponde a uno dei valori specificati, questo parametro condizionale viene aggiunto alla prova.
  • ALGORITHM: (facoltativo) L'algoritmo di ricerca da utilizzare in questo job di ottimizzazione degli iperparametri. Può essere ALGORITHM_UNSPECIFIED, GRID_SEARCH o RANDOM_SEARCH.
  • MAX_TRIAL_COUNT: il numero massimo di prove da eseguire.
  • PARALLEL_TRIAL_COUNT: il numero massimo di prove da eseguire in parallelo.
  • MAX_FAILED_TRIAL_COUNT: il numero di job che possono non riuscire prima che il job di ottimizzazione degli iperparametri non riesca.
  • Definisci il job di addestramento personalizzato di prova:
    • MACHINE_TYPE: il tipo di VM da utilizzare per l'addestramento.
    • ACCELERATOR_TYPE: (facoltativo) Il tipo di acceleratore da collegare a ogni prova.
    • ACCELERATOR_COUNT: (facoltativo) Il numero di acceleratori da collegare a ogni prova.
    • REPLICA_COUNT: il numero di repliche dei worker da utilizzare per ogni prova.
    • Se l'applicazione di addestramento viene eseguita in un contenitore personalizzato, specifica quanto segue:
      • CUSTOM_CONTAINER_IMAGE_URI: l'URI di un'immagine container Docker con il codice di addestramento. Scopri come creare un'immagine contenitore personalizzata.
      • CUSTOM_CONTAINER_COMMAND: (facoltativo) Il comando da richiamare all'avvio del container. Questo comando sostituisce l'entrypoint predefinito del container.
      • CUSTOM_CONTAINER_ARGS: (facoltativo) Gli argomenti da passare all'avvio del container.
    • Se l'applicazione di addestramento è un pacchetto Python che viene eseguito in un container predefinito, specifica quanto segue:
      • PYTHON_PACKAGE_EXECUTOR_IMAGE_URI: l'URI dell'immagine del container che esegue il pacchetto Python fornito. Scopri di più sui container predefiniti per l'addestramento.
      • PYTHON_PACKAGE_URIS: la posizione in Cloud Storage dei file del pacchetto Python, ovvero il programma di addestramento e i relativi pacchetti dipendenti. Il numero massimo di URI dei pacchetti è 100.
      • PYTHON_MODULE: il nome del modulo Python da eseguire dopo l'installazione dei pacchetti.
      • PYTHON_PACKAGE_ARGS: (facoltativo) Argomenti della riga di comando da passare al modulo Python.
    • SERVICE_ACCOUNT: (facoltativo) L'account di servizio che Vertex AI utilizzerà per eseguire il codice. Scopri di più su come collegare un account di servizio personalizzato.
    • TIMEOUT: (facoltativo) Il tempo di esecuzione massimo per ogni prova.
  • Specifica LABEL_NAME e LABEL_VALUE per le eventuali etichette da applicare a questo job di ottimizzazione degli iperparametri.

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/hyperparameterTuningJobs

Corpo JSON della richiesta: 

{
  "displayName": DISPLAY_NAME,
  "studySpec": {
    "metrics": [
      {
        "metricId": METRIC_ID,
        "goal": METRIC_GOAL
      }
    ],
    "parameters": [
      {
        "parameterId": PARAMETER_ID,
        "scaleType": PARAMETER_SCALE,

        // Union field parameter_value_spec can be only one of the following:
        "doubleValueSpec": {
            "minValue": DOUBLE_MIN_VALUE,
            "maxValue": DOUBLE_MAX_VALUE
        },
        "integerValueSpec": {
            "minValue": INTEGER_MIN_VALUE,
            "maxValue": INTEGER_MAX_VALUE
        },
        "categoricalValueSpec": {
            "values": [
              CATEGORICAL_VALUES
            ]
        },
        "discreteValueSpec": {
            "values": [
              DISCRETE_VALUES
            ]
        }
        // End of list of possible types for union field parameter_value_spec.

        "conditionalParameterSpecs": [
            "parameterSpec": {
              CONDITIONAL_PARAMETER
            }

            // Union field parent_value_condition can be only one of the following:
            "parentIntValues": {
                "values": [INTEGERS_TO_MATCH]
            }
            "parentCategoricalValues": {
                "values": [CATEGORIES_TO_MATCH]
            }
            "parentDiscreteValues": {
                "values": [DISCRETE_VALUES_TO_MATCH]
            }
            // End of list of possible types for union field parent_value_condition.
        ]
      }
    ],
    "ALGORITHM": ALGORITHM
  },
  "maxTrialCount": MAX_TRIAL_COUNT,
  "parallelTrialCount": PARALLEL_TRIAL_COUNT,
  "maxFailedTrialCount": MAX_FAILED_TRIAL_COUNT,
  "trialJobSpec": {
      "workerPoolSpecs": [
        {
          "machineSpec": {
            "machineType": MACHINE_TYPE,
            "acceleratorType": ACCELERATOR_TYPE,
            "acceleratorCount": ACCELERATOR_COUNT
          },
          "replicaCount": REPLICA_COUNT,

          // Union field task can be only one of the following:
          "containerSpec": {
            "imageUri": CUSTOM_CONTAINER_IMAGE_URI,
            "command": [
              CUSTOM_CONTAINER_COMMAND
            ],
            "args": [
              CUSTOM_CONTAINER_ARGS
            ]
          },
          "pythonPackageSpec": {
            "executorImageUri": PYTHON_PACKAGE_EXECUTOR_IMAGE_URI,
            "packageUris": [
              PYTHON_PACKAGE_URIS
            ],
            "pythonModule": PYTHON_MODULE,
            "args": [
              PYTHON_PACKAGE_ARGS
            ]
          }
          // End of list of possible types for union field task.
        }
      ],
      "scheduling": {
        "TIMEOUT": TIMEOUT
      },
      "serviceAccount": SERVICE_ACCOUNT
  },
  "labels": {
    LABEL_NAME_1": LABEL_VALUE_1,
    LABEL_NAME_2": LABEL_VALUE_2
  }
}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/12345/locations/us-central1/hyperparameterTuningJobs/6789",
  "displayName": "myHyperparameterTuningJob",
  "studySpec": {
    "metrics": [
      {
        "metricId": "myMetric",
        "goal": "MINIMIZE"
      }
    ],
    "parameters": [
      {
        "parameterId": "myParameter1",
        "integerValueSpec": {
          "minValue": "1",
          "maxValue": "128"
        },
        "scaleType": "UNIT_LINEAR_SCALE"
      },
      {
        "parameterId": "myParameter2",
        "doubleValueSpec": {
          "minValue": 1e-07,
          "maxValue": 1
        },
        "scaleType": "UNIT_LINEAR_SCALE"
      }
    ],
    "ALGORITHM": "RANDOM_SEARCH"
  },
  "maxTrialCount": 20,
  "parallelTrialCount": 1,
  "trialJobSpec": {
    "workerPoolSpecs": [
      {
        "machineSpec": {
          "machineType": "n1-standard-4"
        },
        "replicaCount": "1",
        "pythonPackageSpec": {
          "executorImageUri": "us-docker.pkg.dev/vertex-ai/training/training-tf-cpu.2-1:latest",
          "packageUris": [
            "gs://my-bucket/my-training-application/trainer.tar.bz2"
          ],
          "pythonModule": "my-trainer.trainer"
        }
      }
    ]
  }
}

Java

Prima di provare questo esempio, segui le istruzioni di configurazione Java riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java di Vertex AI.

Per autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

import com.google.cloud.aiplatform.v1.AcceleratorType;
import com.google.cloud.aiplatform.v1.CustomJobSpec;
import com.google.cloud.aiplatform.v1.HyperparameterTuningJob;
import com.google.cloud.aiplatform.v1.JobServiceClient;
import com.google.cloud.aiplatform.v1.JobServiceSettings;
import com.google.cloud.aiplatform.v1.LocationName;
import com.google.cloud.aiplatform.v1.MachineSpec;
import com.google.cloud.aiplatform.v1.PythonPackageSpec;
import com.google.cloud.aiplatform.v1.StudySpec;
import com.google.cloud.aiplatform.v1.StudySpec.MetricSpec;
import com.google.cloud.aiplatform.v1.StudySpec.MetricSpec.GoalType;
import com.google.cloud.aiplatform.v1.StudySpec.ParameterSpec;
import com.google.cloud.aiplatform.v1.StudySpec.ParameterSpec.ConditionalParameterSpec;
import com.google.cloud.aiplatform.v1.StudySpec.ParameterSpec.ConditionalParameterSpec.DiscreteValueCondition;
import com.google.cloud.aiplatform.v1.StudySpec.ParameterSpec.DiscreteValueSpec;
import com.google.cloud.aiplatform.v1.StudySpec.ParameterSpec.DoubleValueSpec;
import com.google.cloud.aiplatform.v1.StudySpec.ParameterSpec.ScaleType;
import com.google.cloud.aiplatform.v1.WorkerPoolSpec;
import java.io.IOException;
import java.util.Arrays;

public class CreateHyperparameterTuningJobPythonPackageSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "PROJECT";
    String displayName = "DISPLAY_NAME";
    String executorImageUri = "EXECUTOR_IMAGE_URI";
    String packageUri = "PACKAGE_URI";
    String pythonModule = "PYTHON_MODULE";
    createHyperparameterTuningJobPythonPackageSample(
        project, displayName, executorImageUri, packageUri, pythonModule);
  }

  static void createHyperparameterTuningJobPythonPackageSample(
      String project,
      String displayName,
      String executorImageUri,
      String packageUri,
      String pythonModule)
      throws IOException {
    JobServiceSettings settings =
        JobServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();
    String location = "us-central1";

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (JobServiceClient client = JobServiceClient.create(settings)) {
      // study spec
      MetricSpec metric =
          MetricSpec.newBuilder().setMetricId("val_rmse").setGoal(GoalType.MINIMIZE).build();

      // decay
      DoubleValueSpec doubleValueSpec =
          DoubleValueSpec.newBuilder().setMinValue(1e-07).setMaxValue(1).build();
      ParameterSpec parameterDecaySpec =
          ParameterSpec.newBuilder()
              .setParameterId("decay")
              .setDoubleValueSpec(doubleValueSpec)
              .setScaleType(ScaleType.UNIT_LINEAR_SCALE)
              .build();
      Double[] decayValues = {32.0, 64.0};
      DiscreteValueCondition discreteValueDecay =
          DiscreteValueCondition.newBuilder().addAllValues(Arrays.asList(decayValues)).build();
      ConditionalParameterSpec conditionalParameterDecay =
          ConditionalParameterSpec.newBuilder()
              .setParameterSpec(parameterDecaySpec)
              .setParentDiscreteValues(discreteValueDecay)
              .build();

      // learning rate
      ParameterSpec parameterLearningSpec =
          ParameterSpec.newBuilder()
              .setParameterId("learning_rate")
              .setDoubleValueSpec(doubleValueSpec) // Use the same min/max as for decay
              .setScaleType(ScaleType.UNIT_LINEAR_SCALE)
              .build();

      Double[] learningRateValues = {4.0, 8.0, 16.0};
      DiscreteValueCondition discreteValueLearning =
          DiscreteValueCondition.newBuilder()
              .addAllValues(Arrays.asList(learningRateValues))
              .build();
      ConditionalParameterSpec conditionalParameterLearning =
          ConditionalParameterSpec.newBuilder()
              .setParameterSpec(parameterLearningSpec)
              .setParentDiscreteValues(discreteValueLearning)
              .build();

      // batch size
      Double[] batchSizeValues = {4.0, 8.0, 16.0, 32.0, 64.0, 128.0};

      DiscreteValueSpec discreteValueSpec =
          DiscreteValueSpec.newBuilder().addAllValues(Arrays.asList(batchSizeValues)).build();
      ParameterSpec parameter =
          ParameterSpec.newBuilder()
              .setParameterId("batch_size")
              .setDiscreteValueSpec(discreteValueSpec)
              .setScaleType(ScaleType.UNIT_LINEAR_SCALE)
              .addConditionalParameterSpecs(conditionalParameterDecay)
              .addConditionalParameterSpecs(conditionalParameterLearning)
              .build();

      // trial_job_spec
      MachineSpec machineSpec =
          MachineSpec.newBuilder()
              .setMachineType("n1-standard-4")
              .setAcceleratorType(AcceleratorType.NVIDIA_TESLA_T4)
              .setAcceleratorCount(1)
              .build();

      PythonPackageSpec pythonPackageSpec =
          PythonPackageSpec.newBuilder()
              .setExecutorImageUri(executorImageUri)
              .addPackageUris(packageUri)
              .setPythonModule(pythonModule)
              .build();

      WorkerPoolSpec workerPoolSpec =
          WorkerPoolSpec.newBuilder()
              .setMachineSpec(machineSpec)
              .setReplicaCount(1)
              .setPythonPackageSpec(pythonPackageSpec)
              .build();

      StudySpec studySpec =
          StudySpec.newBuilder()
              .addMetrics(metric)
              .addParameters(parameter)
              .setAlgorithm(StudySpec.Algorithm.RANDOM_SEARCH)
              .build();
      CustomJobSpec trialJobSpec =
          CustomJobSpec.newBuilder().addWorkerPoolSpecs(workerPoolSpec).build();
      // hyperparameter_tuning_job
      HyperparameterTuningJob hyperparameterTuningJob =
          HyperparameterTuningJob.newBuilder()
              .setDisplayName(displayName)
              .setMaxTrialCount(4)
              .setParallelTrialCount(2)
              .setStudySpec(studySpec)
              .setTrialJobSpec(trialJobSpec)
              .build();
      LocationName parent = LocationName.of(project, location);
      HyperparameterTuningJob response =
          client.createHyperparameterTuningJob(parent, hyperparameterTuningJob);
      System.out.format("response: %s\n", response);
      System.out.format("Name: %s\n", response.getName());
    }
  }
}

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 

from google.cloud import aiplatform

from google.cloud.aiplatform import hyperparameter_tuning as hpt


def create_hyperparameter_tuning_job_sample(
    project: str,
    location: str,
    staging_bucket: str,
    display_name: str,
    container_uri: str,
):
    aiplatform.init(project=project, location=location, staging_bucket=staging_bucket)

    worker_pool_specs = [
        {
            "machine_spec": {
                "machine_type": "n1-standard-4",
                "accelerator_type": "NVIDIA_TESLA_K80",
                "accelerator_count": 1,
            },
            "replica_count": 1,
            "container_spec": {
                "image_uri": container_uri,
                "command": [],
                "args": [],
            },
        }
    ]

    custom_job = aiplatform.CustomJob(
        display_name='custom_job',
        worker_pool_specs=worker_pool_specs,
    )

    hpt_job = aiplatform.HyperparameterTuningJob(
        display_name=display_name,
        custom_job=custom_job,
        metric_spec={
            'loss': 'minimize',
        },
        parameter_spec={
            'lr': hpt.DoubleParameterSpec(min=0.001, max=0.1, scale='log'),
            'units': hpt.IntegerParameterSpec(min=4, max=128, scale='linear'),
            'activation': hpt.CategoricalParameterSpec(values=['relu', 'selu']),
            'batch_size': hpt.DiscreteParameterSpec(values=[128, 256], scale='linear')
        },
        max_trial_count=128,
        parallel_trial_count=8,
        labels={'my_key': 'my_value'},
    )

    hpt_job.run()

    print(hpt_job.resource_name)
    return hpt_job

Configurazione del job di addestramento degli iperparametri

I job di ottimizzazione degli iperparametri cercano la migliore combinazione di iperparametri per ottimizzare le metriche. I job di ottimizzazione degli iperparametri eseguono più prove dell'applicazione di addestramento con diversi set di iperparametri.

Quando configuri un job di ottimizzazione degli iperparametri, devi specificare i seguenti dettagli:

Limita il numero di prove

Decidi quante prove vuoi consentire al servizio di eseguire e imposta il valore maxTrialCount nell'oggetto HyperparameterTuningJob.

Quando decidi quante prove consentire, devi tenere conto di due interessi in competizione:

  • tempo (e quindi costi)
  • accuracy

L'aumento del numero di prove generalmente dà risultati migliori, ma non sempre è così. In genere, c'è un punto in cui i risultati diminuiscono dopo il quale ulteriori prove hanno poco o nessun effetto sulla precisione. Prima di avviare un compito con un numero elevato di prove, ti consigliamo di iniziare con un numero ridotto di prove per valutare l'effetto degli iperparametri scelti sull'accuratezza del modello.

Per ottenere il massimo dall'ottimizzazione degli iperparametri, non devi impostare un valore massimo inferiore a dieci volte il numero di iperparametri utilizzati.

Prove parallele

Puoi specificare il numero di prove che possono essere eseguite in parallelo impostandoparallelTrialCount in HyperparameterTuningJob.

L'esecuzione di prove parallele ha il vantaggio di ridurre il tempo necessario per il job di addestramento (in tempo reale, il tempo di elaborazione totale richiesto in genere non cambia). Tuttavia, l'esecuzione in parallelo può ridurre l'efficacia complessiva del job di ottimizzazione. Questo perché l'ottimizzazione degli iperparametri utilizza i risultati delle prove precedenti per determinare i valori da assegnare agli iperparametri delle prove successive. Quando vengono eseguite in parallelo, alcune prove iniziano senza usufruire dei risultati delle prove ancora in esecuzione.

Se utilizzi prove parallele, il servizio di ottimizzazione degli iperparametri prevede più cluster di elaborazione dell'addestramento (o più singole macchine nel caso di un trainer a processo singolo). La specifica del pool di lavoro impostata per il job viene utilizzata per ogni singolo cluster di addestramento.

Gestire le prove non riuscite

Se le prove di ottimizzazione degli iperparametri terminano con errori, ti consigliamo di terminare il job di addestramento in anticipo. Imposta il campo maxFailedTrialCount in HyperparameterTuningJob sul numero di prove non riuscite che vuoi consentire. Dopo questo numero di tentativi non riusciti, Vertex AI termina il job di addestramento. Il valore maxFailedTrialCount deve essere minore o uguale a maxTrialCount.

Se non imposti maxFailedTrialCount o lo imposti su 0, Vertex AI utilizza le seguenti regole per gestire i trial non riusciti:

  • Se il primo tentativo del job non va a buon fine, Vertex AI lo termina immediatamente. Un errore durante la prima prova suggerisce un problema nel codice di addestramento, pertanto è probabile che anche le prove successive non vadano a buon fine. La terminazione del job consente di diagnosticare il problema senza attendere ulteriori prove e senza costi aggiuntivi.
  • Se il primo tentativo va a buon fine, Vertex AI potrebbe terminare il job dopo i fallimenti durante i tentativi successivi in base a uno dei seguenti criteri:
    • Il numero di prove non riuscite è aumentato troppo.
    • Il rapporto tra prove non riuscite e prove riuscite è diventato troppo elevato.

Queste regole sono soggette a modifica. Per garantire un comportamento specifico, imposta il campo maxFailedTrialCount.

Gestire i job di ottimizzazione degli iperparametri

Le sezioni seguenti descrivono come gestire i job di ottimizzazione degli iperparametri.

Recuperare informazioni su un job di ottimizzazione iperparametri

I seguenti esempi di codice mostrano come recuperare un job di ottimizzazione degli iperparametri.

gcloud

Utilizza il comando gcloud ai hp-tuning-jobs describe:

gcloud ai hp-tuning-jobs describe ID_OR_NAME \
    --region=LOCATION

Sostituisci quanto segue:

  • ID_OR_NAME: il nome o l'ID numerico del HyperparameterTuningJob. L'ID è l'ultima parte del nome.

    Potresti aver visto l'ID o il nome quando hai creato il HyperparameterTuningJob. Se non conosci l'ID o il nome, puoi eseguire il comando gcloud ai hp-tuning-jobs list e cercare la risorsa appropriata.

  • LOCATION: la regione in cui è stato creato HyperparameterTuningJob.

REST

Utilizza il seguente esempio di codice per recuperare un job di ottimizzazione degli iperparametri utilizzando il metodo get della risorsa hyperparameterTuningJob.

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

  • LOCATION: la regione in cui è stato creato HyperparameterTuningJob.
  • NAME: il nome del job di ottimizzazione degli iperparametri. Il nome del job utilizza il seguente formato projects/{project}/LOCATIONS/{LOCATION}/hyperparameterTuningJobs/{hyperparameterTuningJob}.

Metodo HTTP e URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1/NAME

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/12345/LOCATIONs/us-central1/hyperparameterTuningJobs/6789",
  "displayName": "my-hyperparameter-tuning-job",
  "studySpec": {
    "metrics": [
      {
        "metricId": "my_metric",
        "goal": "MINIMIZE"
      }
    ],
    "parameters": [
      {
        "parameterId": "my_parameter",
        "doubleValueSpec": {
          "minValue": 1e-05,
          "maxValue": 1
        }
      }
    ]
  },
  "maxTrialCount": 3,
  "parallelTrialCount": 1,
  "trialJobSpec": {
    "workerPoolSpecs": [
      {
        "machineSpec": {
          "machineType": "n1-standard-4"
        },
        "replicaCount": "1",
        "pythonPackageSpec": {
          "executorImageUri": "us-docker.pkg.dev/vertex-ai/training/training-tf-cpu.2-1:latest",
          "packageUris": [
            "gs://my-bucket/my-training-application/trainer.tar.bz2"
          ],
          "pythonModule": "my-trainer.trainer"
        }
      }
    ]
  },
  "trials": [
    {
      "id": "2",
      "state": "SUCCEEDED",
      "parameters": [
        {
          "parameterId": "my_parameter",
          "value": 0.71426874725564571
        }
      ],
      "finalMeasurement": {
        "stepCount": "2",
        "metrics": [
          {
            "metricId": "my_metric",
            "value": 0.30007445812225342
          }
        ]
      },
      "startTime": "2020-09-09T23:39:15.549112551Z",
      "endTime": "2020-09-09T23:47:08Z"
    },
    {
      "id": "3",
      "state": "SUCCEEDED",
      "parameters": [
        {
          "parameterId": "my_parameter",
          "value": 0.3078893356622992
        }
      ],
      "finalMeasurement": {
        "stepCount": "2",
        "metrics": [
          {
            "metricId": "my_metric",
            "value": 0.30000102519989014
          }
        ]
      },
      "startTime": "2020-09-09T23:49:22.451699360Z",
      "endTime": "2020-09-09T23:57:15Z"
    },
    {
      "id": "1",
      "state": "SUCCEEDED",
      "parameters": [
        {
          "parameterId": "my_parameter",
          "value": 0.500005
        }
      ],
      "finalMeasurement": {
        "stepCount": "2",
        "metrics": [
          {
            "metricId": "my_metric",
            "value": 0.30005377531051636
          }
        ]
      },
      "startTime": "2020-09-09T23:23:12.283374629Z",
      "endTime": "2020-09-09T23:36:56Z"
    }
  ],
  "state": "JOB_STATE_SUCCEEDED",
  "createTime": "2020-09-09T23:22:31.777386Z",
  "startTime": "2020-09-09T23:22:34Z",
  "endTime": "2020-09-10T01:31:24.271307Z",
  "updateTime": "2020-09-10T01:31:24.271307Z"
}

Java

Prima di provare questo esempio, segui le istruzioni di configurazione Java riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java di Vertex AI.

Per autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

import com.google.cloud.aiplatform.v1.HyperparameterTuningJob;
import com.google.cloud.aiplatform.v1.HyperparameterTuningJobName;
import com.google.cloud.aiplatform.v1.JobServiceClient;
import com.google.cloud.aiplatform.v1.JobServiceSettings;
import java.io.IOException;

public class GetHyperparameterTuningJobSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "PROJECT";
    String hyperparameterTuningJobId = "HYPERPARAMETER_TUNING_JOB_ID";
    getHyperparameterTuningJobSample(project, hyperparameterTuningJobId);
  }

  static void getHyperparameterTuningJobSample(String project, String hyperparameterTuningJobId)
      throws IOException {
    JobServiceSettings settings =
        JobServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();
    String location = "us-central1";

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (JobServiceClient client = JobServiceClient.create(settings)) {
      HyperparameterTuningJobName name =
          HyperparameterTuningJobName.of(project, location, hyperparameterTuningJobId);
      HyperparameterTuningJob response = client.getHyperparameterTuningJob(name);
      System.out.format("response: %s\n", response);
    }
  }
}

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 

# Copyright 2022 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

from google.cloud import aiplatform


def get_hyperparameter_tuning_job_sample(
    project: str,
    hyperparameter_tuning_job_id: str,
    location: str = "us-central1",
):

    aiplatform.init(project=project, location=location)

    hpt_job = aiplatform.HyperparameterTuningJob.get(
        resource_name=hyperparameter_tuning_job_id,
    )

    return hpt_job

Annullamento di un job di ottimizzazione iperparametri

I seguenti esempi di codice mostrano come annullare un job di ottimizzazione degli iperparametri.

gcloud

Utilizza il comando gcloud ai hp-tuning-jobs cancel:

gcloud ai hp-tuning-jobs cancel ID_OR_NAME \
    --region=LOCATION

Sostituisci quanto segue:

  • ID_OR_NAME: il nome o l'ID numerico del HyperparameterTuningJob. L'ID è l'ultima parte del nome.

    Potresti aver visto l'ID o il nome quando hai creato il HyperparameterTuningJob. Se non conosci l'ID o il nome, puoi eseguire il comando gcloud ai hp-tuning-jobs list e cercare la risorsa appropriata.

  • LOCATION: la regione in cui è stato creato HyperparameterTuningJob.

REST

Utilizza il seguente esempio di codice per annullare un job di ottimizzazione degli iperparametri utilizzando il metodo cancel della risorsa hyperparameterTuningJob.

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

  • LOCATION: la regione in cui è stato creato HyperparameterTuningJob.
  • NAME: il nome del job di ottimizzazione degli iperparametri. Il nome del job utilizza il seguente formato projects/{project}/locations/{location}/hyperparameterTuningJobs/{hyperparameterTuningJob}.

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/NAME:cancel

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere un codice di stato di operazione riuscita (2xx) e una risposta vuota.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 

from google.cloud import aiplatform


def cancel_hyperparameter_tuning_job_sample(
    project: str,
    hyperparameter_tuning_job_id: str,
    location: str = "us-central1",
):

    aiplatform.init(project=project, location=location)

    hpt_job = aiplatform.HyperparameterTuningJob.get(
        resource_name=hyperparameter_tuning_job_id,
    )

    hpt_job.cancel()

Eliminazione di un job di ottimizzazione iperparametri

I seguenti esempi di codice mostrano come eliminare un job di ottimizzazione degli iperparametri utilizzando l'SDK Vertex AI per Python e l'API REST.

REST

Utilizza il seguente esempio di codice per eliminare un job di ottimizzazione degli iperparametri utilizzando il metodo delete della risorsa hyperparameterTuningJob.

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

  • LOCATION: la tua regione.
  • NAME: il nome del job di ottimizzazione degli iperparametri. Il nome del job utilizza il seguente formato projects/{project}/LOCATIONs/{LOCATION}/hyperparameterTuningJobs/{hyperparameterTuningJob}.

Metodo HTTP e URL: 

DELETE https://LOCATION-aiplatform.googleapis.com/v1/NAME

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere un codice di stato di operazione riuscita (2xx) e una risposta vuota.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 

from google.cloud import aiplatform


def delete_hyperparameter_tuning_job_sample(
    project: str,
    hyperparameter_tuning_job_id: str,
    location: str = "us-central1",
):

    aiplatform.init(project=project, location=location)

    hpt_job = aiplatform.HyperparameterTuningJob.get(
        resource_name=hyperparameter_tuning_job_id,
    )

    hpt_job.delete()

Passaggi successivi