ハイパーパラメータ調整を使用する

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

ハイパーパラメータは、バッチサイズ、ディープ ニューラル ネットワークの非表示レイヤの数など、モデルのトレーニング プロセスを管理する変数です。ハイパーパラメータ調整は、トライアル全体で指標の値を最適化して、ハイパーパラメータ値の最適な組み合わせを検出するものです。指標とは、モデルの正確性など、トレーナーに追加するスカラー サマリーです。

詳しくは、Vertex AI でのハイパーパラメータ調整をご覧ください。具体的な例については、Vertex AI: ハイパーパラメータ調整の Codelab をご覧ください。

このページでは、次の方法について説明します。

トレーニング アプリケーションを準備する

ハイパーパラメータ調整ジョブでは、Vertex AI はさまざまなハイパーパラメータ セットを使用してトレーニング ジョブのトライアルを作成し、指定された指標を使用してトライアルの有効性を評価します。Vertex AI は、ハイパーパラメータ値をコマンドライン引数としてトレーニング アプリケーションに渡します。Vertex AI がトライアルの有効性を評価するには、トレーニング アプリケーションが Vertex AI に指標を報告する必要があります。

以降のセクションでは、次のことを説明します。

  • Vertex AI がハイパーパラメータをトレーニング アプリケーションに渡す方法。
  • トレーニング アプリケーションから Vertex AI に指標を渡すオプション。

Vertex AI で実行されるカスタム トレーニング アプリケーションの要件の詳細については、トレーニング コードの要件をご覧ください。

調整するハイパーパラメータのコマンドライン引数の処理

Vertex AI は、トレーニング アプリケーションを呼び出すときにコマンドライン引数を設定します。次のようにコードでコマンドライン引数を使用します。

  1. 各ハイパーパラメータ引数の名前を定義し、任意の引数パーザー(argparse)を使用して解析します。ハイパーパラメータ トレーニング ジョブの構成で指定した引数名を使用します。

    たとえば、トレーニング アプリケーションが my_trainer という名前の Python モジュールで、learning_rate という名前のハイパーパラメータを調整している場合、Vertex AI は次のようなコマンドで各トライアルを開始します。

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

    Vertex AI は learning-rate-in-this-trial を特定し、learning_rate 引数を使用して渡します。

  2. コマンドライン引数の値をトレーニング コードのハイパーパラメータに割り当てます。

詳しくは、コマンドライン引数の解析に関する要件をご覧ください。

Vertex AI に指標を報告する

Vertex AI に指標を報告するには、cloudml-hypertune Python パッケージを使用します。このライブラリは、指標を Vertex AI に報告するためのヘルパー関数を提供します。

詳しくは、ハイパーパラメータ指標の報告方法をご覧ください。

ハイパーパラメータ調整ジョブを作成する

HyperparameterTuningJob の作成に使用するツールに応じて、次のいずれかのタブを選択してください。

Console

Google Cloud Console で HyperparameterTuningJob リソースを直接作成することはできません。ただし、HyperparameterTuningJob を作成する TrainingPipeline リソースを作成することは可能です。

