Résoudre les problèmes avec le wiki de débogage des charges de travail de ML

Le wiki de débogage des charges de travail de ML est un dépôt GitHub que les agents de codage d'IA utilisent pour résoudre les problèmes liés aux charges de travail TPU exécutées sur Google Kubernetes Engine (GKE) avec JAX, XLA ou Pathways. Le wiki permet aux agents IA de collecter les journaux de charge de travail, de faire correspondre les signatures d'erreur aux modes de défaillance connus, d'exécuter des workflows de diagnostic et de signaler les causes principales en fonction des journaux. Cela fournit aux agents les informations nécessaires pour diagnostiquer les plantages, les blocages, les redémarrages ou les préemptions de charges de travail.

Le wiki contient deux types de documents de référence :

  • Pages de connaissances : pages Markdown qui décrivent les concepts, les symptômes de défaillance et leurs signatures de journaux, les playbooks de dépannage et les outils de diagnostic.
  • Procédures exécutables : actions et workflows JSON. Une action est une étape de diagnostic unique, telle qu'une requête de journal ou une commande kubectl. Un workflow exécute une séquence d'actions pour diagnostiquer un mode de défaillance spécifique.

Lorsque vous exécutez la commande /troubleshoot, une équipe de sous-agents spécialisés trie les journaux de la charge de travail, sélectionne et exécute le workflow correspondant à l'échec, puis vérifie chaque conclusion par rapport aux journaux principaux. L'agent signale ensuite la cause principale, les hôtes responsables tels qu'ils sont cités dans les journaux et un tableau des défaillances qui résume chaque interruption.

Fichiers de clé

Le tableau suivant répertorie les principaux fichiers et répertoires du wiki "Déboguer les charges de travail de ML" :

Chemin d'accès Description
_wiki/TUTORIAL.md Présentation de ce qui se passe lors d'un diagnostic et de la manière d'évaluer les résultats, y compris un exemple concret.
_wiki/INDEX.md Un catalogue de chaque page, action et workflow du wiki, avec un résumé d'une ligne pour chacun.
_wiki/concepts/ Concepts d'architecture système et de cycle de vie des composants, tels que le cycle de vie du programme libtpu, le débit utile et la surveillance de la progression de la charge de travail.
_wiki/entities/ Entités matérielles, logicielles et de plate-forme, telles que TPU, GPU, JAX, XLA et Pathways.
_wiki/symptoms/ Modes de défaillance, signatures de journaux et comment les vérifier.
_wiki/playbooks/ Stratégies de dépannage, organigrammes d'arbre de décision et pièges courants.
_wiki/tools/ Outils de diagnostic, scripts et guides de référence de la ligne de commande.
_wiki/workflows/ Procédures de diagnostic au format JSON. Chaque workflow exécute une séquence d'actions pour diagnostiquer un mode de défaillance spécifique.
_wiki/actions/ Étapes de diagnostic individuelles au format JSON, telles que les requêtes de journaux et les commandes kubectl.
_wiki/SCHEMA.md Les types de pages, les exigences de frontmatter et les tags de taxonomie que les pages wiki doivent respecter.
_agents/QUICKSTART.md Détails de la configuration et de l'envoi pour les utilisateurs d'Antigravity.
CLAUDE.md La mise en page de l'espace de travail, les outils de ligne de commande et les rôles de sous-agent pour les utilisateurs de Claude Code.

Commandes clés

Le tableau suivant répertorie les commandes que vous pouvez exécuter avec le wiki :

Commande Utilisation Description
/troubleshoot /troubleshoot WORKLOAD_ID, où WORKLOAD_ID est le nom de la charge de travail ou du JobSet. Diagnostique une charge de travail à l'aide de Cloud Logging, des événements de cluster GKE, des journaux kubelet et des journaux de nœuds. Les sous-agents de routage, de diagnostic, d'examen et de conseil exécutent le diagnostic et signalent la cause principale, les hôtes responsables d'après les journaux et un tableau des défaillances.
/dashboard /dashboard [TARGET], où TARGET est un ID de projet, un nom de cluster ou un ID de charge de travail facultatif. Si vous omettez TARGET, le tableau de bord affiche tous les clusters GKE du projet défini dans votre configuration de la Google Cloud CLI. Démarre le tableau de bord de capacité et de tri GKE, une application Web locale à l'adresse http://localhost:8080. La commande analyse les clusters pour la cible, puis renvoie un lien vers une vue de tableau de bord filtrée sur la cible.
/handoff

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

Tous les arguments, à l'exception de WORKLOAD_ID, sont facultatifs :

  • CASE_ID : numéro de votre demande d'assistance.
  • --bucket=BUCKET : nom du bucket. Si vous omettez cette option, l'agent demande un bucket.
  • --findings=PATH : chemin d'accès à un fichier de résultats existant. Si vous définissez cette option, la commande n'exécute pas /troubleshoot.
  • --no-watch : désactive la surveillance des buckets.
 Empaquette les résultats de /troubleshoot dans un bucket Cloud Storage pour les partager avec Cloud Customer Care, puis surveille le bucket pour détecter les mises à jour. Pour vérifier les mises à jour ultérieurement, exécutez /handoff --watch STORAGE_KEY, où STORAGE_KEY est le nom du dossier de transfert dans le bucket.

