Installation

Transformers fonctionne avec PyTorch. Il a été testé sur Python 3.11+ et PyTorch 2.6+.

Environnement virtuel

uv est un gestionnaire de paquets et de projets Python basé sur Rust, extrêmement rapide, qui requiert par défaut un environnement virtuel pour gérer différents projets et éviter les problèmes de compatibilité entre les dépendances.

Il peut être utilisé comme substitut direct de pip, mais si vous préférez utiliser pip, supprimez uv des commandes ci-dessous.

Consultez la documentation d'installation de uv pour installer uv.

Créez un environnement virtuel pour y installer Transformers.

uv venv .env
source .env/bin/activate

Python

Installez Transformers avec la commande suivante.

uv est un gestionnaire de paquets et de projets Python rapide, basé sur 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

Testez si l'installation a réussi avec la commande suivante. Elle doit retourner un libellé et un score pour le texte fourni.

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

Installation depuis la source

L’installation depuis le code source installe la version la plus récente plutôt que la version stable de la bibliothèque. Elle garantit que vous disposez des modifications les plus à jour de Transformers et est utile pour expérimenter avec les dernières fonctionnalités ou corriger un bug qui n’a pas encore été officiellement publié dans la version stable.

L'inconvénient est que la dernière version n'est pas toujours stable. Si vous rencontrez des problèmes, veuillez ouvrir un GitHub Issue afin que nous puissions le corriger dans les plus brefs délais.

Installez à partir du code source avec la commande suivante.

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

Vérifiez que l'installation a réussi à l'aide de la commande ci-dessous. Elle doit retourner un libellé et un score pour le texte fourni.

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

Installation modifiable

Une installation en mode éditable est utile si vous développez localement avec Transformers. Elle associe votre copie locale de Transformers au dépôt de Transformers au lieu de copier les fichiers. Les fichiers sont ajoutés au chemin d’importation de Python.

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

Vous devez conserver le dossier local Transformers pour continuer à l'utiliser.

Mettez à jour votre version locale de Transformers avec les dernières modifications du dépôt principal à l'aide de la commande suivante.

cd ~/transformers/
git pull

conda

conda est un gestionnaire de paquets indépendant du langage. Installez Transformers depuis le canal conda-forge dans votre nouvel environnement virtuel.

conda install conda-forge::transformers

Configuration

Après l'installation, vous pouvez configurer l'emplacement du cache de Transformers ou configurer la bibliothèque pour une utilisation hors ligne.

Répertoire de cache

Lorsque vous chargez un modèle préentraîné avec from_pretrained(), le modèle est téléchargé depuis le Hub et mis en cache localement.

Si vous passez un hachage de commit, Transformers utilise le cache local pour les fichiers de ce commit et ne re-vérifie pas le Hub pour chacun d’entre eux (y compris les fichiers connus comme manquants). C’est le comportement par défaut lorsqu’aucune révision n’est spécifiée.

Si vous passez une branche ou un tag, Transformers contacte le Hub une seule fois au début du chargement pour sélectionner le commit, puis utilise le cache de la même manière pour les fichiers de ce commit.

Le répertoire par défaut défini par la variable d'environnement du shell HF_HUB_CACHE est ~/.cache/huggingface/hub. Sur Windows, le répertoire par défaut est C:\Users\username\.cache\huggingface\hub.

Mettre un modèle en cache dans un répertoire différent en modifiant le chemin dans les variables d'environnement shell suivantes (classées par ordre de priorité).

1. HF_HUB_CACHE (par défaut)
2. HF_HOME
3. XDG_CACHE_HOME + /huggingface (uniquement si HF_HOME n'est pas défini)

Mode hors ligne

Pour utiliser Transformers dans un environnement hors ligne ou protégé par un pare-feu, il est nécessaire de télécharger et de mettre en cache les fichiers à l'avance. Téléchargez un dépôt de modèle depuis le Hub à l'aide de la méthode snapshot_download.

Reportez-vous au guide Télécharger des fichiers depuis le Hub pour plus d'options de téléchargement de fichiers depuis le Hub. Vous pouvez télécharger des fichiers depuis des révisions spécifiques, télécharger depuis le CLI et même filtrer les fichiers à télécharger depuis un dépôt.

from huggingface_hub import snapshot_download

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

Définissez la variable d'environnement HF_HUB_OFFLINE=1 pour empêcher les appels HTTP au Hub lors du chargement d'un modèle.

Une autre option pour ne charger que les fichiers en cache consiste à définir local_files_only=True dans from_pretrained().

from transformers import LlamaForCausalLM

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

Le mode hors ligne (ou local_files_only=True) peut toujours convertir une branche ou un tag en commit si un chargement en ligne antérieur a enregistré cette correspondance dans le cache. Si la correspondance n’a jamais été enregistrée, Transformers conserve la branche ou le tag demandé et poursuit avec le chargement hors ligne standard. Vous obtenez les mêmes correspondances de cache ou erreurs de fichier manquant qu’avec un chargement hors ligne normal.