Hugging Face ha proposto i Model Integration Contracts (MIC), un metodo per eseguire controlli leggeri sui modelli di Transformers durante le pull request. L’obiettivo è individuare le regressioni prima che raggiungano il codebase principale, senza dover eseguire l’intera suite di integrazione su GPU per ogni modifica.

La proposta nasce da un bug relativo all’attenzione di T5. Il 30 luglio 2026, Transformers ha abilitato l’attenzione scaled dot-product di PyTorch per T5, consentendo così anche al decoder di UMT5 di prestare attenzione ai token futuri durante l’addestramento. Il problema è rimasto nel branch principale fino alla correzione, avvenuta il 28 settembre. Riproducendo i commit intermedi, il team ha verificato che un piccolo fixture di UMT5 eseguito su CPU segnalava la regressione.

Transformers supporta più di 750 tipi di modelli. Il suo branch principale ha oltre 88.000 test su CPU, mentre un’esecuzione giornaliera include più di 200.000 test su GPU. I test di integrazione completi caricano checkpoint reali e mettono alla prova i modelli su hardware reale, ma eseguirli tutti per ogni pull request richiederebbe di tenere impegnate le GPU per l’intera giornata. Inoltre, i test programmati possono individuare un problema solo dopo che è arrivato nel branch principale.

I MIC affrontano questo compromesso testando fixture più piccoli, creati a partire dalle configurazioni di checkpoint reali. Questi mantengono i diversi tipi di layer presenti in un modello, ma usano meno layer e di dimensioni inferiori; i file di tokenizer e processor restano invariati. I fixture vengono pubblicati una volta e riutilizzati nei test di integrazione rapidi su CPU. Nello studio su UMT5, i pesi del fixture occupavano 66 MB, contro i 1.227 MB del checkpoint di origine. Questo approccio può inoltre coprire modelli molto grandi che non possono essere eseguiti sui runner GPU standard.

Ogni contratto ha tre componenti: un fixture bloccato a una versione specifica, un esempio eseguibile di un’attività del modello e baseline degli output registrate a partire da un’esecuzione nota come corretta e revisionate da una persona. Il controllo viene superato quando l’esempio eseguito sul fixture corrisponde a queste baseline. Un contratto è legato a un’architettura e a un percorso d’uso, anziché a un singolo checkpoint: così checkpoint compatibili possono condividere un fixture, mantenendo i propri risultati attesi.

Gli esempi possono testare più del semplice caricamento del modello e del completamento di un passaggio forward. Per esempio, un contratto di SmolLM genera testo a partire da un prompt e confronta gli ID dei token risultanti con una risposta registrata. Controlla anche la loss di addestramento, verifica che i gradienti siano finiti e conferma che un passaggio dell’ottimizzatore modifichi i pesi. Nelle pull request, CI seleziona i contratti in base ai file modificati.

La riproduzione del bug di UMT5 ha mostrato quanto sia importante il percorso testato: le log-probabilità delle etichette differivano di 1,22 dalla baseline revisionata e la loss di addestramento di circa 0,20. Il contratto usava SDPA, il percorso di attenzione predefinito; testare soltanto la variante di attenzione eager avrebbe mancato il problema. Ripristinando la versione precedente alla correzione in un branch di prova CI di Transformers, è stato possibile riprodurre l’errore: il passaggio di esecuzione del contratto T5 selezionato richiedeva 13,4 secondi su CPU, esclusa la configurazione iniziale.

La procedura per creare i fixture è stata inoltre adattata alle architetture miste. Riduce le dimensioni dei modelli mantenendo i diversi tipi di layer, comprese combinazioni come attenzione sliding e full o layer densi e mixture-of-experts. Preserva gli asset di preelaborazione, inclusi vocabolario e token speciali, e mantiene il formato originale dei file dei pesi, così da continuare a esercitare il codice di conversione dei checkpoint. Le build vengono convalidate per verificare che gli output siano reattivi e i risultati finiti, quindi congelate con baseline revisionate per le piattaforme e le precisioni supportate.

L’entità della riduzione è illustrata da un fixture di Llama 4 Scout: i suoi 108,6 miliardi di parametri diventano 44,7 milioni, mantenendo i tipi di layer e lo stile di routing MoE verificati. Lo strumento a riga di comando tmic crea i contratti e i fixture. Per i nuovi modelli, un LLM può preparare una bozza del codice d’uso e del manifest, ma le aspettative modificate devono essere revisionate da persone. Il flusso di lavoro locale permette di creare e testare un contratto senza caricarlo.

Il team ha anche confrontato pesi casuali dei fixture con pesi addestrati su alcuni esempi. In uno studio con guasti sintetici, i fixture casuali di Whisper hanno individuato 18 dei 24 problemi inseriti, mentre quelli addestrati su un piccolo insieme di esempi li hanno rilevati tutti e 24. Gli autori avvertono che questo non dimostra quale approccio sia migliore nella pratica: i test usavano guasti sintetici ed entrambe le versioni non hanno rilevato un bug di decodifica assistita emerso con il checkpoint reale di Whisper. L’approccio attuale mantiene i pesi casuali quando superano la convalida e usa l’overfitting quando servono una maggiore sensibilità o output leggibili.

Al 1° novembre 2026, il job MIC nella CI di Transformers segnala gli errori, ma non blocca le pull request. Il team afferma che deve ancora misurare quanti bug reali vengano individuati dai controlli, quanto spesso generino falsi allarmi e quanto lavoro richieda la revisione delle baseline. La copertura è ancora parziale e il progetto prevede di aggiungere percorsi d’uso quando le regressioni metteranno in luce delle lacune. I test esistenti resteranno finché la loro copertura non sarà stata contabilizzata.

Fonti: Hugging Face Blog.