Criar um job de ajuste de hiperparâmetros

Os hiperparâmetros são variáveis que controlam o processo de treinamento de um modelo, como tamanho do lote ou número de camadas ocultas em uma rede neural profunda. Os jobs de ajustes de hiperparâmetros fazem vários testes para otimizar os valores das métricas. Dessa forma, é possível encontrar a melhor combinação de valores de hiperparâmetros. As métricas são resumos de escala que você adiciona ao treinador, como a acurácia do modelo.

Saiba mais sobre o ajuste de hiperparâmetros na Vertex AI. Para ver um exemplo passo a passo, consulte o codelab: Vertex AI Ajustar parâmetros (em inglês).

Esta página mostra como:

Prepare o aplicativo de treinamento para ajuste de hiperparâmetros. Basta atualizá-lo para aceitar hiperparâmetros como argumentos de linha de comando e informar valores de métrica à Vertex AI.
Crie o job de treinamento de hiperparâmetro. Para mais informações sobre as opções de configuração, consulte Noções básicas sobre a configuração de ajuste de hiperparâmetros.

Preparar o aplicativo de treinamento

Em um job de ajuste de hiperparâmetros, a Vertex AI cria testes do job de treinamento com diferentes conjuntos de hiperparâmetros e avalia a eficácia de um teste usando métricas especificadas. A Vertex AI transmite valores de hiperparâmetros para o aplicativo de treinamento como argumentos de linha de comando. Para que a Vertex AI avalie a eficácia de um teste, o aplicativo de treinamento precisa informar as métricas à Vertex AI.

As seções a seguir descrevem o seguinte:

Como a Vertex AI transmite hiperparâmetros ao aplicativo de treinamento.
Opções para transmitir métricas do aplicativo de treinamento à Vertex AI.

Para saber mais sobre os requisitos dos aplicativos de treinamento personalizados que são executados na Vertex AI, leia Requisitos do código de treinamento.

Gerenciar os argumentos de linha de comando para os hiperparâmetros a serem ajustados

A Vertex AI define argumentos de linha de comando quando chama o aplicativo de treinamento. Use os argumentos de linha de comando em seu código:

Defina um nome para cada argumento de hiperparâmetro e analise usando o analisador de argumentos de sua preferência, como argparse. Use os mesmos nomes de argumento ao configurar o job de treinamento de hiperparâmetro.

Por exemplo, se o aplicativo de treinamento for um módulo Python chamado my_trainer e você estiver ajustando um hiperparâmetro chamado learning_rate, a Vertex AI iniciará cada avaliação com um comando como este:
```
python3 -m my_trainer --learning_rate learning-rate-in-this-trial
```
A Vertex AI determina o learning-rate-in-this-trial e o transmite usando o argumento learning_rate.
Atribua os valores dos argumentos de linha de comando aos hiperparâmetros em seu código de treinamento.

Saiba mais sobre os requisitos para analisar argumentos de linha de comando.

Informar as métricas à Vertex AI

Para informar as métricas à Vertex AI, use o pacote cloudml-hypertune do Python. Essa biblioteca fornece funções auxiliares para informar métricas à Vertex AI.

Saiba mais sobre como relatar métricas de hiperparâmetros.

Criar um job de ajuste de hiperparâmetros

Dependendo da ferramenta que você quer usar para criar um HyperparameterTuningJob, selecione uma das seguintes guias:

Console

No console do Google Cloud, não é possível criar um recurso HyperparameterTuningJob diretamente. No entanto, é possível criar um recurso TrainingPipeline que gere um HyperparameterTuningJob.

As instruções a seguir descrevem como criar um TrainingPipeline que cria um HyperparameterTuningJob e não faz mais nada. Se você quiser usar outros recursos de TrainingPipeline, como treinamento com um conjunto de dados gerenciado, leia Como criar pipelines de treinamento.

No Console do Google Cloud, na seção "Vertex AI", acesse a página Pipelines de treinamento.

Acessar pipelines de treinamento
Clique em Criar para abrir o painel Treinar novo modelo.

