Hugging Face's logo

PEFT documentation

UniLoRA

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.21.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

UniLoRA

Uni-LoRA est une méthode PEFT qui partage une banque de vecteurs compacts et entraînables entre les poids des adaptateurs de faible rang. Plutôt que d’apprendre chaque élément de la matrice LoRA de manière indépendante, UniLoRA projette de façon déterministe les entrées vers des valeurs partagées theta_d et apprend les paramètres partagés utilisés par la mise à jour de l’adaptateur.

Démarrage rapide

from peft import UniLoraConfig, get_peft_model
from transformers import AutoModelForCausalLM

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

config = UniLoraConfig(
    r=32,
    theta_d_length=256,
    proj_seed=42,
    target_modules=["q_proj", "v_proj"],
    unilora_dropout=0.0,
    init_weights=True,
    task_type="CAUSAL_LM",
)

peft_model = get_peft_model(model, config)
peft_model.print_healthcheck()

Paramètres importants

r contrôle la dimension de l'adaptateur de rang faible. Des valeurs plus élevées augmentent la capacité de l'adaptateur et l'utilisation de la mémoire.

theta_d_length contrôle la longueur de la banque de vecteurs UniLoRA partagée. Il s’agit du principal stockage entraînable partagé par les entrées d’adaptateur projetées.

proj_seed contrôle la génération déterministe des indices pour les projections fixes vers theta_d. Réutiliser la même graine et la même configuration permet de reproduire les indices d’adaptateurs générés.

target_modules sélectionne les modules qui reçoivent les adaptateurs UniLoRA. Utilisez des suffixes de module tels que ["q_proj", "v_proj"], une chaîne regex, ou "all-linear" si l’architecture du modèle le prend en charge.

unilora_dropout applique le dropout dans les couches d’adaptateurs UniLoRA pendant l’entraînement.

init_weights contrôle l’initialisation des paramètres de UniLoRA. Définissez-le sur False pour conserver une initialisation aléatoire de theta_d lorsque vous devez gérer l’initialisation manuellement.

save_indices contrôle si les points de contrôle UniLoRA enregistrent les tenseurs d’index et d’échelle générés avec les paramètres partagés theta_d. Laisser cette option désactivée produit des points de contrôle plus petits et régénère les index à partir de proj_seed ; l’activer rend les adaptateurs enregistrés indépendants des futures modifications de la génération d’index.

Aperçu des benchmarks

API

UniLoraConfig

classe peft.UniLoraConfig

< >

( 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 = Falser: int = 4proj_seed: int = 42theta_d_length: int = 256target_modules: list[str] | str | None = Noneunilora_dropout: float = 0.0fan_in_fan_out: bool = Falsebias: str = 'none'modules_to_save: list[str] | None = Noneinit_theta_d_bound: float = 0.02init_weights: bool = Truesave_indices: bool = Falselayers_to_transform: list[int] | int | None = Nonelayers_pattern: list[str] | str | None = None )

Paramètres

  • r (int) — Rang de l'adaptation de bas rang. Cela contrôle la capacité expressive de la mise à jour UniLora.
  • proj_seed (int) — Graine aléatoire utilisée pour générer l’attribution fixe des index. Cela garantit la reproductibilité entre les exécutions.
  • theta_d_length (int) — Longueur du vecteur UniLora partagé theta_d.
  • target_modules (Union[list[str], str], facultatif) — Noms ou motifs des modules auxquels les adaptateurs UniLora sont appliqués.
    • Si une chaîne est fournie, elle est traitée comme une expression régulière.
    • Si une liste est fournie, les modules sont appariés par nom exact ou par suffixe.
    • La valeur spéciale ‘all-linear’ applique UniLora à toutes les couches Linear / Conv1D, à l’exception de la couche de sortie. Si elle n’est pas spécifiée, les modules sont déduits de l’architecture du modèle. Une erreur est levée si l’architecture n’est pas prise en charge.
  • unilora_dropout (float) — Probabilité de dropout appliquée au sein des couches UniLora.
  • fan_in_fan_out (bool) — Indique si la couche remplacée stocke les poids au format (fan_in, fan_out). Cette valeur doit être définie sur True pour les modèles tels que GPT-2 qui utilisent des couches Conv1D.
  • bias (str) — Spécifie quels termes de biais sont entraînables :
    • ‘none’ : aucun paramètre de biais n'est mis à jour
    • ‘all’ : tous les paramètres de biais sont mis à jour
    • ‘unilora_only’ : seules les biais dans les couches UniLora sont mis à jour Remarque : l’activation des mises à jour des biais modifie les sorties du modèle, même lorsque les adaptateurs sont désactivés.
  • modules_to_save (list[str], facultatif) — Modules supplémentaires (en dehors des couches UniLora) qui doivent rester entraînables et être enregistrés dans le point de contrôle final. Cette option est couramment utilisée pour les têtes spécifiques à la tâche, telles que les classifieurs.
  • init_theta_d_bound (float) — Limite d'initialisation pour la banque de vecteurs UniLora. Les vecteurs sont échantillonnés uniformément dans l'intervalle [-init_theta_d_bound, init_theta_d_bound]. L'initialisation par zéro est évitée afin de prévenir les gradients qui s'annulent. Des valeurs faibles (par exemple, 0.02) sont recommandées pour un entraînement stable.
  • init_weights (bool) — Indique s'il faut initialiser theta_d avec l'initialisation UniLora par défaut. Si défini sur False, theta_d conserve une initialisation aléatoire.
  • save_indices (bool) — Indique s'il faut enregistrer l'index UniLora généré et les tampons d'échelle avec theta_d. Cela augmente la taille du point de contrôle, mais rend les adaptateurs enregistrés indépendants des modifications futures de la routine de génération d'index.
  • layers_to_transform (Union[list[int], int], facultatif) — Indices des couches de transformer auxquelles UniLora est appliqué. Si spécifié, seules ces couches sont modifiées. Cette option n’est valide que lorsque target_modules est une liste.
  • layers_pattern (Union[list[str], str], facultatif) — Motif de nom de couche personnalisé utilisé avec layers_to_transform lorsque le modèle ne suit pas les conventions de nommage standard des couches. Cette option n'est valide que si target_modules est une liste.

Classe de configuration pour les adaptateurs UniLora.

Cette classe définit tous les hyperparamètres nécessaires pour initialiser et appliquer les couches UniLora au sein du framework PEFT. La configuration est volontairement minimale et n'inclut que les paramètres activement utilisés par l'implémentation actuelle de UniLora.

Référence : Uni-LoRA: One Vector Is All You Need https://arxiv.org/abs/2506.00799

UniLoraModel

classe peft.UniLoraModel

< >

( modelconfigadapter_namelow_cpu_mem_usage: bool = Falsestate_dict: dict[str, torch.Tensor] | None = None )

Crée un adaptateur UniLora autour d'un modèle pré-entraîné.

generate_index

< >

( lora_param_count: inttheta_d_length: intproj_seed: int )

Attribuer des indices theta_d déterministes à l'espace de paramètres UniLora aplati.

Un simple np.random.choice(np.arange(theta_d_length), size=lora_param_count) échantillonne chaque position indépendamment, ce qui peut laisser certaines entrées de theta_d inutilisées pour les adaptateurs plus petits. UniLora utilise à la place une affectation déterministe équilibrée : chaque index apparaît soit floor(D / d) fois, soit ceil(D / d) fois, où D est le nombre de paramètres LoRA aplatis et d est theta_d_length. Cela maintient la normalisation par index stable tout en mélangeant l'affectation avec proj_seed.

Update on GitHub

←TinyLoRA VB-LoRA→