AmeliorIA

tekio.org

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.py appelle commun/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.sh documente deux montages :
    • logits : accelerate launch de run.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.