Observação: digite model.new em um navegador para acessar diretamente a página de criação do modelo.
Na etapa Escolher método de treinamento, especifique as seguintes configurações:
1. Na lista suspensa Conjunto de dados, selecione Nenhum conjunto de dados gerenciado.
2. Selecione Treinamento personalizado (avançado).
Clique em Continuar.
Na etapa Detalhes do modelo, escolha Treinar novo modelo ou Treinar nova versão. Se você selecionar "Treinar novo modelo", insira um nome para sua escolha, MODEL_NAME, para seu modelo. Clique em Continuar.
Na etapa Contêiner de treinamento, especifique as seguintes configurações:
1. Selecione se precisa usar um contêiner pré-criado ou um contêiner personalizado para treinamento.
2. Dependendo do que você escolher, siga um destes procedimentos:
  - Se você quiser usar um contêiner pré-criado para treinamento, forneça à Vertex AI as informações necessárias para usar o pacote de treinamento que você enviou para o Cloud Storage:
    1. Use as listas suspensas Framework do modelo e Versão do framework do modelo para especificar o contêiner pré-criado que você quer.
    2. No campo Local do pacote, especifique o URI do Cloud Storage do aplicativo de treinamento em Python que você criou e enviou. Esse arquivo geralmente termina com .tar.gz.
    3. No campo Módulo do Python, insira o nome do módulo do ponto de entrada do aplicativo de treinamento.
  - Se você quiser usar um contêiner personalizado para treinamento, no campo Imagem do contêiner, especifique o URI do Artifact Registry ou do Docker Hub da imagem do seu contêiner.
3. No campo Diretório de saída do modelo, especifique o URI do Cloud Storage de um diretório em um bucket a que você tenha acesso. O conjunto de dados ainda não precisa existir.
  
  Esse valor é transmitido à Vertex AI no campo da API baseOutputDirectory, que define várias variáveis de ambiente que o aplicativo de treinamento pode acessar quando é executado.
4. Opcional: no campo Arguments, é possível especificar argumentos para que a Vertex AI use quando começar a executar seu código de treinamento. O tamanho máximo de todos os argumentos combinados é de 100.000 caracteres. O comportamento desses argumentos varia de acordo com o tipo de contêiner que você está usando:
  - Se você estiver usando um contêiner pré-criado, a Vertex AI transmitirá os argumentos como sinalizações de linha de comando ao módulo Python.
  - Se você estiver usando um contêiner personalizado, a Vertex AI substituirá a instrução CMD do contêiner pelos argumentos.
Clique em Continuar.
Na etapa Ajuste de hiperparâmetro, marque a caixa de seleção Ativar ajuste de hiperparâmetro e especifique as seguintes configurações:
1. Na seção Novo hiperparâmetro, especifique o Nome do parâmetro e o Tipo de um hiperparâmetro que você quer ajustar. Dependendo do tipo especificado, defina as configurações de hiperparâmetros adicionais que aparecem.
  
  Saiba mais sobre os tipos de hiperparâmetros e as configurações deles.
2. Se você quiser ajustar mais de um hiperparâmetro, clique em Adicionar novo parâmetro e repita a etapa anterior na nova seção exibida.
  
  Repita esse procedimento para cada hiperparâmetro que você quer ajustar.
3. NoMétrica a ser otimizada e o campoMeta lista suspensa, especifique o nome e a metamétrica que você quer otimizar para criar um anexo da VLAN de monitoramento.
4. No campo Número máximo de testes, especifique o número máximo de testes que você quer que a Vertex AI execute no job de ajuste de hiperparâmetro.
5. No campo Número máximo de testes em paralelo, especifique o número máximo de testes que a Vertex AI pode executar ao mesmo tempo.
6. Na lista suspensa Algoritmo de pesquisa, especifique um algoritmo de pesquisa para ser usado pela Vertex AI.
7. Ignore a opção Ativar parada antecipada, que não tem nenhum efeito.
Clique em Continuar.
Na etapa Computação e preços, especifique as seguintes configurações:
1. Na lista suspensa Região, selecione uma região compatível com o treinamento personalizado.
2. Na seção Pool de worker 0, especifique recursos de computação que serão usados no treinamento.
  
  Se você especificar aceleradores, verifique se o tipo de acelerador escolhido está disponível na região selecionada.
  
  Se você quiser executar o treinamento distribuído, clique em Adicionar mais pools de workers e especifique um conjunto adicional de recursos de computação para cada um deles. que você quiser.
Clique em Continuar.
Na etapa Contêiner de previsão, selecione Nenhum contêiner de previsão.
Clique em Iniciar treinamento.

gcloud

