ML 診断 CLI を使ってみる

ML Diagnostics Google Cloud CLI を使用して、ML 実行を作成し、スケーラブルなバックエンドを備えたマネージド インスタンスとして XProf をデプロイし、 Google Cloudでマネージド プロファイリング エクスペリエンスを提供します。

ML Diagnostics gcloud CLI コマンドには、machine-learning-run コマンドと profiler コマンドの 2 つのカテゴリがあります。machine-learning-run コマンドを使用して、ML 実行の作成、削除、記述、一覧表示、更新を行います。profiler コマンドを使用してノードを一覧表示し、CLI からオンデマンド プロファイルをキャプチャします。

  • Machine-learning-run コマンド: Create、Delete、Describe、List、Update。
  • プロファイラ コマンド:
    • profiler-target: List
    • profiler-session: Capture、List

すべての gcloud CLI コマンドには、環境で定義されたプロジェクトが必要です。プロジェクトを設定するには:

gcloud config set project PROJECT_ID

ML Diagnostics gcloud CLI コマンドの詳細については、API リファレンスをご覧ください。

プロファイルのキャプチャ

ML ワークロードの XProf プロファイルは、プログラムによるキャプチャまたはオンデマンド キャプチャ（手動キャプチャ）でキャプチャできます。プログラムによるキャプチャでは、プロファイリング コマンドを ML コードに直接埋め込み、データの記録を開始および停止するタイミングを明示的に指定します。オンデマンド キャプチャはリアルタイムで行われます。ワークロードがすでにアクティブに実行されているときに、プロファイラをトリガーします。

オンデマンド キャプチャを有効にするには、コード内で XProf サーバーを起動し、profiler.start_server メソッドを呼び出す必要があります。これにより、ML ワークロードで XProf サーバーが起動します。このサーバーがオンデマンド キャプチャ トリガーをリッスンして、プロファイルのキャプチャを開始します。このコマンドにはポート 9999 を使用します。 profiler.start_server(port=9999)

プログラムによるキャプチャとオンデマンド キャプチャのいずれの方法でも、キャプチャしたプロファイルの保存先を指定します。例: gs://my-bucket/my-run。プロファイルは、gs://my-bucket/my-run/plugins/profile/session1/ の場所にあるネストされたディレクトリに保存されます。プログラムによるプロファイル キャプチャとオンデマンド キャプチャは、同じ期間に実行できません。

オンデマンド プロファイル キャプチャの場合は、GKE クラスタを設定し、ラベル managed-mldiagnostics-gke=true を使用してワークロードをデプロイします。

JAX を使用したプロファイリングの詳細については、計算のプロファイリングをご覧ください。

ML の実行を作成する

指定されたプロジェクトとロケーションに ML の実行リソースを作成します。machine-learning-run create コマンドは、プロジェクトに XProf をマネージド インスタンスとしてデプロイします。マネージド XProf インスタンスは、プロジェクト内のすべてのプロファイルを表示するために使用され、プロジェクトで最初の ML 実行が作成されるときに作成されます。

machine-learning-run create コマンドを使用します。

gcloud alpha mldiagnostics machine-learning-run create

ML 実行を作成する方法は 2 つあります。

  • 既存のキャプチャされたプロファイルを ML 診断プラットフォームに登録します。
  • ML Diagnostics を使用して、アクティブな実行を登録し、オンデマンド プロファイル キャプチャを実行します。これには、GKE クラスタの設定と、ラベル managed-mldiagnostics-gke=true を使用して GKE にデプロイされたワークロードが必要です。

ML 実行を作成し、既存のキャプチャされたプロファイルを登録する

次のコードは、実行を作成し、既存のキャプチャされたプロファイルを ML Diagnostics に登録します。

gcloud alpha mldiagnostics machine-learning-run create RUN_NAME \
  --location LOCATION \
  --run-group GROUP_NAME \
  --gcs-path gs://BUCKET_NAME \
  --display-name DISPLAY_NAME \
  --labels "list_existing_sessions_only"="true"

