PEFT documentation

Tour rapide

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Tour rapide

PEFT propose des méthodes efficaces en termes de paramètres pour l’ajustement fin de grands modèles pré-entraînés. Le paradigme traditionnel consiste à ajuster finement l’ensemble des paramètres d’un modèle pour chaque tâche en aval, mais cette approche devient extrêmement coûteuse et peu pratique en raison du nombre considérable de paramètres des modèles actuels. Il est donc plus efficace d’entraîner un plus petit nombre de paramètres de prompt ou d’utiliser une méthode de reparamétrisation comme l’adaptation de faible rang (LoRA) afin de réduire le nombre de paramètres entraînables.

PEFT peut être considéré comme un framework permettant d’ajouter des paramètres entraînables à des emplacements arbitraires dans des modèles existants (« modèles de base »). Les méthodes PEFT spécifiques organisent les paramètres entraînables de certaines manières ou modifient le processus d’entraînement afin d’atteindre des performances de fine-tuning comparables à celles obtenues en entraînant l’ensemble des paramètres du modèle de base.

Cette visite rapide vous présente les principales fonctionnalités de PEFT et comment vous pouvez entraîner ou exécuter des inférences sur de grands modèles qui seraient généralement inaccessibles sur des appareils grand public.

Configuration PEFT et modèle

Pour toute méthode PEFT, vous devez créer une configuration contenant tous les paramètres qui spécifient comment la méthode PEFT doit être appliquée, et en particulier quelles couches du modèle existant cibler avec des paramètres entraînables. Une fois la configuration définie, transmettez-la à la fonction get_peft_model() avec le modèle de base pour créer un PeftModel entraînable.

Prenons LoRA comme exemple, mais ne discutons que des paramètres courants - vous pourriez vouloir utiliser l'une des nombreuses autres méthodes PEFT. La configuration implique généralement ceci :

  • target_modules : les modules du modèle de base à adapter
  • task_type (par défaut : None, voir les TaskType disponibles) : la nature de la tâche entraînée ; si fournie, elle peut aider à enregistrer automatiquement les couches pertinentes aux côtés des poids de l’adaptateur ou à vous avertir des incompatibilités
  • inference_mode (par défaut : False) : indique si le modèle est utilisé pour l'inférence

Selon la méthode PEFT que vous choisissez, vous ajouterez des paramètres spécifiques qui, par exemple, déterminent la taille des matrices de mise à jour. Voici un exemple de configuration que vous pourriez rencontrer dans la pratique :

from peft import LoraConfig, TaskType

peft_config = LoraConfig(target_modules=["q_proj"], task_type=TaskType.CAUSAL_LM, inference_mode=False, r=8, lora_alpha=32, lora_dropout=0.1)

Consultez le guide de configuration pour plus de détails sur le fonctionnement interne de la configuration PEFT.

Une fois le LoraConfig configuré, créez un PeftModel à l’aide de la fonction get_peft_model(). Elle prend en entrée un modèle de base – que vous pouvez (mais n’êtes pas obligé de) charger depuis la bibliothèque Transformers – ainsi que le LoraConfig contenant les paramètres pour configurer le modèle en vue de l’entraînement avec LoRA.

Chargez le modèle de base que vous souhaitez affiner.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-1B")

Enveloppez maintenant le modèle de base et peft_config avec la fonction get_peft_model() pour créer un PeftModel.

Wrapping signifie que PEFT remplace les cibles visées (ici : toutes les couches q_proj) par la couche spécifique à l'adaptateur correspondant au type de la couche cible. Comme nous traitons des couches linéaires, il s'agira, dans ce cas, d'une couche lora.Linear. Notez que ces modifications sont effectuées in-place afin d'économiser de la mémoire, votre modèle de base est donc désormais modifié.

Notez que nous n'avons spécifié que q_proj, mais en réalité nous visons toutes les couches model.layers[:].self_attn.q_proj. Cela est dû au fait que PEFT recherche par défaut les suffixes correspondants. Transmettez une chaîne contenant une expression régulière si vous souhaitez cibler des motifs de couches plus complexes.