As etapas a seguir mostram como usar a CLI do Google Cloud para criar um HyperparameterTuningJob com uma configuração relativamente mínima. Para saber mais sobre todas as opções de configuração que podem ser usadas nesta tarefa, consulte a documentação de referência do comando gcloud ai hp-tuning-jobs create e os recurso da API HyperparameterTuningJob.

Crie um arquivo YAML chamado config.yaml com alguns campos de API que você quer especificar para o novo 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
```
Substitua:
- METRIC_ID: o nome de uma métrica de hiperparâmetro que será otimizada. O código de treinamento precisará informar essa métrica quando executado.
- METRIC_GOAL: a meta da métrica de hiperparâmetro. Pode ser MAXIMIZE ou MINIMIZE.
- HYPERPARAMETER_ID: o nome de um hiperparâmetro que será ajustado. O código de treinamento precisa analisar uma sinalização de linha de comando com esse nome. Neste exemplo, o hiperparâmetro precisa ter valores de ponto flutuante. Saiba mais sobre outros tipos de dados de hiperparâmetros.
- DOUBLE_MIN_VALUE: o valor mínimo (um número) que você quer que a Vertex AI tente para esse hiperparâmetro.
- DOUBLE_MAX_VALUE: o valor máximo (um número) que você quer que a Vertex AI tente para esse hiperparâmetro.
- MACHINE_TYPE: o tipo de máquina que será usada no treinamento.
- CUSTOM_CONTAINER_IMAGE_URI: o URI de uma imagem de contêiner do Docker com o código de treinamento. Saiba como criar uma imagem de contêiner personalizada.
  
  Neste exemplo, é necessário usar um contêiner personalizado. Os recursos do HyperparameterTuningJob também suportam código de treinamento em uma distribuição de origem do Python em vez de um contêiner personalizado.
No mesmo diretório do arquivo config.yaml, execute o seguinte 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
```
Substitua:
- LOCATION: a região em que você quer criar o HyperparameterTuningJob. Use uma região que suporte treinamento personalizado.
- DISPLAY_NAME: um nome de exibição fácil de lembrar que você preferir para a HyperparameterTuningJob. Saiba mais sobre os requisitos de nome de recurso.
- MAX_TRIAL_COUNT: o número máximo de testes que serão executados.
- PARALLEL_TRIAL_COUNT: o número máximo de testes que serão executados em paralelo;

REST

Use o exemplo de código a seguir para criar um job de ajuste de hiperparâmetro usando o método create do recurso hyperparameterTuningJob.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

LOCATION: a região em que você quer criar o HyperparameterTuningJob. Use uma região que suporte treinamento personalizado.
PROJECT: o ID do projeto.
DISPLAY_NAME: um nome de exibição fácil de lembrar que você preferir para a HyperparameterTuningJob. Saiba mais sobre os requisitos de nome de recurso.
Especifique suas métricas:
- METRIC_ID: o nome de uma métrica de hiperparâmetro que será otimizada. O código de treinamento precisará informar essa métrica quando executado.
- METRIC_GOAL: a meta da métrica de hiperparâmetro. Pode ser MAXIMIZE ou MINIMIZE.
Especifique os hiperparâmetros:
- HYPERPARAMETER_ID: o nome de um hiperparâmetro que será ajustado. O código de treinamento precisa analisar uma sinalização de linha de comando com esse nome.
- PARAMETER_SCALE: opcional. Como o parâmetro deve ser dimensionado. Deixe indefinido para parâmetros categóricos. Pode ser UNIT_LINEAR_SCALE, UNIT_LOG_SCALE, UNIT_REVERSE_LOG_SCALE, SCALE_TYPE_UNSPECIFIED, ou .
- Se o tipo de hiperparâmetro for DOUBLE, especifique os valores mínimo (DOUBLE_MIN_VALUE) e máximo (DOUBLE_MAX_VALUE) para ele.
- Se o tipo de hiperparâmetro for INTEGER, especifique os valores mínimo (INTEGER_MIN_VALUE) e máximo (INTEGER_MAX_VALUE) para ele.
- Se o tipo desse hiperparâmetro for COTEGORICAL, especifique os valores aceitáveis (CATEGORICAL_VALUES) como uma matriz de strings.
- Se o tipo desse hiperparâmetro for DISCRETE, especifique os valores aceitáveis (DISCRETE_VALUES) como uma matriz de números.
- Especificar hiperparâmetros condicionais. Os hiperparâmetros condicionais são adicionados a um teste quando o valor do hiperparâmetro pai corresponde à condição especificada. Saiba mais sobre os hiperparâmetros condicionais.
  - CONDITIONAL_PARAMETER: o ParameterSpec do parâmetro condicional. Essa especificação inclui o nome, a escala, o intervalo de valores do parâmetro e quaisquer parâmetros condicionais que dependem desse hiperparâmetro.
  - Se o tipo do hiperparâmetro pai for INTEGER, especifique uma lista de números inteiros como INTEGERS_TO_MATCH. Se o valor do hiperparâmetro pai corresponder a um dos valores especificados, esse parâmetro condicional será adicionado ao teste.
  - Se o tipo de hiperparâmetro pai for COTEGORICAL, especifique uma lista de categorias como CATEGORIES_TO_MATCH. Se o valor do hiperparâmetro pai corresponder a um dos valores especificados, esse parâmetro condicional será adicionado ao teste.
  - Se o tipo do hiperparâmetro pai for DISCRETE, especifique uma lista de números inteiros como DISCRETE_VALUES_TO_MATCH. Se o valor do hiperparâmetro pai corresponder a um dos valores especificados, esse parâmetro condicional será adicionado ao teste.
