Transformers

Visão Geral

A biblioteca Hugging Face Transformers fornece acesso a milhares de modelos pré-treinados para tarefas em domínios de NLP, visão computacional, áudio e multimodais. Use esta habilidade para carregar modelos, realizar inferência e ajustar em dados personalizados.

Instalação

Visa Transformers 5.18.0, verificado contra sua fonte lançada em 01/10/2026. Verificações nativas de CPU usam Python 3.11, Torch 2.14.1, Datasets 5.0.1, Accelerate 1.15.0, PEFT 0.21.2 e Hub 1.33.0. O extra Torch requer Torch >=2.5. Instale em um ambiente dedicado:

uv venv --python 3.11 .venv-transformers
uv pip install --python .venv-transformers/bin/python "transformers[torch]==5.18.0" "torch==2.14.1" "huggingface-hub==1.33.0" "datasets==5.0.1" "accelerate==1.15.0" "peft==0.21.2"

Use .venv-transformers/Scripts/python.exe no Windows. Selecione um build do Torch apropriado para o hardware de destino antes da instalação. Hub 2.1.1 é mais novo, mas Datasets 5.0.1 requer Hub <2; atualizar cada pacote independentemente torna esta pilha de treinamento insatisfaciível. O SDK esm separado atualmente requer Transformers <5 e pertence a outro ambiente.

Dependências opcionais (instale apenas para o fluxo de trabalho selecionado): Pillow 12.3.0 para imagens; torchvision compatível com Torch e timm 1.0.30 para modelos que os exigem; librosa 1.0.0 e soundfile 0.14.0 para pré-processamento de áudio (librosa requer Python >=3.12); FFmpeg para entradas de arquivos de áudio codificados; pytesseract mais Tesseract para pipelines de documentos OCR; bitsandbytes 0.50.2 para backends de quantização suportados. Veja carregamento de modelos antes de escolher precisão ou quantização.

A verificação usou modelos aleatórios minúsculos, entrada sintética e apenas salvamento/recarregamento local. Exemplos pré-treinados do Hub nesta habilidade são ilustrativos: metadados e configurações de checkpoint públicos foram revisados, mas nenhum peso ou conjunto de dados foi baixado e nenhuma inferência hospedada ou upload foi executado. Caminhos opcionais de exportação/distribuídos/hardware são verificados na fonte, não testados de ponta a ponta. Veja evidências de revisão.

Verifique sua versão:

import transformers
print(transformers.__version__)

Autenticação

Muitos modelos no Hugging Face Hub são restritos ou privados. Autentique-se antes de carregá-los.

Recomendado: Login via CLI (usa $HF_TOKEN_PATH, padrão para $HF_HOME/token, normalmente ~/.cache/huggingface/token):

hf auth login

Python:

from huggingface_hub import login
login()  # Interactive prompt; do not hardcode tokens in scripts

Servidores / CI: defina HF_TOKEN no ambiente (nunca cometa tokens no git ou perfis de shell):

export HF_TOKEN="..."  # Read token from a secret manager, not source code

Obtenha tokens em: https://huggingface.co/settings/tokens

Segurança: Nunca cole tokens em notebooks, repositórios ou configurações compartilhadas. Prefira hf auth login em vez de exportar tokens em .bashrc ou .zshrc.

Use o escopo de token mais restrito que funcionar: read para downloads de modelos privados ou restritos, write apenas para uploads. Se um ambiente de longa execução não deve enviar o token armazenado em cada solicitação do Hub, defina HF_HUB_DISABLE_IMPLICIT_TOKEN=1 e passe um token apenas onde a autenticação for necessária.

Transformers v5

Transformers v5 é apenas PyTorch (backends TensorFlow e JAX foram removidos). Para atualizações da v4, consulte o guia de migração v5. Transformers 5.18.0 aceita Hub >=1.31,<3; preserve a restrição mais apertada de Datasets ao treinar.

Arquiteturas restritas ou personalizadas: aceite a licença do modelo no Hub, depois carregue com trust_remote_code=True apenas quando o código personalizado necessário tiver sido revisado; fixe seu commit imutável completo com revision (e code_revision para um repositório de código separado). Restrição e código personalizado são independentes: uma arquitetura integrada restrita não requer código remoto.

Localização do cache: defina HF_HOME para todos os caches do Hugging Face, ou HF_HUB_CACHE apenas para arquivos do Hub. Use HF_HUB_OFFLINE=1 apenas após os snapshots de modelo necessários já estarem em cache.

Início Rápido

Use a API Pipeline para inferência rápida sem configuração manual:

from transformers import pipeline

# Geração de texto (prefira max_new_tokens para LMs causais)
generator = pipeline("text-generation", model="Qwen/Qwen2.5-1.5B")
result = generator("The future of AI is", max_new_tokens=50)

# Classificação de texto

…