インタラクティブシェルを使用したトレーニングのモニタリングとデバッグを行う

このページでは、インタラクティブシェルを使用して、トレーニングコードが実行されているコンテナを検査する方法について説明します。ファイルシステムを参照して、Vertex AI で実行されているビルド済みコンテナまたはカスタムコンテナごとにデバッグユーティリティを実行できます。

インタラクティブシェルを使用してトレーニングコンテナを検査すると、トレーニングコードや Vertex AI の構成の問題をデバッグできます。たとえば、インタラクティブシェルを使用すると、次のことができます。

トレースツールとプロファイリングツールを実行する
GPU の使用状況を分析する
コンテナで使用できる Google Cloud の権限を確認する

Cloud Profiler を使用して、カスタムトレーニングジョブのモデルトレーニングのパフォーマンスをデバッグすることもできます。詳細については、Profiler を使用してモデルのトレーニングパフォーマンスのプロファイルを作成するをご覧ください。

始める前に

CustomJob リソース、HyperparameterTuningJob リソース、またはカスタム TrainingPipeline リソースを使用してカスタムトレーニングを行う場合は、インタラクティブシェルを使用できます。トレーニングコードを準備して任意のカスタムトレーニングリソースを構成する場合は、次の要件を満たしていることを確認してください。

トレーニングコンテナに bash がインストールされている。

すべてのビルド済みトレーニングコンテナに bash がインストールされている。トレーニング用のカスタムコンテナを作成する場合は、bash を含むベースコンテナを使用するか、bash を Dockerfile にインストールします。
インタラクティブシェルをサポートするリージョンでカスタムトレーニングを行う。
インタラクティブシェルにアクセスするすべてのユーザーに、カスタムトレーニングを実行している Google Cloud プロジェクトに対する次の権限が付与されていることを確認します。
- aiplatform.customJobs.create
- aiplatform.customJobs.get
- aiplatform.customJobs.cancel
自分でカスタムトレーニングを開始する場合、これらの権限がすでに付与されているため、インタラクティブシェルにアクセスできます。ただし、インタラクティブシェルを使用して、組織内の他のユーザーが作成したカスタムトレーニングのリソースを検査する場合は、これらの権限の取得が必要になることがあります。

これらの権限を取得するには、組織の管理者に Vertex AI ユーザーロール（roles/aiplatform.user）を付与するように依頼する方法があります。

高度なケースの要件

特定の高度な機能を使用する場合は、次の追加要件を満たす必要があります。

カスタムトレーニングリソースにカスタムサービスアカウントを関連付ける場合は、インタラクティブシェルにアクセスするユーザーに、関連するサービスアカウントに対する iam.serviceAccounts.actAs 権限があることを確認します。

カスタムサービスアカウントのガイドには、サービスアカウントを関連付けるにはこの権限が必要であることが記載されています。この権限は、カスタムトレーニングでインタラクティブシェルを表示する場合にも必要です。

たとえば、サービスアカウントが設定された CustomJob を作成するには、サービスアカウントに対する iam.serviceAccounts.actAs 権限が必要です。同僚の 1 人がこの CustomJob のインタラクティブシェルを表示するには、そのユーザーにも同じ iam.serviceAccounts.actAs 権限が付与されている必要があります。
Vertex AI で VPC Service Controls を使用するようにプロジェクトを構成している場合は、次の制限も考慮する必要があります。
- カスタムトレーニングにプライベート IP は使用できません。VPC-SC と VPC ピアリングが必要な場合、インタラクティブシェルを使用するには追加の設定が必要です。VPC-SC と VPC ピアリングを使用した Ray ダッシュボードとインタラクティブシェルの手順に沿って、ユーザープロジェクトで VPC-SC と VPC ピアリングを使用してインタラクティブシェルの設定を構成します。
- インタラクティブシェル内から、サービス境界外の公共のインターネットや Google Cloud リソースにアクセスすることはできません。
- インタラクティブシェルへのアクセスを保護するには、aiplatform.googleapis.com に加えて、サービス境界内で制限されているサービスとして notebooks.googleapis.com を追加する必要があります。notebooks.googleapis.com ではなく aiplatform.googleapis.com のみを制限すると、ユーザーはサービス境界外のマシンからインタラクティブシェルにアクセスできるため、VPC Service Controls を使用するセキュリティ上のメリットが少なくなります。
  
  注: 一般的には、サービス境界を作成するときに、すべてのサービスを制限することをおすすめします。サービス境界の作成方法については、VPC Service Controls ガイドをご覧ください。

インタラクティブシェルを有効にする

