開始使用機器學習診斷 CLI

使用 ML Diagnostics Google Cloud CLI 建立及管理機器學習執行作業、將 XProf 部署為具有可擴充後端的代管執行個體,並在 Google Cloud提供代管剖析體驗。您也可以透過 CLI 或 API,列出工作負載監控偵測到的所有事件,並取得這些事件的分析器詳細資料。

下表匯總了 ML 診斷 gcloud CLI 指令的類別:

類別 指令 函式
機器學習執行作業 machine-learning-run:create、describe、list、update、delete、start-continuous-profiling、stop-continuous-profiling 建立及管理機器學習執行作業,以及啟動或停止持續剖析。
Profiler
  • profiler-target:list
  • profiler-session:list,capture
列出工作負載節點和分析器工作階段,並擷取隨選設定檔或連續分析快照。
監控的事件 monitored-events:list、describe 列出工作負載監控偵測到的事件,並取得各事件的分析器詳細資料。

如要進一步瞭解機器學習診斷 gcloud CLI 指令,請參閱 API 參考資料。

必要條件

執行機器學習診斷 gcloud CLI 指令前,請先完成下列必要條件:

  1. 啟用 Cluster Director API,並授予必要的 Identity and Access Management (IAM) 權限。詳情請參閱「ML Diagnostics 必要條件」。
  2. 安裝 gcloud CLI,然後安裝 alpha 元件:

    gcloud components install alpha
    
  3. 在環境中設定預設專案,這是所有 gcloud CLI 指令的必要設定:

    gcloud config set project PROJECT_ID
    

    將 PROJECT_ID 替換為您的 Google Cloud專案 ID。

建立機器學習執行作業

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

使用 machine-learning-run create 指令:

gcloud alpha mldiagnostics machine-learning-run create

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

  • 將現有擷取的設定檔註冊至 ML Diagnostics 平台。
  • 使用 ML Diagnostics 註冊執行中的作業,即可隨選擷取設定檔。這項操作需要設定 GKE 叢集。

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

下列程式碼會建立執行作業,並將現有擷取的設定檔註冊到機器學習診斷:

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。如果名稱不重複,執行作業建立作業就會失敗,並顯示「機器學習執行作業已存在」訊息。
location 必填 除了 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。

如要在機器學習診斷中查看及管理現有的收集設定檔,則必須使用 --labels list_existing_sessions_only=true 旗標。這個旗標會執行下列動作:

  1. 建立狀態為「已完成」的機器學習執行作業。
  2. 遞迴搜尋 Cloud Storage 目錄路徑中的 xplane.pb 檔案。
  3. 將所有找到的設定檔工作階段載入 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

更新機器學習執行作業

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

gcloud alpha mldiagnostics machine-learning-run update

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

etag 旗標是必填欄位,應為機器學習執行資源的最新 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

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

開始持續剖析

啟用連續剖析功能後,機器學習診斷平台會持續在 TPU 主機的記憶體緩衝區中擷取設定檔。您可以針對執行中的機器學習作業,對一或多個分析器目標啟動持續分析。

啟用持續剖析功能後,每個目標上的 XProf 剖析器都會在記憶體內循環緩衝區中,保留最近 2 GB 的追蹤記錄資料。機器學習執行作業一次只能有一個持續剖析工作階段。

持續剖析功能僅支援在裝置上追蹤,不會收集主機或 Python 追蹤記錄。啟用持續剖析功能時,無法變更追蹤器層級和 XProf 伺服器通訊埠。如要變更追蹤程式層級,必須停止持續剖析並重新啟動程序。

如要開始持續剖析,請在執行中的機器學習作業,對一或多個剖析器目標執行下列指令:

gcloud alpha mldiagnostics machine-learning-run start-continuous-profiling \
  --machine-learning-run=RUN_NAME \
  --location=LOCATION \
  --targets=TARGETS

更改下列內容:

  • RUN_NAME:有效機器學習執行的 ID。
  • LOCATION:機器學習執行的區域,例如 us-central1。
  • TARGETS:以半形逗號分隔的分析器目標 ID 清單,或分析器目標的完整名稱。例如:my-node-0,my-node-1。如要查看可用的目標,請參閱「列出分析器目標」。

如要將緩衝的追蹤記錄資料儲存為分析器工作階段,請使用 profiler-session capture 指令搭配 --kind=snapshot 旗標:

gcloud alpha mldiagnostics profiler-session capture \
  SESSION_NAME \
  --machine-learning-run=RUN_NAME \
  --location=LOCATION \
  --targets=TARGETS \
  --kind=snapshot

將 SESSION_NAME 替換為擷取的分析器工作階段 ID。

停止持續剖析

您可以停止剖析機器學習執行作業的所有剖析器目標。停止持續剖析後,剖析器目標會停止將追蹤記錄資料記錄到記憶體緩衝區,您也無法擷取新的快照。現有的快照剖析器工作階段不受影響。

使用下列指令,停止持續剖析機器學習執行作業:

gcloud alpha mldiagnostics machine-learning-run stop-continuous-profiling \
  --machine-learning-run=RUN_NAME \
  --location=LOCATION

更改下列內容:

  • RUN_NAME:機器學習執行的 ID。
  • LOCATION:機器學習執行作業的區域。例如:us-central1。

分析器指令

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

列出剖析器目標

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

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

這個指令需要下列項目:

  • 工作負載已啟用隨選 XProf,會將 XProf 伺服器部署至工作負載的所有節點。
  • GKE 叢集已設定為使用 ML Diagnostics,並部署了 Webhook 和運算子,或 ML Diagnostics DaemonSet。
  • 在 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

列出分析器工作階段

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

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 Diagnostics,並部署了 Webhook 和運算子,或 ML Diagnostics DaemonSet。
  • 在 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。 舉例來說,指定 1s 代表 1 秒,400ms 代表 400 毫秒,5m 代表 5 分鐘。
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。
kind 選用 分析器工作階段類型。預設值:on-demand。接受的值:
  • on-demand:透過 CLI、 Google Cloud 控制台或 API 中的隨選要求建立的 Profiler 工作階段。
  • snapshot:透過連續剖析流程建立的 Profiler 工作階段,用於擷取快照。

監控的事件

您可以使用 monitored-events 指令,列出工作負載監控偵測到的所有事件,並取得各事件的分析器詳細資料。

列出監控的事件

列出工作負載監控偵測到的所有事件,這些事件與機器學習執行作業相關聯。

以下是要求範例:

gcloud alpha mldiagnostics monitored-events list \
 --machine-learning-run=my-run-123 \
 --location=us-central1 \
 --project=PROJECT_ID \
 --format=json

以下是輸出內容範例:

[
 {
   "displayName": "Performance degradation - 2026-05-01T12:00:00Z",
   "endTime": "2026-05-01T12:10:00Z",
   "name": "projects/PROJECT_ID/locations/us-central1/machineLearningRuns/my-run-123/monitoredEvents/abc-123-def-456",
   "startTime": "2026-05-01T12:00:00Z",
   "type": "PERFORMANCE_DEGRADATION"
 },
 {
   "displayName": "Performance degradation - 2026-06-27T07:35:00Z",
   "endTime": "2026-06-27T08:15:00Z",
   "name": "projects/PROJECT_ID/locations/us-central1/machineLearningRuns/my-run-123/monitoredEvents/abc-789-def-123",
   "startTime": "2026-06-27T07:35:00Z",
   "type": "PERFORMANCE_DEGRADATION"
   }
   // ... other events
]

描述監控的事件

針對與機器學習執行作業相關聯的工作負載監控作業偵測到的每個事件,取得分析器詳細資料。

以下是要求範例:

gcloud alpha mldiagnostics monitored-events describe abc-123-def-456 \
 --machine-learning-run=my-run-123 \
 --location=us-central1 \
 --project=PROJECT_ID \
 --format=json

以下是輸出內容範例:

{
 "analyzerReports": [
   {
     "analyzer": "ICI Link Analyzer",
     "detectionState": "DETECTED",
     "details": "ICI Link issues detected in <instance_ids>: This indicates networking issues on ICI links connected between TPU processors.",
     "recommendedActions": [
       {
         "description": "Contact Google team for further diagnosis. Potential action could be to Outkast affected nodes, but there could be other causes that need further investigation.",
         "documentationUrl": "https://docs.cloud.google.com/tpu/docs/ml-diagnostics/workload-monitoring"
       }
     ]
   }
 ],
 "displayName": "Performance degradation - 2026-05-01T12:00:00Z",
 "endTime": "2026-05-01T12:10:00Z",
 "name": "projects/PROJECT_ID/locations/us-central1/machineLearningRuns/my-run-123/monitoredEvents/abc-123-def-456",
 "startTime": "2026-05-01T12:00:00Z",
 "type": "PERFORMANCE_DEGRADATION"
}