Hugging Face Transformers

Hugging Face Transformers est la librairie Python de référence pour utiliser des LLMs open source. Ce guide vous apprend à charger un modèle, générer du texte et créer un assistant conversationnel, le tout en quelques lignes de code.

Prérequis

• Python 3.10+
• 8 Go de RAM minimum (16 Go recommandé)
• Notions de base en Python (fonctions, classes)
• Connaître le concept de LLM (guide d'introduction)

Ce que vous allez apprendre

À la fin de ce guide, vous saurez :

• Utiliser pipeline() pour des tâches courantes (génération, résumé, classification)
• Charger un modèle manuellement avec AutoModel et AutoTokenizer
• Contrôler la génération de texte (température, sampling, longueur)
• Optimiser l'inférence sur CPU avec la quantification
• Créer un assistant conversationnel local

Qu'est-ce que Hugging Face ?

Hugging Face est une plateforme et un écosystème qui facilite l'utilisation des modèles d'IA. Son Hub héberge des milliers de modèles open source versionnés, chacun accompagné de ses poids, de sa configuration et de sa documentation, téléchargeables en une ligne de code depuis la librairie Transformers.

Composant	Rôle
Hub	Catalogue de modèles
Transformers	Librairie Python pour charger les modèles
Datasets	Jeux de données pour l'entraînement
Accelerate	Optimisation multi-GPU et mémoire

Glissez pour voir

La librairie Transformers fonctionne avec PyTorch et TensorFlow. Dans ce guide, nous utilisons PyTorch (le défaut).

Installation

1. Créer un environnement virtuel

   python -m venv hf-env
   source hf-env/bin/activate  # Windows: hf-env\Scripts\activate

2. Installer les librairies

   pip install transformers torch accelerate

   • transformers : la librairie principale
   • torch : PyTorch (backend de calcul)
   • accelerate : optimisation automatique de la mémoire

3. Vérifier l'installation

   import transformers
   print(transformers.__version__)
   # Attendu : 4.x.x ou 5.x.x

Authentification (optionnel)

Certains modèles (Llama, Mistral) nécessitent une authentification. Créez un compte sur huggingface.co, puis :

pip install huggingface_hub
huggingface-cli login

Collez votre token (récupérable sur huggingface.co/settings/tokens).

Pipeline : l'API la plus simple

L'API pipeline() est le moyen le plus rapide d'utiliser un modèle. Une seule ligne de code suffit pour effectuer une tâche.

Génération de texte

from transformers import pipeline

# Créer un pipeline de génération
generator = pipeline("text-generation", model="Qwen/Qwen2.5-0.5B-Instruct")

# Générer du texte
result = generator("L'intelligence artificielle permet de", max_new_tokens=50)
print(result[0]["generated_text"])

Sortie attendue :

L'intelligence artificielle permet de résoudre des problèmes complexes
en analysant de grandes quantités de données...

Tâches disponibles

Le pipeline() supporte de nombreuses tâches :

Tâche	Identifiant	Exemple d'utilisation
Génération de texte	text-generation	Écrire, compléter, coder
Résumé	summarization	Condenser un article
Traduction	translation	FR → EN, EN → FR
Classification	text-classification	Sentiment, catégorie
Question-réponse	question-answering	Extraire une réponse d'un texte
Remplissage	fill-mask	Deviner un mot manquant

Glissez pour voir

Exemple : classification de sentiment

Ce deuxième exemple montre que pipeline() ne se limite pas à la génération : ici, la tâche text-classification attribue une note de sentiment à un texte. Observez la sortie, une liste de dictionnaires avec un label (« 5 stars ») et un score de confiance entre 0 et 1. C'est ce score qu'on filtre en pratique pour ne garder que les prédictions fiables.

from transformers import pipeline

classifier = pipeline("text-classification", model="nlptown/bert-base-multilingual-uncased-sentiment")

result = classifier("Ce produit est vraiment excellent, je recommande !")
print(result)
# [{'label': '5 stars', 'score': 0.73}]

Configurer le device

Par défaut, le pipeline utilise le CPU. Pour utiliser un GPU ou laisser accelerate choisir automatiquement :

CPU (défaut)

pipeline = pipeline("text-generation", model="Qwen/Qwen2.5-0.5B-Instruct", device=-1)

GPU

pipeline = pipeline("text-generation", model="Qwen/Qwen2.5-0.5B-Instruct", device=0)

Auto (recommandé)

pipeline = pipeline("text-generation", model="Qwen/Qwen2.5-0.5B-Instruct", device_map="auto")

AutoModel et AutoTokenizer

Pour un contrôle plus fin, chargez le modèle et le tokenizer séparément. C'est l'approche recommandée pour les applications en production.

Comprendre le tokenizer

Le tokenizer convertit du texte en nombres (tokens) que le modèle comprend, puis reconvertit la sortie en texte lisible.

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct")

# Texte → Tokens
text = "Bonjour, comment ça va ?"
tokens = tokenizer(text, return_tensors="pt")
print(tokens["input_ids"])
# tensor([[9707, 11, 3530, 9255, 8089, 949]])

# Tokens → Texte
decoded = tokenizer.decode(tokens["input_ids"][0])
print(decoded)
# "Bonjour, comment ça va ?"

Charger le modèle

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model_id = "Qwen/Qwen2.5-0.5B-Instruct"

# Charger avec optimisation automatique
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    device_map="auto",
    torch_dtype=torch.float16  # Réduit l'utilisation mémoire
)
tokenizer = AutoTokenizer.from_pretrained(model_id)

