Instalación

Transformers funciona con PyTorch. Se ha probado con Python 3.11+ y PyTorch 2.6+.

Entorno virtual

uv es un gestor de paquetes y proyectos de Python basado en Rust, extremadamente rápido, que requiere un entorno virtual de forma predeterminada para gestionar diferentes proyectos y evitar problemas de compatibilidad entre dependencias.

Puede usarse como un reemplazo directo de pip, pero si prefiere usar pip, elimine uv de los comandos siguientes.

Consulte la documentación de instalación de uv para instalar uv.

Cree un entorno virtual para instalar Transformers.

uv venv .env
source .env/bin/activate

Python

Instale Transformers con el siguiente comando.

uv es un gestor de paquetes y proyectos de Python rápido basado en 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

Pruebe si la instalación fue exitosa con el siguiente comando. Debería devolver una etiqueta y una puntuación para el texto proporcionado.

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

Instalación desde el código fuente

Instalar desde el código fuente instala la versión más reciente en lugar de la versión estable de la biblioteca. Esto garantiza que cuentes con los cambios más actualizados de Transformers y resulta útil para experimentar con las funciones más recientes o para corregir un error que aún no se ha publicado oficialmente en la versión estable.

La desventaja es que la última versión no siempre es estable. Si encuentras algún problema, abre un GitHub Issue para que podamos solucionarlo lo antes posible.

Instale desde el código fuente con el siguiente comando.

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

Comprueba si la instalación fue exitosa con el comando siguiente. Debería devolver una etiqueta y una puntuación para el texto proporcionado.

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

Instalación editable

Una instalación editable es útil si estás desarrollando localmente con Transformers. Enlaza tu copia local de Transformers con el repositorio de Transformers en lugar de copiar los archivos. Los archivos se añaden a la ruta de importación de Python.

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

Debes conservar la carpeta local de Transformers para seguir usándola.

Actualiza tu versión local de Transformers con los últimos cambios del repositorio principal con el siguiente comando.

cd ~/transformers/
git pull

conda

conda es un gestor de paquetes agnóstico de lenguaje. Instala Transformers desde el canal conda-forge en tu entorno virtual recién creado.

conda install conda-forge::transformers

Configuración

Después de la instalación, puedes configurar la ubicación de la caché de Transformers o configurar la biblioteca para su uso sin conexión.

Directorio de caché

Al cargar un modelo preentrenado con from_pretrained(), el modelo se descarga desde el Hub y se almacena en caché localmente.

Si pasas un hash de commit, Transformers utiliza la caché local para los archivos de ese commit y no vuelve a verificar el Hub para cada uno (incluidos los archivos que se sabe que faltan). Este es el comportamiento predeterminado cuando no se especifica una revisión.

Si pasas una rama o una etiqueta, Transformers contacta con el Hub una vez al inicio de la carga para seleccionar el commit y luego utiliza la caché de la misma manera para los archivos de ese commit.

El directorio predeterminado indicado por la variable de entorno de la shell HF_HUB_CACHE es ~/.cache/huggingface/hub. En Windows, el directorio predeterminado es C:\Users\username\.cache\huggingface\hub.

Cache un modelo en un directorio diferente cambiando la ruta en las siguientes variables de entorno de shell (enumeradas por prioridad).

1. HF_HUB_CACHE (predeterminado)
2. HF_HOME
3. XDG_CACHE_HOME + /huggingface (solo si HF_HOME no está definido)

Modo sin conexión

Para usar Transformers en un entorno sin conexión o con cortafuegos, es necesario descargar y almacenar en caché los archivos con antelación. Descargue un repositorio de modelos del Hub con el método snapshot_download.

Consulte la guía Descarga de archivos del Hub para conocer más opciones de descarga de archivos del Hub. Puede descargar archivos de revisiones específicas, descargar desde la CLI e incluso filtrar qué archivos descargar de un repositorio.

from huggingface_hub import snapshot_download

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

Establezca la variable de entorno HF_HUB_OFFLINE=1 para evitar las llamadas HTTP al Hub al cargar un modelo.

Otra opción para cargar solo archivos en caché es establecer local_files_only=True en from_pretrained().

from transformers import LlamaForCausalLM

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

El modo offline (o local_files_only=True) aún puede convertir una rama o etiqueta en un commit si una carga online anterior guardó esa correspondencia en la caché. Si la correspondencia nunca se guardó, Transformers mantiene la rama o etiqueta que solicitaste y continúa con la carga offline regular. Obtendrás los mismos aciertos de caché o errores de archivo no encontrado que en una carga offline normal.