Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Erste Schritte mit der ML Diagnostics CLI

Mit der ML Diagnostics Google Cloud CLI können Sie Machine-Learning- Ausführungen erstellen und verwalten, XProf als verwaltete Instanz mit einem skalierbaren Backend bereitstellen und eine verwaltete Profilerstellung in durchführen Google Cloud. Sie können auch alle von der Arbeitslastüberwachung erkannten Ereignisse auflisten und über die CLI oder API Analysedetails für diese Ereignisse abrufen.

Es gibt drei Kategorien von ML Diagnostics gcloud CLI-Befehlen: machine-learning-run, profiler und monitored-events. Mit den machine-learning-run-Befehlen können Sie Machine-Learning-Ausführungen erstellen, löschen, beschreiben, auflisten und aktualisieren. Mit den profiler-Befehlen können Sie Knoten auflisten und On-Demand-Profile über die CLI erfassen. Mit den monitored-events-Befehlen können Sie alle von der Arbeitslastüberwachung erkannten Ereignisse auflisten und Analysedetails für jedes Ereignis abrufen.

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

Für alle gcloud CLI-Befehle muss ein Projekt in der Umgebung definiert sein. So legen Sie das Projekt fest:

gcloud config set project PROJECT_ID

Weitere Informationen zu den ML Diagnostics gcloud CLI-Befehlen finden Sie unter der API-Referenz.

Profile erfassen

Sie können XProf-Profile Ihrer ML-Arbeitslast programmatisch oder on demand (manuelle Erfassung) erfassen. Bei der programmatischen Erfassung werden Profilerstellungsbefehle 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-Profilerstellung 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-Profilerstellung 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 Profilerstellung und die On-Demand-Profilerstellung dürfen nicht während desselben Zeitraums erfolgen.

Für die On-Demand-Profilerstellung richten Sie einen GKE-Cluster ein, in dem connection-operator installiert wird. Für die programmatische Profilerstellung richten Sie einen GKE-Cluster ein, in dem injection-webhook installiert wird. Verwenden Sie dazu das ML Diagnostics SDK und kennzeichnen Sie die Arbeitslast.

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

Machine-Learning-Ausführung erstellen

Erstellen Sie 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 verwendet, um alle Profile im Projekt anzusehen. Sie wird erstellt, wenn die erste Machine-Learning-Ausführung im Projekt erstellt wird.

Verwenden Sie den Befehl machine-learning-run create:

gcloud alpha mldiagnostics machine-learning-run create

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

Registrieren Sie vorhandene erfasste Profile auf der ML Diagnostics-Plattform.
Verwenden Sie ML Diagnostics, um eine On-Demand-Profilerstellung durchzuführen, indem Sie eine aktive Ausführung registrieren. Dazu ist eine GKE-Clusterkonfiguration erforderlich.

ML-Ausführung erstellen und vorhandene erfasste Profile registrieren

Mit dem folgenden Code wird eine Ausführung erstellt und vorhandene erfasste Profile werden in 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 diese bestimmte Ausführung. Wenn der Name nicht eindeutig ist, schlägt die Erstellung der Ausführung mit der Meldung „ML Run already exists“ fehl.
`location`	Erforderlich	Alle Cluster Director-Standorte werden unterstützt, außer `us-east5`. Dieses Flag kann mit einem Argument für jeden Befehl oder mit dem Befehl: `gcloud config set compute/region` festgelegt werden.
`gcs-path`	Erforderlich	Der Cloud Storage-Speicherort, an dem alle Profile gespeichert werden. Google Cloud Beispiel: `gs://my-bucket` oder `gs://my-bucket/folder1`. Nur erforderlich, wenn das SDK für die Profilerstellung verwendet wird.
`run-group`	Optional	Eine Kennung, mit der mehrere Ausführungen gruppiert werden können, die zum selben Experiment gehören. Beispielsweise könnten alle Ausführungen, die mit einer TPU-Slice-Größen optimierung verknüpft sind, zur selben Gruppe gehören.
`display-name`	Optional	Anzeigename für die Machine-Learning-Ausführung. Wenn keine Angabe erfolgt, wird die ID der Machine-Learning-Ausführung verwendet.

Das Flag --labels list_existing_sessions_only=true ist erforderlich, wenn Sie vorhandene erfasste Profile in ML Diagnostics 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 in Google Cloudangesehen 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 eine Ausführung auf true gesetzt ist, können Sie keine On-Demand-Profilerstellung durchführen oder die Ausführung aktualisieren. Sie können nur vorhandene Profile ansehen und verwalten.

ML-Ausführung erstellen, um eine On-Demand-Profilerstellung durchzuführen

Mit dem folgenden Code wird eine mlrun erstellt, um eine On-Demand-Profilerstellung durchzuführen:

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

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

