Transformers 2

Transformers 2: o que você precisa saber antes de implementar

O transformers 2 é a versão mais recente da biblioteca Hugging Face que mudou bastante a forma como trabalhamos com modelos de linguagem. A interface de treinamento foi quase completamente redesenhada, e quem estava acostumado com a v1 perdeu horas tentando encontrar configurações que simplesmente não existem mais. O problema é que a documentação oficial fala bastante sobre os benefícios, mas fala muito pouco sobre os pontos que quebram em produção. A primeira coisa que todo mundo nota é a API do Trainer. Os parâmetros de configuração agora são organizados de forma diferente, com muitas opções agrupadas em classes como TrainingArguments que não aceitam parâmetros antigos. Migrei um projeto inteiro de classificação de texto e gastei três dias só corrigindo warnings que pareciam inofensivos mas na verdade estavam causando um comportamento completamente errado no gradiente acumulado.

Como configurar o transformers 2 na prática

O primeiro passo é atualizar o pacote. Um pip install transformers==4.40.0 já resolve a maioria dos conflitos, mas você vai querer verificar se o tokenizers também está na mesma versão major, porque há incompatibilidades conhecidas entre versões do tokenizer e da biblioteca principal que resultam em erros de shape que não fazem sentido algum. Na minha experiência, o fluxo mais produtivo é esse: carregar o modelo com AutoModelForSequenceClassification, definir os argumentos de treinamento com dados específicos do seu problema, e usar o DataCollatorWithPadding para lidar com sequências de tamanhos variados. O collator antigo foi descontinuado e continua aparecendo em tutoriais obsoletos pela internet.

from transformers import AutoModelForSequenceClassification, TrainingArguments, Trainer, AutoTokenizer
import torch

tokenizer = AutoTokenizer.from_pretrained("bert-base-portuguese-cased")
model = AutoModelForSequenceClassification.from_pretrained("bert-base-portuguese-cased", num_labels=5)

training_args = TrainingArguments(
    output_dir="./results",
    num_train_epochs=3,
    per_device_train_batch_size=16,
    per_device_eval_batch_size=32,
    warmup_steps=500,
    weight_decay=0.01,
    logging_dir="./logs",
    logging_steps=100,
    evaluation_strategy="epoch",
    save_strategy="epoch",
    load_best_model_at_end=True,
)

Isso parece simples, mas tem uma pegadinha que quase ninguém menciona. O parâmetro load_best_model_at_end requer que o metric_for_best_model esteja definido, senão o Trainer salva o último checkpoint e ignora completamente a métrica de avaliação. Isso acontece silenciosamente, sem erro, então você simplesmente não percebe até verificar os arquivos na pasta de output.

O caso do gradiente que desaparecia

Eu enfrentei um problema específico durante um fine-tune de um modelo de tradução usando transformers 2. O loss caía normalmente nas primeiras épocas, mas parava de diminuir depois do segundo epoch sem nenhuma mensagem de erro. O modelo basicamente treinava e não aprendia nada novo. Levei cerca de seis horas para identificar que o problema era o gradient_accumulation_steps combinado com um learning rate scheduler configurado de forma padrão. A solução foi ajustar o num_warmup_steps para uma fração maior do total de steps de treinamento e ativar o gradient clipping explicitamente com max_grad_norm=1.0. Também mudei o scheduler de linear para cosine com restarts, o que fez o modelo convergir em dois epochs a mais mas com uma perda final significativamente menor. O processo todo demorou menos tempo do que eu esperava por causa do cache de dados que o transformers 2 ativa por padrão quando você passa um dataset do Dataset do Hugging Face.

Limitações que a documentação não destaca

Transformers 2 não é uma solução perfeita. Existem problemas reais que você precisa considerar antes de migrar. O suporte a modelos muito grandes ainda demanda mais memória do que a v1 em alguns cenários, especialmente quando você usa gradient checkpointing junto com mixed precision. Eu perdi cerca de 20% de throughput em uma GPU A100 só por causa de overhead de memória na comunicação entre módulos. Se você trabalha com modelos acima de 13 bilhões de parâmetros, fazer profiling de memória antes de treinar é obrigatório, não opcional.

Outro ponto importante: a compatibilidade com hardware antigo. Se você ainda depende de CUDA 11.3 ou inferior, vai enfrentar problemas sérios. A biblioteca agora exige CUDA 11.8 ou superior para funcionar corretamente, e tentar contornar isso resulta em erros de importação difíceis de diagnosticar. Para setups legados, a alternativa mais viável é manter uma instância separada com transformers 4.34, que ainda suporta essas versões mais antigas. Existe também o problema dos datasets processados. Quando você atualiza a biblioteca, os datasets que já estavam cacheados na versão anterior podem ter a pipeline de tokenização incompatível. Eu já vi projetos inteiros falharem porque o cache do dataset não foi limpo após a atualização. Rodar um rm -rf ~/.cache/huggingface/datasets é uma medida preventiva barata que evita horas de dor de cabeça.

Alternativas quando transformers 2 não é a melhor opção

Se o seu projeto não precisa das funcionalidades novas, como o Native Ampere support ou as otimizações de memory-efficient attention, considerar manter a v1 pode ser mais sensato. A aceleração com torch.compile, disponível no transformers 2, só começa a fazer diferença real em modelos maiores do que 3 bilhões de parâmetros. Para modelos menores, o overhead de compilação pode aumentar o tempo de warmup em até 40 segundos por epoch, o que em um treinamento curto de 3 épocas representa um gasto significativo. Também vale mencionar que a integração com experiment tracking mudou. Owandb e o tensorboard ainda funcionam, mas a API de logging foi relocada para um módulo separado, e configurar callbacks manualmente exige mais código do que na versão anterior. Se você tem pipelines automatizadas de treinamento rodando há meses, atualizar exige revisão de cada script.

O transformers 2 é maduro o suficiente para uso em produção, mas exige atenção aos detalhes que a comunidade ainda está documentando. A maioria dos artigos online cobre apenas o tutorial básico de instalação. O que realmente faz diferença no dia a dia são esses pequenos ajustes de configuração que ninguém documenta formalmente. Investir tempo entendendo o comportamento do Trainer nos cenários que você realmente vai encontrar evita frustração muito maior no futuro.