PEFT documentation

Format de point de contrôle PEFT

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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 :

  1. adapter_model.safetensors ou adapter_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.

  1. 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.

  1. 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 = kwargs

Dans 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.weight
  • base_model.model.encoder.layer.0.attention.self.query.lora_B.weight
  • base_model.model.encoder.layer.0.attention.self.value.lora_A.weight
  • base_model.model.encoder.layer.0.attention.self.value.lora_B.weight
  • base_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 query et value du module d'attention. C'est pourquoi vous voyez attention.self.query et attention.self.value dans les noms de clés de chaque couche.
  • LoRA décompose les poids en deux matrices de faible rang, lora_A et lora_B. C'est d'où viennent lora_A et lora_B dans 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_embedding et lora_B_embedding.
  • Les clés du state_dict commencent 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 (LoraModel dans 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_dict sans 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é dans some/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 DoRA

Cela 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>)
Update on GitHub