Paramètres importants :

Paramètre	Effet
device_map="auto"	Place le modèle sur le meilleur device disponible
torch_dtype=torch.float16	Utilise la demi-précision (moins de RAM)
torch_dtype=torch.bfloat16	Alternative à float16, plus stable
low_cpu_mem_usage=True	Charge le modèle progressivement

Glissez pour voir

Générer du texte manuellement

Après le chargement séparé du modèle et du tokenizer, la génération se fait en trois temps que le code ci-dessous enchaîne : tokeniser le prompt, appeler generate() avec ses paramètres, puis décoder les tokens de sortie en texte. Le .to(model.device) est le détail qui compte, il place les tenseurs d'entrée sur le même device que le modèle, faute de quoi la génération échoue.

# Préparer l'entrée
prompt = "Explique ce qu'est Python en une phrase."
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)

# Générer
outputs = model.generate(
    **inputs,
    max_new_tokens=100,
    do_sample=True,
    temperature=0.7,
)

# Décoder la sortie
response = tokenizer.decode(outputs[0], skip_special_tokens=True)
print(response)

Paramètres de génération

La méthode generate() offre de nombreux paramètres pour contrôler la sortie.

Paramètres essentiels

Le paramètre pivot est do_sample : tant qu'il vaut False, la génération est déterministe et les réglages temperature, top_p et top_k n'ont aucun effet. Activez do_sample=True d'abord, puis ajustez ces trois curseurs. max_new_tokens mérite aussi votre attention, car il plafonne la longueur de la réponse et donc le temps de calcul.

Paramètre	Type	Description	Valeur typique
max_new_tokens	int	Nombre max de tokens à générer	50-500
do_sample	bool	Active l'échantillonnage aléatoire	True pour créatif
temperature	float	Contrôle la créativité (0.1-2.0)	0.7 par défaut
top_p	float	Nucleus sampling (0.0-1.0)	0.9
top_k	int	Limite les tokens candidats	50
repetition_penalty	float	Pénalise les répétitions	1.1-1.3

Glissez pour voir

Stratégies de décodage

Greedy (déterministe)

Sélectionne toujours le token le plus probable. Rapide mais répétitif.

outputs = model.generate(
    **inputs,
    max_new_tokens=50,
    do_sample=False  # Greedy par défaut
)

Sampling (créatif)

Échantillonne parmi les tokens probables. Plus varié.

outputs = model.generate(
    **inputs,
    max_new_tokens=50,
    do_sample=True,
    temperature=0.8,
    top_p=0.9
)

Beam Search (structuré)

Explore plusieurs chemins en parallèle. Bon pour la traduction.

outputs = model.generate(
    **inputs,
    max_new_tokens=50,
    num_beams=4,
    early_stopping=True
)

Température : impact sur la sortie

La température règle le niveau de hasard au moment de choisir chaque token : basse, le modèle privilégie les mots les plus probables ; haute, il ose des suites moins attendues. Lisez ce tableau comme une échelle, choisissez une valeur basse (0.1-0.3) dès que la justesse prime (code, réponses techniques), une valeur plus haute (0.8-1.0) pour la variété. Au-delà de 1.0, la sortie devient souvent incohérente.

Température	Comportement	Cas d'usage
0.1-0.3	Très prévisible, factuel	Code, réponses techniques
0.5-0.7	Équilibré	Conversations, résumés
0.8-1.0	Créatif, varié	Écriture créative
>1.0	Très aléatoire, incohérent	Rarement utile

