#
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 `TRANSFORMERS_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 TRANSFORMERS_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 ↓.

- 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")

  2. 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")

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

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