次の手順では、HyperparameterTuningJob を作成する TrainingPipeline を作成し、他の処理は行いません。マネージド データセットを使用したトレーニングなど、追加の TrainingPipeline 機能を使用する場合は、トレーニング パイプラインの作成をご覧ください。

  1. コンソールの Vertex AI セクションで、[トレーニング パイプライン] ページに移動します。

    [トレーニング パイプライン] に移動

  2. [作成] をクリックして、[新しいモデルのトレーニング] ペインを開きます。

  3. トレーニング方法のステップで、次の設定を指定します。

    1. [データセット] プルダウン リストで、[管理されているデータセットなし] を選択します。

    2. [カスタム トレーニング(上級者向け)] を選択します。

    [続行] をクリックします。

  4. [モデルの詳細] ステップで、[新しいモデルをトレーニング] または [新しいバージョンをトレーニング] を選択します。新しいモデルをトレーニングする場合は、モデルに任意の名前(MODEL_NAME)を入力します。[続行] をクリックします。

  5. [トレーニング コンテナ] ステップで、次の設定を指定します。

    1. トレーニングにビルド済みのコンテナカスタム コンテナのどちらを使用するかを選択します。

    2. 選択した内容に応じて、次のいずれかを行います。

    3. [Model output directory] フィールドに、アクセス権があるバケット内のディレクトリの Cloud Storage URI を指定できます。そのディレクトリがまだ存在していなくてもかまいません。

      この値は、Vertex AI の baseOutputDirectory API フィールドに渡されます。この値に基づいて、トレーニング アプリケーションが実行時にアクセスする複数の環境変数が設定されます。

    4. 省略可: [引数] フィールドに、Vertex AI がトレーニング コードの実行開始時に使用する引数を指定できます。すべての引数の合計長は 100,000 文字以下にする必要があります。これらの引数の動作は、使用しているコンテナの種類によって異なります。

      • ビルド済みのコンテナを使用する場合、Vertex AI は引数をコマンドライン フラグとして Python モジュールに渡します。

      • カスタム コンテナを使用している場合、Vertex AI はコンテナの CMD 命令を引数でオーバーライドします。

    [続行] をクリックします。

  6. [ハイパーパラメータ] ステップで、[Enable hyperparameter tuning] チェックボックスをオンにして、次の設定を指定します。

    1. [新しいハイパーパラメータ] セクションで、調整するハイパーパラメータのパラメータ名タイプを指定します。指定したタイプに応じて、表示される追加のハイパーパラメータ設定を構成します。

      ハイパーパラメータ タイプとその構成で詳細をご覧ください。

    2. 複数のハイパーパラメータを調整する場合は、[新しいパラメータを追加] をクリックして、表示された新しいセクションで前の手順を繰り返します。

      調整するハイパーパラメータごとに上記の手順を繰り返します。

    3. [最適化する指標] フィールドと [目標] プルダウン リストに、最適化する指標の名前と目標を指定します。

    4. [最大試行数] フィールドに、Vertex AI がハイパーパラメータ調整ジョブで実行するトライアルの最大数を指定します。

    5. [並列試行の最大数] フィールドに、Vertex AI が同時に実行するトライアルの最大数を指定します。

    6. [Algorithm] プルダウン リストで、Vertex AI で使用する検索アルゴリズムを指定します。

    7. [Enable early stopping] の切り替えは無視します。これは効果がありません。

    [続行] をクリックします。

  7. [コンピューティングと料金] ステップで、次の設定を指定します。

    1. [リージョン] プルダウン リストで、カスタム トレーニングをサポートするリージョンを選択します。

    2. [Worker pool 0] セクションで、トレーニングに使用するコンピューティング リソースを指定します。

      アクセラレータを指定する場合は、選択したアクセラレータが選択したリージョンで使用できることを確認してください

      分散トレーニングを行う場合は、[ADD MORE WORKER POOLS] をクリックし、追加のワーカープールごとに追加のコンピューティング リソースのセットを指定します。

    [続行] をクリックします。

  8. [予測コンテナ] ステップで、[No prediction container] を選択します。

  9. [トレーニングを開始] をクリックして、カスタム トレーニング パイプラインを開始します。

gcloud

次の手順では、Google Cloud CLI を使用して、比較的最小限の構成で HyperparameterTuningJob を作成する方法を示します。このタスクで使用できるすべての構成オプションについては、リファレンス ドキュメントで gcloud ai hp-tuning-jobs create コマンドHyperparameterTuningJob API リソースの説明をご覧ください。

  1. 新しい HyerparameterTuningJob に指定する API フィールドを含む config.yaml という YAML ファイルを作成します。

    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
    

    次のように置き換えます。

    • METRIC_ID: 最適化するハイパーパラメータ指標の名前。トレーニング コードは、実行時にこの指標を報告する必要があります。

    • METRIC_GOAL: ハイパーパラメータ指標の目標(MAXIMIZE または MINIMIZE)。

    • HYPERPARAMETER_ID: 調整するハイパーパラメータの名前。トレーニング コードは、この名前でコマンドライン フラグを解析する必要があります。この例では、ハイパーパラメータは浮動小数点値を受け取る必要があります。他のハイパーパラメータ データ型を確認してください。

    • DOUBLE_MIN_VALUE: Vertex AI がこのハイパーパラメータを試行する最小値(数値)。

    • DOUBLE_MAX_VALUE: Vertex AI がこのハイパーパラメータを試行する最大値(数値)。

    • MACHINE_TYPE: トレーニングに使用する VM のタイプ

    • CUSTOM_CONTAINER_IMAGE_URI: トレーニング コードを含む Docker コンテナ イメージの URI。カスタム コンテナ イメージの作成方法を確認してください。

      この例では、カスタム コンテナを使用する必要があります。HyperparameterTuningJob リソースは、カスタム コンテナの代わりに Python ソース配布のトレーニング コードもサポートしています。

  2. config.yaml ファイルと同じディレクトリで、次のシェルコマンドを実行します。

    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
    

    次のように置き換えます。