La couche du modèle de base sera encapsulée, conservée et non entraînée, tandis que de nouveaux poids entraînables sont ajoutés et combinés. La manière dont ces nouveaux poids sont structurés et combinés avec les poids du modèle de base constitue une grande partie de ce qui distingue les différentes méthodes PEFT.

Avant de lancer l’entraînement, exécutez un contrôle d’intégrité pour confirmer l’état de l’adaptateur et vérifier le nombre de paramètres entraînables.

from peft import get_peft_model, LoraConfig

peft_config = LoraConfig()  # or your other PEFT method of choice
peft_model = get_peft_model(model, peft_config)
peft_model.print_healthcheck()

Le healthcheck inclut la fraction de paramètres entraînables, ainsi que l'état de l'adaptateur, la configuration du modèle et l'environnement.

Lancer un contrôle d'intégrité

Utilisez print_healthcheck() pour identifier les états suspects, tels que des adaptateurs fusionnés ou incohérents, et pour générer un rapport compact destiné à un signalement de bug.

peft_model.print_healthcheck()

Cela devrait afficher quelque chose comme :

PEFT healthcheck
Model:
  ID: meta-llama/Llama-3.2-1B, type: LlamaForCausalLM, adapters: default (LORA)
Environment:
  peft: 0.21.0, transformers: 5.18.0.dev0, torch: 2.14.0+cu130, Python: 3.13.9
Runtime:
  training: True, devices: cpu, dtypes: bfloat16=1,235,814,400, float32=851,968, activation checkpointing: False
Parameters:
  trainable: 851,968, total: 1,236,666,368, percent trainable: 0.0689%, adapter layers: 32
State:
  adapter is enabled: True, active: default, merged: none
Layer types:
  default:
    lora.Linear=32

La sortie de l’impression est susceptible de changer, ne tentez pas de l’analyser. Pour un usage programmatique, appelez plutôt healthcheck(), qui renvoie les mêmes informations sous forme de dictionnaire sérialisable en JSON.

C'est tout 🎉 ! Vous pouvez maintenant entraîner le modèle avec le Trainer de Transformers, Accelerate, ou toute boucle d'entraînement PyTorch personnalisée.

Par exemple, pour entraîner avec la classe Trainer, configurez une classe TrainingArguments avec certains hyperparamètres d'entraînement.

training_args = TrainingArguments(
    output_dir="your-name/meta-llama/my-llama3.2-adapter",
    learning_rate=1e-3,
    per_device_train_batch_size=32,
    per_device_eval_batch_size=32,
    num_train_epochs=2,
    weight_decay=0.01,
    eval_strategy="epoch",
    save_strategy="epoch",
    load_best_model_at_end=True,
)

Passez le modèle, les arguments d’entraînement, le jeu de données, le tokenizer et tout autre composant nécessaire au Trainer, puis appelez train pour démarrer l’entraînement.

trainer = Trainer(
    model=peft_model,
    args=training_args,
    train_dataset=tokenized_datasets["train"],
    eval_dataset=tokenized_datasets["test"],
    data_collator=data_collator,
    compute_metrics=compute_metrics,
)

trainer.train()

Enregistrer le modèle

Une fois l’entraînement de votre modèle terminé, vous pouvez l’enregistrer dans un répertoire à l’aide de la fonction save_pretrained().

peft_model.save_pretrained("output_dir")

Vous pouvez également enregistrer votre modèle sur le Hub (assurez-vous d’abord d’être connecté à votre compte Hugging Face) à l’aide de la fonction push_to_hub.

from huggingface_hub import notebook_login

notebook_login()
peft_model.push_to_hub("your-name/my-llama3.2-adapter")

Les deux méthodes ne sauvegardent que les poids PEFT supplémentaires qui ont été entraînés, ce qui les rend extrêmement efficaces à stocker, transférer et charger. Par exemple, ce modèle facebook/opt-350m entraîné avec LoRA ne contient que deux fichiers : adapter_config.json et adapter_model.safetensors. Le fichier adapter_model.safetensors ne fait que 6,3 Mo !

Les poids de l’adaptateur pour un modèle opt-350m stocké sur le Hub ne font que ~6 Mo, contre ~700 Mo pour la taille complète des poids du modèle.

Inférence