ALGORITHM: opcional. O algoritmo de pesquisa a ser usado neste job de ajuste de hiperparâmetro. Pode ser ALGORITHM_UNSPECIFIED, GRID_SEARCH, RANDOM_SEARCH, , ou .
MAX_TRIAL_COUNT: o número máximo de testes que serão executados.
PARALLEL_TRIAL_COUNT: o número máximo de testes que serão executados em paralelo;
MAX_FAILED_TRIAL_COUNT: o número de jobs que podem falhar antes que o job de ajuste de hiperparâmetro falhe.
Defina o job de treinamento personalizado da avaliação:
- MACHINE_TYPE: o tipo de máquina que será usada no treinamento.
- ACCELERATOR_TYPE: opcional. O tipo de acelerador a ser anexado a cada teste.
- ACCELERATOR_COUNT: opcional. O número de aceleradores a serem anexados a cada teste.
- REPLICA_COUNT: o número de réplicas de worker a serem usadas em cada teste.
- Se o aplicativo de treinamento for executado em um contêiner personalizado, especifique o seguinte:
  - CUSTOM_CONTAINER_IMAGE_URI: o URI de uma imagem de contêiner do Docker com o código de treinamento. Saiba como criar uma imagem de contêiner personalizada.
  - CUSTOM_CONTAINER_COMMAND: opcional. O comando que será invocado quando o contêiner for iniciado. Esse comando substitui o ponto de entrada padrão do contêiner.
  - CUSTOM_CONTAINER_ARGS: opcional. Argumentos a serem passados ao iniciar o contêiner.
- Se o aplicativo de treinamento for um pacote Python executado em um contêiner pré-criado, especifique o seguinte:
  - PYTHON_PACKAGE_EXECUTOR_IMAGE_URI: o URI da imagem do contêiner que executa o pacote Python fornecido. Saiba mais sobre contêineres pré-criados para treinamento.
  - PYTHON_PACKAGE_URIS: o local do Cloud Storage dos arquivos do pacote do Python que são o programa de treinamento e os pacotes dependentes. O número máximo de URIs de pacote é 100.
  - PYTHON_MODULE: O nome do módulo Python que será executado após a instalação dos pacotes.
  - PYTHON_PACKAGE_ARGS: opcional. Argumentos da linha de comando a serem passados para o módulo Python.
- SERVICE_ACCOUNT: opcional. A conta de serviço que a Vertex AI usará para executar o código. Saiba mais sobre como anexar uma conta de serviço personalizada.
- TIMEOUT: opcional. O tempo máximo de execução para cada avaliação.
Especifique LABEL_NAME e LABEL_VALUE para todos os rótulos que você quiser aplicar a esse job de ajuste de hiperparâmetro.

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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/locations/LOCATION/hyperparameterTuningJobs"

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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/locations/LOCATION/hyperparameterTuningJobs" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

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

Antes de testar esse exemplo, siga as instruções de configuração para Java no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Java.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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_K80)
              .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

Para saber como instalar ou atualizar o Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da 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

Configuração do job de treinamento de hiperparâmetros