REST とコマンドライン

次のコードサンプルでは、hyperparameterTuningJob リソースの create メソッドを使用してハイパーパラメータ調整ジョブを作成します。

リクエストのデータを使用する前に、次のように置き換えます。

  • LOCATION: HyperparameterTuningJob を作成するリージョン。カスタム トレーニングをサポートするリージョンを使用します。
  • PROJECT: プロジェクト ID。
  • DISPLAY_NAME: HyperparameterTuningJob の覚えやすい表示名。リソース名の要件を確認してください。
  • 次のように指標を指定します。
  • ハイパーパラメータを指定します。
    • HYPERPARAMETER_ID: 調整するハイパーパラメータの名前。トレーニング コードは、この名前でコマンドライン フラグを解析する必要があります。
    • PARAMETER_SCALE: 省略可。パラメータのスケーリング方法。CATEGORICAL パラメータには設定しないでください。UNIT_LINEAR_SCALEUNIT_LOG_SCALEUNIT_REVERSE_LOG_SCALE、または SCALE_TYPE_UNSPECIFIED のいずれかです。
    • このハイパーパラメータのタイプが DOUBLE の場合は、このハイパーパラメータの最小値(DOUBLE_MIN_VALUE)と最大値(DOUBLE_MAX_VALUE)を指定します。
    • このハイパーパラメータのタイプが INTEGER の場合は、このハイパーパラメータの最小値(INTEGER_MIN_VALUE)と最大値(INTEGER_MAX_VALUE)を指定します。
    • このハイパーパラメータのタイプが CATEGORICAL の場合は、許容値(CATEGORICAL_VALUES)を文字列の配列として指定します。
    • このハイパーパラメータのタイプが DISCRETE の場合は、許容値(DISCRETE_VALUES)を数値の配列として指定します。
    • 条件付きハイパーパラメータを指定します。親のハイパーパラメータの値が指定した条件と一致すると、条件付きハイパーパラメータがトライアルに追加されます。詳細については、条件付きハイパーパラメータをご覧ください。
      • CONDITIONAL_PARAMETER: 条件パラメータの ParameterSpec。この仕様には、パラメータの名前、スケール、値の範囲、このハイパーパラメータに依存する条件パラメータが含まれます。
      • 親ハイパーパラメータの型が INTEGER の場合は、整数のリストを INTEGERS_TO_MATCH として指定します。親ハイパーパラメータの値が指定した値のいずれかに一致すると、この条件パラメータがトライアルに追加されます。
      • 親ハイパーパラメータの型が CATEGORICAL の場合は、カテゴリのリストを CATEGORIES_TO_MATCH として指定します。親ハイパーパラメータの値が指定した値のいずれかに一致すると、この条件パラメータがトライアルに追加されます。
      • 親ハイパーパラメータの型が DISCRETE の場合は、整数のリストを DISCRETE_VALUES_TO_MATCH として指定します。親ハイパーパラメータの値が指定した値のいずれかに一致すると、この条件パラメータがトライアルに追加されます。
  • ALGORITHM: 省略可。このハイパーパラメータ調整ジョブで使用する検索アルゴリズム。ALGORITHM_UNSPECIFIEDGRID_SEARCH、または RANDOM_SEARCH のいずれかです。
  • MAX_TRIAL_COUNT: 実行するトライアルの最大数
  • PARALLEL_TRIAL_COUNT: 並行して実行するトライアルの最大数
  • MAX_FAILED_TRIAL_COUNT: ハイパーパラメータ調整ジョブが失敗する前に失敗する可能性があるジョブの数。
  • トライアルのカスタム トレーニング ジョブを定義します。
    • MACHINE_TYPE: トレーニングに使用する VM のタイプ
    • ACCELERATOR_TYPE: 省略可。各トライアルに接続するアクセラレータのタイプ。
    • ACCELERATOR_COUNT: 省略可。各トライアルに接続するアクセラレータの数。
    • REPLICA_COUNT: 各トライアルで使用するワーカー レプリカの数。
    • トレーニング アプリケーションがカスタム コンテナで実行される場合は、次のように指定します。
      • CUSTOM_CONTAINER_IMAGE_URI: トレーニング コードを含む Docker コンテナ イメージの URI。カスタム コンテナ イメージの作成方法を確認してください。
      • CUSTOM_CONTAINER_COMMAND: 省略可。コンテナの起動時に呼び出されるコマンド。このコマンドは、コンテナのデフォルトのエントリポイントをオーバーライドします。
      • CUSTOM_CONTAINER_ARGS: 省略可。コンテナの起動時に渡される引数。
    • トレーニング アプリケーションが事前ビルド済みのコンテナで実行される Python パッケージの場合は、以下を指定します。
      • PYTHON_PACKAGE_EXECUTOR_IMAGE_URI: 提供された Python パッケージを実行するコンテナ イメージの URI。詳しくは、トレーニング用の事前ビルドコンテナをご覧ください。
      • PYTHON_PACKAGE_URIS: トレーニング プログラムとその依存パッケージである Python パッケージ ファイルの Cloud Storage のロケーション。パッケージ URI の最大数は 100 です。
      • PYTHON_MODULE: パッケージのインストール後に実行する Python モジュール名。
      • PYTHON_PACKAGE_ARGS: 省略可。Python モジュールに渡すコマンドライン引数。
    • SERVICE_ACCOUNT: 省略可。Vertex AI がコードを実行するために使用するサービス アカウント。カスタム サービス アカウントの接続についての詳細。
    • TIMEOUT: 省略可。トライアルごとの最大実行時間。
  • このハイパーパラメータ調整ジョブに適用するラベルの LABEL_NAMELABEL_VALUE を指定します。

