開始使用 ML Diagnostics CLI

使用 ML Diagnostics Google Cloud CLI 建立機器學習執行作業、將 XProf 部署為可擴充後端的代管執行個體，並在 Google Cloud上提供代管的剖析體驗。

ML Diagnostics gcloud CLI 指令分為兩類：machine-learning-run 指令和 profiler 指令。使用 machine-learning-run 指令建立、刪除、說明、列出及更新機器學習執行作業。使用 profiler 指令列出節點，並從 CLI 擷取隨選設定檔。

Machine-learning-run 指令：Create、Delete、Describe、List、Update。
Profiler 指令：
- profiler-target：List
- profiler-session：Capture、List

所有 gcloud CLI 指令都需要環境中定義的專案。如要設定專案：

gcloud config set project PROJECT_ID

如要進一步瞭解 ML Diagnostics gcloud CLI 指令，請參閱 API 參考資料。

擷取設定檔

您可以透過程式輔助擷取或隨選擷取 (手動擷取)，擷取機器學習工作負載的 XProf 剖析檔。程式輔助擷取是指直接將剖析指令嵌入機器學習程式碼，並明確指出開始和停止記錄資料的時間。隨選擷取作業會即時進行，您可以在工作負載已主動執行的情況下觸發剖析器。

如要啟用隨選設定檔擷取功能，您需要在程式碼中啟動 XProf 伺服器，並呼叫 profiler.start_server 方法。這會在機器學習工作負載上啟動 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 進行剖析，請參閱「剖析運算」一文。

建立機器學習執行作業

在指定專案和位置建立機器學習執行作業資源。machine-learning-run create 指令會在專案中將 XProf 部署為代管執行個體。受管理 XProf 執行個體用於查看專案中的所有設定檔，並在專案中建立第一個機器學習執行時建立。

使用 machine-learning-run create 指令：

gcloud alpha mldiagnostics machine-learning-run create

建立機器學習執行作業的方法有兩種：

將現有擷取的設定檔註冊至 ML Diagnostics 平台。
使用 ML Diagnostics 註冊執行中的作業，即可執行隨選設定檔擷取作業。這需要設定 GKE 叢集，並在 GKE 上部署標籤為 managed-mldiagnostics-gke=true 的工作負載。

建立機器學習執行作業，並註冊現有擷取的設定檔

下列程式碼會建立執行作業，並將現有擷取的設定檔註冊至 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`	必填	這項特定執行的專屬 ID。如果名稱不重複，系統會顯示「ML Run already exists」(機器學習執行作業已存在) 訊息，導致執行作業建立失敗。
`location`	必填	系統支援所有 Cluster Director 位置，但 `us-east5` 除外。這個旗標可透過每個指令的引數設定，或使用 `gcloud config set compute/region` 指令設定。
`gcs-path`	必填	儲存所有設定檔的 Google Cloud 儲存位置。例如：`gs://my-bucket` 或 `gs://my-bucket/folder1`。只有在 SDK 用於擷取設定檔時才須提供。
`run-group`	選用	這個 ID 可協助您將屬於同一項實驗的多個執行作業分組。舉例來說，與 TPU 節點大小掃描相關聯的所有執行作業，都可能屬於同一個群組。
`display-name`	選用	機器學習執行的顯示名稱。如未提供，系統會設為機器學習執行 ID。

如要查看及管理 ML 診斷中現有的已收集設定檔，就必須設定 --labels list_existing_sessions_only=true 旗標。這個旗標會執行下列作業：

建立狀態為「已完成」的機器學習執行作業。
遞迴搜尋 Cloud Storage 目錄路徑中的 xplane.pb 檔案。
將所有找到的設定檔工作階段載入 ML Diagnostics 資料庫，以便在 Google Cloud中查看、建立設定檔工作階段的可共用連結，並讓使用者透過 ML Diagnostics 平台管理這些設定檔。

如果將執行作業的 --labels list_existing_sessions_only 標記設為 true，您就無法執行隨選剖析或更新執行作業。你只能查看及管理現有設定檔。

建立機器學習執行作業，以便按照需求擷取設定檔

下列程式碼會建立 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 的必要條件	工作負載的 ID。例如：`jobset-abcd`。
`gke-workload-create-time`	GKE 的必要條件	JobSet 的建立時間戳記，採用 ISO 時間戳記格式。例如：`2026-02-20T06:00:00Z`。
`run-phase`	選用	執行作業的階段和狀態。如未提供，預設為 `ACTIVE`。

說明機器學習執行作業

使用 machine-learning-run describe 指令查看機器學習執行的詳細資料：

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

列出機器學習執行作業

使用 machine-learning-run list 指令，取得指定專案和位置的機器學習執行作業清單：

gcloud alpha mldiagnostics machine-learning-run list

以下範例要求最多列出兩個執行作業，並輸出 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

更新機器學習執行作業

在指定專案和位置更新機器學習執行作業。您可以更新顯示名稱、執行階段、協調器和 GKE 工作負載詳細資料。執行 ID 和位置無法變更。使用 machine-learning-run update 指令更新執行作業：

gcloud alpha mldiagnostics machine-learning-run update

請提供 create 要求中包含的所有欄位。如果更新要求未提供必要欄位，系統會以預設值覆寫這些欄位。

etag 旗標為必填欄位，應為 ML 執行資源的最新 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

刪除機器學習執行作業

使用 machine-learning-run delete 指令，刪除指定專案和位置的機器學習執行作業：

gcloud alpha mldiagnostics machine-learning-run delete RUN_NAME

刪除 ML 執行作業不會刪除 Cloud Storage、Cloud Logging 或 GKE 工作負載中的任何資料。刪除 mlrun 只會刪除 ML Diagnostics 系統中與執行作業相關的中繼資料。

Profiler 指令

您可以使用分析器指令群組列出所有設定檔、找出 XProf 伺服器執行的工作負載 GKE 節點，以及從 CLI 擷取隨選設定檔。

列出分析器目標

列出與指定專案和位置的機器學習執行作業相關聯的所有剖析器目標：

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

這項指令需要下列項目：

工作負載已啟用隨選 Xprof，這會將 XProf 伺服器部署至工作負載的所有節點。
已為 ML 診斷設定 GKE 叢集，並部署 Webhook 和運算子。
在 GKE 上部署的工作負載，標籤為： managed-mldiagnostics-gke=true。

以下是要求範例：

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

列出剖析器工作階段

使用下列指令，列出指定專案和位置中與機器學習執行作業相關聯的所有剖析器工作階段：

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

擷取隨選剖析器工作階段

您可以針對工作負載執行的特定節點集 (剖析器目標)，擷取機器學習執行作業的隨選剖析器工作階段。

這項指令需要下列項目：

工作負載中已啟用隨選 XProf，可將 XProf 伺服器部署至工作負載的所有節點
GKE 叢集已設定 ML 診斷，並部署 Webhook 和運算子
在 GKE 上部署的工作負載，標籤為： managed-mldiagnostics-gke=true。

以下是要求範例：

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 或完整 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`。