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

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

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

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

コマンドライン引数としてハイパーパラメータを受け入れ、Vertex AI に指標の値を報告するように、ハイパーパラメータ調整のトレーニングアプリケーションを準備する。
ハイパーパラメータトレーニングジョブを作成する。構成オプションの詳細については、ハイパーパラメータ調整の構成についてをご覧ください。

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

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

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

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

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

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

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

各ハイパーパラメータ引数の名前を定義し、任意の引数パーザー（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 引数を使用して渡します。
コマンドライン引数の値をトレーニングコードのハイパーパラメータに割り当てます。

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

Vertex AI に指標を報告する

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

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

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

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

コンソール

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

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

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

[トレーニングパイプライン] に移動
[作成] をクリックして、[新しいモデルのトレーニング] ペインを開きます。

注: ブラウザに「model.new」と入力すると、モデル作成ページに直接移動できます。
トレーニング方法のステップで、次の設定を指定します。
1. [データセット] プルダウンリストで、[管理されているデータセットなし] を選択します。
2. [カスタムトレーニング（上級者向け）] を選択します。
[続行] をクリックします。
[モデルの詳細] ステップで、[新しいモデルをトレーニング] または [新しいバージョンをトレーニング] を選択します。新しいモデルをトレーニングする場合は、モデルに任意の名前（MODEL_NAME）を入力します。[続行] をクリックします。
[トレーニングコンテナ] ステップで、次の設定を指定します。
1. トレーニングにビルド済みのコンテナとカスタムコンテナのどちらを使用するかを選択します。
2. 選択した内容に応じて、次のいずれかを行います。
  - ビルド済みのコンテナをトレーニングに使用する場合は、Cloud Storage にアップロードしたトレーニングパッケージを使用するために必要な情報を Vertex AI に提供します。
    1. [モデルフレームワーク] と [モデルフレームワークのバージョン] のプルダウンリストから、使用するビルド済みのコンテナを指定します。
    2. [パッケージの場所] フィールドで、作成およびアップロードした Python トレーニングアプリケーションの Cloud Storage URI を指定します。通常、このファイルは .tar.gz で終わります。
    3. [Python モジュール] フィールドに、トレーニングアプリケーションのエントリポイントのモジュール名を入力します。
  - トレーニングにカスタムコンテナを使用する場合は、[コンテナイメージ] フィールドにコンテナイメージの Artifact Registry または Docker Hub の URI を指定します。
3. [Model output directory] フィールドに、アクセス権があるバケット内のディレクトリの Cloud Storage URI を指定できます。そのディレクトリがまだ存在していなくてもかまいません。
  
  この値は、Vertex AI の baseOutputDirectory API フィールドに渡されます。この値に基づいて、トレーニングアプリケーションが実行時にアクセスする複数の環境変数が設定されます。
4. 省略可: [引数] フィールドに、Vertex AI がトレーニングコードの実行開始時に使用する引数を指定できます。すべての引数の合計長は 100,000 文字以下にする必要があります。これらの引数の動作は、使用しているコンテナの種類によって異なります。
  - ビルド済みのコンテナを使用する場合、Vertex AI は引数をコマンドラインフラグとして Python モジュールに渡します。
  - カスタムコンテナを使用している場合、Vertex AI はコンテナの CMD 命令を引数でオーバーライドします。
[続行] をクリックします。
[ハイパーパラメータ] ステップで、[Enable hyperparameter tuning] チェックボックスをオンにして、次の設定を指定します。
1. [新しいハイパーパラメータ] セクションで、調整するハイパーパラメータのパラメータ名とタイプを指定します。指定したタイプに応じて、表示される追加のハイパーパラメータ設定を構成します。
  
  ハイパーパラメータタイプとその構成で詳細をご覧ください。
2. 複数のハイパーパラメータを調整する場合は、[新しいパラメータを追加] をクリックして、表示された新しいセクションで前の手順を繰り返します。
  
  調整するハイパーパラメータごとに上記の手順を繰り返します。
