Compétence de Triage des Problèmes PyTorch

Cette compétence aide au triage des problèmes GitHub en routant les problèmes, en appliquant des étiquettes et en laissant des réponses de première ligne.

Contenus

• Outils MCP disponibles
• Étiquettes à JAMAIS ajouter
• Étapes du triage des problèmes
  • Étape 0 : Déjà routé — IGNORER
  • Étape 1 : Question vs Bug/Fonctionnalité
  • Étape 1.5 : Reproduction nécessaire — Fichiers externes
  • Étape 2 : Transfert
  • Étape 2.5 : Problèmes PT2 — Gestion spéciale
  • Étape 3 : Rediriger vers l'oncall secondaire
  • Étape 4 : Étiqueter le problème
  • Étape 5 : Haute priorité — NÉCESSITE UNE VÉRIFICATION HUMAINE
  • Étape 6 : bot-triaged (automatique)
  • Étape 7 : Marquer comme trié
• Contraintes V1

Référence des étiquettes : Consultez labels.json pour le catalogue complet des étiquettes appropriées pour le triage. N'appliquez QUE les étiquettes qui existent dans ce fichier. N'inventez pas et ne devinez pas les noms d'étiquettes. Ce fichier exclut les déclencheurs CI, les configs de test, les notes de version, les étiquettes dépréciées et les étiquettes nécessitant une décision humaine.

Guide de triage PT2 : Consultez pt2-triage-rubric.md pour des conseils détaillés sur l'étiquetage lors du triage des problèmes PT2/torch.compile.

Modèles de réponse : Consultez templates.json pour les messages de réponse standard.

Outils MCP disponibles

Utilisez ces outils GitHub MCP pour le triage :

Étiquettes à JAMAIS ajouter

Si bloqué : Quand une étiquette est bloquée par le hook, ajoutez UNIQUEMENT triage review et arrêtez. Un humain s'en chargera.

Ces règles sont appliquées par un hook PreToolUse qui valide toutes les étiquettes par rapport à labels.json.

Ne jamais remplacer les étiquettes humaines

Si un humain a déjà appliqué des étiquettes (en particulier ci: sev, des étiquettes de sévérité ou des étiquettes de priorité), ne les supprimez pas et ne les remplacez pas. Votre travail est de compléter, pas de remplacer.

Étapes du triage des problèmes (pour chaque problème)

0) Déjà routé — IGNORER

Si un problème a DÉJÀ une étiquette oncall:, IGNOREZ-LE entièrement. Ne :

• Ajoutez aucune étiquette
• Ajoutez triaged
• Laissez des commentaires
• Faites aucun travail de triage

Ce problème appartient à l'équipe sous-oncall. Ils gèrent leur queue.

1) Question vs Bug/Fonctionnalité

• Si c'est une question (pas un rapport de bug ou une demande de fonctionnalité) : fermez et utilisez le modèle redirect_to_forum depuis templates.json.
• Si vous ne savez pas si c'est un bug/fonctionnalité ou une question : demandez des informations supplémentaires avec le modèle request_more_info et arrêtez.

1.5) Reproduction nécessaire — Fichiers externes

Vérifiez si le corps du problème contient des liens vers des fichiers externes que les utilisateurs devraient télécharger pour reproduire.

Modèles à détecter :

• Fichiers joints : .zip, .pt, .pth, .pkl, .safetensors, .onnx, .bin
• Stockage externe : Liens Google Drive, Dropbox, OneDrive, Mega, WeTransfer
• Hubs de modèles : Liens Hugging Face Hub vers des fichiers de modèles

Action :

1. Éditer le corps du problème pour supprimer/masquer les liens de téléchargement
   • Remplacer par : [Lien supprimé - les téléchargements de fichiers externes ne sont pas autorisés pour des raisons de sécurité]
2. Ajouter l'étiquette needs reproduction
3. Utiliser le modèle needs_reproduction depuis templates.json pour demander une reproduction autonome
4. Ne PAS ajouter triaged — attendez que l'utilisateur fournisse un exemple reproductible

1.55) Reproduction nécessaire — Autres cas

Ajouter aussi needs reproduction quand :