Glissez pour voir

Cas pratique : assistant conversationnel

Créons un assistant capable de maintenir une conversation multi-turn.

Le code complet

Ce script réunit tout ce qui précède en un assistant conversationnel. Deux mécanismes le rendent multi-tour : la liste messages qui conserve l'historique (system, user, assistant) d'un échange à l'autre, et apply_chat_template() qui met en forme cet historique selon le format attendu par le modèle. Le découpage outputs[0][input_ids.shape[1]:] isole la réponse en retirant le prompt d'entrée.

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

# Configuration
model_id = "Qwen/Qwen2.5-0.5B-Instruct"

# Chargement
print("Chargement du modèle...")
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    device_map="auto",
    torch_dtype=torch.float16
)
tokenizer = AutoTokenizer.from_pretrained(model_id)
print("Modèle prêt !")

def chat(messages: list[dict], max_tokens: int = 200) -> str:
    """Génère une réponse à partir d'un historique de conversation."""
    # Appliquer le template de chat du modèle
    input_ids = tokenizer.apply_chat_template(
        messages,
        add_generation_prompt=True,
        return_tensors="pt"
    ).to(model.device)

    # Générer
    outputs = model.generate(
        input_ids,
        max_new_tokens=max_tokens,
        do_sample=True,
        temperature=0.7,
        top_p=0.9,
        repetition_penalty=1.1,
        pad_token_id=tokenizer.eos_token_id
    )

    # Extraire uniquement la réponse (sans le prompt)
    response = tokenizer.decode(
        outputs[0][input_ids.shape[1]:],
        skip_special_tokens=True
    )
    return response.strip()

# Boucle de conversation
messages = [
    {"role": "system", "content": "Tu es un assistant DevOps expert et pédagogue."}
]

print("\nAssistant DevOps prêt. Tapez 'quit' pour quitter.\n")

while True:
    user_input = input("Vous : ").strip()
    if user_input.lower() == "quit":
        break

    messages.append({"role": "user", "content": user_input})
    response = chat(messages)
    messages.append({"role": "assistant", "content": response})

    print(f"\nAssistant : {response}\n")

Exemple de conversation

Voici ce que produit le script sur deux tours de dialogue. L'intérêt est de vérifier la mémoire conversationnelle : à la deuxième question (« Comment en créer un ? »), l'assistant comprend que « en » renvoie au conteneur Docker évoqué juste avant, car l'historique complet lui est renvoyé à chaque appel.

Vous : C'est quoi un conteneur Docker ?

Assistant : Un conteneur Docker est un environnement isolé et léger
qui contient une application avec toutes ses dépendances. Imagine
une boîte qui contient tout ce dont ton application a besoin pour
fonctionner, indépendamment du système hôte.

Vous : Comment en créer un ?

Assistant : Pour créer un conteneur, tu as besoin d'abord d'une image.
Voici les étapes :
1. Crée un fichier `Dockerfile` qui décrit ton image
2. Construis l'image : `docker build -t mon-app .`
3. Lance le conteneur : `docker run mon-app`

Optimisation pour CPU

Les modèles LLM sont gourmands en ressources. Voici comment les optimiser pour un usage CPU.

Quantification avec bitsandbytes

La quantification réduit la précision des poids (32 bits → 8 ou 4 bits), diminuant la mémoire et accélérant l'inférence.

pip install bitsandbytes

from transformers import AutoModelForCausalLM, BitsAndBytesConfig
import torch

# Configuration 4-bit
quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.float16
)

model = AutoModelForCausalLM.from_pretrained(
    "mistralai/Mistral-7B-Instruct-v0.2",
    quantization_config=quantization_config,
    device_map="auto"
)

Impact de la quantification :

Précision	RAM pour 7B	Qualité	Vitesse
float32	~28 Go	Maximale	Lente
float16	~14 Go	Très bonne	Moyenne
int8	~7 Go	Bonne	Rapide
int4	~4 Go	Acceptable	Très rapide

Glissez pour voir

Modèles légers recommandés

Pour un usage CPU sans quantification, privilégiez les modèles de petite taille :

Modèle	Taille	Langue	Cas d'usage
Qwen/Qwen2.5-0.5B-Instruct	0.5B	Multi	Chat léger, tests
Qwen/Qwen2.5-1.5B-Instruct	1.5B	Multi	Chat équilibré
google/gemma-2-2b-it	2B	Multi	Bon compromis
microsoft/Phi-3-mini-4k-instruct	3.8B	EN	Performances/taille
mistralai/Mistral-7B-Instruct-v0.2	7B	Multi	Qualité (avec quant.)

