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.pyappellecommun/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/), puisrun.pyconfie 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 danscommun/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).