Hugging Face a proposé les contrats d’intégration de modèles (MIC), un moyen d’exécuter des vérifications légères sur les modèles Transformers lors des pull requests. L’objectif est de détecter les régressions avant qu’elles n’atteignent la base de code principale, sans devoir exécuter toute la suite d’intégration sur GPU à chaque modification.

La proposition fait suite à un bug lié à l’attention de T5. Le 30 juillet 2026, Transformers a activé l’attention à produit scalaire mise à l’échelle de PyTorch pour T5, ce qui a également permis au décodeur d’UMT5 de prêter attention à des tokens futurs pendant l’entraînement. Le problème est resté dans la branche principale jusqu’à sa correction, le 28 septembre. Lorsque l’équipe a rejoué les commits intermédiaires, un petit exemple d’UMT5 exécuté sur CPU a signalé la régression.

Transformers prend en charge plus de 750 types de modèles. Sa branche principale compte plus de 88 000 tests CPU, tandis qu’une exécution quotidienne comprend plus de 200 000 tests GPU. Les tests d’intégration complets chargent de vrais checkpoints et font fonctionner les modèles sur du matériel réel, mais les exécuter tous à chaque pull request nécessiterait de mobiliser les GPU toute la journée. Les tests planifiés peuvent également ne détecter un problème qu’après son arrivée dans la branche principale.

Les MIC répondent à ce compromis en testant des exemples plus petits, construits à partir de configurations de vrais checkpoints. Ils conservent les différents types de couches d’un modèle, mais utilisent moins de couches, plus étroites ; les fichiers du tokenizer et du processeur restent inchangés. Les exemples sont publiés une fois et réutilisés dans des tests d’intégration rapides sur CPU. Dans l’étude sur UMT5, les poids de l’exemple occupaient 66 Mo, contre 1 227 Mo pour le checkpoint source. Cette approche peut aussi couvrir de très grands modèles qui ne tiennent pas sur les runners GPU standard.

Chaque contrat comporte trois éléments : un exemple figé, un exemple exécutable d’une tâche du modèle et des références de sortie enregistrées lors d’une exécution dont le bon fonctionnement est connu, puis examinées par une personne. La vérification réussit lorsque l’exécution de l’exemple sur le modèle correspond à ces références. Un contrat est lié à une architecture et à un parcours d’utilisation plutôt qu’à un seul checkpoint, ce qui permet à des checkpoints compatibles de partager un exemple tout en conservant leurs propres résultats attendus.

Les exemples peuvent vérifier davantage que le simple chargement d’un modèle et l’exécution complète d’un passage avant. Un contrat SmolLM, par exemple, génère du texte à partir d’une invite et compare les identifiants des tokens obtenus à une réponse enregistrée. Il vérifie aussi la perte d’entraînement, s’assure que les gradients sont finis et confirme qu’une étape de l’optimiseur modifie les poids. Lors des pull requests, CI sélectionne les contrats en fonction des fichiers modifiés.

Le rejeu d’UMT5 a montré pourquoi le parcours testé est important : les log-probabilités des étiquettes différaient de 1,22 par rapport à la référence examinée, et la perte d’entraînement d’environ 0,20. Le contrat utilisait SDPA, le parcours d’attention par défaut ; tester uniquement la variante d’attention eager aurait laissé passer le problème. La réversion du correctif dans une branche de preuve CI de Transformers a reproduit l’échec ; l’étape d’exécution du contrat T5 sélectionné prenait 13,4 secondes sur CPU, sans compter la configuration.

La recette de création des exemples a également été adaptée aux architectures mixtes. Elle réduit les dimensions du modèle tout en conservant les différents types de couches, notamment les combinaisons d’attention glissante et complète ou de couches denses et de couches à mélange d’experts. Elle préserve les ressources de prétraitement, notamment le vocabulaire et les tokens spéciaux, et conserve le format original des fichiers de poids afin que le code de conversion des checkpoints soit toujours testé. Les exemples sont validés pour vérifier que les sorties sont réactives et finies, puis figés avec des références examinées pour les plateformes et précisions prises en charge.

L’ampleur de la réduction est illustrée par un exemple de Llama 4 Scout : ses 108,6 milliards de paramètres passent à 44,7 millions, tout en conservant les types de couches et le style de routage MoE vérifiés. L’outil en ligne de commande tmic crée les contrats et les exemples. Pour les nouveaux modèles, un LLM peut rédiger le code d’utilisation et le manifeste, mais les personnes doivent examiner les attentes modifiées. Le flux de travail local permet de construire et de tester un contrat sans le téléverser.

L’équipe a également comparé des poids aléatoires à des poids entraînés sur quelques exemples. Dans une étude utilisant des défauts synthétiques, les exemples aléatoires de Whisper ont détecté 18 des 24 problèmes injectés, tandis que les exemples entraînés sur un petit ensemble d’exemples les ont tous détectés. Les auteurs précisent que cela ne permet pas d’établir quelle approche est la meilleure en pratique : les tests utilisaient des défauts synthétiques, et les deux versions ont manqué un bug de décodage assisté révélé par le véritable checkpoint Whisper. L’approche actuelle conserve les poids aléatoires lorsqu’ils passent la validation et recourt au surapprentissage lorsqu’une sensibilité accrue ou des sorties lisibles sont nécessaires.

Au 1er novembre 2026, le job MIC dans la CI de Transformers signale les échecs, mais ne bloque pas les pull requests. L’équipe indique qu’elle doit encore mesurer combien de bugs réels ces vérifications détectent, à quelle fréquence elles génèrent de fausses alertes et quelle charge représentent les examens des références. La couverture reste partielle, et le projet prévoit d’ajouter des parcours d’utilisation lorsque des régressions révèlent des lacunes. Les tests existants seront conservés jusqu’à ce que leur couverture ait été prise en compte.

Sources: Hugging Face Blog.