Os jobs de ajuste de hiperparâmetros pesquisam a melhor combinação de hiperparâmetros para otimizar as métricas. Os jobs de ajuste de hiperparâmetros fazem isso durante a execução de vários testes do aplicativo de treinamento com diferentes conjuntos de hiperparâmetros.

Ao configurar um job de ajuste de hiperparâmetros, é preciso especificar os seguintes detalhes:

Os hiperparâmetros que você quer ajustar e as métricas que quer usar para avaliar testes.

Saiba mais sobre como selecionar hiperparâmetros e métricas.
Detalhes sobre o número de testes a serem executados como parte desse job de ajuste, como o seguinte:
Detalhes sobre o job de treinamento personalizado que é executado para cada teste, por exemplo:
- O tipo de máquina em que os jobs de teste são executados e os aceleradores que o job usa.
  
  Observação: atualmente, a Vertex AI não é compatível com jobs de ajuste de hiperparâmetros que exigem TPUs.
- Os detalhes do contêiner personalizado ou do job de pacote do Python.
  
  Saiba mais sobre os requisitos do código de treinamento.

Limitar o número de testes

Decida quantos testes o serviço poderá executar e defina o valor de maxTrialCount no objeto HyperparameterTuningJob.

Ao decidir o número permitido de testes, você deverá pensar em dois interesses conflitantes:

tempo (e, portanto, custo)
precisão

Aumentar o número de testes geralmente produz melhores resultados, mas nem sempre é assim. Normalmente, há um ponto de as retornos decrescentes após os quais os outros testes têm pouco ou nenhum efeito sobre a precisão. Antes de iniciar um job com um grande número de testes, convém começar com um pequeno número de testes para avaliar o efeito dos hiperparâmetros escolhidos na precisão do modelo.

Para aproveitar ao máximo o ajuste de hiperparâmetro, o valor máximo não pode ser inferior a 10 vezes o número de hiperparâmetros utilizados.

Testes paralelos

É possível especificar quantos testes podem ser executados em paralelo definindo parallelTrialCount no HyperparameterTuningJob.

A execução de testes em paralelo tem a vantagem de reduzir a duração do job de treinamento (tempo real, o tempo de processamento necessário total geralmente não é alterado). No entanto, a execução em paralelo pode reduzir a eficácia do job de ajuste em geral. Isso ocorre porque o ajuste de hiperparâmetro usa os resultados de testes anteriores para informar os valores a serem atribuídos aos hiperparâmetros de testes subsequentes. Quando executados em paralelo, alguns testes são iniciados sem a vantagem de usar os resultados dos testes ainda em execução.

Quando você usa testes em paralelo, o ajuste de hiperparâmetros provisiona vários clusters de processamento de treinamento (ou várias máquinas individuais, no caso de um treinador de processo único). A especificação do pool de trabalho que você define para o job é usada para cada cluster de treinamento individual.

Processar testes com falha

Se os testes de ajuste de hiperparâmetro forem encerrados com erros, convém encerrar o job de treinamento antecipadamente. Defina o campo maxFailedTrialCount no HyperparameterTuningJob como o número de testes com falha que você quer permitir. Após esse número de falhas, a Vertex AI encerra o job de treinamento. O valor de maxFailedTrialCount precisa ser menor ou igual ao de maxTrialCount.

Se você não definir maxFailedTrialCount, ou se definir como 0, a Vertex AI usará as regras a seguir para lidar com testes com falha:

Se o primeiro teste do job falhar, a Vertex AI encerra o job imediatamente. A falha durante o primeiro teste sugere um problema no código de treinamento. Portanto, outros testes provavelmente também falharão. O encerramento do job permite diagnosticar o problema sem esperar outros testes e gerar custos maiores.
Se o primeiro teste for bem-sucedido, a Vertex AI talvez encerre o job após falhas durante testes subsequentes com base em um dos critérios a seguir:
- O número de testes com falha aumentou muito.
- A proporção entre testes com falha e testes bem-sucedidos aumentou muito.

Essas regras estão sujeitas a alterações. Para garantir um comportamento específico, defina o campo maxFailedTrialCount.

Gerenciar jobs de ajustes de hiperparâmetros

As seções a seguir descrevem como gerenciar os jobs de ajuste de hiperparâmetros.

Recuperar informações sobre um job de ajuste de hiperparâmetros

