PEFT documentation
X-LoRA
X-LoRA
Mixture of LoRA Experts (X-LoRA) est une méthode PEFT permettant un mélange sparse ou dense d'experts LoRA basé sur une matrice de mise à l'échelle à haute granularité (token, couche, séquence). Cette approche exploite des adaptateurs LoRA figés et un modèle de base figé pour réduire considérablement le nombre de paramètres devant être affinés.
Un aspect unique de X-LoRA est sa polyvalence : il peut être appliqué à tout modèle de base transformers doté d'adaptateurs LoRA. Cela signifie que, malgré la stratégie de mélange d'experts, aucune modification du code du modèle n'est nécessaire.
Le graphique ci-dessous illustre comment les échelles évoluent pour différents prompts à chaque jeton. Cela met en évidence l'activation de différents adaptateurs au fur et à mesure que la génération progresse et que la séquence crée un nouveau contexte.

À chaque étape, X-LoRA nécessite d'exécuter le modèle de base deux fois : d'abord, pour obtenir les états cachés sans aucun adaptateur LoRA, et ensuite, les états cachés sont utilisés pour calculer les échelles qui sont appliquées aux adaptateurs LoRA, et le modèle est exécuté une seconde fois. La sortie de la seconde exécution est le résultat de l'étape du modèle.
En fin de compte, X-LoRA permet au modèle de réfléchir à ses connaissances grâce au schéma de double passe avant, et de reconfigurer dynamiquement l'architecture.
L'abstract de l'article est :
Nous présentons une stratégie de mélange d’experts pour créer de grands modèles de langage affinés à l’aide d’une approche profonde, couche par couche et au niveau des jetons, basée sur l’adaptation de faible rang (LoRA). À partir d’un ensemble d’adaptateurs LoRA pré-entraînés, notre stratégie de routage utilise les états cachés pour mélanger dynamiquement les couches adaptées, permettant au modèle X-LoRA résultant de s’appuyer sur différentes capacités et de créer des combinaisons profondes, couche par couche, inédites pour résoudre des tâches. La conception s’inspire des principes biologiques d’universalité et de diversité, où les briques de base des réseaux de neurones sont réutilisées dans différentes manifestations hiérarchiques. Par conséquent, le modèle X-LoRA peut être facilement implémenté pour n’importe quel grand modèle de langage (LLM) existant, sans nécessiter de modifications de la structure sous-jacente. Nous développons un modèle X-LoRA sur mesure offrant des capacités scientifiques, notamment des tâches d’analyse directe/inverse et une capacité de raisonnement renforcée, axées sur l’analyse des biomatériaux, la mécanique et la conception des protéines. L’impact de ce travail inclut l’accès à des modèles facilement extensibles et adaptables, dotés d’une solide connaissance de domaine et de la capacité à s’intégrer à travers différents domaines de connaissance. En mettant en avant des experts en biologie, mathématiques, raisonnement, matériaux bio-inspirés, mécanique et matériaux, chimie, biophysique des protéines, mécanique et propriétés moléculaires basées sur la mécanique quantique, nous menons une série d’études de cas axées sur la physique. Nous examinons la récupération de connaissances, les tâches directes/inverses de mécanique des protéines, la conception de protéines, la modélisation agentique adversariale incluant la construction de graphes de connaissances ontologiques, ainsi que la conception moléculaire. Le modèle est capable non seulement de faire des prédictions quantitatives des propriétés nanomécaniques des protéines ou des propriétés moléculaires quantiques, mais aussi de raisonner sur les résultats et de prédire correctement les mécanismes probables qui expliquent les comportements moléculaires distincts..
Veuillez citer X-LoRA comme suit :
@article{10.1063/5.0203126,
author = {Buehler, Eric L. and Buehler, Markus J.},
title = "{X-LoRA: Mixture of low-rank adapter experts, a flexible framework for large language models with applications in protein mechanics and molecular design}",
journal = {APL Machine Learning},
volume = {2},
number = {2},
pages = {026119},
year = {2024},
month = {05},
abstract = "{We report a mixture of expert strategy to create fine-tuned large language models using a deep layer-wise token-level approach based on low-rank adaptation (LoRA). Starting with a set of pre-trained LoRA adapters, our gating strategy uses the hidden states to dynamically mix adapted layers, allowing the resulting X-LoRA model to draw upon different capabilities and create never-before-used deep layer-wise combinations to solve tasks. The design is inspired by the biological principles of universality and diversity, where neural network building blocks are reused in different hierarchical manifestations. Hence, the X-LoRA model can be easily implemented for any existing large language model without a need for modifications of the underlying structure. We develop a tailored X-LoRA model that offers scientific capabilities, including forward/inverse analysis tasks and enhanced reasoning capability, focused on biomaterial analysis, protein mechanics, and design. The impact of this work includes access to readily expandable and adaptable models with strong domain knowledge and the capability to integrate across areas of knowledge. Featuring experts in biology, mathematics, reasoning, bio-inspired materials, mechanics and materials, chemistry, protein biophysics, mechanics, and quantum-mechanics based molecular properties, we conduct a series of physics-focused case studies. We examine knowledge recall, protein mechanics forward/inverse tasks, protein design, adversarial agentic modeling including ontological knowledge graph construction, and molecular design. The model is capable not only of making quantitative predictions of nanomechanical properties of proteins or quantum mechanical molecular properties but also reasoning over the results and correctly predicting likely mechanisms that explain distinct molecular behaviors.}",
issn = {2770-9019},
doi = {10.1063/5.0203126},
url = {https://doi.org/10.1063/5.0203126},
eprint = {https://pubs.aip.org/aip/aml/article-pdf/doi/10.1063/5.0203126/19964043/026119\_1\_5.0203126.pdf},
}API
XLoraConfig
classe peft.XLoraConfig
< source >( task_type: Optional[Union[str, TaskType]] = Nonepeft_type: Optional[Union[str, PeftType]] = Noneauto_mapping: Optional[dict] = Nonepeft_version: Optional[str] = Nonebase_model_name_or_path: Optional[str] = Nonerevision: Optional[str] = Noneinference_mode: bool = Falsehidden_size: int = Noneadapters: dict[str, str] = Noneenable_softmax: bool = Trueenable_softmax_topk: bool = Falselayerwise_scalings: bool = Falsexlora_depth: int = 1xlora_size: int = 2048xlora_dropout_p: float = 0.2use_trainable_adapters: bool = Falsesoftmax_temperature: float = 1.0top_k_lora: Optional[int] = Nonescaling_pass_value: float = 0.0global_scaling_weight: float = 1.0 )
Paramètres
- hidden_size (
int) — Taille cachée du modèle de base. - adapters (
dict) — Mapping of adapter names to the LoRA adapter id, as per PeftModel.load_adapter. They will be automatically loaded, to use as LoRA experts. When using from_pretrained, pass the new adapters dict as a keyword argument. - enable_softmax (
bool, facultatif, valeur par défautTrue) — Active l'application du softmax pour le classifieur X-LoRA. - enable_softmax_topk (
bool, facultatif, valeur par défautFalse) — Active l'application du softmax pour les adaptateurs LoRA top-k. Mutuellement exclusif avecenable_softmaxet ne doit être défini que sitop_k_loral'est. - softmax_temperature (
float, facultatif, valeur par défaut 1.0) — Température du softmax, une valeur plus basse produit des prédictions plus nettes - layerwise_scalings (
bool, facultatif, par défautFalse) — Si True, génère des échelles pour chaque adaptateur LoRA (chaque couche). Si False, les échelles sont diffusées, identiques, à chaque couche. - top_k_lora (
int, facultatif, valeur par défaut None) — Sélectionne de manière creuse les top_k experts LoRA au lieu de la méthode dense par défaut. - xlora_depth (
int, facultatif, valeur par défaut 1) — Profondeur du classifieur X-LoRA. - xlora_size (
int, facultatif, valeur par défaut 2048) — Taille cachée du classifieur X-LoRA, sans importance sixlora_depth=1. - xlora_dropout_p (
float, facultatif, valeur par défaut 0.2) — Probabilité de dropout du classifieur X-LoRA, sans effet sixlora_depth=1. - use_trainable_adapters (
bool, facultatif, valeur par défaut False) — Rend les adaptateurs entraînables. - scaling_pass_value (
float, facultatif, valeur par défaut 0) — Valeur de passage de mise à l'échelle. - global_scaling_weight (
float, facultatif, valeur par défaut 1) — Poids à multiplier par la sortie de chaque adaptateur LoRA.
Ceci est la classe de configuration destinée à stocker la configuration d'un XLoraModel. Lors du rechargement de la configuration, les chemins du champ adapters sont ignorés au profit des adaptateurs enregistrés. Ainsi, seules les clés sont prises en compte lors du chargement.
XLoraModel
classe peft.XLoraModel
< source >( model: nn.Moduleconfig: Union[dict[str, XLoraConfig], XLoraConfig]adapter_name: strtorch_device: Optional[str] = Noneephemeral_gpu_offload: bool = Falseautocast_adapter_dtype: bool = True**kwargs ) → torch.nn.Module
Paramètres
- model (
torch.nn.Module) — Le modèle à adapter. - config (XLoraConfig) — La configuration du modèle Lora.
- adapter_name (
str) — Le nom de l'adaptateur, n'affecte pas les noms des adaptateurs LoRA.
Retourne
torch.nn.Module
Le modèle X-LoRA.
Crée un modèle X-LoRA (Mixture of LoRA experts) à partir d'un modèle transformers pré-entraîné. Actuellement, cette implémentation X-LoRA ne fonctionne qu'avec des modèles ayant une architecture transformer.
La méthode est décrite en détail dans https://huggingface.co/papers/2402.07148.
Exemple :
>>> import torch
>>> from transformers import AutoModelForCausalLM, AutoConfig, BitsAndBytesConfig
>>> from peft import XLoraConfig, get_peft_model, prepare_model_for_kbit_training
>>> model_config = AutoConfig.from_pretrained("mistralai/Mistral-7B-Instruct-v0.1")
>>> config = XLoraConfig(
... task_type="CAUSAL_LM",
... hidden_size=model_config.hidden_size,
... xlora_depth=4,
... adapters={
... "adapter_1": "./path/to/the/checkpoint/",
... "adapter_2": "./path/to/the/checkpoint/",
... "adapter_n": "./path/to/the/checkpoint/",
... },
... )
>>> int8_config = BitsAndBytesConfig(load_in_8bit=True)
>>> model = AutoModelForCausalLM.from_pretrained(
... "mistralai/Mistral-7B-Instruct-v0.1",
... trust_remote_code=True,
... attn_implementation="flash_attention_2",
... device_map="cuda:0",
... torch_dtype=torch.bfloat16,
... quantization_config=int8_config,
... )
>>> model = prepare_model_for_kbit_training(model)
>>> xlora_model = get_peft_model(model, config)Effacer le journal des scalings.
Désactiver la journalisation des échelles, sans effacer le journal.
Activer la journalisation des échelles.
Retourne des échelonnements groupés, regroupés par seq_len. Chaque valeur est constituée des positions (en premier) et des tenseurs associés. Les positions sont appariées aux tenseurs associés et indiquent la position dans le journal d'échelonnement.
Obtenir le poids global LoRA.
Retourne la dernière prédiction de scalings, ou None si aucun scalings n'a été prédit. Le tenseur est de forme (batch_size, seq_len, n_layers, n_classes).
Retourne une copie superficielle (copie uniquement la liste elle-même, pas les tenseurs) de la liste contenant le journal des échelles. La modification de la liste ne modifie pas le journal sous-jacent. Les tenseurs ont la forme (batch_size, seq_len, n_layers, n_classes). La dimension seq_len peut varier en fonction de la dimension d'entrée.
Définissez le poids global de LoRA, un scalaire à multiplier par la sortie de chaque adaptateur LoRA. Par défaut, il vaut 1. Cela est reflété dans la configuration.
Définissez la valeur du passage de mise à l'échelle, c'est-à-dire la valeur à laquelle les mises à l'échelle sont réglées pendant ce passage. Si la valeur est None, la valeur du passage de mise à l'échelle sera 1/n, où n est le nombre d'adaptateurs.
Sélectionner de manière creuse les experts LoRA top_k spécifiés plutôt que la méthode dense par défaut. Définir sur None pour utiliser la méthode dense. Cela est reflété dans la configuration.