PEFT documentation

튜너

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

튜너

Tuner(또는 adapter)는 torch.nn.Module에 연결할 수 있는 모듈입니다. BaseTuner는 다른 tuner의 베이스 클래스로, 어댑터 구성을 준비하고 대상 모듈을 어댑터 모듈로 교체하기 위한 공유 메서드와 속성을 제공합니다. BaseTunerLayer는 어댑터 레이어의 베이스 클래스입니다. 어댑터 활성화 및 비활성화 등 어댑터 관리를 위한 메서드와 속성을 제공합니다.

BaseTuner

class peft.tuners.tuners_utils.BaseTuner

< >

( modelpeft_config: Union[PeftConfig, dict[str, PeftConfig]]adapter_name: strlow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict[str, torch.Tensor]] = None )

매개변수

  • model (torch.nn.Module) — 어댑터 튜너 레이어가 연결될 모델입니다.
  • forward (Callable) — 모델의 forward 메서드입니다.
  • peft_config (Union[PeftConfig, dict[str, PeftConfig]]) — 어댑터 구성 객체입니다. str에서 PeftConfig 객체로 매핑된 사전이어야 합니다. PeftConfig 객체를 전달하면 기본 이름 adapter를 가진 새로운 어댑터가 생성되거나, 키가 adapter_name이고 값이 해당 peft config인 새로운 사전이 생성됩니다.
  • config (dict[str, Any]) — 모델 구성 객체입니다. str에서 Any 객체로 매핑된 사전이어야 합니다.
  • targeted_module_names (list[str]) — 실제로 적응된 모듈 이름 목록입니다. config.target_modules가 올바르게 지정되었는지 빠르게 확인하고 싶을 때 유용합니다.
  • targeted_parameter_names (list[str]) — 실제로 적응된 매개변수 이름 목록입니다. config.target_parameters가 올바르게 지정되었는지 빠르게 확인하고 싶을 때 유용합니다.
  • prefix (str) — PEFT 방법별로 고유한 접두사입니다. 예를 들어 LoRA의 경우 "lora_"입니다.

torch.nn.Module에 주입 가능한 모든 튜너에 공통으로 사용되는 메서드와 속성을 제공하는 기본 튜너 모델

새로운 Tuner 클래스를 추가하려면 다음 메서드를 오버라이드해야 합니다:

  • _prepare_adapter_config: 필드 target_modules가 누락된 경우와 같이 어댑터 구성을 최종적으로 준비하기 위한 비공개 메서드입니다.
  • _create_and_replace: 타겟 모듈을 어댑터 모듈로 생성하고 교체하는 private method입니다.
  • _check_target_module_exists: adapter_config의 대상 모듈 중 하나와 전달된 모듈의 키 이름이 일치하는지 확인하는 비공개 헬퍼 메서드입니다.

가장 쉬운 방법은 peft.tuners.lora.LoraModel 클래스에서 어떤 처리가 이루어지는지 확인하는 것입니다.

delete_adapter

< >

( adapter_name: str )

매개변수

  • adapter_name (str) — 삭제할 어댑터의 이름.

기존 어댑터를 삭제합니다.

disable_adapter_layers

< >

( )

in-place로 모든 어댑터를 비활성화합니다.

모든 어댑터를 비활성화하면 모델 출력은 베이스 모델의 출력과 동일해집니다.

enable_adapter_layers

< >

( )

Enable all adapters in-place

get_model_config

< >

( model: nn.Module )

매개변수

  • model (nn.Module) — 설정(config)을 가져올 모델.
  • default (dict|None, 선택 사항) —: 모델에 config 속성이 없는 경우 반환할 값.

이 메서드는 모델에서 config를 딕셔너리 형태로 가져옵니다. 모델에 config 속성이 없으면 이 메서드는 기본 config를 반환합니다.

inject_adapter

< >

( model: nn.Moduleadapter_name: strautocast_adapter_dtype: bool = Truelow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict[str, torch.Tensor]] = None )

매개변수

  • model (nn.Module) — 튜닝할 모델.
  • adapter_name (str) — 어댑터 이름입니다.
  • autocast_adapter_dtype (bool, 선택 사항) — 어댑터 dtype를 자동 변환할지 여부입니다. 기본값은 True입니다.
  • low_cpu_mem_usage (bool, optional, 기본값 False) — 메타 디바이스에 빈 어댑터 가중치를 생성합니다. 로딩 프로세스를 가속하는 데 유용합니다.
  • state_dict (dict, 선택 사항, 기본값 None) — 여기에 state_dict가 전달되면, state_dict의 항목을 기반으로 어댑터가 주입됩니다. 이는 PEFT 메서드의 정확한 target_modules가 알려지지 않은 경우, 예를 들어 메타 데이터 없이 체크포인트가 생성된 경우 등에 유용할 수 있습니다. state_dict의 값은 사용되지 않으며, 어댑팅해야 할 올바른 레이어를 결정하는 데 키만 사용됩니다.

