开始使用 ML Diagnostics CLI

使用 ML Diagnostics Google Cloud CLI 创建机器学习运行，将 XProf 部署为具有可伸缩后端的受管实例，并在 Google Cloud上提供受管的分析体验。

ML 诊断 gcloud CLI 命令分为两类：machine-learning-run 命令和 profiler 命令。使用 machine-learning-run 命令可创建、删除、描述、列出和更新机器学习运行。使用 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 参考文档。

捕获配置文件

您可以通过程序化捕获或按需捕获（手动捕获）来捕获机器学习工作负载的 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 诊断平台。
通过注册有效运行，使用 ML Diagnostics 执行按需性能分析文件捕获。这需要设置 GKE 集群，并在 GKE 上部署带有标签 managed-mldiagnostics-gke=true 的工作负载。

创建 ML 运行并注册现有的捕获配置文件

以下代码会创建一个运行，并将现有的捕获配置文件注册到 ML 诊断：

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。

如果您想在 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 所需的	工作负载的标识符。例如：`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 诊断系统中的运行相关的元数据。

性能分析器命令

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

列出分析器目标

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

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

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

工作负载中已启用按需 XProf，这会将 XProf 服务器部署到工作负载的所有节点中。
GKE 集群已设置为支持 ML 诊断，并已部署 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`。例如，指定 `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`。