Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

开始使用 ML Diagnostics CLI

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

ML Diagnostics gcloud CLI 命令分为三类：machine-learning-run、profiler 和 monitored-events 命令。使用 machine-learning-run 命令创建、删除、描述、列出和更新机器学习运行作业。使用 profiler 命令列出节点并从 CLI 捕获按需性能分析文件。使用 monitored-events 命令列出工作负载监控检测到的所有事件，并接收每个事件的分析器详细信息。

Machine-learning-run 命令：Create、Delete、Describe、List、Update。
Monitored-events 命令：Describe、List
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/。程序化性能分析文件捕获和按需捕获不得在同一时间段内进行。

对于按需性能分析文件捕获，请设置安装 connection-operator 的 GKE 集群。对于程序化性能分析文件捕获，请设置安装 injection-webhook 的 GKE 集群，使用 ML Diagnostics SDK 并为工作负载添加标签。

如需详细了解如何使用 JAX 进行性能分析，请参阅性能分析计算。

创建机器学习运行作业

在指定的项目和位置中创建机器学习运行作业资源。machine-learning-run create 命令会将 XProf 部署为项目中的托管实例。托管 XProf 实例用于查看项目中的所有性能分析文件，并且是在项目中创建第一个机器学习运行作业时创建的。

使用 machine-learning-run create 命令：

gcloud alpha mldiagnostics machine-learning-run create

您可以通过两种方式创建机器学习运行作业：

将现有捕获的性能分析文件注册到 ML Diagnostics 平台。
通过注册活跃运行作业，使用 ML Diagnostics 执行按需性能分析文件捕获。这需要设置 GKE 集群。

创建机器学习运行作业并注册现有捕获的性能分析文件

以下代码会创建一个运行作业，并将现有捕获的性能分析文件注册到 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` 之外，所有 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。

如果您想在 ML Diagnostics 中查看和管理现有收集的性能分析文件，则需要使用 --labels list_existing_sessions_only=true 标志。该标志的作用如下：

创建一个状态为“Completed”的机器学习运行作业。
以递归方式搜索 Cloud Storage 目录路径中的 xplane.pb 文件。
将所有找到的性能分析会话加载到 ML Diagnostics 数据库中以供查看 in 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 系统中与运行作业相关的元数据。

Profiler 命令

您可以使用 Profiler 命令组列出所有性能分析文件，查找运行 XProf 服务器的工作负载的 GKE 节点，并从 CLI 捕获按需性能分析文件。

列出 Profiler 目标

列出与指定项目和位置中的机器学习运行作业关联的所有 Profiler 目标：

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

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

工作负载中启用了按需 XProf，这会将 XProf 服务器部署到工作负载的所有节点中。
为 ML Diagnostics 设置了 GKE 集群，并部署了 Webhook 和运算符。
在 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

列出 Profiler 会话

使用以下命令列出与指定项目和位置中的机器学习运行作业关联的所有 Profiler 会话：

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

捕获按需 Profiler 会话

您可以为工作负载运行的指定节点集（Profiler 目标）上的机器学习运行作业捕获按需 Profiler 会话。

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

工作负载中启用了按需 XProf，这会将 XProf 服务器部署到工作负载的所有节点中
为 ML Diagnostics 设置了 GKE 集群，并部署了 Webhook 和运算符
在 GKE 上部署了工作负载。

以下是请求示例：

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

该示例使用以下标志：

标志	要求	说明
`profiler-session-name`	必需	要捕获的 Profiler 会话的名称。
`duration`	必需	Profiler 会话捕获的时长。它是 `Duration` 类型。例如，指定时长 `1s` 表示 1 秒， `400ms` 表示 400 毫秒，以及 `5m` 表示 5 分钟。
`targets`	必需	Profiler 目标的 ID 或 Profiler 目标的完全限定标识符。必须与运行作业关联的目标列表匹配。
`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`。

Monitored-events 命令

您可以使用 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"
}