カスタムトレーニングリソースにインタラクティブシェルを有効にするには、CustomJob、HyperparameterTuningJob、またはカスタム TrainingPipeline を作成するときに、enableWebAccess API フィールドを true に設定します。

以下では、この操作をいくつかの異なるツールで行う方法を説明します。

Console

ガイドに沿って、Google Cloud Console でカスタム TrainingPipeline を作成します。[新しいモデルのトレーニング] ペインで、[モデルの詳細] ステップになるまで次の操作を行います。

[詳細オプション] をクリックします。
[Enable training debugging] チェックボックスをオンにします。

次に、[新しいモデルのトレーニング] ワークフローの残りの作業を完了します。

gcloud

CustomJob を作成する場合は、gcloud ai custom-jobs create コマンドに --enable-web-access フラグを指定して実行します。
HyperparameterTuningJob を作成する場合は、gcloud ai hp-tuning-jobs create コマンドに --enable-web-access フラグを指定して実行します。

これらのコマンドの使用方法については、CustomJob の作成に関するガイドと HyperparameterTuningJob の作成に関するガイドをご覧ください。

API

以下に、カスタムトレーニングリソースの種類ごとに REST リクエスト本文で enableWebAccess フィールドを指定する場所を示します。

CustomJob

次の例は、projects.locations.customJobs.create API メソッドのリクエスト本文の一部を示したものです。

{
  ...
  "jobSpec": {
    ...
    "enableWebAccess": true
  }
  ...
}

CustomJob を作成する API リクエストを送信する例については、カスタムトレーニングジョブの作成をご覧ください。

HyperparameterTuningJob

次の例は、projects.locations.hyperparameterTuningJobs.create API メソッドのリクエスト本文の一部を示したものです。

{
  ...
  "trialJobSpec": {
    ...
    "enableWebAccess": true
  }
  ...
}

API リクエストを送信して HyperparameterTuningJob を作成する例については、ハイパーパラメータ調整の使用をご覧ください。

カスタム TrainingPipeline

次の例は、projects.locations.trainingPipelines.create API メソッドのリクエスト本文の一部を示したものです。ハイパーパラメータ調整を使用しているかどうかに応じてタブを選択してください。

ハイパーパラメータ調整なし

{
  ...
  "trainingTaskInputs": {
    ...
    "enableWebAccess": true
  }
  ...
}

ハイパーパラメータ調整あり

{
  ...
  "trainingTaskInputs": {
    ...
    "trialJobSpec": {
      ...
      "enableWebAccess": true
    }
  }
  ...
}

API リクエストを送信してカスタム TrainingPipeline を作成する例については、トレーニングパイプラインの作成をご覧ください。

Python

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

次のいずれかのメソッドを実行する場合は、enable_web_access パラメータを true に設定します。

CustomJob を作成する場合は、CustomJob.run メソッドを使用します。
HyperparameterTuningJob を作成する場合は、HyperparameterTuningJob.run メソッドを使用します。
カスタム TrainingPipeline を作成する場合は、次のいずれかのメソッドを使用します。

インタラクティブシェルに移動する

前のセクションのガイダンスに従ってカスタムトレーニングを開始すると、Vertex AI は、インタラクティブシェルへのアクセスに使用できる URI を生成します。Vertex AI は、ジョブのトレーニングノードごとに一意の URI を生成します。

次のいずれかの方法でインタラクティブシェルを開くことができます。

Google Cloud コンソールでリンクをクリックする
Vertex AI API を使用してシェルのウェブアクセス URI を取得する

Google Cloud コンソールから移動する

Google Cloud コンソールの [Vertex AI] セクションで、次のいずれかのページに移動します。
- ハイパーパラメータ調整を使用していない場合は、[CUSTOM JOBS] ページに移動します。
  
  [カスタムジョブ] に移動
- ハイパーパラメータチューニングを使用している場合は、[ハイパーパラメータチューニングジョブ] ページに移動します。
  
  [ハイパーパラメータチューニングジョブ] に移動
カスタムトレーニングリソースの名前をクリックします。

カスタムトレーニング用に TrainingPipeline を作成した場合は、TrainingPipeline によって作成された CustomJob または HyperparameterTuningJob の名前をクリックします。たとえば、パイプラインの名前が PIPELINE_NAME の場合、PIPELINE_NAME-custom-job または PIPELINE_NAME-hyperparameter-tuning-job になります。
ジョブのページで、[ウェブターミナルを起動] をクリックします。ジョブで複数のノードを使用している場合は、インタラクティブシェルを追加するノードの横にある [ウェブターミナルを起動] をクリックします。

