Erste Schritte mit der ML Diagnostics CLI

Mit der Google Cloud CLI für ML Diagnostics können Sie einen Lauf für maschinelles Lernen erstellen, XProf als verwaltete Instanz mit einem skalierbaren Backend bereitstellen und eine verwaltete Profilerstellung auf Google Cloudermöglichen.

Es gibt zwei Kategorien von gcloud CLI-Befehlen für ML Diagnostics: machine-learning-run-Befehle und profiler-Befehle. Verwenden Sie die machine-learning-run-Befehle, um Machine-Learning-Läufe zu erstellen, zu löschen, zu beschreiben, aufzulisten und zu aktualisieren. Verwenden Sie die profiler-Befehle, um Knoten aufzulisten und On-Demand-Profile über die Befehlszeile zu erfassen.

Machine-learning-run-Befehle: Create, Delete, Describe, List, Update.
Profiler-Befehle:
- profiler-target: List
- profiler-session: Capture, List

Für alle gcloud CLI-Befehle ist ein in der Umgebung definiertes Projekt erforderlich. So legen Sie das Projekt fest:

gcloud config set project PROJECT_ID

Weitere Informationen zu den gcloud CLI-Befehlen für ML Diagnostics finden Sie in der API-Referenz.

Aufnahmeprofile

Sie können XProf-Profile Ihrer ML-Arbeitslast mit programmatischer oder On-Demand-Erfassung (manuelle Erfassung) erfassen. Bei der programmatischen Erfassung werden Profiling-Befehle direkt in Ihren Machine-Learning-Code eingebettet und Sie geben explizit an, wann die Aufzeichnung von Daten gestartet und beendet werden soll. Die On-Demand-Erfassung erfolgt in Echtzeit. Sie lösen den Profiler aus, während die Arbeitslast bereits aktiv ausgeführt wird.

Um die On-Demand-Profilerfassung zu aktivieren, müssen Sie den XProf-Server in Ihrem Code starten und die Methode profiler.start_server aufrufen. Dadurch wird ein XProf-Server für Ihre ML-Arbeitslast gestartet. Dieser wartet auf den Trigger für die On-Demand-Erfassung, der die Erfassung von Profilen startet. Verwenden Sie für diesen Befehl Port 9999: profiler.start_server(port=9999)

Sowohl bei der programmatischen als auch bei der On-Demand-Profilaufzeichnung müssen Sie den Speicherort für die erfassten Profile angeben. Beispiel: gs://my-bucket/my-run. Profile werden in Verzeichnissen gespeichert, die sich am folgenden Speicherort befinden:gs://my-bucket/my-run/plugins/profile/session1/. Die programmatische Profilerfassung und die On-Demand-Erfassung dürfen nicht gleichzeitig erfolgen.

Für die On-Demand-Profilerstellung richten Sie einen GKE-Cluster ein und stellen Sie eine Arbeitslast mit dem Label managed-mldiagnostics-gke=true bereit.

Weitere Informationen zur Profilerstellung mit JAX finden Sie unter Profilerstellung für Berechnungen.

Machine-Learning-Ausführung erstellen

Erstellt eine Machine-Learning-Ausführungsressource in einem angegebenen Projekt und an einem angegebenen Standort. Mit dem Befehl machine-learning-run create wird XProf als verwaltete Instanz in Ihrem Projekt bereitgestellt. Die verwaltete XProf-Instanz wird zum Ansehen aller Profile im Projekt verwendet und wird erstellt, wenn der erste Machine-Learning-Lauf im Projekt erstellt wird.

Führen Sie den Befehl machine-learning-run create aus:

gcloud alpha mldiagnostics machine-learning-run create

Es gibt zwei Möglichkeiten, eine Machine-Learning-Ausführung zu erstellen:

Vorhandene erfasste Profile auf der ML Diagnostics-Plattform registrieren
Mit ML Diagnostics können Sie eine On-Demand-Profilerfassung durchführen, indem Sie eine aktive Ausführung registrieren. Dazu ist ein GKE-Cluster und eine bereitgestellte Arbeitslast in GKE mit dem Label managed-mldiagnostics-gke=true erforderlich.

ML-Lauf erstellen und vorhandene erfasste Profile registrieren

Mit dem folgenden Code wird ein Lauf erstellt und vorhandene erfasste Profile werden bei ML Diagnostics registriert:

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"

Im Codebeispiel werden die folgenden Flags verwendet:

Flag	Anforderung	Beschreibung
`machine-learning-run`	Erforderlich	Eine eindeutige Kennung für diesen bestimmten Lauf. Wenn der Name nicht eindeutig ist, schlägt die Erstellung des Laufs mit der Meldung „ML Run already exists“ (ML-Lauf ist bereits vorhanden) fehl.
`location`	Erforderlich	Alle Cluster Director-Standorte werden unterstützt, mit Ausnahme von `us-east5`. Dieses Flag kann für jeden Befehl mit einem Argument oder mit dem Befehl `gcloud config set compute/region` festgelegt werden.
`gcs-path`	Erforderlich	Der Google Cloud Speicherort, an dem alle Profile gespeichert werden. Beispiel: `gs://my-bucket` oder `gs://my-bucket/folder1` Nur erforderlich, wenn das SDK zum Erfassen von Profilen verwendet wird.
`run-group`	Optional	Eine Kennung, mit der mehrere Läufe derselben Testgruppe zusammengefasst werden können. Beispielsweise können alle Läufe, die mit einem Sweep der TPU-Slice-Größe verknüpft sind, zur selben Gruppe gehören.
`display-name`	Optional	Anzeigename für den Machine-Learning-Lauf. Wenn nicht angegeben, wird sie auf die ID des Machine-Learning-Laufs festgelegt.

Das Flag --labels list_existing_sessions_only=true ist erforderlich, wenn Sie vorhandene erfasste Profile in der ML-Diagnose ansehen und verwalten möchten. Das Flag bewirkt Folgendes:

Erstellt eine Machine-Learning-Ausführung mit dem Status „Abgeschlossen“.
Sucht rekursiv nach xplane.pb-Dateien im Cloud Storage-Verzeichnispfad.
Lädt alle gefundenen Profilsitzungen in die ML Diagnostics-Datenbank, damit sie in Google Cloudangezeigt werden können, erstellt freigabefähige Links für die Profilsitzungen und ermöglicht Nutzern, diese Profile mit der ML Diagnostics-Plattform zu verwalten.

Wenn das Flag --labels list_existing_sessions_only für einen Lauf auf true gesetzt ist, können Sie kein On-Demand-Profiling durchführen oder den Lauf aktualisieren. Sie können nur vorhandene Profile ansehen und verwalten.

ML-Ausführung erstellen, um On-Demand-Profile zu erfassen

Mit dem folgenden Code wird ein mlrun erstellt, um ein On-Demand-Profil zu erfassen:

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

Zusätzlich zu den Flags aus dem vorherigen Beispiel werden im Codebeispiel die folgenden zusätzlichen Flags verwendet:

Flag	Anforderung	Beschreibung
`orchestrator`	Optional	Der für den Lauf verwendete Orchestrator. Falls nichts angegeben wird, wird standardmäßig `gke` verwendet. Zulässige Werte: `gce`, `gke`, `slurm`.
`gke-cluster-name`	Für GKE erforderlich	Der Cluster der Arbeitslast. Beispiel: `/projects/<project_id>/locations/<location>/clusters/<cluster_name>`.
`gke-kind`	Für GKE erforderlich	Die Art der Arbeitslast. Beispiel: `JobSet`.
`gke-namespace`	Für GKE erforderlich	Der Namespace der Arbeitslast. Beispiel: `default`.
`gke-workload-name`	Für GKE erforderlich	Die ID der Arbeitslast. Beispiel: `jobset-abcd`.
`gke-workload-create-time`	Für GKE erforderlich	Der Erstellungszeitstempel für ein JobSet im ISO-Zeitstempelformat. Beispiel: `2026-02-20T06:00:00Z`.
`run-phase`	Optional	Phase und Status eines Laufs. Wenn keine Angabe erfolgt, wird standardmäßig `ACTIVE` verwendet.

Machine-Learning-Ausführung beschreiben

Rufen Sie die Details eines Machine-Learning-Laufs mit dem Befehl machine-learning-run describe auf:

gcloud alpha mldiagnostics machine-learning-run describe RUN_NAME --FORMAT=FORMAT

Das folgende Beispiel zeigt eine Anfrage für Laufdetails in JSON:

gcloud alpha mldiagnostics machine-learning-run describe my-run-on-demand \
  --format json

Die Ausgabe sieht etwa so aus:

