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

Fehlerbehebung mit dem ML Workload Debugging Wiki

Das ML Workload Debugging Wiki ist ein GitHub-Repository, das KI-Codierungs-Agents verwenden, um Fehler in TPU-Arbeitslasten zu beheben, die in der Google Kubernetes Engine (GKE) mit JAX, XLA oder Pathways ausgeführt werden. Das Wiki ermöglicht es KI-Agenten, Arbeitslastprotokolle zu erfassen, Fehlersignaturen mit bekannten Fehlermodi abzugleichen, Diagnose-Workflows auszuführen und Ursachen basierend auf Protokollen zu melden. So erhalten die Kundenservicemitarbeiter die Informationen, die sie für die Diagnose von Abstürzen, Hängern, Neustarts oder Preemptions von Arbeitslasten benötigen.

Das Wiki enthält zwei Arten von Referenzmaterial:

Wissensseiten: Markdown-Seiten, auf denen Konzepte, Fehlersymptome und ihre Logsignaturen, Playbooks zur Fehlerbehebung und Diagnosetools beschrieben werden.
Ausführbare Verfahren: JSON-Aktionen und ‑Workflows. Eine Aktion ist ein einzelner Diagnoseschritt, z. B. eine Logabfrage oder ein kubectl-Befehl. Ein Workflow führt eine Abfolge von Aktionen aus, um einen bestimmten Fehlermodus zu diagnostizieren.

Wenn Sie den Befehl /troubleshoot ausführen, wird ein Team spezialisierter Sub-Agents die Arbeitslastlogs sichten, den Workflow auswählen und ausführen, der dem Fehler entspricht, und jede Schlussfolgerung mit den primären Logs abgleichen. Der Agent meldet dann die Ursache, die betroffenen Hosts, wie sie in den Logs zitiert werden, und eine Fehlertabelle, in der jede Störung zusammengefasst ist.

Schlüsseldateien

In der folgenden Tabelle sind die wichtigsten Dateien und Verzeichnisse im Debug ML Workloads Wiki aufgeführt:

Pfad	Beschreibung
`_wiki/TUTORIAL.md`	Eine Erläuterung der Vorgänge während einer Diagnose und der Auswertung der Ergebnisse, einschließlich eines Beispiels.
`_wiki/INDEX.md`	Ein Katalog aller Seiten, Aktionen und Workflows im Wiki mit einer einzeiligen Zusammenfassung für jeden Eintrag.
`_wiki/concepts/`	Konzepte der Systemarchitektur und des Komponentenlebenszyklus, z. B. der Lebenszyklus des libtpu-Programms, Goodput und die Überwachung des Arbeitslastfortschritts.
`_wiki/entities/`	Hardware-, Software- und Plattformentitäten wie TPU, GPU, JAX, XLA und Pathways.
`_wiki/symptoms/`	Fehlermodi, ihre Protokollsignaturen und wie sie jeweils überprüft werden können.
`_wiki/playbooks/`	Strategien zur Fehlerbehebung, Flussdiagramme für Entscheidungsbäume und häufige Fallstricke.
`_wiki/tools/`	Diagnosetools, Skripts und Referenzhandbücher für die Befehlszeile.
`_wiki/workflows/`	Diagnoseverfahren im JSON-Format. In jedem Workflow wird eine Abfolge von Aktionen ausgeführt, um einen bestimmten Fehlermodus zu diagnostizieren.
`_wiki/actions/`	Einzelne Diagnoseschritte im JSON-Format, z. B. Logabfragen und `kubectl`-Befehle.
`_wiki/SCHEMA.md`	Die Seitentypen, Frontmatter-Anforderungen und Taxonomie-Tags, die Wiki-Seiten erfüllen müssen.
`_agents/QUICKSTART.md`	Einrichtungs- und Versanddetails für Antigravity-Nutzer.
`CLAUDE.md`	Das Arbeitsbereichslayout, die Befehlszeilentools und die Subagentenrollen für Claude Code-Nutzer.

Wichtige Befehle

In der folgenden Tabelle sind die Befehle aufgeführt, die Sie mit dem Wiki ausführen können:

Befehl Nutzung Beschreibung

/troubleshoot /troubleshoot WORKLOAD_ID, wobei WORKLOAD_ID der Name der Arbeitslast oder des JobSets ist. Diagnostiziert eine Arbeitslast mithilfe von Cloud Logging, GKE-Clusterereignissen, Kubelet-Logs und Knotenlogs. Die Sub-Agents für Router, Practitioner, Reviewer und Advisor führen die Diagnose aus und melden die Ursache, die betroffenen Hosts, wie in den Logs angegeben, und eine Fehlertabelle.

/dashboard /dashboard [TARGET], wobei TARGET eine optionale Projekt-ID, ein Clustername oder eine Arbeitslast-ID ist. Wenn Sie TARGET weglassen, werden im Dashboard alle GKE-Cluster im Projekt angezeigt, das in Ihrer Google Cloud CLI-Konfiguration festgelegt ist. Startet das GKE-Dashboard für Kapazität und Triage, eine lokale Webanwendung unter http://localhost:8080. Der Befehl scannt die Cluster nach dem Ziel und gibt dann einen Link zu einer Dashboard-Ansicht zurück, die nach dem Ziel gefiltert ist.