Flag	Anforderung	Beschreibung
`orchestrator`	Optional	Der für die Ausführung verwendete Orchestrator. Wenn nichts angegeben ist, wird standardmäßig `gke` verwendet. Gültige Werte: `gce`, `gke`, `slurm`.
`gke-cluster-name`	Erforderlich für GKE	Der Cluster der Arbeitslast. Beispiel: `/projects/<project_id>/locations/<location>/clusters/<cluster_name>`.
`gke-kind`	Erforderlich für GKE	Die Art der Arbeitslast. Beispiel: `JobSet`.
`gke-namespace`	Erforderlich für GKE	Der Namespace der Arbeitslast. Beispiel: `default`.
`gke-workload-name`	Erforderlich für GKE	Die Kennung der Arbeitslast. Beispiel: `jobset-abcd`.
`gke-workload-create-time`	Erforderlich für GKE	Der Zeitstempel der Erstellung für ein JobSet im ISO-Zeitstempelformat. Beispiel: `2026-02-20T06:00:00Z`.
`run-phase`	Optional	Phase und Status einer Ausführung. Wenn nichts angegeben ist, wird standardmäßig `ACTIVE` verwendet.

Machine-Learning-Ausführung beschreiben

Mit dem Befehl machine-learning-run describe können Sie die Details einer Machine-Learning-Ausführung ansehen:

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

Das folgende Beispiel zeigt eine Anfrage nach Ausführungsdetails im JSON-Format:

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 zeigt eine Anfrage nach einer Liste von bis zu zwei Ausführungen 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. Die Ausführungs-ID und der Standort können nicht geändert werden. Aktualisieren Sie eine Ausführung 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 der Aktualisierungsanfrage keine Pflichtfelder angegeben werden, werden sie durch die Standardwerte überschrieben.

Das Flag etag ist ein Pflichtfeld und sollte der aktuelle ETag-Wert (Entity-Tag) für eine ML-Ausführungsressource sein. Weitere Informationen finden Sie unter Entity-Tags für die optimistische Nebenläufigkeitserkennung verwenden. Verwenden Sie Folgendes, um den richtigen ETag-Wert zu finden:

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 an einem angegebenen Standort löschen:

gcloud alpha mldiagnostics machine-learning-run delete RUN_NAME

Durch das Löschen einer ML-Ausführung werden keine Daten in Cloud Storage, Cloud Logging oder der GKE-Arbeitslast gelöscht. Durch das Löschen von mlrun werden nur Metadaten im Zusammenhang mit der Ausführung im ML Diagnostics-System gelöscht.

Profiler-Befehle

Mit der Befehlsgruppe „Profiler“ 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 CLI erfassen.

Profiler-Ziele auflisten

Listen Sie alle Profiler-Ziele auf, die mit einer Machine-Learning-Ausführung 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 ist in GKE bereitgestellt.

Das folgende Beispiel zeigt 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 mit einer Machine-Learning-Ausführung in einem angegebenen Projekt und an einem angegebenen Standort verknüpft sind:

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

Für diesen Profiler-Befehl ist keine GKE- oder Arbeitslastkonfiguration erforderlich. Es werden alle Profilsitzungen aufgelistet, sowohl programmatische als auch On-Demand-Sitzungen. Wenn Sie nur programmatische Profilerstellungen haben, verwenden Sie diesen Befehl, um alle Profilsitzungen aufzulisten. Es ist keine GKE-Einrichtung, keine GKE-Arbeitslastkennzeichnung und keine On-Demand-XProf-Aktivierung erforderlich.

Das folgende Beispiel zeigt 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-Profilerstellungssitzung für eine Machine-Learning-Ausführung 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. 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 ist in GKE bereitgestellt.

Das folgende Beispiel zeigt eine Anfrage:

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

Im Beispiel werden die folgenden Flags verwendet:

Flag	Anforderung	Beschreibung
`profiler-session-name`	Erforderlich	Name der zu erfassenden Profilerstellungssitzung.
`duration`	Erforderlich	Dauer für die Erfassung der Profilerstellungssitzung. Der Typ ist `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 Kennungen für die Profiler-Ziele. Muss mit einer Liste von Zielen übereinstimmen, die mit der Ausführung verknüpft sind.
`device-tracer-level`	Optional	Geräte-Tracer-Ebene für die Sitzung. Zulässige 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. Zulässige Werte: `python-tracer-level-disabled` (Standard), `python-tracer-level-enabled`.

`monitored-events`-Befehle

Mit den monitored-events-Befehlen können Sie alle von der Arbeitslastüberwachung erkannten Ereignisse auflisten und Analysedetails für jedes Ereignis abrufen.

`monitored-events` auflisten

Listen Sie alle von der Arbeitslastüberwachung erkannten Ereignisse auf, die mit einer Machine-Learning-Ausführung verknüpft sind.

Das folgende Beispiel zeigt eine Anfrage:

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

Das folgende Beispiel zeigt die Ausgabe:

[
 {
   "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
]

`monitored-events` beschreiben

Rufen Sie Analysedetails für jedes der von der Arbeitslastüberwachung erkannten Ereignisse ab, die mit einer Machine-Learning-Ausführung verknüpft sind.

Das folgende Beispiel zeigt eine Anfrage:

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

Das folgende Beispiel zeigt die Ausgabe:

{
 "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"
}