インタラクティブシェルには、ジョブの実行中にのみアクセスできます。[ウェブターミナルを起動] が表示されない場合は、Vertex AI がまだジョブの実行を開始していないか、ジョブがすでに完了または失敗している可能性があります。ジョブのステータスが Queued または Pending の場合は、1 分ほど待ち、ページを更新してみてください。

ハイパーパラメータ調整を使用している場合は、トライアルごとに個別の [ウェブターミナルを起動] リンクがあります。

API からウェブアクセス URI を取得する

projects.locations.customJobs.get API メソッドまたは projects.locations.hyperparameterTuningJobs.get API メソッドを使用して、インタラクティブシェルへのアクセスに使用できる URI を確認します。

使用しているカスタムトレーニングリソースの種類に応じて次のいずれかのタブを選択してください。webAccessUris API フィールドを見つける方法を確認できます。このフィールドには、ジョブの各ノードのインタラクティブシェル URI が格納されています。

CustomJob

以下のタブでは、projects.locations.customJobs.get リクエストの送信方法を説明します。

gcloud

gcloud ai custom-jobs describe コマンドを実行します。

gcloud ai custom-jobs describe JOB_ID \
  --region=LOCATION \
  --format=json

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

JOB_ID: ジョブの数値 ID。この ID は、ジョブの name フィールドの最後の部分です。ジョブを作成したときに、ID が表示される場合があります（ジョブの ID がわからない場合は、gcloud ai custom-jobs list コマンドを実行して、該当するジョブを探します）。
LOCATION: ジョブを作成したリージョン。

REST

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

LOCATION: ジョブを作成したリージョン。
PROJECT_ID: 実際のプロジェクト ID。
JOB_ID: ジョブの数値 ID。この ID は、ジョブの name フィールドの最後の部分です。ジョブを作成したときに、ID が表示される場合があります。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/customJobs/JOB_ID

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

curl（Linux、macOS、Cloud Shell）

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/customJobs/JOB_ID"

PowerShell（Windows）

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

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

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

出力で、次のものを探します。

{
  ...
  "state": "JOB_STATE_RUNNING",
  ...
  "webAccessUris": {
    "workerpool0-0": "INTERACTIVE_SHELL_URI"
  }
}

webAccessUris フィールドが表示されない場合は、Vertex AI がジョブの実行をまだ開始していない可能性があります。JOB_STATE_RUNNING に state フィールドが表示されていることを確認します。状態が JOB_STATE_QUEUED または JOB_STATE_PENDING の場合は、1 分ほど待ちます。その後、プロジェクト情報をもう一度取得してみてください。

HyperparameterTuningJob

以下のタブでは、projects.locations.hyperparameterTuningJobs.get リクエストの送信方法を説明します。

gcloud

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

gcloud ai hp-tuning-jobs describe JOB_ID \
  --region=LOCATION \
  --format=json

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

JOB_ID: ジョブの数値 ID。この ID は、ジョブの name フィールドの最後の部分です。ジョブを作成したときに、ID が表示される場合があります（ジョブの ID がわからない場合は、gcloud ai hp-tuning-jobs list コマンドを実行して、該当するジョブを探します）。
LOCATION: ジョブを作成したリージョン。

REST

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

LOCATION: ジョブを作成したリージョン。
PROJECT_ID: 実際のプロジェクト ID。
JOB_ID: ジョブの数値 ID。この ID は、ジョブの name フィールドの最後の部分です。ジョブを作成したときに、ID が表示される場合があります。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/hyperparameterTuningJobs/JOB_ID

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

curl（Linux、macOS、Cloud Shell）

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/hyperparameterTuningJobs/JOB_ID"

PowerShell（Windows）

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

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

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

出力で、次のものを探します。

{
  ...
  "state": "JOB_STATE_RUNNING",
  ...
  "trials": [
    ...
    {
      ...
      "state": "ACTIVE",
      ...
      "webAccessUris": {
        "workerpool0-0": "INTERACTIVE_SHELL_URI"
      }
    }
  ],
}

トライアルが ACTIVE 状態になると、Vertex AI は各ハイパーパラメータ調整トライアルに一連のインタラクティブシェル URI を提供します。以降のトライアルのインタラクティブシェル URI を取得する場合は、トライアルの開始後にジョブ情報を再度取得します。

上の例は、単一レプリカのトレーニングで予想される出力を示しています。これは、プライマリトレーニングノードの URI の 1 つです。分散トレーニングを実行している場合、出力にはトレーニングノード（ワーカープール）ごとに 1 つの URI が表示されます。

