PEFT documentation

튜너

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

튜너

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