Instalação

Transformers funciona com PyTorch. Ele foi testado em Python 3.11+ e PyTorch 2.6+.

Ambiente virtual

uv é um gerenciador de pacotes e projetos Python extremamente rápido, baseado em Rust, que exige um ambiente virtual por padrão para gerenciar diferentes projetos e evitar problemas de compatibilidade entre dependências.

Ele pode ser usado como uma substituição direta para o pip, mas, se você preferir usar o pip, remova uv dos comandos abaixo.

Consulte a documentação de instalação do uv para instalar o uv.

Crie um ambiente virtual para instalar o Transformers.

uv venv .env
source .env/bin/activate

Python

Instale o Transformers com o seguinte comando.

uv é um gerenciador rápido de pacotes e projetos Python baseado em Rust.

nvidia-smi

uv pip install "transformers[torch]"

nvidia-smi

uv pip install torch --index-url https://pypi.nvidia.com
uv pip install transformers

uv pip install torch --index-url https://download.pytorch.org/whl/cpu
uv pip install transformers

xpu-smi

uv pip install "transformers[torch]" --extra-index-url https://download.pytorch.org/whl/xpu

Teste se a instalação foi bem-sucedida com o seguinte comando. Ele deve retornar um rótulo e uma pontuação para o texto fornecido.

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]

Instalação a partir do código-fonte

A instalação a partir do código-fonte instala a versão mais recente em vez da versão estável da biblioteca. Isso garante que você tenha as alterações mais atualizadas do Transformers e é útil para experimentar os recursos mais recentes ou corrigir um bug que ainda não foi oficialmente lançado na versão estável.

A desvantagem é que a versão mais recente nem sempre é estável. Se você encontrar algum problema, abra um GitHub Issue para que possamos corrigi-lo o mais rápido possível.

Instale a partir do código-fonte com o seguinte comando.

uv pip install git+https://github.com/huggingface/transformers

Verifique se a instalação foi bem-sucedida com o comando abaixo. Ele deve retornar um rótulo e uma pontuação para o texto fornecido.

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]

Instalação editável

Uma instalação editável é útil se você estiver desenvolvendo localmente com o Transformers. Ela vincula sua cópia local do Transformers ao repositório do Transformers, em vez de copiar os arquivos. Os arquivos são adicionados ao caminho de importação do Python.

git clone https://github.com/huggingface/transformers.git
cd transformers
uv pip install -e .

Você deve manter a pasta local do Transformers para continuar usando-a.

Atualize sua versão local do Transformers com as últimas alterações no repositório principal usando o seguinte comando.

cd ~/transformers/
git pull

conda

conda é um gerenciador de pacotes agnóstico de linguagem. Instale o Transformers a partir do canal conda-forge no seu novo ambiente virtual criado.

conda install conda-forge::transformers

Configuração

Após a instalação, você pode configurar a localização do cache do Transformers ou configurar a biblioteca para uso offline.

Diretório de cache

Ao carregar um modelo pré-treinado com from_pretrained(), o modelo é baixado do Hub e armazenado em cache localmente.

Se você passar um hash de commit, o Transformers usa o cache local para os arquivos desse commit e não reconfere o Hub para cada um deles (incluindo arquivos que são conhecidos por estarem ausentes). Esse é o comportamento padrão quando nenhuma revisão é especificada.

Se você passar um branch ou tag, o Transformers contata o Hub uma vez no início do carregamento para selecionar o commit e, em seguida, usa o cache da mesma forma para os arquivos desse commit.

O diretório padrão definido pela variável de ambiente do shell HF_HUB_CACHE é ~/.cache/huggingface/hub. No Windows, o diretório padrão é C:\Users\username\.cache\huggingface\hub.

Cache um modelo em um diretório diferente alterando o caminho nas variáveis de ambiente de shell a seguir (listadas por prioridade).

1. HF_HUB_CACHE (padrão)
2. HF_HOME
3. XDG_CACHE_HOME + /huggingface (somente se HF_HOME não estiver definido)

Modo offline

Para usar o Transformers em um ambiente offline ou protegido por firewall, é necessário baixar e armazenar em cache os arquivos com antecedência. Baixe um repositório de modelo do Hub com o método snapshot_download.

Consulte o guia Baixar arquivos do Hub para mais opções de download de arquivos do Hub. Você pode baixar arquivos de revisões específicas, baixar pela CLI e até mesmo filtrar quais arquivos baixar de um repositório.

from huggingface_hub import snapshot_download

snapshot_download(repo_id="meta-llama/Llama-2-7b-hf", repo_type="model")

Defina a variável de ambiente HF_HUB_OFFLINE=1 para impedir chamadas HTTP ao Hub ao carregar um modelo.

Outra opção para carregar apenas os arquivos em cache é definir local_files_only=True em from_pretrained().

from transformers import LlamaForCausalLM

model = LlamaForCausalLM.from_pretrained("./path/to/local/directory", local_files_only=True)

O modo offline (ou local_files_only=True) ainda pode converter um branch ou tag em um commit se um carregamento online anterior tiver salvo esse mapeamento no cache. Se o mapeamento nunca tiver sido salvo, o Transformers mantém o branch ou tag solicitado e continua com o carregamento offline regular. Você obtém os mesmos acertos de cache ou erros de arquivo ausente de um carregamento offline normal.