Triage du pipeline EAGLE3

Diagnostiquez les défaillances du pipeline offline EAGLE3 en 4 étapes. Cette compétence parcourt chaque étape, identifie le point de défaillance et fournit des corrections actionnables.

Aperçu du pipeline

Étape 0 — Localiser l'expérience

Demandez à l'utilisateur l'un des éléments suivants :

• Répertoire d'expérience (par ex., le --job-dir passé à launch.py ou slurm.py)
• Le nom du modèle / YAML qu'il a exécuté

Trouvez les expériences récentes sous le répertoire de tâche :

ls -td experiments/cicd/cicd_* | head -10
# ou selon où --job-dir était pointé

Chaque répertoire d'expérience contient un sous-répertoire par tâche (task_0 à task3), chacun avec un fichier journal dont le nom varie selon le mode de lancement (Slurm : `sbatch.out, Docker local :.log`).

Étape 1 — Récupérer les journaux de la tâche défaillante

Trouvez les fichiers journaux généralement et lisez la fin de chacun — les erreurs apparaissent à la fin :

find experiments/<exp_id>/ -type f \( -name '*.out' -o -name '*.log' \) | sort | while read -r f; do
  echo "=== $f ==="; tail -200 "$f"; echo
done

Cherchez la première tâche avec un code de sortie non nul ou un message d'erreur.

Étape 2 — Diagnostiquer par étape

Défaillances de task_0 (Synthèse de données)

Fonctionnement : Lance un serveur vLLM compatible OpenAI, sonde /health jusqu'à ce qu'il soit prêt, puis exécute query.py pour générer des paires prompt/réponse synthétiques. La sortie va à /scratchspace/data/.

Défaillances de task_1 (Décharge d'état caché)

Fonctionnement : Charge le modèle cible et exécute une passe avant sur chaque conversation, enregistrant les états cachés sous forme de fichiers .pt dans /scratchspace/offline_hidden_states/.

Trois backends sont disponibles :

Défaillances de task_2 (Entraînement)

Fonctionnement : Installe les exigences, exécute launch_train.sh (Accelerate + FSDP) avec la config de modelopt_recipes/general/speculative_decoding/eagle3.yaml, puis exporte via export_hf_checkpoint.py. Sortie : /scratchspace/eagle3/ et /scratchspace/export/.

Défaillances de task_3 (Benchmark)

Fonctionnement : Lance vLLM avec le modèle cible + brouillon, exécute les benchmarks du taux d'acceptation et du débit. Sortie : fichiers JSON.

Étape 3 — Vérifier les problèmes spécifiques au nouveau modèle

Si l'utilisateur ajoute le support d'un nouveau modèle, vérifiez aussi :

1. Le modèle est-il un VLM ? → Utilisez dump_offline_data_hf.sh (chemin texte uniquement, aucun encodeur de vision invoqué)
2. Le modèle utilise-t-il l'attention à fenêtre glissante (SWA) ? → Le backend TRT-LLM ne fonctionnera pas ; utilisez HF ou vLLM
3. Le modèle a-t-il besoin de trust_remote_code ? → Ajoutez aux args de task_0 ET aux args de task_3
4. Le modèle est-il MoE ? → Vérifiez que eagle_config.json intermediate_size correspond au moe_intermediate_size du modèle
5. L'architecture du modèle est-elle reconnue par l'entraînement EAGLE3 ? → peut nécessiter des changements de code dans modelopt/torch/speculative/
6. Tokenizer personnalisé ? → Peut nécessiter des variables d'environnement supplémentaires (par ex., TIKTOKEN_RS_CACHE_DIR)

Étape 4 — Suggérer une correction et les prochaines étapes

Après le diagnostic, fournissez :

1. Cause racine — résumé d'une ligne
2. Correction — changement de config spécifique, édition de code ou commande à exécuter
3. Comment réexécuter — ignorez les étapes antérieures réussies en pointant vers les artifacts scratchspace existants

Pour ignorer task_0 et task_1 et réexécuter à partir de task_2 :

uv run launch.py --yaml examples/<Org>/<Model>/hf_offline_eagle3.yaml \
    pipeline.task_0.skip=true \
    pipeline.task_1.skip=true \
    --yes

Pour exécuter uniquement task_1 en standalone (en utilisant les données task_0 existantes) :

uv run launch.py --yaml examples/<Org>/<Model>/hf_offline_eagle3.yaml \
    pipeline.task_0.skip=true \
    pipeline.task_2.skip=true \
    pipeline.task_3.skip=true \
    --yes

Si la correction nécessite des changements de code dans ModelOpt (par ex., supporter une nouvelle architecture de modèle), notez qu'une PR séparée dans le repo modelopt est nécessaire.

Étape 5 — Enregistrer le motif de défaillance

Si vous rencontrez un motif de défaillance non vus auparavant, capturez-le dans le tracker de triage interne de l'équipe — le symptôme, la cause racine et la correction — afin que le prochain ingénieur déboguant le même problème en bénéficie.