AmeliorIA

tekio.org

Exemple de code : PEFT (LoRA, QLoRA...)

Ce que le dossier 03-peft/ fournit pour cette méthode. Principe et références : PEFT (LoRA, QLoRA...).

Ce que fait l'exemple

Même besoin, mêmes données et même évaluation que le fine-tuning complet (DATA02) : router les messages de clients d'une banque vers l'une de 77 intentions. Seule change la part des poids entraînée.

Résultats (RTX 5070 Ti Laptop, 12 Go ; 3 080 messages de test, 200 problèmes de non-régression) :

Intentions Non-régression (arithmétique) Entraîné Entraînement
Qwen2.5-0.5B-Instruct, avant 0,229 [0,214 ; 0,244] 0,955 [0,917 ; 0,976]
LoRA, avec remélange (config.yaml) 0,891 [0,879 ; 0,901] 0,95 [0,910 ; 0,973] 1,7 %, adaptateur de 35 Mo 18 min, 8,7 Gio
même modèle, adaptateur désactivé — 0,955
LoRA, sans remélange 0,925 [0,915 ; 0,934] 0,33 [0,269 ; 0,398] 14 min, 8,7 Gio
SFT complet, avec remélange (DATA02) 0,904 [0,893 ; 0,914] 0,765 [0,702 ; 0,818] 100 %, modèle de 2 Go 23 min, 9,2 Gio

Gain sur les intentions, apparié sur les mêmes messages : +0,662 [+0,645 ; +0,679], p de McNemar < 10⁻³⁰⁰. Non-régression : −0,005 [−0,035 ; +0,025], p = 1,0, aucun écart mesurable.

Ce qu'on en retient.

  • LoRA apprend presque autant que le fine-tuning complet : 0,891 contre 0,904, en n'entraînant que 1,7 % des paramètres.
  • Et oublie beaucoup moins : avec le même remélange, l'arithmétique reste à 0,95, contre 0,765 en fine-tuning complet. C'est le résultat de Biderman et al. (2024), LoRA Learns Less and Forgets Less.
  • L'adaptateur se désactive : sans lui, le modèle est exactement celui d'origine (0,955). Un seul modèle de base peut servir plusieurs tâches, chacune avec son adaptateur de quelques dizaines de Mo.
  • Le remélange reste nécessaire : sans lui, même LoRA perd le raisonnement pas à pas (0,33), car il apprend à répondre par un mot.

Variantes

Variante diffusion : apprendre un sujet à Stable Diffusion

variantes/diffusion-lora apprend à Stable Diffusion 1.5 un chien précis, à partir de 5 photos (diffusers/dog-example), associé à l'identifiant rare « sks » (recette DreamBooth-LoRA : rang 8 sur l'attention de l'UNet, 500 pas). Les mesures sont celles du papier DreamBooth. Quatre prompts (« a photo of sks dog », « a sks dog on the beach », « … in the snow », « … wearing a red hat ») sont tirés chacun avec 8 graines, les mêmes avant et après : 32 images par état, comparées image par image.

  • Fidélité au sujet : similarité DINO (ViT-S/16) moyenne entre l'image générée et les 5 photos.
  • Fidélité au prompt : similarité CLIP (ViT-B/32) entre l'image et le prompt sans l'identifiant (« a dog on the beach »). Elle vérifie que le modèle place encore le sujet dans la scène demandée au lieu de recopier les photos.
Fidélité au sujet (DINO) Fidélité au prompt (CLIP)
Avant 0,281 0,300
Après 0,751 0,293
Écart apparié (32 images), intervalle à 95 % +0,470 [+0,439 ; +0,500], p < 0,001 −0,008 [−0,017 ; +0,001], p = 0,11, non significatif

