Guía de instalación

En esta guía puedes encontrar información para instalar 🤗 Transformers para cualquier biblioteca de Machine Learning con la que estés trabajando. Además, encontrarás información sobre cómo establecer el caché y cómo configurar 🤗 Transformers para correrlo de manera offline (opcional).

🤗 Transformers ha sido probada en Python 3.6+, PyTorch 1.1.0+, TensorFlow 2.0+, y Flax. Para instalar la biblioteca de deep learning con la que desees trabajar, sigue las instrucciones correspondientes listadas a continuación:

Instalación con pip

Es necesario instalar 🤗 Transformers en un entorno virtual. Si necesitas más información sobre entornos virtuales de Python, consulta esta guía. Un entorno virtual facilita el manejo de proyectos y evita problemas de compatibilidad entre dependencias.

Comienza por crear un entorno virtual en el directorio de tu proyecto:

python -m venv .env

Activa el entorno virtual:

source .env/bin/activate

Ahora puedes instalar 🤗 Transformers con el siguiente comando:

pip install transformers

Solo para CPU, puedes instalar 🤗 Transformers y una biblioteca de deep learning con un comando de una sola línea.

Por ejemplo, instala 🤗 Transformers y Pytorch:

pip install transformers[torch]

🤗 Transformers y TensorFlow 2.0:

pip install transformers[tf-cpu]

🤗 Transformers y Flax:

pip install transformers[flax]

Por último, revisa si 🤗 Transformers ha sido instalada exitosamente con el siguiente comando que descarga un modelo pre-entrenado:

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

Después imprime la etiqueta y el puntaje:

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

Instalación desde la fuente

Instala 🤗 Transformers desde la fuente con el siguiente comando:

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

El comando de arriba instala la versión master más actual en vez de la última versión estable. La versión master es útil para obtener los últimos avances de 🤗 Transformers. Por ejemplo, se puede dar el caso de que un error fue corregido después de la última versión estable pero aún no se ha liberado un nuevo lanzamiento. Sin embargo, existe la posibilidad de que la versión master no sea estable. El equipo trata de mantener la versión master operacional y la mayoría de los errores son resueltos en unas cuantas horas o un día. Si encuentras algún problema, por favor abre un Issue para que pueda ser corregido más rápido.

Verifica si 🤗 Transformers está instalada apropiadamente con el siguiente comando:

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

Instalación editable

Necesitarás una instalación editable si deseas:

Usar la versión master del código fuente.
Contribuir a 🤗 Transformers y necesitas probar cambios en el código.

Clona el repositorio e instala 🤗 Transformers con los siguientes comandos:

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

Éstos comandos van a ligar el directorio desde donde clonamos el repositorio al path de las bibliotecas de Python. Python ahora buscará dentro de la carpeta que clonaste además de los paths normales de la biblioteca. Por ejemplo, si los paquetes de Python se encuentran instalados en ~/anaconda3/envs/main/lib/python3.7/site-packages/, Python también buscará en el directorio desde donde clonamos el repositorio ~/transformers/.

Debes mantener el directorio transformers si deseas seguir usando la biblioteca.

Puedes actualizar tu copia local a la última versión de 🤗 Transformers con el siguiente comando:

cd ~/transformers/
git pull

El entorno de Python que creaste para la instalación de 🤗 Transformers encontrará la versión master en la siguiente ejecución.

Instalación con conda

Puedes instalar 🤗 Transformers desde el canal de conda huggingface con el siguiente comando:

conda install -c huggingface transformers

Configuración de Caché

Los modelos preentrenados se descargan y almacenan en caché localmente en: ~/.cache/huggingface/transformers/. Este es el directorio predeterminado proporcionado por la variable de entorno de shell TRANSFORMERS_CACHE. En Windows, el directorio predeterminado es dado por C:\Users\username\.cache\huggingface\transformers. Puedes cambiar las variables de entorno de shell que se muestran a continuación, en orden de prioridad, para especificar un directorio de caché diferente:

Variable de entorno del shell (por defecto): TRANSFORMERS_CACHE.
Variable de entorno del shell:HF_HOME + transformers/.
Variable de entorno del shell: XDG_CACHE_HOME + /huggingface/transformers.

🤗 Transformers usará las variables de entorno de shell PYTORCH_TRANSFORMERS_CACHE o PYTORCH_PRETRAINED_BERT_CACHE si viene de una iteración anterior de la biblioteca y ha configurado esas variables de entorno, a menos que especifiques la variable de entorno de shell TRANSFORMERS_CACHE.

Modo Offline

🤗 Transformers puede ejecutarse en un entorno con firewall o fuera de línea (offline) usando solo archivos locales. Configura la variable de entorno TRANSFORMERS_OFFLINE=1 para habilitar este comportamiento.

Puedes añadir 🤗 Datasets al flujo de entrenamiento offline declarando la variable de entorno HF_DATASETS_OFFLINE=1.

Por ejemplo, normalmente ejecutarías un programa en una red normal con firewall para instancias externas con el siguiente comando:

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

Ejecuta este mismo programa en una instancia offline con el siguiente comando:

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

El script ahora debería ejecutarse sin bloquearse ni esperar a que se agote el tiempo de espera porque sabe que solo debe buscar archivos locales.

Obtener modelos y tokenizers para uso offline

Otra opción para usar 🤗 Transformers offline es descargando previamente los archivos y después apuntar al path local donde se encuentren. Hay tres maneras de hacer esto:

Descarga un archivo mediante la interfaz de usuario del Model Hub haciendo click en el ícono ↓.

Utiliza el flujo de PreTrainedModel.from_pretrained() y PreTrainedModel.save_pretrained():

Descarga previamente los archivos con PreTrainedModel.from_pretrained():

>>> from transformers import AutoTokenizer, AutoModelForSeq2SeqLM

>>> tokenizer = AutoTokenizer.from_pretrained("bigscience/T0_3B")
>>> model = AutoModelForSeq2SeqLM.from_pretrained("bigscience/T0_3B")

Guarda los archivos en un directorio específico con PreTrainedModel.save_pretrained():

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

Cuando te encuentres offline, recarga los archivos con PreTrainedModel.from_pretrained() desde el directorio especificado:

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

Descarga de manera programática los archivos con la biblioteca huggingface_hub:
1. Instala la biblioteca huggingface_hub en tu entorno virtual:
```
python -m pip install huggingface_hub
```
2. Utiliza la función hf_hub_download para descargar un archivo a un path específico. Por ejemplo, el siguiente comando descarga el archivo config.json del modelo T0 al path deseado:
```
>>> from huggingface_hub import hf_hub_download

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

Una vez que el archivo se descargue y se almacene en caché localmente, especifica tu ruta local para cargarlo y usarlo:

>>> from transformers import AutoConfig

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

Para más detalles sobre cómo descargar archivos almacenados en el Hub consulta la sección How to download files from the Hub.