Glissez pour voir

Conseil performance

Sur CPU, un modèle de 1-3B paramètres offre le meilleur rapport qualité/vitesse. Au-delà de 7B, la quantification est quasi obligatoire.

Stocker les modèles localement

Les modèles sont téléchargés dans ~/.cache/huggingface/. Pour les stocker ailleurs :

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-0.5B-Instruct",
    cache_dir="./models/"
)

Pour un usage offline, le modèle sera chargé depuis ./models/ sans connexion.

Résolution des erreurs courantes

Erreur d'authentification

You are trying to access a gated model.

Solution : Le modèle nécessite une authentification.

huggingface-cli login

Puis acceptez les conditions d'utilisation sur la page du modèle.

Mémoire insuffisante (OOM)

CUDA out of memory / Killed

Solutions :

1. Utiliser un modèle plus petit
2. Activer la quantification (int8 ou int4)
3. Réduire max_new_tokens
4. Ajouter low_cpu_mem_usage=True au chargement

Génération trop lente

Solutions :

1. Utiliser torch_dtype=torch.float16
2. Activer la quantification
3. Réduire max_new_tokens
4. Installer accelerate pour l'optimisation automatique

Modèle qui se répète

La réponse contient des répétitions...répétitions...répétitions

Solution : Ajuster les paramètres de génération :

outputs = model.generate(
    **inputs,
    repetition_penalty=1.2,  # Augmenter (1.1-1.5)
    no_repeat_ngram_size=3   # Interdit les répétitions de 3 tokens
)

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

Concept	Ce qu'il faut retenir
Pipeline	API simple pour tâches courantes, 1 ligne de code
AutoModel	Contrôle fin, recommandé en production
Tokenizer	Convertit texte ↔ tokens
device_map="auto"	Laisse accelerate choisir le meilleur device
torch_dtype=float16	Divise par 2 l'utilisation mémoire
Quantification	Réduit encore la mémoire (int8, int4)
temperature	0.1-0.3 factuel, 0.7+ créatif

Glissez pour voir

Pour aller plus loin

• SGLang : RadixAttention : Le serveur qui prend le relais de Transformers quand le débit GPU devient le sujet.
• Introduction au RAG : Brancher un modèle Transformers sur vos propres documents.
• Embeddings et similarité : La famille de modèles Hugging Face qui sert à indexer plutôt qu'à générer.

FAQ - Questions Fréquemment Posées

Qu'est-ce que Hugging Face ?

Hugging Face est une entreprise française qui propose une plateforme et des outils open source pour partager, utiliser et entraîner des modèles d'intelligence artificielle, notamment dans le domaine du traitement automatique du langage naturel.

Qu'est-ce que la bibliothèque Transformers ?

Transformers est une bibliothèque Python développée par Hugging Face. Elle permet de télécharger, charger et utiliser facilement des modèles de type Transformer comme BERT, GPT ou LLaMA pour diverses tâches de NLP.

Quels sont les prérequis matériels pour exécuter un LLM en local ?

Il faut un ordinateur sous Linux, macOS ou Windows, avec 8 à 16 Go de RAM, un processeur moderne (Intel ou AMD) et 5 à 10 Go d'espace disque libre.

Quels sont les modèles adaptés au français et à une exécution sur CPU ?

Parmi les modèles adaptés : camembert-base pour la classification, bloomz-560m pour la génération de texte multilingue, et t5-small pour la traduction ou le résumé. Tous sont légers et partiellement ou entièrement compatibles avec le français.

Comment s'authentifier sur Hugging Face pour accéder à certains modèles ?

Il faut créer un compte Hugging Face, générer un token via les paramètres, puis s'authentifier avec la commande `huggingface-cli login` en collant le token.

Comment créer un assistant local avec Hugging Face ?

Il faut charger un modèle adapté (comme LiquidAI/LFM2-1.2B), préparer un prompt, générer une réponse avec `model.generate`, et afficher le texte obtenu via le tokenizer.

Que faire en cas d'erreur de mémoire ou de plantage ?

Essayez un modèle plus petit, utilisez une version quantifiée, réduisez le nombre de tokens générés ou libérez de la RAM en fermant d'autres programmes.

Qu'est-ce qu'un modèle quantifié ?

Un modèle quantifié est un modèle dont les poids ont été compressés (par exemple en int8) pour utiliser moins de mémoire et s'exécuter plus rapidement, particulièrement utile sur CPU.

×

📖 Voir la documentation →