たとえば、ジョブに 1 つのレプリカを持つプライマリワーカープールと 2 つのレプリカを持つセカンダリワーカープールがある場合、webAccessUris フィールドは次のようになります。

{
  "workerpool0-0": "URI_FOR_PRIMARY",
  "workerpool1-0": "URI_FOR_FIRST_SECONDARY",
  "workerpool1-1": "URI_FOR_SECOND_SECONDARY"
}

インタラクティブシェルを使用する

トレーニングノードでインタラクティブシェルを使用するには、前のセクションで確認した URI の 1 つに移動します。ブラウザに Bash シェルが表示され、Vertex AI がトレーニングコードを実行しているコンテナのファイルシステムにアクセスできます。

以降のセクションでは、シェルを使用する際の考慮事項について説明します。また、シェルで使用できるモニタリングツールの例を示します。

ジョブの実行を継続する

Vertex AI でジョブまたはトライアルの実行を終了するとすぐに、インタラクティブシェルへのアクセス権が失われます。その場合、command terminated with exit code 137 というメッセージが表示されるか、シェルが応答不能になります。コンテナのファイルシステムにファイルを作成した場合、ジョブが終了すると、そのファイルは保持されません。

インタラクティブシェルでデバッグするために、ジョブを長時間実行したい場合があります。たとえば、例外が発生してから 1 時間以上、ジョブの実行を継続させる場合は、次のようなコードをトレーニングコードに追加します。

import time
import traceback

try:
    # Replace with a function that runs your training code
    train_model()
except Exception as e:
    traceback.print_exc()
    time.sleep(60 * 60)  # 1 hour

ただし、ジョブが実行されている間は Vertex AI Training の料金が課金されます。

権限の問題を確認する

インタラクティブシェル環境では、Vertex AI がトレーニングコードの実行に使用するサービスアカウントのアプリケーションのデフォルト認証情報（ADC）を使用して認証が行われます。詳細については、シェルで gcloud auth list を実行してください。

シェルでは、bq など、ADC をサポートするツールを使用できます。これは、ジョブが特定の Cloud Storage バケット、BigQuery テーブル、またはトレーニングコードに必要な他の Google Cloud リソースにアクセスできることの確認に役立ちます。

`py-spy` を使用して Python の実行を可視化する

py-spy を使用すると、実行中の Python プログラムを変更せずにプロファイリングできます。インタラクティブシェルで py-spy を使用するには、次の操作を行います。

py-spy をインストールします。
```
pip3 install py-spy
```
シェルで ps aux を実行し、Python トレーニングプログラムの PID を確認します。
py-spy のドキュメントで説明されているサブコマンドのいずれかを実行し、前の手順で確認した PID を使用します。
py-spy record を使用して SVG ファイルを作成する場合は、後でローカルコンピュータで閲覧できるように、このファイルを Cloud Storage バケットにコピーします。例:
```
gcloud storage cp profile.svg gs://BUCKET
```
BUCKET は、アクセスできるバケットの名前に置き換えます。

`perf` でパフォーマンスを分析する

perf を使用すると、トレーニングノードのパフォーマンスを分析できます。ノードの Linux カーネルに適した perf のバージョンをインストールするには、次のコマンドを実行します。

apt-get update
apt-get install -y linux-tools-generic
rm /usr/bin/perf
LINUX_TOOLS_VERSION=$(ls /usr/lib/linux-tools | tail -n 1)
ln -s "/usr/lib/linux-tools/${LINUX_TOOLS_VERSION}/perf" /usr/bin/perf

その後、perf のドキュメントで説明されているサブコマンドを実行できます。

GPU の使用状況に関する情報を取得する

通常、GPU を使用するノード上で動作する GPU 対応コンテナには、GPU の使用状況のモニタリングに役立つコマンドラインツールがプリインストールされています。次に例を示します。

nvidia-smi を使用して、GPU の使用状況をモニタリングします。
nvprof を使用して、さまざまな GPU プロファイリング情報を収集します。nvprof は既存のプロセスには接続できないため、このツールを使用して、トレーニングコードを実行する追加のプロセスを開始することをおすすめします（この場合、ノードでトレーニングコードが 2 回実行されることになります）。例:
```
nvprof -o prof.nvvp python3 -m MODULE_NAME
```
MODULE_NAME は、トレーニングアプリケーションのエントリポイントモジュールの完全修飾名で置き換えます（例: trainer.task）。