HTTP メソッドと URL:

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

JSON 本文のリクエスト:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

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

Vertex AI 用のクライアント ライブラリをインストールして使用する方法については、Vertex AI クライアント ライブラリをご覧ください。詳細については、Vertex AI Java API のリファレンス ドキュメントをご覧ください。

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

Vertex AI 用のクライアント ライブラリをインストールして使用する方法については、Vertex AI クライアント ライブラリをご覧ください。詳細については、Vertex AI Python API のリファレンス ドキュメントをご覧ください。

from google.cloud import aiplatform

def create_hyperparameter_tuning_job_python_package_sample(
    project: str,
    display_name: str,
    executor_image_uri: str,
    package_uri: str,
    python_module: str,
    location: str = "us-central1",
    api_endpoint: str = "us-central1-aiplatform.googleapis.com",
):
    # The AI Platform services require regional API endpoints.
    client_options = {"api_endpoint": api_endpoint}
    # Initialize client that will be used to create and send requests.
    # This client only needs to be created once, and can be reused for multiple requests.
    client = aiplatform.gapic.JobServiceClient(client_options=client_options)

    # study_spec
    metric = {
        "metric_id": "val_rmse",
        "goal": aiplatform.gapic.StudySpec.MetricSpec.GoalType.MINIMIZE,
    }

    conditional_parameter_decay = {
        "parameter_spec": {
            "parameter_id": "decay",
            "double_value_spec": {"min_value": 1e-07, "max_value": 1},
            "scale_type": aiplatform.gapic.StudySpec.ParameterSpec.ScaleType.UNIT_LINEAR_SCALE,
        },
        "parent_discrete_values": {"values": [32, 64]},
    }
    conditional_parameter_learning_rate = {
        "parameter_spec": {
            "parameter_id": "learning_rate",
            "double_value_spec": {"min_value": 1e-07, "max_value": 1},
            "scale_type": aiplatform.gapic.StudySpec.ParameterSpec.ScaleType.UNIT_LINEAR_SCALE,
        },
        "parent_discrete_values": {"values": [4, 8, 16]},
    }
    parameter = {
        "parameter_id": "batch_size",
        "discrete_value_spec": {"values": [4, 8, 16, 32, 64, 128]},
        "scale_type": aiplatform.gapic.StudySpec.ParameterSpec.ScaleType.UNIT_LINEAR_SCALE,
        "conditional_parameter_specs": [
            conditional_parameter_decay,
            conditional_parameter_learning_rate,
        ],
    }

    # trial_job_spec
    machine_spec = {
        "machine_type": "n1-standard-4",
        "accelerator_type": aiplatform.gapic.AcceleratorType.NVIDIA_TESLA_K80,
        "accelerator_count": 1,
    }
    worker_pool_spec = {
        "machine_spec": machine_spec,
        "replica_count": 1,
        "python_package_spec": {
            "executor_image_uri": executor_image_uri,
            "package_uris": [package_uri],
            "python_module": python_module,
            "args": [],
        },
    }

    # hyperparameter_tuning_job
    hyperparameter_tuning_job = {
        "display_name": display_name,
        "max_trial_count": 4,
        "parallel_trial_count": 2,
        "study_spec": {
            "metrics": [metric],
            "parameters": [parameter],
            "algorithm": aiplatform.gapic.StudySpec.Algorithm.RANDOM_SEARCH,
        },
        "trial_job_spec": {"worker_pool_specs": [worker_pool_spec]},
    }
    parent = f"projects/{project}/locations/{location}"
    response = client.create_hyperparameter_tuning_job(
        parent=parent, hyperparameter_tuning_job=hyperparameter_tuning_job
    )
    print("response:", response)