어댑터 레이어를 생성하고 대상 모듈을 어댑터 레이어로 대체합니다. 프롬프트 튜닝이 아닌 어댑터 클래스가 전달되면 peft.mapping.get_peft_model이 내부적으로 이 메서드를 호출합니다.

해당 PEFT 설정은 BaseTuner 클래스의 peft_config 속성에서 직접 가져옵니다.

merge_adapter

< >

( adapter_names: Optional[list[str]] = Nonesafe_merge: bool = False )

매개변수

  • adapter_names (list[str], 선택 사항) — 병합할 어댑터 이름 목록입니다. None인 경우 모든 활성 어댑터가 병합됩니다. 기본값은 None입니다.
  • safe_merge (bool, 선택 사항) — True인 경우, 병합 작업은 원래 가중치의 복사본에서 수행되며 가중치를 병합하기 전에 NaN을 확인합니다. 병합 작업이 NaN을 생성하는지 확인하려는 경우 유용합니다. 기본값은 False입니다.

이 메서드는 어댑터 레이어를 베이스 모델에 병합합니다.

어댑터를 병합하면 forward pass의 속도가 빨라질 수 있습니다. 어댑터를 병합 해제(unmerge)하려면 어댑터 가중치의 사본이 메모리에 유지되어야 합니다. 메모리에 가중치를 유지하지 않고 어댑터 가중치를 병합하려면 merge_and_unload를 호출하세요.

레이어가 어댑터 가중치를 병합한 후에는 forward pass에서 해당 가중치만 사용합니다. 따라서 adapter_names가 모든 활성 어댑터를 포함하지 않으면, 나머지 활성 어댑터는 여전히 활성으로 보고되더라도 조용히 적용되지 않습니다. 모든 활성 어댑터를 병합하거나 먼저 unmerge_adapter를 호출하십시오. 이 동작은 v1.0 릴리스에서 변경될 예정입니다.

merge_and_unload

< >

( progressbar: bool = Falsesafe_merge: bool = Falseadapter_names: Optional[list[str]] = None )

매개변수

  • progressbar (bool) — 언로드 및 병합 과정을 나타내는 진행 표시줄을 표시할지 여부 (기본값: False).
  • safe_merge (bool) — 어댑터 가중에 잠재적인 Nan이 있는지 확인하기 위한 안전 병합 체크를 활성화할지 여부
  • adapter_names (List[str], 선택 사항) — 병합할 어댑터 이름 목록입니다. None인 경우 모든 활성 어댑터가 병합됩니다. 기본값은 None입니다.

이 메서드는 어댑터 레이어를 베이스 모델에 병합합니다.

누군가 베이스 모델을 독립적인 모델로 사용하려는 경우 이 작업이 필요합니다. 반환되는 모델은 원래 베이스 모델과 동일한 아키텍처를 가집니다.

반환된 모델을 변수에 할당하고 사용하는 것이 중요합니다. 이는 in-place 연산이 아닙니다!

예:

>>> from transformers import AutoModelForCausalLM
>>> from peft import PeftModel

>>> model_id = ...
>>> base_model = AutoModelForCausalLM.from_pretrained(model_id)
>>> peft_model_id = ...
>>> model = PeftModel.from_pretrained(base_model, peft_model_id)
>>> merged_model = model.merge_and_unload()

set_adapter

< >

( adapter_name: str | list[str]inference_mode: bool = False )

매개변수

  • adapter_name (str, list[str]) — 활성으로 설정할 어댑터의 이름
  • inference_mode (bool, optional) — 활성화된 어댑터를 고정(frozen)할지 여부(즉, requires_grad=False). 기본값은 False입니다.

활성 어댑터를 설정합니다.

set_requires_grad

< >

( adapter_names: str | Sequence[str]requires_grad: bool = True )

매개변수

  • adapter_names (str 또는 Sequence[str]) — 활성화/비활성화할 그래디언트를 가진 어댑터의 이름입니다.
  • requires_grad (bool, 선택 사항) — 활성화(True, 기본값) 또는 비활성화(False) 여부를 지정합니다.

지정된 어댑터에 대해 그라디언트를 활성화하거나 비활성화합니다.

supports_lora_conversion

< >

( adapter_name: str = 'default' )

이 모델의 어댑터를 LoRA로 변환할 수 있는지 여부

일반적으로 PEFT 방법이 가산적(additive)인 경우, 즉 W’ = W_base + delta_weight인 경우 이 방식이 작동합니다.

unload

< >

( )

모든 PEFT 모듈을 제거하여 기본 모델을 반환합니다.

반환된 모델을 변수에 할당하고 사용하는 것이 중요합니다. 이는 in-place 연산이 아닙니다!

unmerge_adapter

< >

( )

이 메서드는 베이스 모델에서 병합된 모든 어댑터 레이어를 병합 해제합니다.

BaseTunerLayer

class peft.tuners.tuners_utils.BaseTunerLayer

< >

( )