Befehl	Nutzung	Beschreibung
`/troubleshoot`	`/troubleshoot WORKLOAD_ID`, wobei `WORKLOAD_ID` der Name der Arbeitslast oder des JobSets ist.	Diagnostiziert eine Arbeitslast mithilfe von Cloud Logging, GKE-Clusterereignissen, Kubelet-Logs und Knotenlogs. Die Sub-Agents für Router, Practitioner, Reviewer und Advisor führen die Diagnose aus und melden die Ursache, die betroffenen Hosts, wie in den Logs angegeben, und eine Fehlertabelle.
`/dashboard`	`/dashboard [TARGET]`, wobei `TARGET` eine optionale Projekt-ID, ein Clustername oder eine Arbeitslast-ID ist. Wenn Sie `TARGET` weglassen, werden im Dashboard alle GKE-Cluster im Projekt angezeigt, das in Ihrer Google Cloud CLI-Konfiguration festgelegt ist.	Startet das GKE-Dashboard für Kapazität und Triage, eine lokale Webanwendung unter `http://localhost:8080`. Der Befehl scannt die Cluster nach dem Ziel und gibt dann einen Link zu einer Dashboard-Ansicht zurück, die nach dem Ziel gefiltert ist.
`/handoff`	`/handoff WORKLOAD_ID [CASE_ID] [--bucket=BUCKET] [--findings=PATH] [--no-watch]` Alle Argumente außer `WORKLOAD_ID` sind optional: `CASE_ID`: Ihre Supportfallnummer. `--bucket=BUCKET`: der Name des Buckets. Wenn Sie dieses Flag weglassen, fragt der Agent nach einem Bucket. `--findings=PATH`: der Pfad zu einer vorhandenen Ergebnisdatei. Wenn Sie dieses Flag festlegen, wird `/troubleshoot` nicht vom Befehl ausgeführt. `--no-watch`: Deaktiviert das Bucket-Monitoring.	Verpackt `/troubleshoot`-Ergebnisse in einen Cloud Storage-Bucket, um sie mit Cloud Customer Care zu teilen, und überwacht den Bucket dann auf Aktualisierungen. Wenn Sie später nach Updates suchen möchten, führen Sie `/handoff --watch STORAGE_KEY` aus, wobei `STORAGE_KEY` der Name des Übergabeordners im Bucket ist.

/handoff

/handoff WORKLOAD_ID [CASE_ID] [--bucket=BUCKET] [--findings=PATH] [--no-watch]

Alle Argumente außer WORKLOAD_ID sind optional:

CASE_ID: Ihre Supportfallnummer.
--bucket=BUCKET: der Name des Buckets. Wenn Sie dieses Flag weglassen, fragt der Agent nach einem Bucket.
--findings=PATH: der Pfad zu einer vorhandenen Ergebnisdatei. Wenn Sie dieses Flag festlegen, wird /troubleshoot nicht vom Befehl ausgeführt.
--no-watch: Deaktiviert das Bucket-Monitoring.

Verpackt /troubleshoot-Ergebnisse in einen Cloud Storage-Bucket, um sie mit Cloud Customer Care zu teilen, und überwacht den Bucket dann auf Aktualisierungen. Wenn Sie später nach Updates suchen möchten, führen Sie /handoff --watch STORAGE_KEY aus, wobei STORAGE_KEY der Name des Übergabeordners im Bucket ist.

Vorbereitung

Bevor Sie das Wiki einrichten, müssen Sie die Arbeitslast identifizieren, die Sie diagnostizieren möchten, und die folgenden Details notieren:

Der Name der Arbeitslast oder des JobSets.
Die ID des Google Cloud -Projekts, in dem die Arbeitslast ausgeführt wird.
Der ungefähre Zeitraum der Ausführung, die diagnostiziert werden soll.

Installationen

Für das Wiki sind die folgenden Installationen erforderlich:

Installieren Sie Python 3, einschließlich des Moduls venv. Für das Wiki ist Python 3.9 oder höher erforderlich. Unter Debian und Ubuntu befindet sich das Modul venv im Paket python3-venv.
Installieren und initialisieren Sie das Google Cloud CLI.
Installieren Sie kubectl und gke-gcloud-auth-plugin.
Installieren Sie einen der folgenden KI-Agenten zum Programmieren. Das Wiki enthält Konfigurationsdateien für beide:
- Claude Code
- Google Antigravity

Erforderliche Rollen

Die Agenten führen Diagnosebefehle mit Ihren Google Cloud -Anmeldedaten aus. Weisen Sie dem Projekt, in dem die Arbeitslast ausgeführt wird, die folgenden IAM-Rollen zu, um eine Arbeitslast zu diagnostizieren:

Loganzeige (roles/logging.viewer): Ermöglicht den Agents, die Arbeitslastcontainer-, Knoten- und Audit-Logs zu lesen.
Kubernetes Engine-Betrachter (roles/container.viewer): Ermöglicht den Agents, den Cluster, die Knoten und die Pods zu prüfen, auf denen die Arbeitslast ausgeführt wurde.
Compute-Betrachter (roles/compute.viewer): Ermöglicht den Agents, die Compute Engine-VMs zu prüfen, die die Clusterknoten unterstützen, einschließlich VM-Wartungs- und Beendigungsereignissen.
Monitoring-Betrachter (roles/monitoring.viewer): Ermöglicht den Agents, Cloud Monitoring-Messwerte für Workflows zu lesen, die Arbeitslast- und Knotenmesswerte prüfen.

Zum Ausführen des Befehls /handoff benötigen Sie außerdem die Rolle „Storage-Objekt-Administrator“ (roles/storage.objectAdmin) für den Cloud Storage-Bucket, den Sie für Cloud Customer Care freigeben. Mit dieser Rolle können die Agenten Ergebnisse in den Bucket hochladen und auf Aktualisierungen überwachen.

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Wiki einrichten

Klonen Sie das Repository und rufen Sie das Stammverzeichnis auf:
```
git clone https://github.com/google/ml-workload-debugging-wiki.git
cd ./ml-workload-debugging-wiki
```
Das Wiki verwendet Pfade, die relativ zum Repository-Stammverzeichnis sind. Führen Sie die Befehle also aus und starten Sie Ihren Agenten in diesem Verzeichnis.
Erstellen und aktivieren Sie eine virtuelle Python-Umgebung und installieren Sie die Abhängigkeiten des Wikis:
```
python3 -m venv _wiki/.venv
source _wiki/.venv/bin/activate
pip install -r _wiki/requirements.txt
```
Erstellen Sie lokale Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) für Ihr Nutzerkonto. Die Python-Tools des Wikis verwenden Standardanmeldedaten für Anwendungen, um Cloud Logging abzufragen:
```
gcloud auth application-default login
```
Überprüfen Sie Ihre Einrichtung, indem Sie den Wiki-Linter ausführen:
```
python3 _wiki/wiki_linter.py
```
Der Linter prüft die Struktur, die Schemas und die Links des Wikis und gibt dann einen JSON-Bericht aus. Wenn der Bericht "status": "PASS" enthält, war die Prüfung erfolgreich. Warnungen im Bericht haben keine Auswirkungen auf den Status.

Fehlerbehebung bei einer Arbeitslast

So beheben Sie Probleme mit einer Arbeitslast mithilfe des ML-Arbeitslast-Debugging-Wikis:

Starten Sie den KI-Agenten im Stammverzeichnis des ML Workload Debugging Wiki-Repositorys:
- Claude Code: Führen Sie in der Shell, in der Sie die virtuelle Umgebung aktiviert haben, claude aus. Claude Code lädt die Anweisungen des Wikis aus CLAUDE.md und die Befehls- und Subagentendefinitionen aus dem Verzeichnis .claude/.
- Antigravity: Öffnen Sie das Stammverzeichnis des Repositorys als Arbeitsbereich. Die Definitionen für den Antigravity-Skill und die Sub-Agents des Wikis befinden sich im Verzeichnis _agents/. Informationen zur Einrichtung finden Sie unter _agents/QUICKSTART.md.
Führen Sie den Befehl /troubleshoot aus und geben Sie den Namen der Arbeitslast oder des JobSets an, die bzw. das Sie diagnostizieren möchten:
```
/troubleshoot WORKLOAD_ID
```
Geben Sie dem KI-Agenten die Projekt-ID und den Zeitraum der Ausführung an. Sie können einen genauen Zeitraum im UTC-Zeitstempelformat (YYYY-MM-DDTHH:MM:SSZ) oder relative Zeiträume in natürlicher Sprache angeben, z. B. „vor einer Stunde“ oder „letzte 24 Stunden“. Die KI-Agenten verwenden den Zeitraum, um ihre Logabfragen einzugrenzen. Achten Sie also darauf, dass er den gesamten Ausführungszeitraum abdeckt.

Bei Diagnose-Workflows werden standardmäßig schreibgeschützte Prüfungen ausgeführt. Bevor der Agent eine Aktion ausführt, die den Clusterstatus ändert, z. B. einen Knoten aus- und wieder einschaltet oder markiert, fordert er Ihre ausdrückliche Bestätigung an. Jeder Befehl muss überprüft und genehmigt werden. Diese Aktionen sind in ihren Definitionen in _wiki/actions/ mit requires_approval: true gekennzeichnet. Der KI-Agent meldet seine Ergebnisse, nachdem die Diagnose abgeschlossen ist.

Informationen zum Auswerten der Ergebnisse, einschließlich des Erkennens eines nicht aussagekräftigen Ergebnisses, finden Sie unter _wiki/TUTORIAL.md.