ハイパーパラメータ トレーニング ジョブの構成

ハイパーパラメータ調整ジョブで、ハイパーパラメータを最適化し、指標を最適化します。ハイパーパラメータ調整ジョブでは、異なるハイパーパラメータ セットを使用して、トレーニング アプリケーションのトライアルを複数回実行します。

ハイパーパラメータ調整ジョブを構成するときは、次の詳細を指定する必要があります。

トライアル数を制限する

サービスに実行を許可するトライアルの数を決めて、HyperparameterTuningJob オブジェクトに maxTrialCount 値を設定します。

許可するトライアル数を決定する際には、次の 2 つの競合する事項について考慮する必要があります。

  • 時間(結果として、費用)
  • 精度

トライアル数を増やすと一般には結果が向上しますが、常に向上するとは限りません。通常、返されるポイントが減った場合、追加のトライアルが精度に与える影響はほとんどありません。多数のトライアルでジョブを開始する前に、少数のトライアルから開始して、選択したハイパーパラメータがモデルの精度に与える効果を測定することをおすすめします。

ハイパーパラメータ調整を最大限に活用するには、設定する最大値がハイパーパラメータの数の 10 倍を下回らないようにしてください。

並列トライアル

HyperparameterTuningJobparallelTrialCount を設定することで、同時に実行できるトライアルの数を指定できます。

トライアルの並列実行には、トレーニング ジョブの所要時間を短縮できるというメリットがあります(リアルタイムの時間という意味であり、所要処理時間の合計は特に変わりません)。ただし、並列で実行すると、調整ジョブ全体の効果が減じることがあります。なぜなら、ハイパーパラメータ調整は、前のトライアルの結果を使用して、後続のトライアルのハイパーパラメータに割り当てる値を通知するからです。並列実行の場合、まだ実行中のトライアルの結果を利用できないままに開始するトライアルもでてくることになります。

トライアルを並列実行する場合、ハイパーパラメータ調整サービスは複数のトレーニング処理クラスタ(または、単一プロセス トレーナーの場合は複数のマシン)をプロビジョニングします。ジョブに設定したワーカープールの仕様は、個々のトレーニング クラスタで使用されます。

失敗したトライアルの処理

