A Hugging Face propôs os Contratos de Integração de Modelos (MICs), uma forma de executar verificações leves em modelos do Transformers durante pull requests. O objetivo é detectar regressões antes que cheguem à base de código principal, sem precisar executar o conjunto completo de testes de integração em GPUs a cada alteração.
A proposta surgiu após um bug relacionado à atenção do T5. Em 30 de julho de 2026, o Transformers habilitou a atenção de produto escalar escalado do PyTorch para o T5, o que também permitiu que o decodificador do UMT5 atendesse a tokens futuros durante o treinamento. O problema permaneceu na branch principal até ser corrigido em 28 de setembro. Quando a equipe reproduziu os commits desse período, um pequeno fixture de UMT5 executado em CPU sinalizou a regressão.
O Transformers oferece suporte a mais de 750 tipos de modelos. Sua branch principal tem mais de 88.000 testes de CPU, enquanto uma execução diária inclui mais de 200.000 testes de GPU. Os testes completos de integração carregam checkpoints reais e exercitam modelos em hardware real, mas executá-los todos a cada pull request exigiria que as GPUs ficassem ocupadas durante todo o dia. Testes agendados também podem detectar um problema somente depois que ele chega à branch principal.
Os MICs abordam essa troca ao testar fixtures menores criados a partir de configurações de checkpoints reais. Eles preservam os diferentes tipos de camadas de um modelo, mas usam menos camadas, e camadas mais estreitas; os arquivos do tokenizador e do processador permanecem inalterados. Os fixtures são publicados uma vez e reutilizados em testes rápidos de integração em CPU. No estudo do UMT5, os pesos do fixture ocupavam 66 MB, em comparação com 1.227 MB do checkpoint de origem. A abordagem também pode cobrir modelos muito grandes que não cabem nos executores de GPU padrão.
Cada contrato tem três partes: um fixture fixado, um exemplo executável de uma tarefa do modelo e baselines de saída registrados a partir de uma execução considerada correta e revisados por uma pessoa. A verificação é aprovada quando a execução do exemplo com o fixture corresponde a esses baselines. Um contrato está vinculado a uma arquitetura e a um caminho de uso, e não a um único checkpoint, permitindo que checkpoints compatíveis compartilhem um fixture, mantendo seus próprios resultados esperados.
Os exemplos podem testar mais do que apenas se um modelo carrega e conclui uma passagem forward. Um contrato do SmolLM, por exemplo, gera texto a partir de um prompt e compara os IDs de token resultantes com uma resposta registrada. Também verifica a perda de treinamento, confirma que os gradientes são finitos e garante que uma etapa do otimizador altera os pesos. Em pull requests, o CI seleciona contratos de acordo com os arquivos alterados.
A reprodução do UMT5 mostrou por que o caminho testado importa: as log-probabilidades dos rótulos diferiram do baseline revisado em 1,22, e a perda de treinamento, em cerca de 0,20. O contrato usou SDPA, o caminho de atenção padrão; testar apenas a variante de atenção eager teria deixado o problema passar. Reverter a correção em uma branch de prova do CI do Transformers reproduziu a falha, e a etapa do executor do contrato T5 selecionado levou 13,4 segundos em CPU, sem contar a configuração.
A receita de criação de fixtures também foi adaptada para arquiteturas mistas. Ela reduz as dimensões do modelo mantendo os diferentes tipos de camadas, incluindo combinações como atenção deslizante e completa ou camadas densas e de mistura de especialistas. Preserva os recursos de pré-processamento, incluindo o vocabulário e os tokens especiais, e mantém o formato original dos arquivos de pesos, para que o código de conversão de checkpoints continue sendo exercitado. As compilações são validadas quanto a saídas responsivas e resultados finitos e, em seguida, congeladas com baselines revisados para as plataformas e precisões compatíveis.
A escala da redução é ilustrada por um fixture do Llama 4 Scout: 108,6 bilhões de parâmetros passam a 44,7 milhões, mantendo os tipos de camadas verificados e o estilo de roteamento MoE. A ferramenta de linha de comando tmic cria contratos e fixtures. Para modelos novos, um LLM pode elaborar o código de uso e o manifesto, mas as pessoas precisam revisar as expectativas alteradas. O fluxo de trabalho local pode criar e testar um contrato sem fazer upload dele.
A equipe também comparou pesos aleatórios de fixtures com pesos treinados em alguns exemplos. Em um estudo com falhas sintéticas, fixtures aleatórios do Whisper detectaram 18 dos 24 problemas injetados, enquanto fixtures treinados com um pequeno conjunto de exemplos detectaram todos os 24. Os autores alertam que isso não estabelece qual abordagem é melhor na prática: os testes usaram falhas sintéticas, e ambas as versões deixaram passar um bug de decodificação assistida exposto pelo checkpoint real do Whisper. A abordagem atual mantém pesos aleatórios quando eles passam na validação e usa sobreajuste quando é necessária maior sensibilidade ou saídas legíveis.
Em 1º de novembro de 2026, o job de MIC no CI do Transformers informa falhas, mas não bloqueia pull requests. A equipe afirma que ainda precisa medir quantos bugs reais as verificações detectam, com que frequência geram falsos alarmes e quanto trabalho as revisões dos baselines exigem. A cobertura continua parcial, e o projeto planeja adicionar caminhos de uso quando as regressões revelarem lacunas. Os testes existentes serão mantidos até que sua cobertura seja contabilizada.
Fontes: Hugging Face Blog.