Guia de Instalação

Neste guia poderá encontrar informações para a instalação do 🤗 Transformers para qualquer biblioteca de Machine Learning com a qual esteja a trabalhar. Além disso, poderá encontrar informações sobre como gerar cachês e configurar o 🤗 Transformers para execução em modo offline (opcional).

🤗 Transformers foi testado com Python 3.10+ e PyTorch 2.4+. Para instalar a biblioteca de deep learning com que deseja trabalhar, siga as instruções correspondentes listadas a seguir:

• PyTorch

Instalação pelo Pip

É sugerido instalar o 🤗 Transformers num ambiente virtual. Se precisar de mais informações sobre ambientes virtuais em Python, consulte este guia. Um ambiente virtual facilitará a manipulação e organização de projetos e evita problemas de compatibilidade entre dependências.

Comece criando um ambiente virtual no diretório do seu projeto:

python -m venv .env

E para ativar o ambiente virtual:

source .env/bin/activate

Agora É possível instalar o 🤗 Transformers com o comando a seguir:

pip install transformers

Somente para a CPU, é possível instalar o 🤗 Transformers e a biblioteca de deep learning respectiva apenas numa linha.

Por exemplo, para instalar o 🤗 Transformers e o PyTorch, digite:

pip install transformers[torch]

Por último, verifique se o 🤗 Transformers foi instalado com sucesso usando o seguinte comando para baixar um modelo pré-treinado:

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('we love you'))"

Em seguida, imprima um rótulo e sua pontuação:

[{'label': 'POSITIVE', 'score': 0.9998704791069031}]

Instalação usando a fonte

Para instalar o 🤗 Transformers a partir da fonte use o seguinte comando:

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

O comando acima instalará a versão master mais atual em vez da última versão estável. A versão master é útil para utilizar os últimos updates contidos em 🤗 Transformers. Por exemplo, um erro recente pode ter sido corrigido somente após a última versão estável, antes que houvesse um novo lançamento. No entanto, há a possibilidade que a versão master não esteja estável. A equipa trata de mantér a versão master operacional e a maioria dos erros são resolvidos em poucas horas ou dias. Se encontrar quaisquer problemas, por favor abra um Issue para que o mesmo possa ser corrigido o mais rápido possível.

Verifique que o 🤗 Transformers está instalado corretamente usando o seguinte comando:

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('I love you'))"

Instalação editável

Uma instalação editável será necessária caso desejas um dos seguintes:

• Usar a versão master do código fonte.
• Contribuir ao 🤗 Transformers e precisa testar mudanças ao código.

Para tal, clone o repositório e instale o 🤗 Transformers com os seguintes comandos:

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

Estes comandos vão ligar o diretório para o qual foi clonado o repositório ao caminho de bibliotecas do Python. O Python agora buscará dentro dos arquivos que foram clonados além dos caminhos normais da biblioteca. Por exemplo, se os pacotes do Python se encontram instalados no caminho ~/anaconda3/envs/main/lib/python3.10/site-packages/, o Python também buscará módulos no diretório onde clonamos o repositório ~/transformers/.

É necessário manter o diretório transformers se desejas continuar usando a biblioteca.

Assim, É possível atualizar sua cópia local para com a última versão do 🤗 Transformers com o seguinte comando:

cd ~/transformers/
git pull

O ambiente de Python que foi criado para a instalação do 🤗 Transformers encontrará a versão master em execuções seguintes.

Instalação usando o Conda

É possível instalar o 🤗 Transformers a partir do canal conda conda-forge com o seguinte comando:

conda install conda-forge::transformers

Configuração do Cachê

Os modelos pré-treinados são baixados e armazenados no cachê local, encontrado em ~/.cache/huggingface/transformers/. Este é o diretório padrão determinado pela variável HF_HUB_CACHE dentro do shell. No Windows, este diretório pré-definido é dado por C:\Users\username\.cache\huggingface\transformers. É possível mudar as variáveis dentro do shell em ordem de prioridade para especificar um diretório de cachê diferente:

1. Variável de ambiente do shell (por padrão): HF_HUB_CACHE.
2. Variável de ambiente do shell:HF_HOME + transformers/.
3. Variável de ambiente do shell: XDG_CACHE_HOME + /huggingface/transformers.

Modo Offline

O 🤗 Transformers também pode ser executado num ambiente de firewall ou fora da rede (offline) usando arquivos locais. Para tal, configure a variável de ambiente de modo que HF_HUB_OFFLINE=1.

Você pode adicionar o 🤗 Datasets ao pipeline de treinamento offline declarando a variável de ambiente HF_DATASETS_OFFLINE=1.

Segue um exemplo de execução do programa numa rede padrão com firewall para instâncias externas, usando o seguinte comando:

python examples/pytorch/translation/run_translation.py --model_name_or_path google-t5/t5-small --dataset_name wmt16 --dataset_config ro-en ...

Execute esse mesmo programa numa instância offline com o seguinte comando:

HF_DATASETS_OFFLINE=1 HF_HUB_OFFLINE=1 \
python examples/pytorch/translation/run_translation.py --model_name_or_path google-t5/t5-small --dataset_name wmt16 --dataset_config ro-en ...

O script agora deve ser executado sem travar ou expirar, pois procurará apenas por arquivos locais.

Obtendo modelos e tokenizers para uso offline

Outra opção para usar o 🤗 Transformers offline é baixar os arquivos antes e depois apontar para o caminho local onde estão localizados. Existem três maneiras de fazer isso:

• Baixe um arquivo por meio da interface de usuário do Model Hub clicando no ícone ↓.

  

• Use o pipeline do [PreTrainedModel.from_pretrained] e [PreTrainedModel.save_pretrained]:

  1. Baixa os arquivos previamente com [PreTrainedModel.from_pretrained]:

  >>> from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
  
  >>> tokenizer = AutoTokenizer.from_pretrained("bigscience/T0_3B")
  >>> model = AutoModelForSeq2SeqLM.from_pretrained("bigscience/T0_3B")
  

  2. Salve os arquivos em um diretório específico com [PreTrainedModel.save_pretrained]:

  >>> tokenizer.save_pretrained("./your/path/bigscience_t0")
  >>> model.save_pretrained("./your/path/bigscience_t0")
  

  3. Quando estiver offline, acesse os arquivos com [PreTrainedModel.from_pretrained] do diretório especificado:

  >>> tokenizer = AutoTokenizer.from_pretrained("./your/path/bigscience_t0")
  >>> model = AutoModel.from_pretrained("./your/path/bigscience_t0")
  

• Baixando arquivos programaticamente com a biblioteca huggingface_hub:

  1. Instale a biblioteca huggingface_hub em seu ambiente virtual:

  python -m pip install huggingface_hub
  

  2. Utiliza a função hf_hub_download para baixar um arquivo para um caminho específico. Por exemplo, o comando a seguir baixará o arquivo config.json para o modelo T0 no caminho desejado:

  >>> from huggingface_hub import hf_hub_download
  
  >>> hf_hub_download(repo_id="bigscience/T0_3B", filename="config.json", cache_dir="./your/path/bigscience_t0")
  

Depois que o arquivo for baixado e armazenado no cachê local, especifique seu caminho local para carregá-lo e usá-lo:

>>> from transformers import AutoConfig

>>> config = AutoConfig.from_pretrained("./your/path/bigscience_t0/config.json")

Para obter mais detalhes sobre como baixar arquivos armazenados no Hub, consulte a seção How to download files from the Hub.

Source: docs/source/pt/installation.md