ハイパーパラメータ調整トライアルがエラーで終了する場合は、トレーニング ジョブを早期に終了できます。HyperparameterTuningJobmaxFailedTrialCount フィールドに、許可するトライアルの失敗回数を設定します。トライアルの失敗回数がこの数を超えると、Vertex AI はトレーニング ジョブを終了します。maxFailedTrialCount 値は、maxTrialCount 以下にする必要があります。

maxFailedTrialCount を設定しない場合や、0 に設定した場合、Vertex AI は次のルールに従って失敗したトライアルを処理します。

  • ジョブの最初のトライアルが失敗した場合、Vertex AI はジョブを直ちに終了します。最初のトライアルの失敗は、トレーニング コードに問題があることを示唆します。つまり、後続のトライアルも失敗する可能性があります。ジョブを直ちに終了すれば、後続のトライアルを待たずに問題の診断を行うことができ、不要なコストもかかりません。
  • 最初のトライアルが成功した場合、Vertex AI は、次のいずれかの基準に基づいて、後続のトライアルで失敗した後にジョブを終了します。
    • 失敗したトライアルの数が非常に多い。
    • 成功したトライアルに対する失敗したトライアルの比率が非常に高い。

これらのルールは変更される場合があります。特定の動作を保証するには、maxFailedTrialCount フィールドを設定してください。

ハイパーパラメータ調整ジョブの管理

以降のセクションでは、ハイパーパラメータ調整ジョブの管理方法について説明します。

ハイパーパラメータ調整ジョブに関する情報を取得する

次のコードサンプルは、ハイパーパラメータ調整ジョブの取得方法を示しています。

gcloud

gcloud ai hp-tuning-jobs describe コマンドを使用します。

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

次のように置き換えます。

  • ID_OR_NAME: 名前または HyperparameterTuningJob の数値 ID(ID は名前の最後の部分です)。

    HyperparameterTuningJob を作成したときに、ID または名前が表示されていることがあります。ID または名前がわからない場合は、gcloud ai hp-tuning-jobs list コマンドを実行して、適切なリソースを探します。

  • LOCATION: HyperparameterTuningJob が作成されたリージョン。

REST とコマンドライン

次のコードサンプルでは、hyperparameterTuningJob リソースの get メソッドを使用してハイパーパラメータ調整ジョブを取得します。

リクエストのデータを使用する前に、次のように置き換えます。

  • LOCATION: HyperparameterTuningJob が作成されたリージョン。
  • NAME: ハイパーパラメータ調整ジョブの名前。ジョブ名の形式は projects/{project}/LOCATIONS/{LOCATION}/hyperparameterTuningJobs/{hyperparameterTuningJob} です。

HTTP メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

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

Vertex AI 用のクライアント ライブラリをインストールして使用する方法については、Vertex AI クライアント ライブラリをご覧ください。詳細については、Vertex AI Java API のリファレンス ドキュメントをご覧ください。

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

Vertex AI 用のクライアント ライブラリをインストールして使用する方法については、Vertex AI クライアント ライブラリをご覧ください。詳細については、Vertex AI Python API のリファレンス ドキュメントをご覧ください。

from google.cloud import aiplatform

def get_hyperparameter_tuning_job_sample(
    project: str,
    hyperparameter_tuning_job_id: str,
    location: str = "us-central1",
    api_endpoint: str = "us-central1-aiplatform.googleapis.com",
):
    # The AI Platform services require regional API endpoints.
    client_options = {"api_endpoint": api_endpoint}
    # Initialize client that will be used to create and send requests.
    # This client only needs to be created once, and can be reused for multiple requests.
    client = aiplatform.gapic.JobServiceClient(client_options=client_options)
    name = client.hyperparameter_tuning_job_path(
        project=project,
        location=location,
        hyperparameter_tuning_job=hyperparameter_tuning_job_id,
    )
    response = client.get_hyperparameter_tuning_job(name=name)
    print("response:", response)

ハイパーパラメータ調整ジョブをキャンセルする

次のコードサンプルは、ハイパーパラメータ調整ジョブのキャンセル方法を示しています。

gcloud

gcloud ai hp-tuning-jobs cancel コマンドを使用します。

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