このコード例では、次のフラグを使用します。

フラグ 要件 説明
machine-learning-run 必須 この特定の実行の一意の識別子。名前が一意でない場合、実行の作成は失敗し、「ML Run already exists」というメッセージが表示されます。
location 必須 us-east5 を除くすべてのクラスタ ディレクターのロケーションがサポートされています。このフラグは、各コマンドの引数で設定するか、コマンド gcloud config set compute/region で設定できます。
gcs-path 必須 すべてのプロファイルが保存される Google Cloud ストレージの場所。たとえば、gs://my-bucket や gs://my-bucket/folder1 です。SDK がプロファイル キャプチャに使用される場合にのみ必要です。
run-group 省略可 同じテストに属する複数の実行をグループ化するのに役立つ識別子。たとえば、TPU スライスサイズのスイープに関連付けられているすべての実行は、同じグループに属している可能性があります。
display-name 省略可 ML 実行の表示名。指定しない場合、マシンラーニング実行 ID に設定されます。

ML 診断で既存の収集済みプロファイルを表示して管理する場合は、--labels list_existing_sessions_only=true フラグが必要です。このフラグは次の処理を行います。

  1. 状態が「完了」の ML の実行を作成します。
  2. Cloud Storage ディレクトリ パス内の xplane.pb ファイルを再帰的に検索します。
  3. 検出されたすべてのプロファイル セッションを ML Diagnostics データベースに読み込んで Google Cloudで表示し、プロファイル セッションの共有可能なリンクを作成して、ユーザーが ML Diagnostics プラットフォームでこれらのプロファイルを管理できるようにします。

実行の --labels list_existing_sessions_only フラグが true に設定されている場合、オンデマンド プロファイリングを実行したり、実行を更新したりすることはできません。既存のプロファイルの表示と管理のみを行うことができます。

オンデマンド プロファイル キャプチャを実行する ML Run を作成する

次のコードは、オンデマンド プロファイル キャプチャを実行するために mlrun を作成します。

gcloud alpha mldiagnostics machine-learning-run create RUN_NAME \
  --location LOCATION \
  --orchestrator gke \
  --run-group RUN_GROUP \
  --gcs-path gs://BUCKET_NAME \
  --display-name DISPLAY_NAME \
  --gke-cluster-name projects/user/locations/LOCATION/clusters/CLUSTER_NAME \
  --gke-namespace NAMESPACE \
  --gke-workload-name WORKLOAD_NAME \
  --gke-kind GKE_KIND \
  --gke-workload-create-time CREATE_TIME \
  --run-phase RUN_PHASE

このコード例では、前の例のフラグに加えて、次のフラグも使用しています。

フラグ 要件 説明
orchestrator 省略可 実行に使用されたオーケストレーター。指定しない場合、デフォルトで gke が使用されます。有効な値: gce、gke、slurm
gke-cluster-name GKE で必要 ワークロードのクラスタ。例: /projects/<project_id>/locations/<location>/clusters/<cluster_name>
gke-kind GKE で必要 ワークロードの種類。例: JobSet。
gke-namespace GKE で必要 ワークロードの名前空間。例: default。
gke-workload-name GKE で必要 ワークロードの識別子。例: jobset-abcd。
gke-workload-create-time GKE で必要 JobSet の作成タイムスタンプ（ISO タイムスタンプ形式）。例: 2026-02-20T06:00:00Z。
run-phase 省略可 実行のフェーズと状態。指定しない場合、デフォルトは ACTIVE です。

ML の実行を説明する

machine-learning-run describe コマンドを使用して、ML 実行の詳細を表示します。

gcloud alpha mldiagnostics machine-learning-run describe RUN_NAME --FORMAT=FORMAT

次の例は、JSON 形式の実行の詳細のリクエストです。