Pour situer : dans le papier DreamBooth, les photos réelles d'un sujet entre elles donnent 0,774 en DINO, et DreamBooth sur Stable Diffusion 0,668. L'adaptateur occupe 6 Mo et l'exemple complet dure environ 8 minutes. Les images avant-p*-*.png et apres-p*-*.png (2 par prompt) montrent le même chien sur la plage, dans la neige, avec un bonnet rouge. Réserves : un seul sujet, et les photos de référence de la mesure sont aussi celles de l'entraînement. Le chien garde souvent la pose et le fond orangé des photos, un début de surapprentissage que la « prior preservation » de DreamBooth (images de la classe « dog » mêlées à l'entraînement) sert à limiter.

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-0.5B-Instruct"]
  Cache[("cache disque<br/>~/.cache/huggingface")]
  subgraph Py["Processus Python"]
    Run["run.py<br/>charge les données<br/>et le modèle"]
    Ev["evaluation.py<br/>génération"]
    TRL["TRL SFTTrainer<br/>LoRA r = 16"]
  end
  GPU["GPU CUDA, 12 Go"]
  Out[("sorties/03-peft/")]

  Hub -- "① HTTPS GET, 1re fois<br/>poids (1 Go), banking77, Alpaca" --> Cache
  Cache -- "② lecture des poids" --> Run
  Run -- "③ copie des poids<br/>en mémoire GPU" --> GPU
  Run -- "④ ⑨ appel Python<br/>mesure avant, après" --> 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/>adaptateur" --> Out
  Ev -- "⑪ écriture<br/>resultats.json" --> Out

  class Hub externe
  class Run,Ev,TRL code
  class GPU gpu
  class Cache,Out disque

make run EX=DATA03 vérifie les prérequis (modules, GPU), puis lance run.py dans l'environnement .venv. Le script lit config.yaml (modèle, méthode PEFT, données, réglages). Données, remélange et évaluation sont exactement ceux du fine-tuning complet (DATA02) : router les messages de clients d'une banque vers l'une de 77 intentions (banking77), avec la liste des intentions en message système.

  • ① Téléchargement. Au premier lancement, les poids de Qwen2.5-0.5B-Instruct (environ 1 Go), le jeu banking77 et les demandes générales d'Alpaca 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. Les poids sont copiés en bf16 dans la mémoire du GPU, où ils restent jusqu'à la fin. En QLoRA (SET="peft.methode=qlora"), ils y sont stockés en 4 bits par bitsandbytes.
  • ④ Mesure avant. run.py appelle commun/evaluation.py, qui pose au modèle les 3 080 messages de test, par lots de 32, puis les 200 problèmes d'arithmétique de non-régression.
  • ⑤ Génération sur le GPU. Au plus 16 tokens par message, dont la première ligne doit être l'intention attendue ; jusqu'à 256 tokens de raisonnement par problème d'arithmétique.
  • ⑥ Entraînement. Le modèle répond d'abord aux demandes générales du remélange (ou les relit dans sorties/cache-remelange/), puis run.py confie modèle, exemples et configuration LoRA au SFTTrainer de TRL. PEFT ajoute deux petites matrices de rang 16 à chaque couche linéaire et gèle tout le reste : 8,8 millions de paramètres entraînés sur 503 millions (1,7 %).
  • ⑦ Forward et backward sur le GPU. Chaque pas traite 16 exemples (lots de 8, accumulés 2 fois) : passe avant, perte sur la réponse seulement, passe arrière, mise à jour des seules matrices LoRA. 2 époques, taux d'apprentissage 2e-4.
  • ⑧ Écriture de l'adaptateur dans sorties/03-peft/adaptateur-lora/.
  • ⑨ Mesure après, sur les mêmes messages et problèmes, adaptateur actif, puis la non-régression une seconde fois, adaptateur désactivé.
  • ⑩ Génération sur le GPU, avec le même décodage qu'en ⑤.
  • ⑪ Écriture du rapport dans sorties/03-peft/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. En entraînement (⑦), chaque pas fait une passe avant, une passe arrière qui calcule les gradients, puis la mise à jour des paramètres LoRA par l'optimiseur AdamW, dont l'état n'existe que pour ces paramètres. Le pic mesuré est de 8,7 Gio de mémoire GPU, presque autant qu'en fine-tuning complet (9,2 Gio) sur un modèle aussi petit : les activations et les logits d'un vocabulaire de 152 000 tokens dominent. L'écart se creuse avec la taille du modèle, car poids fp32, gradients et état d'AdamW n'existent plus que pour l'adaptateur.

Ce qui est écrit.

Fichier Contenu
adaptateur-lora/adapter_model.safetensors Les matrices LoRA entraînées (35 Mo, en fp32), seules à être sauvegardées : le modèle de base reste celui du Hub
adaptateur-lora/adapter_config.json Rang, alpha, couches ciblées (q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj) et nom du modèle de base, pour recharger l'adaptateur avec PeftModel.from_pretrained
adaptateur-lora/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
adaptateur-lora/training_args.bin Les réglages d'entraînement utilisés
resultats.json Exactitude avant, après et adaptateur désactivé, avec intervalle à 95 % et réponse de chaque question ; comparaisons appariées (différence, intervalle, p de McNemar) ; paramètres entraînés, taille de l'adaptateur, durée d'entraînement et pic de mémoire GPU
config_effective.yaml La configuration réellement utilisée, surcharges SET comprises

Avec SET="peft.fusionner=true", le dossier modele-fusionne/ contient en plus le modèle complet avec l'adaptateur intégré, prêt à servir sans PEFT.

Essayer dans le dépôt

Exemple Statut Résultat mesuré Durée Commande
exemple principal démontré intentions 0,229 → 0,891 (n = 3 080) ; non-régression 0,955 → 0,95 ; adaptateur désactivé 0,955 test : 23 s
complet : 32 min
make test EX=DATA03
variante diffusion-lora démontré fidélité au sujet (DINO) 0,281 → 0,751 (p < 0,001) ; fidélité au prompt (CLIP) 0,300 → 0,293 (n.s.) — un seul sujet, références de mesure = photos d'entraînement ; pose et fond des photos souvent recopiés test : 20 s
complet : 8 min
make test EX=DATA03 VAR=diffusion-lora
non testé version grosse infra jamais exécutée 03-peft/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=DATA03
make run EX=DATA03

Utilisation

python run.py --quick                                        # LoRA sur SmolLM2-135M
python run.py                                                # LoRA r=16 sur Qwen2.5-0.5B-Instruct, banking77, ~30 min
python run.py --set donnees.remelange.part=0                 # sans remélange
python run.py --set peft.methode=qlora --set modele.nom=Qwen/Qwen2.5-7B-Instruct --set entrainement.gradient_checkpointing=true
python run.py --set peft.methode=dora
python run.py --set peft.methode=prompt_tuning
python run.py --set peft.fusionner=true                      # écrit aussi le modèle fusionné
for m in lora dora rslora pissa loha lokr ia3 prompt_tuning prefix_tuning; do python run.py --quick --set peft.methode=$m; done
python variantes/diffusion-lora/run.py --quick               # pipeline SD miniature
python variantes/diffusion-lora/run.py                       # SD 1.5, 5 photos de chien, mesures DINO et CLIP, ~8 min

Paramètres principaux

Clé Rôle
peft.methode Voir le tableau ci-dessus
peft.r, peft.alpha Rang et échelle LoRA (alpha = 2r est un bon départ)
peft.modules all-linear (recommandé) ou une liste de noms de couches
entrainement.lr / lr_par_methode LoRA ~1e-4 à 2e-4 ; IA³ et prompt tuning beaucoup plus haut
peft.fusionner merge_and_unload() puis sauvegarde du modèle complet

Grosse infra

  • En local : LoRA bf16 jusqu'à ~3B, QLoRA jusqu'à ~8B sur 12 Go.
  • infra/config.yaml : QLoRA sur Llama-3.3-70B, FSDP sur 2 à 8 GPU 80 Go. Le 4 bits est découpé grâce à bnb_4bit_quant_storage, réglé automatiquement dans commun/modeles.py.
  • infra/lancer.sh : entraînement, puis service de plusieurs adaptateurs sur une même base avec vLLM (--enable-lora --lora-modules).
  • Diffusion à grande échelle : scripts officiels diffusers train_dreambooth_lora_sdxl.py, train_dreambooth_lora_flux.py (Flux.1-dev : 24 à 40 Go).