次のように置き換えます。

  • ID_OR_NAME: 名前または HyperparameterTuningJob の数値 ID(ID は名前の最後の部分です)。

    HyperparameterTuningJob を作成したときに、ID または名前が表示されていることがあります。ID または名前がわからない場合は、gcloud ai hp-tuning-jobs list コマンドを実行して、適切なリソースを探します。

  • LOCATION: HyperparameterTuningJob が作成されたリージョン。

REST とコマンドライン

次のコードサンプルでは、hyperparameterTuningJob リソースの cancel メソッドを使用してハイパーパラメータ調整ジョブをキャンセルします。

リクエストのデータを使用する前に、次のように置き換えます。

  • LOCATION: HyperparameterTuningJob が作成されたリージョン。
  • NAME: ハイパーパラメータ調整ジョブの名前。ジョブ名の形式は projects/{project}/locations/{location}/hyperparameterTuningJobs/{hyperparameterTuningJob} です。

HTTP メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

成功したことを示すステータス コード(2xx)と空のレスポンスが返されます。

Python

Vertex AI 用のクライアント ライブラリをインストールして使用する方法については、Vertex AI クライアント ライブラリをご覧ください。詳細については、Vertex AI Python API のリファレンス ドキュメントをご覧ください。

from google.cloud import aiplatform

def cancel_hyperparameter_tuning_job_sample(
    project: str,
    hyperparameter_tuning_job_id: str,
    location: str = "us-central1",
    api_endpoint: str = "us-central1-aiplatform.googleapis.com",
):
    # The AI Platform services require regional API endpoints.
    client_options = {"api_endpoint": api_endpoint}
    # Initialize client that will be used to create and send requests.
    # This client only needs to be created once, and can be reused for multiple requests.
    client = aiplatform.gapic.JobServiceClient(client_options=client_options)
    name = client.hyperparameter_tuning_job_path(
        project=project,
        location=location,
        hyperparameter_tuning_job=hyperparameter_tuning_job_id,
    )
    response = client.cancel_hyperparameter_tuning_job(name=name)
    print("response:", response)

ハイパーパラメータ調整ジョブを削除する

次のコードサンプルでは、Vertex AI SDK for Python と REST API を使用してハイパーパラメータ調整ジョブを削除する方法を示します。

REST とコマンドライン

次のコードサンプルでは、hyperparameterTuningJob リソースの delete メソッドを使用してハイパーパラメータ調整ジョブを削除します。

リクエストのデータを使用する前に、次のように置き換えます。

  • LOCATION: 使用するリージョン。
  • NAME: ハイパーパラメータ調整ジョブの名前。ジョブ名の形式は projects/{project}/LOCATIONs/{LOCATION}/hyperparameterTuningJobs/{hyperparameterTuningJob} です。

HTTP メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

成功したことを示すステータス コード(2xx)と空のレスポンスが返されます。

Python

Vertex AI 用のクライアント ライブラリをインストールして使用する方法については、Vertex AI クライアント ライブラリをご覧ください。詳細については、Vertex AI Python API のリファレンス ドキュメントをご覧ください。

from google.cloud import aiplatform

def delete_hyperparameter_tuning_job_sample(
    project: str,
    hyperparameter_tuning_job_id: str,
    location: str = "us-central1",
    api_endpoint: str = "us-central1-aiplatform.googleapis.com",
    timeout: int = 300,
):
    # The AI Platform services require regional API endpoints.
    client_options = {"api_endpoint": api_endpoint}
    # Initialize client that will be used to create and send requests.
    # This client only needs to be created once, and can be reused for multiple requests.
    client = aiplatform.gapic.JobServiceClient(client_options=client_options)
    name = client.hyperparameter_tuning_job_path(
        project=project,
        location=location,
        hyperparameter_tuning_job=hyperparameter_tuning_job_id,
    )
    response = client.delete_hyperparameter_tuning_job(name=name)
    print("Long running operation:", response.operation.name)
    delete_hyperparameter_tuning_job_response = response.result(timeout=timeout)
    print(
        "delete_hyperparameter_tuning_job_response:",
        delete_hyperparameter_tuning_job_response,
    )

次のステップ