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.22.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

UniLoRA

Uni-LoRAは、低ランクアダプター重み間でコンパクトな学習可能ベクトルバンクを共有するPEFT手法です。LoRA行列の各要素を独立に学習するのではなく、UniLoRAは各要素を共有されるtheta_d値に決定論的に射影し、アダプター更新で使用される共有パラメータを学習します。

クイックスタート

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()

重要なパラメータ

r は低ランクアダプターの次元を制御します。値を大きくすると、アダプターの容量とメモリ使用量が増加します。

theta_d_lengthは、共有UniLoRAベクトルバンクの長さを制御します。これは、投影されたアダプターエントリによって共有される主な学習可能なストレージです。

proj_seed は、theta_d への固定投影における決定論的なインデックス生成を制御します。同じシードと設定を再利用することで、生成されるアダプターインデックスを再現可能にします。

target_modulesは、UniLoRAアダプターを適用するモジュールを選択します。モデルアーキテクチャがサポートしている場合、["q_proj", "v_proj"]のようなモジュールのサフィックス、正規表現の文字列、または"all-linear"を使用できます。

unilora_dropout は、学習中に UniLoRA アダプタ層内で dropout を適用します。

init_weightsはUniLoRAのパラメータ初期化を制御します。初期化を手動で管理する必要がある場合は、Falseに設定して、theta_dのランダムな初期化を維持してください。

save_indices は、UniLoRA のチェックポイントが、生成されたインデックスとスケールテンソルを共有の theta_d パラメータとともに保存するかどうかを制御します。これを無効にしておくと、チェックポイントのサイズが小さくなり、インデックスは proj_seed から再生成されます。有効にすると、保存されたアダプターは将来のインデックス生成の変更から独立した形になります。

ベンチマーク概要

API

UniLoraConfig

クラス 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 )

パラメータ

  • r (int) — 低ランク適応のランクです。UniLora更新の表現能力を制御します。
  • proj_seed (int) — 固定インデックス割り当てを生成するために使用されるランダムシード。これにより、実行間での再現性が保証されます。
  • theta_d_length (int) — 共有 UniLora ベクトル theta_d の長さ。
  • target_modules (Union[list[str], str], 省略可能) — UniLora アダプターを適用するモジュールの名前またはパターン。文字列が指定された場合は正規表現として扱われます。リストが指定された場合は、モジュールが完全一致またはサフィックスで一致します。特別な値 'all-linear' を指定すると、出力層を除くすべての Linear / Conv1D 層に UniLora が適用されます。指定されない場合は、モデルのアーキテクチャからモジュールが推論されます。サポートされていないアーキテクチャの場合、エラーが発生します。
    • 文字列が提供された場合、正規表現として扱われます。
    • リストが提供された場合、モジュールは完全な名前またはサフィックスによって一致します。
    • 特殊値 ‘all-linear’ は、出力層を除くすべての Linear / Conv1D 層に UniLora を適用します。 指定されない場合、モジュールはモデルのアーキテクチャから推論されます。アーキテクチャがサポートされていない場合は、エラーが発生します。
  • unilora_dropout (float) — UniLora層内で適用されるDropoutの確率。
  • fan_in_fan_out (bool) — 置換されたレイヤーが重みを (fan_in, fan_out) 形式で保存するかどうかを示します。Conv1D レイヤーを使用する GPT-2 などのモデルでは、これを True に設定する必要があります。
  • bias (str) — 学習可能なバイアス項を指定します:
    • ‘none’: バイアスパラメータは更新されません
    • ‘all’: すべてのバイアスパラメータが更新されます
    • ‘unilora_only’: UniLora層内のバイアスのみが更新されます 注: バイアスの更新を有効にすると、アダプターが無効な場合でもモデルの出力が変更されます。
  • modules_to_save (list[str]、任意) — UniLora レイヤー以外で、最終的なチェックポイントに保存されるべき、学習可能なまま残す追加のモジュールです。分類器などのタスク固有のヘッドに使用されることが一般的です。
  • init_theta_d_bound (float) — UniLora ベクトルバンクの初期化境界値です。ベクトルは [-init_theta_d_bound, init_theta_d_bound] の範囲から一様分布でサンプリングされます。勾配消失を防ぐため、ゼロでの初期化は避けてください。安定した学習のためには、小さな値(例: 0.02)が推奨されます。
  • init_weights (bool) — theta_dをデフォルトのUniLora初期化で初期化するかどうか。Falseに設定すると、theta_dはランダムな初期化を維持します。
  • save_indices (bool) — theta_d とともに、生成された UniLora のインデックスおよびスケールバッファを保存するかどうか。これによりチェックポイントのサイズは増加しますが、保存されたアダプターがインデックス生成ルーチンの将来の変更から独立した状態になります。
  • layers_to_transform (Union[list[int], int], 省略可) — UniLora を適用する Transformer レイヤーのインデックスです。指定した場合、これらのレイヤーのみが変更されます。 このオプションは、target_modules がリストである場合にのみ有効です。
  • layers_pattern (Union[list[str], str]、省略可) — モデルが標準的なレイヤー命名規則に従わない場合に、layers_to_transform と組み合わせて使用するカスタムなレイヤー名パターンです。このオプションは、target_modules がリストである場合にのみ有効です。

UniLoraアダプター用の設定クラスです。

このクラスは、PEFTフレームワーク内でUniLoraレイヤーを初期化および適用するために必要なすべてのハイパーパラメータを定義します。 この設定は意図的に最小限に抑えられており、現在のUniLora実装で実際に使用されているパラメータのみが含まれています。

Reference: Uni-LoRA: One Vector Is All You Need https://arxiv.org/abs/2506.00799

UniLoraModel

class peft.UniLoraModel

< >

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

事前学習済みモデルの周りにUniLoraアダプターを作成します。

generate_index

< >

( lora_param_count: inttheta_d_length: intproj_seed: int )

フラット化されたUniLoraパラメータ空間に、決定論的なtheta_dインデックスを割り当てます。

np.random.choice(np.arange(theta_d_length), size=lora_param_count) のみを使用すると、各位置が独立にサンプリングされるため、小さいアダプタでは一部の theta_d エントリが未使用になる可能性があります。UniLora では、バランスの取れた決定論的な割り当てを使用します。各インデックスは floor(D / d) 回または ceil(D / d) 回出現し、ここで D はフラット化された LoRA パラメータ数、d は theta_d_length です。これにより、proj_seed を使用して割り当てをシャッフルしながらも、インデックスごとの正規化が安定して保たれます。

Update on GitHub