Os exemplos de código a seguir demonstram como recuperar um job de ajuste de hiperparâmetros.

gcloud

Use o comando gcloud ai hp-tuning-jobs describe:

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

Substitua:

ID_OR_NAME: o nome ou o ID numérico do HyperparameterTuningJob. O código é a última parte do nome.

Talvez você tenha visto o ID ou nome quando criou o HyperparameterTuningJob. Se você não souber o ID ou o nome, execute o comando gcloud ai hp-tuning-jobs list e procure o recurso apropriado.
LOCATION: a região em que HyperparameterTuningJob foi criado.

REST

Use o exemplo de código a seguir para recuperar um job de ajuste de hiperparâmetro usando o método get do recurso hyperparameterTuningJob.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

LOCATION: a região em que HyperparameterTuningJob foi criado.
NAME: o nome do job de ajuste de hiperparâmetro. O nome do job usa o seguinte formato projects/{project}/LOCATIONS/{LOCATION}/hyperparameterTuningJobs/{hyperparameterTuningJob}.

Método HTTP e URL:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

execute o seguinte comando:

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

PowerShell (Windows)

execute o seguinte comando:

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/NAME" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

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

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Para saber como instalar ou atualizar o Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da 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

Cancelar um job de ajuste de hiperparâmetros

Os exemplos de código a seguir demonstram como cancelar um job de ajuste de hiperparâmetros.

gcloud

Use o comando gcloud ai hp-tuning-jobs cancel:

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

Substitua:

ID_OR_NAME: o nome ou o ID numérico do HyperparameterTuningJob. O código é a última parte do nome.

Talvez você tenha visto o ID ou nome quando criou o HyperparameterTuningJob. Se você não souber o ID ou o nome, execute o comando gcloud ai hp-tuning-jobs list e procure o recurso apropriado.
LOCATION: a região em que HyperparameterTuningJob foi criado.

REST

Use o exemplo de código a seguir para cancelar um job de ajuste de hiperparâmetro usando o método cancel do recurso hyperparameterTuningJob.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

LOCATION: a região em que HyperparameterTuningJob foi criado.
NAME: o nome do job de ajuste de hiperparâmetro. O nome do job usa o seguinte formato projects/{project}/locations/{location}/hyperparameterTuningJobs/{hyperparameterTuningJob}.

Método HTTP e URL:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

execute o seguinte comando:

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

PowerShell (Windows)

execute o seguinte comando:

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/NAME:cancel" | Select-Object -Expand Content

Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

Python

Para saber como instalar ou atualizar o Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da 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()

Excluir um job de ajuste de hiperparâmetros

Nos exemplos de código a seguir, demonstramos como excluir um job de ajuste de hiperparâmetro usando o Vertex AI SDK para Python e a API REST.

REST

Use o exemplo de código a seguir para excluir um job de ajuste de hiperparâmetro usando o método delete do recurso hyperparameterTuningJob.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

LOCATION: Sua região.
NAME: o nome do job de ajuste de hiperparâmetro. O nome do job usa o seguinte formato projects/{project}/LOCATIONs/{LOCATION}/hyperparameterTuningJobs/{hyperparameterTuningJob}.

Método HTTP e URL:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

execute o seguinte comando:

curl -X DELETE \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://LOCATION-aiplatform.googleapis.com/v1/NAME"

PowerShell (Windows)

execute o seguinte comando:

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

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/NAME" | Select-Object -Expand Content

Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

Python

Para saber como instalar ou atualizar o Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da 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()

A seguir

Saiba mais sobre os conceitos envolvidos no ajuste de hiperparâmetro.

Criar um job de ajuste de hiperparâmetros

Preparar o aplicativo de treinamento

Gerenciar os argumentos de linha de comando para os hiperparâmetros a serem ajustados

Informar as métricas à Vertex AI

Criar um job de ajuste de hiperparâmetros

Console

gcloud

config.yaml

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Java

Python

Configuração do job de treinamento de hiperparâmetros

Limitar o número de testes

Testes paralelos

Processar testes com falha

Gerenciar jobs de ajustes de hiperparâmetros

Recuperar informações sobre um job de ajuste de hiperparâmetros

gcloud

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Java

Python

Cancelar um job de ajuste de hiperparâmetros

gcloud

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Python

Excluir um job de ajuste de hiperparâmetros

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Python

A seguir

`config.yaml`