Risolvi i problemi con il wiki di debug dei workload ML

Il wiki per il debug dei workload di ML è un repository GitHub utilizzato dagli agenti di programmazione AI per risolvere i problemi dei workload TPU in esecuzione su Google Kubernetes Engine (GKE) con JAX, XLA o Pathways. Il wiki consente agli agenti AI di raccogliere i log dei workload, abbinare le firme degli errori alle modalità di errore note, eseguire workflow di diagnostica e segnalare le cause principali in base ai log. In questo modo, gli agenti dispongono delle informazioni necessarie per diagnosticare arresti anomali, blocchi, riavvii o prerilasci dei workload.

Il wiki contiene due tipi di materiale di riferimento:

  • Pagine di conoscenza: pagine Markdown che descrivono concetti, sintomi di errori e le relative firme dei log, playbook per la risoluzione dei problemi e strumenti di diagnostica.
  • Procedure eseguibili: azioni e workflow JSON. Un'azione è un singolo passaggio di diagnostica, ad esempio una query di log o un comando kubectl. Un workflow esegue una sequenza di azioni per diagnosticare una modalità di errore specifica.

Quando esegui il comando /troubleshoot, un team di subagenti specializzati esamina i log del workload, seleziona ed esegue il workflow corrispondente all'errore e confronta ogni conclusione con i log principali. L'agente segnala quindi la causa principale, gli host colpevoli citati nei log e una tabella degli errori che riassume ogni interruzione.

File di chiave

La tabella seguente elenca i file e le directory principali all'interno del wiki Debug ML Workloads:

Percorso Descrizione
_wiki/TUTORIAL.md Una procedura dettagliata di ciò che accade durante una diagnosi e di come valutare i risultati, incluso un esempio pratico.
_wiki/INDEX.md Un catalogo di ogni pagina, azione e workflow nel wiki, con un riepilogo di una riga per ciascuno.
_wiki/concepts/ Concetti di architettura di sistema e ciclo di vita dei componenti, come il ciclo di vita del programma libtpu, il goodput e il monitoraggio dell'avanzamento del workload.
_wiki/entities/ Entità hardware, software e della piattaforma, come TPU, GPU, JAX, XLA e Pathways.
_wiki/symptoms/ Modalità di errore, relative firme dei log e come verificarle.
_wiki/playbooks/ Strategie di risoluzione dei problemi, diagrammi di flusso degli alberi decisionali ed errori comuni.
_wiki/tools/ Strumenti di diagnostica, script e guide di riferimento per la riga di comando.
_wiki/workflows/ Procedure diagnostiche in JSON. Ogni workflow esegue una sequenza di azioni per diagnosticare una modalità di errore specifica.
_wiki/actions/ Singoli passaggi di diagnostica in JSON, come query di log e comandi kubectl.
_wiki/SCHEMA.md I tipi di pagina, i requisiti di frontmatter e i tag di tassonomia che le pagine wiki devono seguire.
_agents/QUICKSTART.md Dettagli di configurazione e invio per gli utenti di Antigravity.
CLAUDE.md Il layout dell'area di lavoro, gli strumenti a riga di comando e i ruoli dei subagenti per gli utenti di Claude Code.

Comandi principali

La tabella seguente elenca i comandi che puoi eseguire con il wiki:

Comando Utilizzo Descrizione
/troubleshoot /troubleshoot WORKLOAD_ID, dove WORKLOAD_ID è il nome del workload o del JobSet. Diagnostica un workload utilizzando Cloud Logging, gli eventi del cluster GKE, i log di kubelet e i log dei nodi. I subagenti router, practitioner, reviewer e advisor eseguono la diagnosi e segnalano la causa principale, gli host colpevoli citati nei log e una tabella degli errori.
/dashboard /dashboard [TARGET], dove TARGET è un ID progetto, un nome cluster o un ID workload facoltativo. Se ometti TARGET, la dashboard mostra tutti i cluster GKE nel progetto impostato nella configurazione di Google Cloud CLI. Avvia la dashboard di capacità e triage di GKE, un'app web locale all'indirizzo http://localhost:8080. Il comando analizza i cluster per la destinazione e restituisce un link a una visualizzazione della dashboard filtrata in base alla destinazione.
/handoff

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

Tutti gli argomenti, ad eccezione di WORKLOAD_ID, sono facoltativi:

  • CASE_ID: il numero della richiesta di assistenza.
  • --bucket=BUCKET: il nome del bucket. Se ometti questo flag, l'agente richiede un bucket.
  • --findings=PATH: il percorso di un file di risultati esistente. Se imposti questo flag, il comando non esegue /troubleshoot.
  • --no-watch: disattiva il monitoraggio del bucket.
 Pacchettizza i risultati di /troubleshoot in un bucket Cloud Storage da condividere con l'assistenza clienti Google Cloud, quindi monitora il bucket per verificare la presenza di aggiornamenti. Per verificare la presenza di aggiornamenti in un secondo momento, esegui /handoff --watch STORAGE_KEY, dove STORAGE_KEY è il nome della cartella di handoff nel bucket.

Prerequisiti