Consultez la référence de l'API AutoPeftModel pour obtenir la liste complète des classes AutoPeftModel disponibles.

Chargez facilement n’importe quel modèle entraîné avec PEFT pour l’inférence à l’aide de la classe AutoPeftModel et de la méthode from_pretrained :

from peft import AutoPeftModelForCausalLM
from transformers import AutoTokenizer
import torch

device = torch.accelerator.current_accelerator().type if hasattr(torch, "accelerator") else "cuda"

peft_model = AutoPeftModelForCausalLM.from_pretrained("ybelkada/opt-350m-lora")
tokenizer = AutoTokenizer.from_pretrained("facebook/opt-350m")

peft_model = peft_model.to(device)
peft_model.eval()
inputs = tokenizer("Preheat the oven to 350 degrees and place the cookie dough", return_tensors="pt")

outputs = peft_model.generate(input_ids=inputs["input_ids"].to(peft_model.device), max_new_tokens=50)
print(tokenizer.batch_decode(outputs.detach().cpu().numpy(), skip_special_tokens=True)[0])

"Preheat the oven to 350 degrees and place the cookie dough in the center of the oven. In a large bowl, combine the flour, baking powder, baking soda, salt, and cinnamon. In a separate bowl, combine the egg yolks, sugar, and vanilla."

Pour les autres tâches qui ne sont pas explicitement prises en charge par une classe AutoPeftModelFor – comme la reconnaissance automatique de la parole – vous pouvez toujours utiliser la classe de base AutoPeftModel pour charger un modèle pour la tâche.

from peft import AutoPeftModel

peft_model = AutoPeftModel.from_pretrained("smangrul/openai-whisper-large-v2-LORA-colab")

La méthode la plus générale pour charger un adaptateur PEFT entraîné sur un modèle consiste à utiliser from_pretrained() :

from transformers import AutoPeftModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("meta-llama/llama3.2-1B")
peft_model = PeftModel.from_pretrained(base_model, "my-user/my-llama-adapter")  # you can also pass a directory instead of a hub path

Plusieurs adaptateurs

PEFT prend en charge l’installation de plusieurs adaptateurs (du même type, dans ce document il s’agit de LoRA) sur un modèle de base. Lorsque vous appelez get_peft_model, il n’y a qu’un seul adaptateur nommé "default", mais vous pouvez ajouter autant d’adaptateurs supplémentaires que vous le souhaitez en appelant peft_model.add_adapter(adapter_name=...).

Cela fonctionne car la couche encapsulée possède en réalité un ensemble unique de poids entraînables pour chaque nom d'adaptateur. Tous les adaptateurs ne sont pas actifs et entraînables par défaut. Vous devez explicitement activer les adaptateurs par leur nom avant qu'ils ne soient actifs. Cela vous permet de basculer rapidement entre les adaptateurs lorsque des connaissances spécifiques à une tâche sont nécessaires, ou de servir différents cas d'usage au-dessus d'un même modèle.

N'oubliez pas d'appeler peft_model.set_adapter(<adapter_name>) en premier pour activer l'adaptateur.

Exemple rapide :

peft_model.add_adapter(adapter_name='new_adapter')
peft_model.set_adapter('new_adapter')

Étapes suivantes

Maintenant que vous avez vu comment entraîner un modèle avec l’une des méthodes PEFT, nous vous encourageons à essayer d’autres méthodes comme le prompt tuning. Les étapes sont très similaires à celles présentées dans le quicktour :

  1. préparez un PeftConfig pour une méthode PEFT, par exemple un LoraConfig ou une autre configuration (voir l'aperçu des méthodes)
  2. utilisez la méthode get_peft_model() pour créer un PeftModel à partir de la configuration et du modèle de base

Ensuite, vous pouvez l’entraîner comme vous le souhaitez ! Pour charger un modèle PEFT pour l’inférence, vous pouvez utiliser la classe AutoPeftModel.

N’hésitez pas à consulter également les guides de tâches si vous souhaitez entraîner un modèle avec une autre méthode PEFT pour une tâche spécifique, telle que la segmentation sémantique, la reconnaissance automatique de la parole multilingue, DreamBooth, la classification de jetons, et bien d’autres.

Update on GitHub