huggingface/peft : LoRA et adaptateurs sans réécrire votre pipeline Transformers
🤗 PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.
En bref
- De quoi s’agit-il ?
- La bibliothèque PEFT encapsule un modèle pré-entraîné et n'entraîne qu'une fraction de ses paramètres. Elle sert surtout à adapter des modèles trop gros pour un fine-tuning complet, mais elle n'est ni un format d'export autonome ni une solution pour les architectures non prises en charge.
- À qui s’adresse-t-il ?
- Adoptez PEFT si vos modèles ne tiennent pas en mémoire avec un fine-tuning complet et que vous acceptez de dépendre de l'écosystème Transformers, Diffusers et Accelerate. Évitez-le si vous devez modifier une architecture non couverte par les modules cibles documentés, ou si votre pipeline d'inférence ne peut pas charger un adaptateur au-dessus du modèle de base.
- Puis-je l’utiliser commercialement ?
- Oui. Apache-2.0 est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Le dépôt a reçu de nouveaux commits au cours des dernières 24 heures.
- En quel langage est-il écrit ?
- Principalement Python, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Le coût du fine-tuning complet, et qui veut l'éviter
Le README ouvre sur un constat simple : entraîner tous les paramètres d'un grand modèle pré-entraîné coûte cher, en calcul comme en stockage. PEFT répond à ce problème en n'entraînant qu'un petit nombre de paramètres supplémentaires, tout en visant une performance comparable au fine-tuning complet. Le public visé est celui qui dispose d'une carte graphique unique ou d'un budget limité, et qui veut adapter un modèle à une tâche aval sans dupliquer des dizaines de gigaoctets de poids. Le README donne l'exemple d'un modèle bigscience/mt0-large où 0,19 % des paramètres sont entraînés, et celui de Qwen/Qwen2.5-3B-Instruct où le total entraînable atteint 3 686 400 paramètres sur 3 089 625 088, soit 0,1193 %. Ce n'est pas un outil pour qui cherche à modifier profondément le comportement d'un modèle ou à poursuivre un pré-entraînement : c'est un outil d'adaptation ciblée. Le tableau du README compare, sur ought/raft/twitter_complaints avec une A100 80GB, le fine-tuning complet et deux variantes LoRA. Un modèle de 12B paramètres provoque un OOM en fine-tuning complet, contre 56GB GPU avec LoRA PyTorch et 22GB avec LoRA DeepSpeed et CPU offloading. Ces chiffres viennent du README, pas d'une mesure indépendante.
Ce que fait get_peft_model sur le graphe du modèle
Le mécanisme central tient en une fonction : get_peft_model(model, peft_config) enveloppe le modèle de base et injecte les paramètres de l'adaptateur. L'entraînement porte sur ces paramètres, pas sur les poids d'origine. La configuration précise où et comment : LoraConfig accepte r, lora_alpha, task_type et, en option, target_modules (par exemple ["q_proj", "v_proj"]). Le README note que target_modules peut être omis, la bibliothèque déterminant alors les modules à cibler selon l'architecture. C'est pratique, mais c'est aussi le point où une architecture inhabituelle peut produire un ciblage inattendu : si vos couches ne portent pas les noms attendus, vous devez les lister explicitement. Côté chargement, PeftModel.from_pretrained(model, "qwen2.5-3b-lora") reconstruit le modèle de base puis applique l'adaptateur sauvegardé. L'adaptateur est donc un artefact séparé du modèle de base, ce qui explique le gain de stockage annoncé : le README indique un checkpoint final de 19MB pour l'exemple T0_3B, contre 11GB pour le modèle complet. Cette séparation a une conséquence pratique : l'adaptateur seul ne suffit pas à l'inférence, il faut toujours le modèle de base correspondant.
Installation et première boucle d'entraînement
L'installation se limite à une commande pip : pip install peft. Le README ne documente pas d'extra ni de dépendance optionnelle, donc la version de transformers installée dans votre environnement détermine ce qui fonctionnera réellement. La séquence minimale tient en quelques lignes : charger le modèle avec AutoModelForCausalLM.from_pretrained(model_id, device_map=device), construire un LoraConfig, appeler get_peft_model, puis vérifier avec model.print_trainable_parameters() avant de lancer l'entraînement. Le README montre ensuite model.save_pretrained("qwen2.5-3b-lora"). Pour l'inférence, on recharge le modèle de base, on applique PeftModel.from_pretrained, puis on génère normalement avec model.generate. Rien dans le README n'impose un Trainer particulier : il mentionne transformers Trainer comme une possibilité parmi d'autres. Le même README signale l'intégration avec Diffusers pour la gestion des adaptateurs et Accelerate pour l'entraînement et l'inférence distribués. Ces intégrations sont annoncées, pas détaillées dans l'extrait fourni : prévoyez de consulter la documentation liée pour les cas distribués.
Quantification et modèles hors de portée d'une seule carte
Le README présente la quantification comme un levier complémentaire, qui réduit la mémoire en représentant les données dans une précision inférieure, et qui se combine avec les méthodes PEFT. Il renvoie à un billet PyTorch et à des notebooks pour le fine-tuning de meta-llama/Llama-2-7b-hf avec QLoRA et TRL sur un GPU de 16GB, ainsi que pour openai/whisper-large-v2 en quantification 8 bits. Ces ressources sont externes au dépôt, et l'extrait ne fournit ni les commandes ni les résultats obtenus. Le tableau du README montre par ailleurs que le CPU offloading déplace une partie de la charge vers la RAM : 52GB de RAM pour le modèle 12B, 35GB pour le 7B. La contrainte se déplace, elle ne disparaît pas. Si votre machine n'a ni la VRAM ni la RAM indiquées, PEFT ne rendra pas le modèle entraînable pour autant. C'est un point que le README rend visible par ses chiffres, ce qui est plus honnête que la plupart des présentations de méthodes d'adaptation.
Là où PEFT n'est pas le bon outil
Le cas le plus net est celui d'un modèle dont les modules ne correspondent à aucun nom cible connu et que vous ne pouvez pas lister vous-même avec certitude. Le README ne fournit pas de procédure de diagnostic pour ce cas : la documentation renvoie à la référence de l'API des adaptateurs, et c'est là qu'il faut vérifier avant de s'engager. Deuxième limite : la performance comparable au fine-tuning complet est présentée comme un objectif atteint par les techniques récentes, mais le seul chiffre de qualité du README est une accuracy de 0,863 pour lora-t0-3b contre 0,892 pour Flan-T5 et 0,897 pour la baseline humaine. Le README précise lui-même que ce résultat n'est pas optimisé, ce qui veut dire que l'écart n'est pas une garantie de plafond ni de plancher. Troisième cas : si votre livrable final doit être un modèle unique et autonome, sans dépendance au modèle de base, l'adaptateur seul ne convient pas. Enfin, si votre tâche exige de modifier la tokenisation, d'ajouter des embeddings entièrement nouveaux ou de changer l'architecture, l'adaptation de paramètres n'est pas le bon cadre.
Face au fine-tuning complet et aux autres méthodes du dépôt
L'alternative directe est le fine-tuning complet, et le README la chiffre : 47,14GB GPU pour T0_3B contre 14,4GB avec LoRA PyTorch. La différence d'approche est structurelle. Le fine-tuning complet modifie tous les poids et produit un modèle autonome, ce qui simplifie le déploiement mais interdit de conserver plusieurs variantes d'une même base. PEFT produit un petit artefact par tâche, empilable au-dessus d'une base partagée, au prix d'une étape de chargement supplémentaire et d'une dépendance à la bibliothèque. Le dépôt contient aussi d'autres familles de méthodes : les adaptateurs, les soft prompts et IA3, chacune avec son guide conceptuel. Le choix entre elles n'est pas arbitré dans l'extrait fourni, et le README ne donne pas de tableau comparatif entre ces familles. Pour un lecteur qui hésite, la référence de l'API des adaptateurs reste le point d'entrée, mais l'absence de comparaison chiffrée interne est une lacune réelle de la documentation.
Maintenance, versions et licence
Le dépôt n'est pas archivé et la dernière poussée date du 9 septembre 2026. Trois versions apparaissent : v0.20.0 le 28 juillet 2026, v0.19.1 le 16 avril 2026, v0.19.0 le 14 avril 2026. L'intervalle entre 0.19.1 et 0.20.0 est d'environ trois mois, ce qui suggère un rythme de publication soutenu, mais l'extrait ne dit rien de la politique de compatibilité entre versions. Comme la bibliothèque s'interface avec transformers, diffusers et accelerate, une montée de version de peft peut exiger une montée coordonnée de ces paquets. Prévoyez de figer les versions dans votre environnement et de tester le chargement d'un adaptateur existant après chaque mise à jour. La licence est Apache-2.0, ce qui autorise l'usage commercial et la modification, avec les obligations habituelles de conservation des mentions et d'état des changements. Le README rappelle que le logiciel est fourni sans garantie. Cette licence couvre le code de PEFT, pas les poids des modèles que vous adaptez : les conditions de meta-llama ou de Qwen restent celles de leurs éditeurs respectifs, et la question de la redistribution d'un adaptateur entraîné sur un modèle sous licence restrictive se pose séparément. Ce n'est pas un avis juridique.
Conclusion éditoriale
Adoptez PEFT si vos modèles ne tiennent pas en mémoire avec un fine-tuning complet et que vous acceptez de dépendre de l'écosystème Transformers, Diffusers et Accelerate. Évitez-le si vous devez modifier une architecture non couverte par les modules cibles documentés, ou si votre pipeline d'inférence ne peut pas charger un adaptateur au-dessus du modèle de base. Avant de vous engager, vérifiez que les target_modules de votre modèle figurent dans la référence de l'API, que votre version de transformers correspond à celle attendue par la version de peft installée, et que votre licence de modèle autorise la redistribution de l'adaptateur séparément des poids de base.
Notes de la communauté