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는 저순위 어댑터 가중치 간에 컴팩트한 학습 가능 벡터 뱅크를 공유하는 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 파라미터 초기화를 제어합니다. 초기화를 수동으로 관리해야 하는 경우 무작위 theta_d 초기화를 유지하려면 False로 설정하세요.

save_indices는 UniLoRA 체크포인트가 생성된 인덱스 및 스케일 텐서를 공유 theta_d 매개변수와 함께 저장할지 여부를 제어합니다. 이 옵션을 비활성화하면 체크포인트 크기가 작아지고 proj_seed에서 인덱스를 재생성합니다. 활성화하면 저장된 어댑터가 향후 인덱스 생성 방식의 변경 사항에서 독립적으로 동작합니다.

벤치마크 개요

API

UniLoraConfig

class 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 어댑터가 적용될 모듈의 이름 또는 패턴입니다.
    • 문자열이 제공되면 정규식으로 처리됩니다.
    • list가 제공되면, 모듈은 정확한 이름 또는 접미사로 일치합니다.
    • 특수 값 ‘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) — 학습 가능한 bias 항을 지정합니다:
    • ‘none’: 편향 매개변수가 업데이트되지 않습니다
    • ‘all’: 모든 bias 매개변수가 업데이트됩니다
    • ‘unilora_only’: UniLora 레이어 내부의 bias만 업데이트됩니다 참고: bias 업데이트를 활성화하면 어댑터가 비활성화된 상태에서도 모델 출력이 변경됩니다.
  • modules_to_save (list[str], 선택 사항) — UniLora 레이어 외부에서 최종 체크포인트에 저장되어야 하는 추가 모듈입니다. 분류기 같은 작업별 헤드를 사용할 때 흔히 사용됩니다.
  • init_theta_d_bound (float) — UniLora 벡터 뱅크의 초기화 경계입니다. 벡터는 [-init_theta_d_bound, init_theta_d_bound] 범위에서 균등하게 샘플링됩니다. 기울기 소실(vanishing gradients)을 방지하기 위해 0으로 초기화하는 것은 피해야 합니다. 안정적인 학습을 위해 작은 값(예: 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는 균형 잡힌 결정론적 할당을 사용합니다. 여기서 D는 평탄화된 LoRA 매개변수 수이고 d는 theta_d_length이며, 각 인덱스는 floor(D / d)번 또는 ceil(D / d)번 등장합니다. 이를 통해 proj_seed로 할당을 셔플하더라도 인덱스별 정규화가 안정적으로 유지됩니다.

Update on GitHub

←TinyLoRA VB-LoRA→