매개변수

  • is_pluggable (bool, 선택 사항) — 어댑터 레이어가 PyTorch 모듈에 연결될 수 있는지 여부
  • active_adapters (Union[Liststr, str], 선택 사항) — 활성 어댑터의 이름입니다.

모든 튜너에 공통된 메서드와 속성을 제공하는 튜너 레이어 믹스인입니다.

delete_adapter

< >

( adapter_name: str )

매개변수

  • adapter_name (str) — 삭제할 어댑터의 이름

layer에서 어댑터를 삭제합니다

…

삭제된 어댑터가 활성 어댑터였던 경우, 이 메서드는 새로운 활성 어댑터도 설정합니다. 모든 레이어에서 동일한 어댑터가 선택되도록 새로운 어댑터가 결정론적인 방식으로 선택되는 것이 중요합니다.

enable_adapters

< >

( enabled: bool )

매개변수

  • enabled (bool) — 어댑터를 활성화하려면 True, 비활성화하려면 False

어댑터 활성화 및 비활성화 전환

어댑터 가중치의 requires_grad 플래그를 설정하는 역할을 합니다.

get_additive_delta

< >

( adapter_name: str = 'default' )

매개변수

  • adapter_name (str) — 어댑터의 이름입니다. 기본값은 "default"입니다.

주어진 어댑터에 대해 가산 델타 가중치 W’ - W를 반환합니다. 여기서 W는 베이스 가중치이고 W’는 어댑터를 베이스 가중치에 병합한 후의 가중치입니다. 이는 병합된 가중치를 base_weight + module.get_additive_delta(adapter_name)을 통해 재구성할 수 있음을 의미합니다.

가산 PEFT 방법(예: LoRA, LoKr, LoHa)의 경우, 이는 get_delta_weight와 동일합니다. 곱셈 방법(예: OFT, BOFT)의 경우, 이 메서드는 유효 가중치 W'를 구성한 후 기본 가중치 W를 뺍니다.

어떤 adapter가 병합된 상태에서 이 메서드를 호출하면 ValueError가 발생합니다. 병합은 기본 가중치를 수정하므로, 반환 값이 현재 병합된 adapter에 의존하게 되기 때문입니다. 먼저 adapter를 병합 해제하세요.

반환되는 텐서는 어댑터 레이어의 가중치(예: LoRA의 경우 lora_A)의 dtype이며, 베이스 레이어 가중치의 dtype이 아닙니다. 이는 변환된 LoRA 어댑터가 사용할 dtype입니다.

결과는 convert_to_lora에서 어댑터를 LoRA 어댑터로 SVD 기반 근사할 때 사용됩니다.

기본적으로 이 메서드는 NotImplementedError를 발생시킵니다. 이 기능을 지원하는 PEFT 메서드는 _get_additive_delta 메서드를 오버라이드하여 additive delta를 반환하도록 해야 합니다.

get_base_layer

< >

( )

(재귀적으로) base_layer를 가져옵니다.

튜너 레이어가 다른 튜너 레이어를 감싸는 경우를 위해 필요합니다.

get_base_weight

< >

( )

기본 레이어의 가중치를 반환합니다.

…

set_adapter

< >

( adapter_names: str | list[str]inference_mode: bool = False )

매개변수

  • adapter_names (str 또는 list[str]) — 활성으로 설정할 어댑터의 이름입니다.
  • inference_mode (bool, optional) — 활성화된 어댑터를 고정(frozen)할지 여부(즉, requires_grad=False). 기본값은 False입니다.

활성 어댑터를 설정합니다.

또한, 이 함수는 inference_mode가 True가 아닌 한, 지정된 어댑터를 학습 가능하도록 설정합니다(즉, requires_grad=True).

set_base_weight

< >

( weight_data: torch.Tensor )

base layer의 기본 가중치를 새로운 텐서로 설정합니다

양자화된 가중치에서도 작동합니다.

set_requires_grad

< >

( adapter_names: str | Sequence[str]requires_grad: bool = True )

매개변수

  • adapter_names (str 또는 Sequence[str]) — 활성화/비활성화할 그래디언트를 가진 어댑터의 이름입니다.
  • requires_grad (bool, 선택 사항) — 활성화(True, 기본값) 또는 비활성화(False) 여부를 지정합니다.

지정된 어댑터에 대해 그라디언트를 활성화하거나 비활성화합니다.

set_training

< >

( adapter_names: str | Sequence[str]training: bool = True )

매개변수

  • adapter_names (str 또는 Sequence[str]) — 학습 모드가 업데이트되어야 하는 어댑터의 이름입니다.
  • training (bool, 선택 사항) — 학습 모드를 활성화(True, 기본값)하거나 비활성화(False)할지 여부.

…

supports_lora_conversion

< >

( adapter_name: str = 'default' )

이 레이어 유형을 LoRA로 변환할 수 있는지 여부입니다.

일반적으로 PEFT 방법이 가산적(additive)인 경우, 즉 W’ = W_base + delta_weight인 경우 이 방식이 작동합니다.

Update on GitHub