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. Pensez-y comme le “GitHub de l’IA” : vous y trouvez des milliers de modèles prêts à l’emploi, téléchargeables en une ligne de code.

Composant	Rôle	Analogie
Hub	Catalogue de modèles	L’App Store des modèles IA
Transformers	Librairie Python pour charger les modèles	Le SDK pour utiliser les modèles
Datasets	Jeux de données pour l’entraînement	La bibliothèque de données
Accelerate	Optimisation multi-GPU et mémoire	Le turbo pour gros modèles

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

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

# 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

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

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

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

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
)

À 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

Prochaines étapes

Ollama : alternative à Transformers Simplifiez l'inférence locale avec Ollama et son API OpenAI-compatible

Prompt Engineering Apprenez à écrire des prompts efficaces pour de meilleures réponses

vLLM : haute performance Servez des LLMs en production avec vLLM

Introduction RAG Augmentez les réponses de votre LLM avec vos propres données

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 →