後でローカルコンピュータで分析できるように、この出力ファイルを Cloud Storage バケットに転送します。例:
```
gcloud storage cp prof.nvvp gs://BUCKET
```
BUCKET は、アクセスできるバケットの名前に置き換えます。
構成または Vertex AI の問題ではなく、GPU のエラーが発生した場合は、nvidia-bug-report.sh を使用してバグレポートを作成します。

その後、レポートを Cloud Storage バケットに転送すると、ローカルコンピュータ上でレポートを分析できるようになります。また、レポートを NVIDIA に送信することもできます。例:
```
gcloud storage cp nvidia-bug-report.log.gz gs://BUCKET
```
BUCKET は、アクセスできるバケットの名前に置き換えます。

これらの NVIDIA コマンドが bash で見つからない場合は、シェルの PATH に /usr/local/nvidia/bin と /usr/local/cuda/bin を追加してみてください。

export PATH="/usr/local/nvidia/bin:/usr/local/cuda/bin:${PATH}"

VPC-SC と VPC ピアリングを使用した Ray ダッシュボードとインタラクティブシェル

peered-dns-domains を構成します。

{
  VPC_NAME=NETWORK_NAME
  REGION=LOCATION
  gcloud services peered-dns-domains create training-cloud \
  --network=$VPC_NAME \
  --dns-suffix=$REGION.aiplatform-training.cloud.google.com.

  # Verify
  gcloud beta services peered-dns-domains list --network $VPC_NAME);
}

NETWORK_NAME: ピアリングされたネットワークに変更します。
LOCATION: 目的のロケーション（例: us-central1）。

DNS managed zone を構成します。

{
  PROJECT_ID=PROJECT_ID
  ZONE_NAME=$PROJECT_ID-aiplatform-training-cloud-google-com
  DNS_NAME=aiplatform-training.cloud.google.com
  DESCRIPTION=aiplatform-training.cloud.google.com

  gcloud dns managed-zones create $ZONE_NAME  \
  --visibility=private  \
  --networks=https://www.googleapis.com/compute/v1/projects/$PROJECT_ID/global/networks/$VPC_NAME  \
  --dns-name=$DNS_NAME  \
  --description="Training $DESCRIPTION"
}

PROJECT_ID: 実際のプロジェクト ID。これらの ID は、Google Cloud コンソールの [ようこそ] ページで確認できます。

DNS トランザクションを記録します。

{
  gcloud dns record-sets transaction start --zone=$ZONE_NAME

  gcloud dns record-sets transaction add \
  --name=$DNS_NAME. \
  --type=A 199.36.153.4 199.36.153.5 199.36.153.6 199.36.153.7 \
  --zone=$ZONE_NAME \
  --ttl=300

  gcloud dns record-sets transaction add \
  --name=*.$DNS_NAME. \
  --type=CNAME $DNS_NAME. \
  --zone=$ZONE_NAME \
  --ttl=300

  gcloud dns record-sets transaction execute --zone=$ZONE_NAME
}

インタラクティブシェル、VPC-SC、VPC ピアリングを有効にしてトレーニングジョブを送信します。

次のステップ

Profiler を使用して、カスタムトレーニングジョブのパフォーマンスを最適化する方法を確認する。
Vertex AI によるカスタムトレーニングのオーケストレーション方法を確認する。
トレーニングコードの要件を確認する。

インタラクティブ シェルを使用したトレーニングのモニタリングとデバッグを行う

始める前に

高度なケースの要件

インタラクティブ シェルを有効にする

Console

gcloud

API

CustomJob

HyperparameterTuningJob

カスタム TrainingPipeline

ハイパーパラメータ調整なし

ハイパーパラメータ調整あり

Python

インタラクティブ シェルに移動する

Google Cloud コンソールから移動する

API からウェブアクセス URI を取得する

CustomJob

gcloud

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

HyperparameterTuningJob

gcloud

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

インタラクティブ シェルを使用する

ジョブの実行を継続する

権限の問題を確認する

py-spy を使用して Python の実行を可視化する

perf でパフォーマンスを分析する

GPU の使用状況に関する情報を取得する

VPC-SC と VPC ピアリングを使用した Ray ダッシュボードとインタラクティブ シェル

次のステップ

インタラクティブシェルを使用したトレーニングのモニタリングとデバッグを行う

インタラクティブシェルを有効にする

インタラクティブシェルに移動する

インタラクティブシェルを使用する

`py-spy` を使用して Python の実行を可視化する

`perf` でパフォーマンスを分析する

VPC-SC と VPC ピアリングを使用した Ray ダッシュボードとインタラクティブシェル