{
  "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-Ausführungen auflisten

Mit dem Befehl machine-learning-run list können Sie eine Liste der Machine-Learning-Ausführungen in einem angegebenen Projekt und an einem angegebenen Standort abrufen:

gcloud alpha mldiagnostics machine-learning-run list

Das folgende Beispiel ist eine Anfrage für eine Liste mit bis zu zwei Läufen mit Ausgaben ihrer URI-Pfade:

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

Machine-Learning-Ausführungen aktualisieren

Aktualisieren Sie eine Machine-Learning-Ausführung in einem angegebenen Projekt und an einem angegebenen Standort. Sie können den Anzeigenamen, die Ausführungsphase, den Orchestrator und die GKE-Arbeitslastdetails aktualisieren. Du kannst die Lauf-ID und den Ort nicht ändern. Aktualisieren Sie einen Lauf mit dem Befehl machine-learning-run update:

gcloud alpha mldiagnostics machine-learning-run update

Geben Sie alle Felder an, die in der create-Anfrage enthalten waren. Wenn bei einer Aktualisierungsanfrage keine Pflichtfelder angegeben werden, werden sie durch die Standardwerte überschrieben.

Das Flag etag ist ein Pflichtfeld und sollte den neuesten ETag-Wert (Entity-Tag) für eine ML-Laufzeitressource enthalten. Weitere Informationen finden Sie unter ETags für die optimistische Gleichzeitigkeitssteuerung verwenden. So finden Sie den richtigen ETAG-Wert:

gcloud alpha mldiagnostics machine-learning-run describe RUN_NAME

Das folgende Beispiel zeigt eine vollständige Aktualisierungsanfrage:

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-Ausführungen löschen

Mit dem Befehl machine-learning-run delete können Sie eine Machine-Learning-Ausführung in einem angegebenen Projekt und einer angegebenen Zone löschen:

gcloud alpha mldiagnostics machine-learning-run delete RUN_NAME

Durch das Löschen eines ML-Laufs werden keine Daten in Cloud Storage, Cloud Logging oder der GKE-Arbeitslast gelöscht. Wenn Sie mlrun löschen, werden nur Metadaten zum Lauf im ML Diagnostics-System gelöscht.

Profiler-Befehle

Mit der Profiler-Befehlsgruppe können Sie alle Profile auflisten, GKE-Knoten der Arbeitslast finden, auf denen der XProf-Server ausgeführt wird, und On-Demand-Profile über die Befehlszeile erfassen.

Profiler-Ziele auflisten

Alle Profiler-Ziele auflisten, die mit einer Ausführung von maschinellem Lernen in einem angegebenen Projekt und an einem angegebenen Standort verknüpft sind:

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

Für diesen Befehl ist Folgendes erforderlich:

On-Demand-Xprof ist in der Arbeitslast aktiviert. Dadurch wird der XProf-Server auf allen Knoten der Arbeitslast bereitgestellt.
Der GKE-Cluster ist für ML Diagnostics eingerichtet und Webhook und Operator sind bereitgestellt.
Die Arbeitslast wurde in GKE mit dem Label managed-mldiagnostics-gke=true bereitgestellt.

Hier ein Beispiel für eine Anfrage:

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

Das folgende Beispiel zeigt die Ausgabe:

---
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-Sitzungen auflisten

Mit dem folgenden Befehl können Sie alle Profiler-Sitzungen auflisten, die einer Ausführung von maschinellem Lernen in einem angegebenen Projekt und an einem angegebenen Standort zugeordnet sind:

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

Für diesen Profiler-Befehl ist keine Einrichtung von GKE oder Arbeitslasten erforderlich. Dort werden alle Profilsitzungen aufgeführt, sowohl programmatische als auch On-Demand-Sitzungen. Wenn Sie nur programmatische Profilerfassungen haben, verwenden Sie diesen Befehl, um alle Profilsitzungen aufzulisten. Es ist keine GKE-Einrichtung, GKE-Arbeitslastkennzeichnung oder On-Demand-XProf-Aktivierung erforderlich.

Hier ein Beispiel für eine Anfrage:

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

On-Demand-Profilerstellungssitzungen erfassen

Sie können eine On-Demand-Profilersitzung für eine Ausführung von maschinellem Lernen auf einer bestimmten Gruppe von Knoten erfassen, auf denen die Arbeitslast ausgeführt wird (Profiler-Ziele).

Für diesen Befehl ist Folgendes erforderlich:

On-Demand-XProf ist in der Arbeitslast aktiviert. Der XProf-Server wird auf allen Knoten der Arbeitslast bereitgestellt.
Der GKE-Cluster ist für ML Diagnostics eingerichtet und Webhook und Operator sind bereitgestellt.
Die Arbeitslast wurde in GKE mit dem Label managed-mldiagnostics-gke=true bereitgestellt.

Hier ein Beispiel für eine Anfrage:

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

In diesem Beispiel werden die folgenden Flags verwendet:

Flag	Anforderung	Beschreibung
`profiler-session-name`	Erforderlich	Name der zu erfassenden Profiler-Sitzung.
`duration`	Erforderlich	Dauer der Profilerstellungssitzung. Sie ist vom Typ `Duration`. Geben Sie beispielsweise eine Dauer von `1s` für 1 Sekunde, `400ms` für 400 Millisekunden und `5m` für 5 Minuten an.
`targets`	Erforderlich	IDs der Profiler-Ziele oder vollqualifizierte Kennzeichnungen für die Profiler-Ziele. Muss mit einer Liste von Zielen übereinstimmen, die mit dem Lauf verknüpft sind.
`device-tracer-level`	Optional	Geräte-Tracer-Ebene für die Sitzung. Akzeptierte Werte: `device-tracer-level-enabled`, `device-tracer-level-disabled` (Standard).
`host-tracer-level`	Optional	Host-Tracer-Ebene für die Sitzung. Zulässige Werte: `host-tracer-level-info` (Standard), `host-tracer-level-critical`, `host-tracer-level-disabled`, `host-tracer-level-verbose`.
`python-tracer-level`	Optional	Python-Tracer-Ebene für die Sitzung. Akzeptierte Werte: `python-tracer-level-disabled` (Standard), `python-tracer-level-enabled`.