• L'utilisateur signale un problème spécifique au matériel (p. ex., un modèle GPU spécifique) sans script de repro autonome
• L'utilisateur fait référence à un modèle/checkpoint/dataset spécifique qui n'est pas exécutable publiquement en quelques lignes
• Le problème décrit un break lors de la mise à jour de version mais ne fournit qu'une description haut niveau sans un script minimal
• La repro dépend d'une configuration d'entraînement spécifique, d'un environnement distribué ou d'une infrastructure non triviale

1.6) Cas limites et précision numérique

Si le problème implique des valeurs extrêmes ou des différences de précision numérique :

Modèles à détecter :

• Valeurs près de torch.finfo(dtype).max ou torch.finfo(dtype).min
• NaN/Inf apparaissant dans les sorties d'entrées valides (mais extrêmes)
• Différences entre les résultats CPU et GPU
• Différences de précision entre dtypes (p. ex., fp32 vs fp16)
• Cas limites générés par fuzzer

IMPORTANT — éviter les mislabeling déclenchés par des mots-clés :

Étiquetez en fonction de la cause racine, pas des mots-clés qui apparaissent dans l'erreur ou le titre. Un mot-clé indique ce qui a échoué, pas pourquoi.

• Une erreur undefined symbol: ncclAlltoAll à import torch est un problème d'empaquetage (module: binaries), pas un bug d'entraînement distribué — l'utilisateur n'a jamais exécuté de code distribué.
• Un nan dans le nom d'un paramètre ou une vérification de tolérance n'est pas module: NaNs and Infs sauf si le bug traite réellement de la propagation des NaN.
• Une stack trace mentionnant autograd ne signifie pas module: autograd — vérifiez si le bug est dans autograd lui-même ou juste sur le chemin d'appel.
• Une défaillance de test avec des seuils de tolérance est module: tests, pas module: numerical-stability.

Posez-vous la question : « Où la correction devrait-elle être faite ? » Cela détermine l'étiquette.

Action :

1. Ajouter l'étiquette module: edge cases
2. Si provenant d'un fuzzer, ajouter aussi topic: fuzzer
3. Utiliser le modèle numerical_accuracy depuis templates.json pour lier vers la documentation
4. Si le problème est clairement un comportement attendu selon la documentation, fermez-le avec le commentaire du modèle

2) Transfert (bibliothèque de domaine ou ExecuTorch)

Si le problème appartient à un autre dépôt (vision/texte/audio/RL/ExecuTorch/etc.), transférez le problème et ARRÊTEZ.

2.5) Problèmes PT2 — Gestion spéciale

PT2 n'est PAS une redirection. oncall: pt2 n'est pas comme les autres étiquettes oncall de l'étape 3. Les problèmes PT2 continuent à travers les étapes 4–7 pour un triage complet — ajouter oncall: pt2, puis procéder à l'étiquetage avec des étiquettes module:, marquer triaged, etc.

Chaque problème oncall: pt2 DOIT avoir au moins une étiquette module:. La queue d'oncall PT2 est trop large sans étiquette de module — l'équipe doit savoir quel composant est affecté (p. ex., module: dynamo, module: inductor, module: helion, module: dynamic shapes). Si vous ne pouvez pas déterminer le module spécifique, utilisez module: compile ux comme recours, mais essayez toujours d'être spécifique d'abord. Consultez pt2-triage-rubric.md pour des conseils détaillés.

3) Rediriger vers l'oncall secondaire

CRITIQUE : Quand redirigeant vers une queue oncall non-PT2, appliquez exactement une étiquette oncall: ... et ARRÊTEZ. Ne :

• Ajoutez aucune étiquette module:
• Ne le marquez pas triaged
• Ne faites aucun travail de triage supplémentaire

L'équipe sous-oncall gérera son propre triage. Votre travail est uniquement de la router vers eux.

Étiquettes de redirection oncall

Erreurs de routage courantes à éviter :

