PEFT documentation
Format de point de contrôle PEFT
Format de point de contrôle PEFT
Ce document décrit la structure des fichiers de point de contrôle de PEFT et comment convertir entre le format PEFT et d'autres formats.
Fichiers PEFT
Les méthodes PEFT (parameter-efficient fine-tuning) ne mettent à jour qu’un petit sous-ensemble des paramètres d’un modèle, plutôt que l’ensemble. C’est un avantage, car les fichiers de checkpoint sont généralement beaucoup plus petits que les fichiers du modèle d’origine, ce qui les rend plus faciles à stocker et à partager. Cependant, cela signifie également que, pour charger un modèle PEFT, le modèle d’origine doit également être disponible.
Lorsque vous appelez save_pretrained() sur un modèle PEFT, le modèle PEFT enregistre trois fichiers, décrits ci-dessous :
adapter_model.safetensorsouadapter_model.bin
Par défaut, le modèle est enregistré au format safetensors, une alternative sécurisée au format bin, réputé vulnérable à des failles de sécurité car il utilise l'utilitaire pickle en interne. Les deux formats stockent toutefois le même state_dict et sont interchangeables.
Le state_dict ne contient que les paramètres du module d’adaptateur, et non ceux du modèle de base. Pour illustrer la différence de taille, un modèle BERT standard nécessite environ 420 Mo d’espace disque, tandis qu’un adaptateur IA³ ajouté à ce modèle BERT n’en nécessite que ~260 Ko.
adapter_config.json
Le fichier adapter_config.json contient la configuration du module d'adaptateur, nécessaire pour charger le modèle. Voici un exemple de adapter_config.json pour un adaptateur IA³ avec des paramètres standard appliqués à un modèle BERT :
{
"auto_mapping": {
"base_model_class": "BertModel",
"parent_library": "transformers.models.bert.modeling_bert"
},
"base_model_name_or_path": "bert-base-uncased",
"fan_in_fan_out": false,
"feedforward_modules": [
"output.dense"
],
"inference_mode": true,
"init_ia3_weights": true,
"modules_to_save": null,
"peft_type": "IA3",
"revision": null,
"target_modules": [
"key",
"value",
"output.dense"
],
"task_type": null
}Le fichier de configuration contient :
- le type de module d'adaptateur stocké,
"peft_type": "IA3" - des informations sur le modèle de base telles que
"base_model_name_or_path": "bert-base-uncased" - la révision du modèle (le cas échéant),
"revision": null
Si le modèle de base n’est pas un modèle Transformers préentraîné, les deux dernières entrées seront null. À part cela, les paramètres sont tous liés à l’adaptateur IA³ spécifique utilisé pour l’ajustement fin du modèle.
README.md
Le README.md généré est la fiche modèle d'un modèle PEFT et contient quelques champs pré-remplis. L'objectif est de faciliter le partage du modèle avec d'autres personnes et de fournir des informations de base à son sujet. Ce fichier n'est pas nécessaire pour charger le modèle.
Convertir au format PEFT
Lors de la conversion depuis un autre format vers le format PEFT, nous exigeons à la fois le fichier adapter_model.safetensors (ou adapter_model.bin) et le fichier adapter_config.json.
adapter_model
Pour les poids du modèle, il est important d’utiliser la correspondance correcte entre le nom du paramètre et sa valeur afin que PEFT puisse charger le fichier. Obtenir cette correspondance correctement est un exercice de vérification des détails d’implémentation, car il n’existe pas de format généralement convenu pour les adaptateurs PEFT.
Heureusement, déterminer ce mapping n’est pas trop compliqué pour les cas de base courants. Examinons un exemple concret, le LoraLayer :
# showing only part of the code
class LoraLayer(BaseTunerLayer):
# All names of layers that may contain (trainable) adapter weights
adapter_layer_names = ("lora_A", "lora_B", "lora_embedding_A", "lora_embedding_B")
# All names of other parameters that may contain adapter-related parameters
other_param_names = ("r", "lora_alpha", "scaling", "lora_dropout")
def __init__(self, base_layer: nn.Module, **kwargs) -> None:
self.base_layer = base_layer
self.r = {}
self.lora_alpha = {}
self.scaling = {}
self.lora_dropout = nn.ModuleDict({})
self.lora_A = nn.ModuleDict({})
self.lora_B = nn.ModuleDict({})
# For Embedding layer
self.lora_embedding_A = nn.ParameterDict({})
self.lora_embedding_B = nn.ParameterDict({})
# Mark the weight as unmerged
self._disable_adapters = False
self.merged_adapters = []
self.use_dora: dict[str, bool] = {}
self.lora_magnitude_vector: Optional[torch.nn.ParameterDict] = None # for DoRA
self._caches: dict[str, Any] = {}
self.kwargs = kwargsDans le code __init__ utilisé par toutes les classes LoraLayer de PEFT, il y a un ensemble de paramètres utilisés pour initialiser le modèle, mais seuls quelques-uns sont pertinents pour le fichier de checkpoint : lora_A, lora_B, lora_embedding_A et lora_embedding_B. Ces paramètres sont répertoriés dans l'attribut de classe adapter_layer_names et contiennent les paramètres apprenables, ils doivent donc être inclus dans le fichier de checkpoint. Tous les autres paramètres, comme le rang r, sont dérivés du adapter_config.json et doivent y être inclus (sauf si la valeur par défaut est utilisée).
Vérifions le state_dict d’un modèle PEFT LoRA appliqué à BERT. En affichant les cinq premières clés avec les paramètres LoRA par défaut (les clés restantes sont identiques, avec simplement des numéros de couche différents), on obtient :
base_model.model.encoder.layer.0.attention.self.query.lora_A.weightbase_model.model.encoder.layer.0.attention.self.query.lora_B.weightbase_model.model.encoder.layer.0.attention.self.value.lora_A.weightbase_model.model.encoder.layer.0.attention.self.value.lora_B.weightbase_model.model.encoder.layer.1.attention.self.query.lora_A.weight- etc.
Décomposons cela :
- Par défaut, pour les modèles BERT, LoRA est appliqué aux couches
queryetvaluedu module d'attention. C'est pourquoi vous voyezattention.self.queryetattention.self.valuedans les noms de clés de chaque couche. - LoRA décompose les poids en deux matrices de faible rang,
lora_Aetlora_B. C'est d'où viennentlora_Aetlora_Bdans les noms des clés. - Ces matrices LoRA sont implémentées sous forme de couches
nn.Linear, les paramètres sont donc stockés dans l'attribut.weight(lora_A.weight,lora_B.weight). - Par défaut, LoRA n’est pas appliqué à la couche d’embedding de BERT, il n’y a donc aucune entrée pour
lora_A_embeddingetlora_B_embedding. - Les clés du
state_dictcommencent toujours par"base_model.model.". La raison en est que, dans PEFT, nous encapsulons le modèle de base dans un modèle spécifique au tuner (LoraModeldans ce cas), qui est lui-même encapsulé dans un modèle PEFT général (PeftModel). Pour cette raison, ces deux préfixes sont ajoutés aux clés. Lors de la conversion au format PEFT, il est nécessaire d'ajouter ces préfixes.
Ce dernier point n’est pas vrai pour les techniques de prefix tuning comme le prompt tuning. Dans ce cas, les embeddings supplémentaires sont stockés directement dans le
state_dictsans qu’aucun préfixe ne soit ajouté aux clés.
Lors de l’inspection des noms de paramètres du modèle chargé, vous pourriez être surpris de constater qu’ils présentent une apparence légèrement différente, par exemple base_model.model.encoder.layer.0.attention.self.query.lora_A.default.weight. La différence réside dans la partie .default du deuxième segment à partir de la fin. Cette partie existe car PEFT autorise généralement l’ajout de plusieurs adaptateurs simultanément (en utilisant un nn.ModuleDict ou un nn.ParameterDict pour les stocker). Par exemple, si vous ajoutez un autre adaptateur nommé « other », la clé de cet adaptateur serait base_model.model.encoder.layer.0.attention.self.query.lora_A.other.weight.
Lors de l’appel de save_pretrained(), le nom de l’adaptateur est retiré des clés. La raison en est que le nom de l’adaptateur ne fait pas partie intégrante de l’architecture du modèle ; il s’agit simplement d’un nom arbitraire. Au chargement de l’adaptateur, vous pourriez choisir un nom totalement différent, et le modèle fonctionnerait de la même manière. C’est pourquoi le nom de l’adaptateur n’est pas stocké dans le fichier de point de contrôle.
Si vous appelez
save_pretrained("some/path")et que le nom de l’adaptateur n’est pas"default", l’adaptateur est stocké dans un sous-répertoire portant le même nom que l’adaptateur. Ainsi, si le nom est « other », il sera stocké danssome/path/other.
Dans certaines circonstances, la décision des valeurs à ajouter au fichier de point de contrôle peut devenir un peu plus complexe. Par exemple, dans PEFT, DoRA est implémenté comme un cas particulier de LoRA. Si vous souhaitez convertir un modèle DoRA en PEFT, vous devez créer un point de contrôle LoRA avec des entrées supplémentaires pour DoRA. Vous pouvez le constater dans le __init__ du code LoraLayer précédent :
self.lora_magnitude_vector: Optional[torch.nn.ParameterDict] = None # for DoRACela indique qu'il existe un paramètre supplémentaire facultatif par couche pour DoRA.
adapter_config
Toutes les autres informations nécessaires pour charger un modèle PEFT sont contenues dans le fichier adapter_config.json. Vérifions ce fichier pour un modèle LoRA appliqué à BERT :
{
"alpha_pattern": {},
"auto_mapping": {
"base_model_class": "BertModel",
"parent_library": "transformers.models.bert.modeling_bert"
},
"base_model_name_or_path": "bert-base-uncased",
"bias": "none",
"fan_in_fan_out": false,
"inference_mode": true,
"init_lora_weights": true,
"layer_replication": null,
"layers_pattern": null,
"layers_to_transform": null,
"loftq_config": {},
"lora_alpha": 8,
"lora_dropout": 0.0,
"megatron_config": null,
"megatron_core": "megatron.core",
"modules_to_save": null,
"peft_type": "LORA",
"r": 8,
"rank_pattern": {},
"revision": null,
"target_modules": [
"query",
"value"
],
"task_type": null,
"use_dora": false,
"use_rslora": false
}Ce fichier contient de nombreuses entrées et, à première vue, il peut sembler intimidant de déterminer toutes les valeurs correctes à y inscrire. Cependant, la plupart des entrées ne sont pas nécessaires pour charger le modèle. C’est soit parce qu’elles utilisent les valeurs par défaut et n’ont donc pas besoin d’être ajoutées, soit parce qu’elles n’affectent que l’initialisation des poids LoRA, ce qui est sans importance lors du chargement du modèle. Si vous ne savez pas à quoi sert un paramètre spécifique, par exemple "use_rslora",, ne l’ajoutez pas et tout devrait fonctionner correctement. Notez également qu’avec l’ajout de nouvelles options, ce fichier contiendra davantage d’entrées à l’avenir, mais il devrait rester rétrocompatible.
Au minimum, vous devez inclure les entrées suivantes :
{
"target_modules": ["query", "value"],
"peft_type": "LORA"
}Cependant, il est recommandé d’ajouter le plus d’entrées possible, comme le rang r ou le base_model_name_or_path (s’il s’agit d’un modèle Transformers). Ces informations aident les autres à mieux comprendre le modèle et à le partager plus facilement. Pour vérifier les clés et les valeurs attendues, consultez le fichier config.py (à titre d’exemple, il s’agit du fichier de configuration pour LoRA) dans le code source de PEFT.
Stockage des modèles
Dans certaines circonstances, vous pouvez vouloir stocker le modèle PEFT complet, y compris les poids de base. Cela peut être nécessaire si, par exemple, le modèle de base n'est pas disponible pour les utilisateurs qui tentent de charger le modèle PEFT. Vous pouvez d'abord fusionner les poids ou le convertir en modèle Transformer.
Fusionner les poids
La méthode la plus simple pour stocker le modèle PEFT complet consiste à fusionner les poids de l’adaptateur dans les poids de base :
merged_model = model.merge_and_unload() merged_model.save_pretrained(...)
Cependant, cette approche présente certains inconvénients :
- Une fois que merge_and_unload() est appelé, vous obtenez un modèle de base sans aucune fonctionnalité spécifique à PEFT. Cela signifie que vous ne pouvez plus utiliser aucune des méthodes spécifiques à PEFT.
- Vous ne pouvez pas fusionner les poids, charger plusieurs adaptateurs à la fois, désactiver l'adaptateur, etc.
- Toutes les méthodes PEFT ne prennent pas en charge la fusion des poids.
- Certaines méthodes PEFT autorisent généralement la fusion, mais pas avec des configurations spécifiques (par exemple, lors de l'utilisation de certaines techniques de quantification).
- Le modèle complet sera beaucoup plus volumineux que le modèle PEFT, car il contiendra également tous les poids de base.
En revanche, l'inférence avec un modèle fusionné devrait être un peu plus rapide.
Convertir en modèle Transformers
Une autre méthode pour enregistrer le modèle complet, en supposant que le modèle de base est un modèle Transformers, consiste à utiliser cette approche astucieuse pour insérer directement les poids PEFT dans le modèle de base et l’enregistrer. Cela ne fonctionne que si vous « trompez » Transformers en lui faisant croire que le modèle PEFT n’est pas un modèle PEFT. Cette méthode ne fonctionne qu’avec LoRA, car les autres adaptateurs ne sont pas implémentés dans Transformers.
model = ... # the PEFT model
...
# after you finish training the model, save it in a temporary location
model.save_pretrained(<temp_location>)
# now load this model directly into a transformers model, without the PEFT wrapper
# the PEFT weights are directly injected into the base model
model_loaded = AutoModel.from_pretrained(<temp_location>)
# now make the loaded model believe that it is _not_ a PEFT model
model_loaded._hf_peft_config_loaded = False
# now when we save it, it will save the whole model
model_loaded.save_pretrained(<final_location>)
# or upload to Hugging Face Hub
model_loaded.push_to_hub(<final_location>)