开始使用机器学习诊断 CLI

使用 ML Diagnostics Google Cloud CLI 创建和管理机器学习运行作业,将 XProf 部署为具有可伸缩后端的代管式实例,并在 Google Cloud上提供代管式性能分析体验。您还可以通过 CLI 或 API 列出工作负载监控检测到的所有事件,并获取这些事件的分析器详细信息。

下表总结了 ML Diagnostics 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 参考文档。

前提条件

在运行 ML Diagnostics gcloud CLI 命令之前,请先完成以下前提条件:

  1. 启用 Cluster Director API 并授予所需的 Identity and Access Management (IAM) 权限。如需了解详情,请参阅机器学习诊断前提条件。
  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 必填 此特定运行的唯一标识符。如果名称不唯一,则运行作业创建会失败,并显示以下消息:“ML 运行作业已存在”。
location 必填 除 us-east5 外,所有 Cluster Director 位置均受支持。此标志可通过每个命令的参数进行设置,也可通过以下命令进行设置:gcloud config set compute/region。
gcs-path 必填 Google Cloud 保存所有配置文件的存储位置。 例如:gs://my-bucket 或 gs://my-bucket/folder1。 仅当 SDK 用于配置文件捕获时才需要。
run-group 可选 一个标识符,可帮助将属于同一实验的多次运行归为一组。例如,与 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 必需 工作负载的标识符。例如: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 标志是必填字段,应为机器学习运行资源的最新 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 只会删除 ML Diagnostics 系统中与运行相关的元数据。

开始持续分析

启用持续分析后,机器学习诊断平台会持续在 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 目标。

如需将缓冲的跟踪记录数据保存为性能分析器会话,请使用带有 --kind=snapshot 标志的 profiler-session capture 命令:

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。

性能分析器命令

您可以使用 profiler 命令组列出所有性能分析文件、查找运行 XProf 服务器的工作负载的 GKE 节点、捕获按需性能分析文件,以及通过 CLI 捕获持续分析快照。

列出性能分析器目标

列出与指定项目和位置中的机器学习运行关联的所有性能分析器目标:

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

此命令需要满足以下条件:

  • 在工作负载中启用按需 XProf,这会将 XProf 服务器部署到工作负载的所有节点中。
  • GKE 集群已针对 ML Diagnostics 进行设置,并部署了 webhook 和 Operator 或 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

此 Profiler 命令不需要 GKE 或工作负载设置。其中列出了所有性能分析会话,包括程序化、按需和持续分析快照会话。如果您只有程序化配置文件捕获,请使用此命令列出所有配置文件会话。无需进行 GKE 设置、GKE 工作负载标记或按需 XProf 启用。

以下是请求示例:

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

捕获性能分析器会话

您可以捕获按需性能分析器会话,也可以跨活跃机器学习运行的一个或多个性能分析器目标保存持续分析快照。

配置文件捕获需要满足以下条件:

  • 在工作负载中启用按需 XProf,这会将 XProf 服务器部署到工作负载的所有节点中。
  • GKE 集群已针对 ML Diagnostics 进行设置,并部署了 webhook 和 Operator 或 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 或性能分析器目标的完全限定标识符。必须与和运行关联的目标列表匹配。
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"
}