• MPS ≠ Mobile. MPS (Metal Performance Shaders) est le backend GPU de macOS/Apple Silicon. Ne routez PAS les problèmes MPS vers oncall: mobile. Les problèmes MPS restent dans la queue générale avec module: mps.
• DTensor → oncall: distributed. Les problèmes DTensor doivent toujours être routés vers oncall: distributed, même s'ils ne mentionnent pas DDP/FSDP.
• ONNX → module: onnx. Il n'y a pas d'oncall: onnx. Utilisez module: onnx et gardez dans la queue générale.
• CI/releng → module: ci. N'utilisez pas oncall: releng. Utilisez module: ci pour les problèmes d'infrastructure CI.
• torch.compile + distribué. Quand torch.compile maltraite une op distribuée (p. ex., dist.all_reduce), le problème a généralement besoin à la fois de oncall: pt2 et oncall: distributed car la correction peut s'étendre sur les deux codebases.

Note : oncall: cpu inductor est une sous-queue de PT2. Pour le triage général, utilisez simplement oncall: pt2.

4) Étiqueter le problème (s'il n'est PAS transféré/redirigé)

Uniquement si le problème reste dans la queue générale :

• Ajouter 1+ étiquettes module: ... basées sur la zone affectée
• Préférer les étiquettes spécifiques aux générales quand les deux existent. Consultez les descriptions dans labels.json pour savoir quand une étiquette spécifique remplace une générale (p. ex., module: sdpa à la place de module: nn pour les problèmes SDPA, module: flex attention au lieu de module: nn pour flex attention).
• feature — une fonctionnalité entièrement nouvelle qui n'existe pas aujourd'hui sous aucune forme
• enhancement — amélioration de quelque chose qui fonctionne déjà (p. ex., ajouter un kernel de backend natif pour une op qui s'exécute déjà via fallback/composite, optimisation de performance, meilleurs messages d'erreur). Si l'enhancement concerne la performance, ajouter aussi module: performance.
• function request — une nouvelle fonction ou de nouveaux arguments/modes pour une fonction existante
• Si le problème dit que l'opération « fonctionne actuellement » ou « bascule vers » un chemin plus lent, c'est enhancement, pas feature

Étiquettes couramment oubliées — vérifiez toujours celles-ci :

Étiquetez selon le bug réel, pas les mots-clés. Lisez le problème pour comprendre ce qui est réellement cassé. Un bug sur le broadcasting qui mentionne par hasard « nan » dans un nom de paramètre est un bug frontend, pas un bug NaN/Inf.

5) Haute priorité — NÉCESSITE UNE VÉRIFICATION HUMAINE

CRITIQUE : Si vous pensez qu'un problème est de haute priorité, vous DEVEZ :

1. Ajouter l'étiquette triage review et ne pas ajouter triaged

N'ajoutez PAS directement high priority sans confirmation humaine.

Critères de haute priorité :

• Crash/segfault/accès mémoire illégal
• Problème de correction silencieuse (résultats incorrects sans erreur)
• Régression par rapport à une version antérieure
• Défaillance d'assert interne
• Nombreux utilisateurs affectés
• Impact sur un composant principal ou un modèle populaire

6) bot-triaged (automatique)

L'étiquette bot-triaged est automatiquement appliquée par un post-hook après toute mutation de problème. Vous n'avez pas besoin de l'ajouter manuellement.

7) Marquer comme trié

Si non transféré/redirigé et non signalé pour vérification, ajouter triaged.

Contraintes V1

NE PAS :

• Fermer automatiquement les rapports de bugs ou demandes de fonctionnalité
• Fermer les problèmes sauf s'ils sont des questions d'utilisation claires selon l'étape 1
• Assigner les problèmes à des utilisateurs
• Ajouter high priority directement sans confirmation humaine
• Ajouter des étiquettes de module lors de la redirection vers oncall
• Ajouter des commentaires aux rapports de bugs ou demandes de fonctionnalité, sauf une seule demande d'info quand la classification n'est pas claire

FAIRE :

• Fermer les questions d'utilisation claires et pointer vers discuss.pytorch.org (selon l'étape 1)
• Être conservateur - en cas de doute, ajouter triage review pour l'attention humaine
• Appliquer les étiquettes de type (feature, enhancement, function request) quand confiant
• Ajouter l'étiquette triaged quand la classification est complète

Note : bot-triaged est automatiquement appliquée par un post-hook après toute mutation de problème.