Prérequis

Avant de configurer le wiki, identifiez la charge de travail que vous souhaitez diagnostiquer et notez les détails suivants :

  • Nom de la charge de travail ou du JobSet.
  • ID du projet Google Cloud qui exécute la charge de travail.
  • La période approximative de l'exécution à diagnostiquer.

Installations

Le wiki nécessite les installations suivantes :

  1. Installez Python 3, y compris le module venv. Le wiki nécessite Python 3.9 ou une version ultérieure. Sur Debian et Ubuntu, le module venv se trouve dans le package python3-venv.
  2. Installez et initialisez la Google Cloud CLI.
  3. Installez kubectl et gke-gcloud-auth-plugin.
  4. Installez l'un des agents de codage IA suivants. Le wiki inclut des fichiers de configuration pour les deux :

Rôles requis

Les agents exécutent des commandes de diagnostic avec vos identifiants Google Cloud . Pour diagnostiquer une charge de travail, attribuez les rôles IAM suivants au projet qui exécute la charge de travail :

  • Visionneuse de journaux (roles/logging.viewer) : permet aux agents de lire les journaux d'audit, de nœud et de conteneur de la charge de travail.
  • Lecteur Kubernetes Engine (roles/container.viewer) : permet aux agents d'inspecter le cluster, les nœuds et les pods qui ont exécuté la charge de travail.
  • Lecteur Compute (roles/compute.viewer) : permet aux agents d'inspecter les VM Compute Engine qui soutiennent les nœuds du cluster, y compris les événements de maintenance et d'arrêt des VM.
  • Lecteur Monitoring (roles/monitoring.viewer) : permet aux agents de lire les métriques Cloud Monitoring pour les workflows qui inspectent les métriques de charge de travail et de nœud.

Pour exécuter la commande /handoff, vous devez également disposer du rôle Administrateur des objets de l'espace de stockage (roles/storage.objectAdmin) sur le bucket Cloud Storage que vous partagez avec Cloud Customer Care. Ce rôle permet aux agents d'importer des résultats dans le bucket et de le surveiller pour détecter les mises à jour.

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Configurer le wiki

  1. Clonez le dépôt et accédez à son répertoire racine :

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

    Le wiki utilise des chemins d'accès relatifs à la racine du dépôt. Exécutez donc les commandes et démarrez votre agent à partir de ce répertoire.

  2. Créez et activez un environnement virtuel Python, puis installez les dépendances du wiki :

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

  3. Créez des identifiants par défaut de l'application (ADC) locaux pour votre compte utilisateur. Les outils Python du wiki utilisent ADC pour interroger Cloud Logging :

    gcloud auth application-default login

  4. Vérifiez votre configuration en exécutant le linter wiki :

    python3 _wiki/wiki_linter.py

    Le linter vérifie la structure, les schémas et les liens du wiki, puis imprime un rapport JSON. Si le rapport contient "status": "PASS", la vérification a réussi. Les avertissements figurant dans le rapport n'ont aucune incidence sur l'état.

Résoudre les problèmes liés à une charge de travail

Pour résoudre les problèmes d'une charge de travail à l'aide du wiki de débogage des charges de travail de ML, procédez comme suit :

  1. Démarrez votre agent à partir de la racine du dépôt ML Workload Debugging Wiki :

    • Claude Code : dans le shell où vous avez activé l'environnement virtuel, exécutez claude. Claude Code charge les instructions du wiki à partir de CLAUDE.md, ainsi que ses définitions de commandes et de sous-agents à partir du répertoire .claude/.
    • Antigravity : ouvrez la racine du dépôt en tant qu'espace de travail. Les définitions de la compétence et du sous-agent Antigravity du wiki se trouvent dans le répertoire _agents/. Pour en savoir plus sur la configuration, consultez _agents/QUICKSTART.md.

  2. Exécutez la commande /troubleshoot en spécifiant le nom de la charge de travail ou du JobSet que vous souhaitez diagnostiquer :

    /troubleshoot WORKLOAD_ID

  3. Fournissez à l'agent l'ID du projet et la période de l'exécution. Vous pouvez fournir une période précise au format de code temporel UTC (YYYY-MM-DDTHH:MM:SSZ) ou des périodes relatives en langage naturel, telles que "il y a une heure" ou "ces dernières 24 heures". Les agents utilisent la période pour définir le champ d'application de leurs requêtes de journaux. Assurez-vous donc qu'elle couvre l'intégralité de l'exécution.

Par défaut, les workflows de diagnostic exécutent des vérifications en lecture seule. Avant que l'agent n'exécute une action qui modifie l'état du cluster, comme le redémarrage ou l'ajout d'un rejet à un nœud, il demande votre confirmation explicite. Chaque commande doit être examinée et approuvée. Ces actions sont marquées par requires_approval: true dans leurs définitions dans _wiki/actions/. L'agent communique ses conclusions une fois le diagnostic terminé.

Pour savoir comment évaluer les résultats, y compris comment reconnaître un résultat non concluant, consultez _wiki/TUTORIAL.md.