Transformers documentation

Installation

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Installation

Installez 🤗 Transformers pour n’importe quelle librairie d’apprentissage profond avec laquelle vous avez l’habitude de travaillez, configurez votre cache et configurez 🤗 Transformers pour un usage hors ligne (facultatif).

🤗 Transformers est testé avec Python 3.6+, PyTorch 1.1.0+, TensorFlow 2.0+ et Flax. Consulter les instructions d’installation ci-dessous pour la librairie d’apprentissage profond que vous utilisez:

  • Instructions d’installation pour PyTorch.
  • Instructions d’installation pour TensorFlow 2.0.
  • Instructions d’installation pour Flax.

Installation avec pip

Vous devriez installer 🤗 Transformers dans un environnement virtuel. Si vous n’êtes pas à l’aise avec les environnements virtuels, consultez ce guide. Utiliser un environnement virtuel permet de facilement gérer différents projets et d’éviter des erreurs de compatibilité entre les différentes dépendances.

Commencez par créer un environnement virtuel dans l’espace de travail de votre projet :

python -m venv .env

Activez l’environnement virtuel. Sur Linux ou MacOs :

source .env/bin/activate

Activez l’environnement virtuel sur Windows :

.env/Scripts/activate

Maintenant, 🤗 Transformers peut être installé avec la commande suivante :

pip install transformers

Pour une utilisation avec CPU seulement, 🤗 Transformers et la librairie d’apprentissage profond de votre choix peuvent être installés en une seule ligne. Par exemple, installez 🤗 Transformers et PyTorch avec la commande suivante :

pip install 'transformers[torch]'

🤗 Transformers et TensorFlow 2.0 :

pip install 'transformers[tf-cpu]'

Pour les architectures mac M1 / ARM

Vous devez installer les outils suivants avant d’installer TensorFLow 2.0

brew install cmake
brew install pkg-config

🤗 Transformers et Flax :

pip install 'transformers[flax]'

Vérifiez que 🤗 Transformers a bien été installé avec la commande suivante. La commande va télécharger un modèle pré-entraîné :

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

Le label et score sont ensuite affichés :

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

Installation depuis le code source

Installez 🤗 Transformers depuis le code source avec la commande suivante :

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

Cette commande installe la version depuis la branche main au lieu de la dernière version stable. La version de la branche main est utile pour avoir les derniers développements. Par exemple, si un bug a été résolu depuis la dernière version stable mais n’a pas encore été publié officiellement. Cependant, cela veut aussi dire que la version de la branche main n’est pas toujours stable. Nous nous efforçons de maintenir la version de la branche main opérationnelle, et la plupart des problèmes sont généralement résolus en l’espace de quelques heures ou d’un jour. Si vous recontrez un problème, n’hésitez pas à créer une Issue pour que l’on puisse trouver une solution au plus vite !

Vérifiez que 🤗 Transformers a bien été installé avec la commande suivante :

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

Installation modifiable

Vous aurez besoin d’une installation modifiable si vous le souhaitez :

  • Utiliser la version de la branche main du code source.
  • Contribuer à 🤗 Transformers et vouler tester vos modifications du code source.

Clonez le projet et installez 🤗 Transformers avec les commandes suivantes :

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

Ces commandes créent des liens entre le dossier où le projet a été cloné et les chemins de vos librairies Python. Python regardera maintenant dans le dossier que vous avez cloné en plus des dossiers où sont installées vos autres librairies. Par exemple, si vos librairies Python sont installées dans ~/anaconda3/envs/main/lib/python3.7/site-packages/, Python cherchera aussi dans le dossier où vous avez cloné : ~/transformers/.

Vous devez garder le dossier transformers si vous voulez continuer d’utiliser la librairie.

Maintenant, vous pouvez facilement mettre à jour votre clone avec la dernière version de 🤗 Transformers en utilisant la commande suivante :

cd ~/transformers/
git pull

Votre environnement Python utilisera la version de la branche main lors de la prochaine exécution.

Installation avec conda

Installation via le canal conda-forge de conda :

conda install conda-forge::transformers

Configuration du cache

