Exemple de code : Distillation
Ce que le dossier 06-distillation/ fournit pour cette méthode. Principe et références : Distillation.
Ce que fait l'exemple
Le besoin : un petit modèle, rapide et peu coûteux à servir, qui raisonne mieux sur des problèmes rédigés. On dispose d'un modèle plus gros et meilleur, et de questions, mais pas forcément de bonnes solutions rédigées.
Résultats (RTX 5070 Ti Laptop ; 1 319 problèmes de test de GSM8K, 200 problèmes de non-régression) :
| GSM8K | Non-régression (arithmétique) | |
|---|---|---|
| Enseignant Qwen2.5-3B-Instruct | 0,760 [0,736 ; 0,782] | 0,985 |
| Élève Qwen2.5-0.5B-Instruct, avant | 0,411 [0,385 ; 0,438] | 0,955 |
| Élève distillé (2 488 solutions justes de l'enseignant) | 0,451 [0,424 ; 0,478] | 0,915 |
| Témoin : même entraînement, solutions écrites par les auteurs du jeu | 0,302 [0,278 ; 0,327] | 0,855 |
Écarts appariés sur les mêmes problèmes : distillé − avant +0,040 [+0,014 ; +0,067], p = 0,004 ; distillé − témoin +0,149 [+0,119 ; +0,180] ; non-régression du distillé −0,04, non significatif (p = 0,08).
Ce qu'on en retient.
- La distillation fait progresser l'élève de 4 points, un écart net mais modeste : l'élève reste loin de l'enseignant (0,76). Un modèle 6 fois plus petit n'absorbe pas tout le raisonnement d'un plus gros en 2 488 exemples.
- Qui rédige les solutions compte plus que leur justesse : les solutions humaines de GSM8K sont justes mais très courtes (« Ben's iPhone is 2 * 1 year = 2 years old… »). L'élève qui les imite cesse de raisonner pas à pas et chute à 0,30. Les solutions de l'enseignant, détaillées dans le style des modèles Qwen, le font progresser : +15 points par rapport au témoin.
- C'est la recette des petits modèles de raisonnement (DeepSeek-R1-Distill, Qwen2.5-Math) : faire rédiger un modèle fort, garder ce qui est vérifié juste, entraîner le petit dessus.
Variantes
Variante encodeur : distiller un classifieur
Le besoin : un classifieur de texte (sentiment, modération, routage) qui tourne sur CPU ou à fort débit, alors que le bon modèle est un gros encodeur. On a peu d'exemples étiquetés, mais beaucoup de textes sans étiquette.
variantes/encodeur-classification distille RoBERTa-base fine-tuné sur SST-2 (125 M paramètres) vers BERT-mini (11 M), la recette DistilBERT / TinyBERT. L'élève apprend les probabilités de classes de l'enseignant (température 3) ; les deux modèles tokenisent chacun le texte, leurs tokenizers peuvent différer. L'élève voit 2 000 phrases étiquetées et 18 000 phrases sans étiquette annotées par l'enseignant. Témoin : le même élève entraîné sur les seules 2 000 phrases étiquetées, sans enseignant (alpha=0). La mesure porte sur les 872 phrases de validation de SST-2.
| Exactitude (872 phrases) | Paramètres | |
|---|---|---|
| Enseignant RoBERTa-base | 0,940 [0,923 ; 0,954] | 125 M |
| Élève, avant | 0,509 [0,476 ; 0,542] | 11 M |
| Témoin sans enseignant | 0,758 [0,729 ; 0,785] | 11 M |
| Élève distillé | 0,839 [0,814 ; 0,862] | 11 M |
La distillation apporte 8 points sur le témoin, avec un modèle 11 fois plus petit : l'enseignant transmet ce qu'il sait des 18 000 phrases sans étiquette. L'élève reste à 10 points de l'enseignant ; un élève plus grand (DistilBERT, 66 M) réduit l'écart.
Composants de l'exemple
flowchart TD
classDef externe fill:#fed7aa,stroke:#ea580c,color:#7c2d12
classDef code fill:#ffffff,stroke:#6b7280,color:#1f2937
classDef gpu fill:#fecaca,stroke:#dc2626,color:#7f1d1d
classDef disque fill:#dcfce7,stroke:#16a34a,color:#14532d
Hub["Hugging Face Hub<br/>Qwen2.5-3B-Instruct<br/>Qwen2.5-0.5B-Instruct, GSM8K"]
Cache[("cache disque<br/>~/.cache/huggingface")]
subgraph Py["Processus Python"]
Run["run.py<br/>charge les données<br/>et les 2 modèles"]
Ev["evaluation.py<br/>génération"]
TRL["TRL SFTTrainer<br/>élève, tous les poids"]
end
GPU["GPU CUDA, 12 Go"]
Out[("sorties/06-distillation/")]
Hub -- "① HTTPS GET, 1re fois<br/>poids (6 Go + 1 Go), GSM8K" --> Cache
Cache -- "② lecture des poids<br/>et des données" --> Run
Run -- "③ copie des poids<br/>en mémoire GPU" --> GPU
Run -- "④ ⑥ ⑨ appel Python<br/>mesures, réponses de l'enseignant" --> Ev
Ev -- "⑤ noyaux CUDA<br/>génération" --> GPU
Run -- "⑦ ⑪ appel Python<br/>trainer.train()" --> TRL
TRL -- "⑧ noyaux CUDA<br/>forward, backward" --> GPU
TRL -- "⑩ écriture<br/>élève distillé" --> Out
Run -- "⑫ écriture<br/>resultats.json" --> Out
GPU ~~~ Out
class Hub externe
class Run,Ev,TRL code
class GPU gpu
class Cache,Out disque
make run EX=SIGN06 vérifie les prérequis (modules, GPU), puis lance run.py dans l'environnement .venv. Le script lit config.yaml (enseignant, élève, mode sequence, réglages) et charge GSM8K : des problèmes de mathématiques rédigés, avec la solution écrite par les auteurs du jeu. 3 000 problèmes d'entraînement servent de questions à l'enseignant ; les 1 319 problèmes de test servent à mesurer. L'enseignant, Qwen2.5-3B-Instruct, est nettement meilleur que l'élève, Qwen2.5-0.5B-Instruct, sur ces problèmes.
- ① Téléchargement. Au premier lancement, les poids de l'enseignant (environ 6 Go) et de l'élève (environ 1 Go), et le jeu
openai/gsm8k, sont téléchargés depuis le Hugging Face Hub, par HTTPS. - ② Lecture. Tout est rangé dans le cache
~/.cache/huggingface; les lancements suivants le relisent sur le disque, sans réseau. - ③ Copie sur le GPU. L'élève est copié en float32, parce que c'est lui qu'on entraîne ; l'enseignant en bf16, figé.
- ④ Mesures avant.
run.pyappellecommun/evaluation.py, qui pose les 1 319 problèmes de test à l'enseignant puis à l'élève, ainsi que 200 problèmes d'arithmétique de non-régression. - ⑤ Génération sur le GPU. Par lots de 32, chaque modèle raisonne jusqu'à 512 tokens ; le nombre final de chaque réponse est comparé au résultat attendu.
- ⑥ L'enseignant rédige. Il résout les 3 000 problèmes d'entraînement ; seules ses réponses justes sont gardées (2 488, soit 83 %). Il quitte ensuite le GPU.
- ⑦ Entraînement de l'élève. Les 2 488 couples problème → solution de l'enseignant sont confiés au SFTTrainer de TRL, qui entraîne tous les poids de l'élève, la perte portant sur la réponse seulement.
- ⑧ Forward et backward sur le GPU. Lots de 4, accumulés 4 fois (16 exemples par pas), 2 époques, taux d'apprentissage 1e-5, gradient checkpointing, AdamW 8 bits.
- ⑨ Mesure après, sur les mêmes problèmes, avec le même décodage.
- ⑩ Écriture de l'élève complet dans
sorties/06-distillation/eleve-sequence/. - ⑪ Témoin. L'élève d'origine est rechargé et entraîné exactement de la même façon, sur les mêmes 2 488 problèmes, mais avec les solutions écrites par les auteurs de GSM8K ; il est mesuré comme en ⑨. L'écart avec l'élève distillé isole ce qu'apporte l'enseignant.
- ⑫ Écriture du rapport dans
sorties/06-distillation/resultats.json, avec le même tableau affiché dans le terminal.
Ce que fait le GPU. Le processus Python ne calcule presque rien lui-même : PyTorch envoie au GPU des « noyaux CUDA », de petits programmes qui font les multiplications de matrices et l'attention sur les poids et les activations déjà présents dans sa mémoire. En génération (⑤, ⑥, ⑨), il y a une passe avant par token produit, accélérée par un cache des clés et des valeurs déjà calculées : c'est l'essentiel de la durée (environ 1 h sur 1 h 30), l'enseignant générant 4 300 raisonnements. En entraînement (⑧), chaque pas fait une passe avant, une passe arrière qui calcule les gradients de l'élève, puis la mise à jour de tous ses poids. En modes logits et on_policy, l'enseignant reste sur le GPU pendant l'entraînement et fait une passe avant sur chaque lot : ses logits, sur un vocabulaire de 152 000 tokens, pèsent lourd, d'où les lots de 2 et l'optimiseur 8 bits.
Ce qui est écrit.
| Fichier | Contenu |
|---|---|
eleve-sequence/model.safetensors |
Tous les poids de l'élève distillé (1,98 Go, en float32) |
eleve-sequence/config.json, generation_config.json |
Architecture Qwen2 et réglages de génération, pour recharger l'élève avec AutoModelForCausalLM.from_pretrained |
eleve-sequence/tokenizer.json, tokenizer_config.json, chat_template.jinja |
Le tokenizer et le format de conversation, copiés pour que le dossier se suffise à lui-même |
eleve-sequence/training_args.bin |
Les réglages d'entraînement utilisés |
resultats.json |
Exactitude de l'élève avant, distillé et témoin, et de l'enseignant, sur GSM8K et sur la non-régression, avec intervalle à 95 % et réponse de chaque question ; comparaisons appariées, dont distille_contre_temoin ; nombre de réponses de l'enseignant conservées |
config_effective.yaml |
La configuration réellement utilisée, surcharges SET comprises |
Avec SET="mode=logits" ou SET="mode=on_policy", l'élève est écrit dans eleve-logits/ ou eleve-on_policy/ (sans témoin).
Essayer dans le dépôt
| Exemple | Statut | Résultat mesuré | Durée | Commande |
|---|---|---|---|---|
| exemple principal | démontré | GSM8K (n = 1 319) : élève 0,411 → 0,451 ; témoin solutions humaines 0,302 ; enseignant 0,760 — gain modeste, l'élève reste loin de l'enseignant | test : 16 s complet : 1 h 30 |
make test EX=SIGN06 |
variante encodeur-classification |
démontré | sans enseignant 0,758 ; distillé 0,839 | test : 25 s complet : 78 s |
make test EX=SIGN06 VAR=encodeur-classification |
| non testé version grosse infra | jamais exécutée | 06-distillation/infra/ |
Résultats et durées mesurés sur RTX 5070 Ti Laptop (12 Go, 11,5 Gio utilisables), 30 Go de RAM ; résultats de la configuration complète. make test lance un test rapide sur un petit modèle ; make run lance l'exemple complet ; make verifier contrôle d'abord les prérequis. Installation : Installer et lancer.
make install EXTRAS=1
make test EX=SIGN06
make run EX=SIGN06
Utilisation
python run.py --quick # SmolLM2-360M -> 135M
python run.py # sequence, Qwen2.5-3B-Instruct -> 0.5B-Instruct, GSM8K, ~1 h 30
python run.py --set mode=logits --set entrainement.batch=2 --set entrainement.accumulation=8 --set enseignant.nom=Qwen/Qwen2.5-1.5B-Instruct
python run.py --set mode=on_policy # GKD : l'élève génère, l'enseignant corrige
python run.py --set kd.temperature=1.0 --set kd.alpha=0.5
python variantes/encodeur-classification/run.py --quick # DistilBERT SST-2 -> BERT-tiny
python variantes/encodeur-classification/run.py # RoBERTa-base SST-2 -> BERT-mini, avec et sans enseignant
Paramètres principaux
| Clé | Rôle |
|---|---|
enseignant.nom, eleve.nom |
Même famille pour logits et on_policy |
mode |
sequence, logits ou on_policy |
kd.temperature, kd.alpha |
Adoucissement des distributions, poids de la KL face à l'entropie croisée |
kd.beta_jsd |
on_policy : 0 = KL directe, 1 = KL inverse, entre les deux = JSD généralisée |
generation.filtrer |
sequence : ne garder que les réponses justes de l'enseignant |
temoin |
sequence : entraîner aussi l'élève sur les solutions humaines des mêmes questions, pour isoler l'apport de l'enseignant |
evaluation.non_regression |
Tâche hors sujet mesurée avant et après |
entrainement.batch |
Petit en mode logits : les logits de deux modèles sur un vocabulaire de 152k pèsent lourd |
Grosse infra
infra/config.yaml: logits Llama-3.1-8B-Instruct → Llama-3.2-1B-Instruct sur GSM8K, 1 nœud 8×H100 (l'enseignant est répliqué sur chaque GPU, élève en ZeRO-2).infra/lancer.shdocumente deux montages :logits:accelerate launchderun.py;sequence: génération par un enseignant 70B avec vLLM (infra/generer_vllm.py, rejection sampling inclus), puis SFT de l'élève avec l'infra du DATA02. C'est la recette des modèles « DeepSeek-R1-Distill ».
- Enseignant trop gros pour un GPU : pré-calculer les top-k logits hors ligne (DistillKit) ou passer au mode
sequence. - Distillation massive (Minitron, Gemma 2) : NeMo, torchtitan, sur des dizaines à des centaines de milliards de tokens.