3. [最適化する指標] フィールドと [目標] プルダウンリストに、最適化する指標の名前と目標を指定します。
4. [最大試行数] フィールドに、Vertex AI がハイパーパラメータ調整ジョブで実行するトライアルの最大数を指定します。
5. [並列試行の最大数] フィールドに、Vertex AI が同時に実行するトライアルの最大数を指定します。
6. [Algorithm] プルダウンリストで、Vertex AI で使用する検索アルゴリズムを指定します。
7. [Enable early stopping] の切り替えは無視します。これは効果がありません。
[続行] をクリックします。
[コンピューティングと料金] ステップで、次の設定を指定します。
1. [リージョン] プルダウンリストで、カスタムトレーニングをサポートするリージョンを選択します。
2. [Worker pool 0] セクションで、トレーニングに使用するコンピューティングリソースを指定します。
  
  アクセラレータを指定する場合は、選択したアクセラレータが選択したリージョンで使用できることを確認してください。
  
  分散トレーニングを行う場合は、[ADD MORE WORKER POOLS] をクリックし、追加のワーカープールごとに追加のコンピューティングリソースのセットを指定します。
[続行] をクリックします。
[予測コンテナ] ステップで、[No prediction container] を選択します。
[トレーニングを開始] をクリックして、カスタムトレーニングパイプラインを開始します。

gcloud

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

新しい 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 ソース配布のトレーニングコードもサポートしています。
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
```
次のように置き換えます。
- LOCATION: HyperparameterTuningJob を作成するリージョン。カスタムトレーニングをサポートするリージョンを使用します。
- DISPLAY_NAME: HyperparameterTuningJob の覚えやすい表示名。リソース名の要件を確認してください。
- MAX_TRIAL_COUNT: 実行するトライアルの最大数。
- PARALLEL_TRIAL_COUNT: 並行して実行するトライアルの最大数。

REST

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

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

LOCATION: HyperparameterTuningJob を作成するリージョン。カスタムトレーニングをサポートするリージョンを使用します。
PROJECT: 実際のプロジェクト ID。
DISPLAY_NAME: HyperparameterTuningJob の覚えやすい表示名。リソース名の要件を確認してください。
次のように指標を指定します。
- METRIC_ID: 最適化するハイパーパラメータ指標の名前。トレーニングコードは、実行時にこの指標を報告する必要があります。
- METRIC_GOAL: ハイパーパラメータ指標の目標（MAXIMIZE または MINIMIZE）。
ハイパーパラメータを指定します。
- HYPERPARAMETER_ID: 調整するハイパーパラメータの名前。トレーニングコードは、この名前でコマンドラインフラグを解析する必要があります。
- PARAMETER_SCALE: 省略可。パラメータのスケーリング方法。CATEGORICAL パラメータには設定しないでください。UNIT_LINEAR_SCALE、UNIT_LOG_SCALE、UNIT_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_UNSPECIFIED、GRID_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_NAME と LABEL_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
  }
}

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

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

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）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$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

次のような 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 クイックスタート: クライアントライブラリの使用にある Java の設定手順を完了してください。詳細については、Vertex AI Java API のリファレンスドキュメントをご覧ください。

Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

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

Python をインストールまたは更新する方法については、Vertex AI SDK for Python をインストールするをご覧ください。詳細については、Python API リファレンスドキュメントをご覧ください。

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

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

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

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

調整するハイパーパラメータと、トライアルの評価に使用する指標。

詳しくは、ハイパーパラメータと指標の選択方法をご覧ください。
この調整ジョブの一部として実行するトライアル数の詳細。たとえば、次のようになります。
各トライアルで実行されるカスタムトレーニングジョブの詳細。
- トライアルジョブが実行されるマシンタイプとジョブが使用するアクセラレータ。
  
  注: 現在、Vertex AI は、TPU を必要とするハイパーパラメータ調整ジョブをサポートしていません。
- カスタムコンテナまたは Python パッケージジョブの詳細。
  
  詳しくは、トレーニングコードの要件をご覧ください。

トライアル数を制限する

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

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

時間（結果として、費用）
精度

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

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

並列トライアル

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

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

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

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

ハイパーパラメータ調整トライアルがエラーで終了する場合は、トレーニングジョブを早期に終了できます。HyperparameterTuningJob の maxFailedTrialCount フィールドに、許可するトライアルの失敗回数を設定します。トライアルの失敗回数がこの数を超えると、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

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

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

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

PowerShell（Windows）

次のコマンドを実行します。

$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

次のような 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

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

# 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

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

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

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

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

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

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）

次のコマンドを実行します。

$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

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

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()

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

次のコードサンプルでは、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

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

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

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

PowerShell（Windows）

次のコマンドを実行します。

$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

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

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()

次のステップ

ハイパーパラメータ調整に関連するコンセプトについて学習する。

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

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

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

Vertex AI に指標を報告する

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

コンソール

gcloud

config.yaml

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Java

Python

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

トライアル数を制限する

並列トライアル

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

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

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

gcloud

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Java

Python

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

gcloud

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Python

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

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

Python

次のステップ

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

`config.yaml`

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