Les modèles pré-entraînés sont téléchargés et mis en cache localement dans le dossier suivant : ~/.cache/huggingface/hub. C’est le dossier par défaut donné par la variable d’environnement TRANSFORMERS_CACHE. Sur Windows, le dossier par défaut est C:\Users\nom_utilisateur\.cache\huggingface\hub. Vous pouvez modifier les variables d’environnement indiquées ci-dessous - par ordre de priorité - pour spécifier un dossier de cache différent :

  1. Variable d’environnement (par défaut) : HUGGINGFACE_HUB_CACHE ou TRANSFORMERS_CACHE.
  2. Variable d’environnement : HF_HOME.
  3. Variable d’environnement : XDG_CACHE_HOME + /huggingface.

🤗 Transformers utilisera les variables d’environnement PYTORCH_TRANSFORMERS_CACHE ou PYTORCH_PRETRAINED_BERT_CACHE si vous utilisez une version précédente de cette librairie et avez défini ces variables d’environnement, sauf si vous spécifiez la variable d’environnement TRANSFORMERS_CACHE.

Mode hors ligne

🤗 Transformers peut fonctionner dans un environnement cloisonné ou hors ligne en n’utilisant que des fichiers locaux. Définissez la variable d’environnement HF_HUB_OFFLINE=1 pour activer ce mode.

Ajoutez 🤗 Datasets à votre processus d’entraînement hors ligne en définissant la variable d’environnement HF_DATASETS_OFFLINE=1.

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 ...

Le script devrait maintenant s’exécuter sans rester en attente ou attendre une expiration, car il n’essaiera pas de télécharger des modèle sur le Hub.

Vous pouvez aussi éviter de télécharger un modèle à chaque appel de la fonction from_pretrained() en utilisant le paramètre [local_files_only]. Seuls les fichiers locaux sont chargés lorsque ce paramètre est activé (c.-à-d. local_files_only=True) :

from transformers import T5Model

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

Récupérer des modèles et des tokenizers pour une utilisation hors ligne

Une autre option pour utiliser 🤗 Transformers hors ligne est de télécharger les fichiers à l’avance, puis d’utiliser les chemins locaux lorsque vous en avez besoin en mode hors ligne. Il existe trois façons de faire cela :

  • Téléchargez un fichier via l’interface utilisateur sur le Model Hub en cliquant sur l’icône ↓.

    download-icon

  • Utilisez les fonctions PreTrainedModel.from_pretrained() et PreTrainedModel.save_pretrained() :

    1. Téléchargez vos fichiers à l’avance avec PreTrainedModel.from_pretrained():
    >>> from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
    
    >>> tokenizer = AutoTokenizer.from_pretrained("bigscience/T0_3B")
    >>> model = AutoModelForSeq2SeqLM.from_pretrained("bigscience/T0_3B")
    1. Sauvegardez les fichiers dans un dossier de votre choix avec PreTrainedModel.save_pretrained():
    >>> tokenizer.save_pretrained("./your/path/bigscience_t0")
    >>> model.save_pretrained("./your/path/bigscience_t0")
    1. Maintenant, lorsque vous êtes hors ligne, rechargez vos fichiers avec PreTrainedModel.from_pretrained() depuis le dossier où vous les avez sauvegardés :
    >>> tokenizer = AutoTokenizer.from_pretrained("./your/path/bigscience_t0")
    >>> model = AutoModel.from_pretrained("./your/path/bigscience_t0")
  • Téléchargez des fichiers de manière automatique avec la librairie huggingface_hub :

    1. Installez la librairie huggingface_hub dans votre environnement virtuel :
    python -m pip install huggingface_hub
    1. Utilisez la fonction hf_hub_download pour télécharger un fichier vers un chemin de votre choix. Par exemple, la commande suivante télécharge le fichier config.json du modèle T0 vers le chemin de votre choix :
    >>> from huggingface_hub import hf_hub_download
    
    >>> hf_hub_download(repo_id="bigscience/T0_3B", filename="config.json", cache_dir="./your/path/bigscience_t0")

Une fois que votre fichier est téléchargé et caché localement, spécifiez son chemin local pour le charger et l’utiliser :

>>> from transformers import AutoConfig

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

Consultez la section How to download files from the Hub (Comment télécharger des fichiers depuis le Hub) pour plus de détails sur le téléchargement de fichiers stockés sur le Hub.

< > Update on GitHub