# Instalação Transformers funciona com [PyTorch](https://pytorch.org/get-started/locally/). Ele foi testado em Python 3.11+ e PyTorch 2.6+. ## Ambiente virtual [uv](https://docs.astral.sh/uv/) é um gerenciador de pacotes e projetos Python extremamente rápido, baseado em Rust, que exige um [ambiente virtual](https://docs.astral.sh/uv/pip/environments/) 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](https://pip.pypa.io/en/stable/), mas, se você preferir usar o pip, remova `uv` dos comandos abaixo. > [!TIP] > Consulte a documentação de [instalação](https://docs.astral.sh/uv/guides/install-python/) do uv para instalar o uv. Crie um ambiente virtual para instalar o Transformers. ```bash uv venv .env source .env/bin/activate ``` ## Python Instale o Transformers com o seguinte comando. [uv](https://docs.astral.sh/uv/) é um gerenciador rápido de pacotes e projetos Python baseado em Rust. Para instalar o Transformers com PyTorch para GPU NVIDIA (CUDA), instale os drivers CUDA apropriados para [PyTorch](https://pytorch.org/get-started/locally). Execute o comando abaixo para verificar se o seu sistema detecta uma GPU da NVIDIA. ```bash nvidia-smi ``` ```bash uv pip install "transformers[torch]" ``` Para instalar o Transformers com PyTorch em dispositivos NVIDIA Spark (como um laptop RTX Spark) que executam ARM64, instale o PyTorch a partir do índice PyPI da NVIDIA. Esses dispositivos exigem as compilações ARM64 do PyTorch da NVIDIA, que não estão disponíveis no índice PyPI padrão nem no índice de wheels padrão do PyTorch. Execute o comando abaixo para verificar se o seu sistema detecta uma GPU da NVIDIA. ```bash nvidia-smi ``` Instale o PyTorch a partir do índice PyPI da NVIDIA e, em seguida, instale o Transformers. ```bash uv pip install torch --index-url https://pypi.nvidia.com uv pip install transformers ``` Para instalar uma versão apenas de CPU do Transformers, execute o seguinte comando. ```bash uv pip install torch --index-url https://download.pytorch.org/whl/cpu uv pip install transformers ``` Para instalar o Transformers com PyTorch para GPU Intel (XPU), instale os [drivers de GPU Intel (XPU) para PyTorch](https://www.intel.com/content/www/us/en/developer/articles/tool/pytorch-prerequisites-for-intel-gpu/2-13.html) adequados e adicione a URL do índice do PyTorch para GPU Intel (XPU). Após instalar os drivers, execute o comando abaixo para [verificar se o seu sistema detecta uma GPU Intel](https://dgpu-docs.intel.com/driver/verification.html). ```bash xpu-smi ``` ```bash 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. ```bash 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](https://github.com/huggingface/transformers/issues) para que possamos corrigi-lo o mais rápido possível. Instale a partir do código-fonte com o seguinte comando. ```bash 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. ```bash 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](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs) é útil se você estiver desenvolvendo localmente com o Transformers. Ela vincula sua cópia local do Transformers ao [repositório](https://github.com/huggingface/transformers) do Transformers, em vez de copiar os arquivos. Os arquivos são adicionados ao caminho de importação do Python. ```bash git clone https://github.com/huggingface/transformers.git cd transformers uv pip install -e . ``` > [!WARNING] > 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. ```bash cd ~/transformers/ git pull ``` ## conda [conda](https://docs.conda.io/projects/conda/en/stable/#) é um gerenciador de pacotes agnóstico de linguagem. Instale o Transformers a partir do canal [conda-forge](https://anaconda.org/conda-forge/transformers) no seu novo ambiente virtual criado. ```bash 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()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.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 reconfirma no Hub 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](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#hfhubcache) (padrão) 2. [HF_HOME](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#hfhome) 3. [XDG_CACHE_HOME](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#xdgcachehome) + `/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](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/file_download#huggingface_hub.snapshot_download). > [!TIP] > Consulte o guia [Baixar arquivos do Hub](https://hf.co/docs/huggingface_hub/guides/download) 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. ```py 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()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained). ```py 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.