gcloud alpha mldiagnostics machine-learning-run describe my-run-on-demand \
  --format json

出力は次のようになります。

{
  "artifacts": {
    "gcsPath": "gs://my-bucket"
  },
  "createTime": "2026-02-05T16:25:28.367865234Z",
  "displayName": "mldiagnostics-my-run-on-demand",
  "endTime": "0001-01-01T00:00:00Z",
  "etag": "1f54a7f4-bd25-4f98-a91c-97bfa1c5b7a6",
   "name": "projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand",
  "orchestrator": "GKE",
  "runPhase": "ACTIVE",
  "runSet": "my-run-on-demand-group",
  "tools": [
    {
      "XProf": {}
    }
  ],
  "updateTime": "2026-02-05T16:25:28.367865344Z",
  "workloadDetails": {
    "gke": {
      "cluster": "projects/163028815180/locations/us-central1/clusters/my-cluster",
      "id": "jobset-abcd",
      "kind": "JobSet",
      "namespace": "default"
    }
  }
}

ML の実行を一覧表示する

machine-learning-run list コマンドを使用して、指定されたプロジェクトとロケーション内の ML 実行のリストを取得します。

gcloud alpha mldiagnostics machine-learning-run list

次の例は、最大 2 つの実行のリストとその URI パスの出力をリクエストしています。

gcloud alpha mldiagnostics machine-learning-run list --limit 2 --uri

https://hypercomputecluster.googleapis.com/v1alpha/projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand
https://hypercomputecluster.googleapis.com/v1alpha/projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand-2

ML の実行を更新する

指定されたプロジェクトとロケーションで ML の実行を更新します。表示名、実行フェーズ、オーケストレーター、GKE ワークロードの詳細を更新できます。実行 ID とロケーションは変更できません。machine-learning-run update コマンドを使用して実行を更新します。

gcloud alpha mldiagnostics machine-learning-run update

create リクエストに含まれていたすべてのフィールドを指定します。更新リクエストで必須フィールドが指定されていない場合、デフォルト値でオーバーライドされます。

etag フラグは必須フィールドで、ML Run リソースの最新の ETag（エンティティ タグ）値にする必要があります。詳細については、オプティミスティック同時実行制御にエンティティ タグを使用するをご覧ください。正しい ETag 値を見つけるには、次の手順を行います。

gcloud alpha mldiagnostics machine-learning-run describe RUN_NAME

次に、完全な更新リクエストの例を示します。

gcloud alpha mldiagnostics machine-learning-run update my-run-on-demand \
  --orchestrator gke \
  --run-group my-run-on-demand-group \
  --gcs-path gs://my-bucket \
  --display-name mldiagnostics-my-run-on-demand-completed \
  --gke-cluster-name projects/user/locations/us-central1/clusters/my-cluster \
  --gke-namespace default \
  --gke-workload-name jobset-abcd \
  --gke-kind JobSet \
  --gke-workload-create-time 2026-02-20T06:06:06Z \
  --run-phase COMPLETED \
  --etag 1f54a7f4-bd25-4f98-a91c-97bfa1c5b7a6

ML の実行を削除

machine-learning-run delete コマンドを使用して、指定したプロジェクトとロケーションの ML の実行を削除します。

gcloud alpha mldiagnostics machine-learning-run delete RUN_NAME

ML 実行を削除しても、Cloud Storage、Cloud Logging、GKE ワークロードのデータは削除されません。mlrun を削除すると、ML Diagnostics システム内の実行に関連するメタデータのみが削除されます。

プロファイラ コマンド

プロファイラ コマンド グループを使用すると、すべてのプロファイルのリスト表示、XProf サーバーが実行されているワークロードの GKE ノードの検索、CLI からのオンデマンド プロファイルのキャプチャを行うことができます。

プロファイラ ターゲットの一覧を取得する