Prima di configurare il wiki, identifica il workload di cui vuoi eseguire la diagnostica e prendi nota dei seguenti dettagli:

  • Il nome del workload o del JobSet.
  • L'ID del progetto Google Cloud che esegue il workload.
  • L'intervallo di tempo approssimativo dell'esecuzione da diagnosticare.

Installazioni

Il wiki richiede le seguenti installazioni:

  1. Installa Python 3, incluso il modulo venv. Il wiki richiede Python 3.9 o versioni successive. Su Debian e Ubuntu, il modulo venv si trova nel pacchetto python3-venv.
  2. Installa e inizializza Google Cloud CLI.
  3. Installa kubectl e gke-gcloud-auth-plugin.
  4. Installa uno dei seguenti agenti di programmazione AI. Il wiki include i file di configurazione per entrambi:

Ruoli obbligatori

Gli agenti eseguono i comandi di diagnostica con le tue credenziali Google Cloud . Per diagnosticare un workload, concedi i seguenti ruoli IAM al progetto che esegue il workload:

  • Visualizzatore log (roles/logging.viewer): consente agli agenti di leggere i log dei container, dei nodi e di controllo del workload.
  • Visualizzatore Kubernetes Engine (roles/container.viewer): consente agli agenti di ispezionare il cluster, i nodi e i pod che hanno eseguito il workload.
  • Visualizzatore Compute (roles/compute.viewer): consente agli agenti di ispezionare le VM di Compute Engine che supportano i nodi del cluster, inclusi gli eventi di manutenzione e terminazione delle VM.
  • Visualizzatore Monitoring (roles/monitoring.viewer): consente agli agenti di leggere le metriche di Cloud Monitoring per i workflow che ispezionano le metriche di workload e nodi.

Per eseguire il comando /handoff, devi anche disporre del ruolo Storage Object Admin (roles/storage.objectAdmin) nel bucket Cloud Storage che condividi con l'assistenza clienti Google Cloud. Questo ruolo consente agli agenti di caricare i risultati nel bucket e di monitorarlo per verificare la presenza di aggiornamenti.

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Configura il wiki

  1. Clona il repository e vai alla relativa directory root:

    git clone https://github.com/google/ml-workload-debugging-wiki.git
cd ./ml-workload-debugging-wiki

    Il wiki utilizza percorsi relativi alla radice del repository, quindi esegui i comandi e avvia l'agente da questa directory.

  2. Crea e attiva un ambiente virtuale Python e installa le dipendenze del wiki:

    python3 -m venv _wiki/.venv
source _wiki/.venv/bin/activate
pip install -r _wiki/requirements.txt

  3. Crea Credenziali predefinite dell'applicazione (ADC) locali per il tuo account utente. Gli strumenti Python del wiki utilizzano ADC per eseguire query su Cloud Logging:

    gcloud auth application-default login

  4. Verifica la configurazione eseguendo il linter wiki:

    python3 _wiki/wiki_linter.py

    Il linter controlla la struttura, gli schemi e i link del wiki, quindi stampa un report JSON. Se il report contiene "status": "PASS", il controllo è andato a buon fine. Gli avvisi nel report non influiscono sullo stato.

Risolvi i problemi di un workload

Segui questi passaggi per risolvere i problemi di un workload con il wiki di debug del workload ML:

  1. Avvia l'agente dalla directory principale del repository wiki di debug del workload ML:

    • Claude Code: nella shell in cui hai attivato l'ambiente virtuale, esegui claude. Claude Code carica le istruzioni del wiki da CLAUDE.md e le definizioni dei comandi e dei subagenti dalla directory .claude/.
    • Antigravity: apri la directory root del repository come area di lavoro. Le definizioni delle skill e dei subagenti Antigravity del wiki si trovano nella directory _agents/. Per i dettagli sulla configurazione, vedi _agents/QUICKSTART.md.

  2. Esegui il comando /troubleshoot, specificando il nome del workload o del JobSet di cui vuoi eseguire la diagnostica:

    /troubleshoot WORKLOAD_ID

  3. Fornisci all'agente l'ID progetto e l'intervallo di tempo dell'esecuzione. Puoi fornire un intervallo di tempo preciso nel formato timestamp UTC (YYYY-MM-DDTHH:MM:SSZ) o intervalli di tempo relativi in linguaggio naturale, ad esempio "un'ora fa" o "ultime 24 ore". Gli agenti utilizzano l'intervallo di tempo per definire l'ambito delle query di log, quindi assicurati che copra l'intera esecuzione.

Per impostazione predefinita, i workflow diagnostici eseguono controlli di sola lettura. Prima che l'agente esegua un'azione che modifica lo stato del cluster, ad esempio il ciclo di accensione o la contaminazione di un nodo, richiede la tua conferma esplicita. Ogni comando deve essere esaminato e approvato. Queste azioni sono contrassegnate con requires_approval: true nelle relative definizioni in _wiki/actions/. L'agente segnala i risultati al termine della diagnosi.

Per scoprire come valutare i risultati, incluso come riconoscere un risultato indeterminato, consulta _wiki/TUTORIAL.md.