指定されたプロジェクトとロケーションの ML 実行に関連付けられているすべてのプロファイラ ターゲットを一覧表示します。

gcloud alpha mldiagnostics profiler-target list --machine-learning-run RUN_NAME

このコマンドには次のものが必要です。

  • オンデマンド Xprof がワークロードで有効になり、XProf サーバーがワークロードのすべてのノードにデプロイされます。
  • GKE クラスタが ML Diagnostics 用に設定され、Webhook とオペレーターがデプロイされている。
  • ラベル managed-mldiagnostics-gke=true を使用して GKE にワークロードをデプロイしました。

リクエストの例を次に示します。

gcloud alpha mldiagnostics profiler-target list \
  --machine-learning-run my-run-on-demand

出力の例を以下に示します。

---
hostname: gke-tpu-1f0789b5-jqx9
name: projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand/profilerTargets/jobset-abcd-tpu-slice-0-0-tcw2k
---
hostname: gke-tpu-1f0789b5-rxvf
name: projects/163028815180/locations/us-central1/machineLearningRuns/my-run-on-demand/profilerTargets/jobset-abcd-tpu-slice-0-1-dct59

プロファイラ セッションを一覧表示する

次のコマンドを使用して、指定されたプロジェクトとロケーションにある ML の実行に関連付けられているすべてのプロファイラ セッションを一覧表示します。

gcloud alpha mldiagnostics profiler-session list --machine-learning-run RUN_NAME

このプロファイラ コマンドでは、GKE やワークロードの設定は必要ありません。プログラマティック セッションとオンデマンド セッションの両方を含む、すべてのプロファイル セッションが一覧表示されます。プログラムによるプロファイル キャプチャのみがある場合は、このコマンドを使用してすべてのプロファイル セッションを一覧表示します。必要な GKE の設定、GKE ワークロードのラベル付け、オンデマンド XProf の有効化はありません。

リクエストの例を次に示します。

gcloud alpha mldiagnostics profiler-session list \
  --machine-learning-run my-run-on-demand

オンデマンド プロファイラ セッションをキャプチャする

ワークロードが実行されている特定のノードセット（プロファイラー ターゲット）で、ML の実行のオンデマンド プロファイラー セッションをキャプチャできます。

このコマンドには次のものが必要です。

  • ワークロードでオンデマンド XProf が有効になり、XProf サーバーがワークロードのすべてのノードにデプロイされます。
  • GKE クラスタが ML Diagnostics 用に設定され、Webhook とオペレーターがデプロイされている
  • ラベル managed-mldiagnostics-gke=true を使用して GKE にワークロードをデプロイしました。

リクエストの例を次に示します。

gcloud alpha mldiagnostics profiler-session capture \
  profiler-session-on-demand \
  --machine-learning-run RUN_NAME \
  --targets TARGET \
  --duration DURATION

この例では、次のフラグを使用します。

フラグ 要件 説明
profiler-session-name 必須 キャプチャするプロファイラ セッションの名前。
duration 必須 プロファイラ セッションのキャプチャの期間。Duration 型です。たとえば、1 秒の場合は 1s、400 ミリ秒の場合は 400ms、5 分の場合は 5m を指定します。
targets 必須 プロファイラー ターゲットの ID またはプロファイラー ターゲットの完全修飾識別子。実行に関連付けられたターゲットのリストと一致する必要があります。
device-tracer-level 省略可 セッションのデバイス トレーサー レベル。指定できる値: device-tracer-level-enabled、device-tracer-level-disabled（デフォルト）。
host-tracer-level 省略可 セッションのホスト トレーサー レベル。指定できる値: host-tracer-level-info（デフォルト）、host-tracer-level-critical、host-tracer-level-disabled、host-tracer-level-verbose。
python-tracer-level 省略可 セッションの Python トレーサー レベル。指定できる値: python-tracer-level-disabled（デフォルト）、python-tracer-level-enabled。