# 튜너

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

## BaseTuner[[peft.tuners.tuners_utils.BaseTuner]]

#### peft.tuners.tuners_utils.BaseTuner[[peft.tuners.tuners_utils.BaseTuner]]

```python
peft.tuners.tuners_utils.BaseTuner(model, peft_config: Union[PeftConfig, dict[str, PeftConfig]], adapter_name: str, low_cpu_mem_usage: bool = False, state_dict: Optional[dict[str, torch.Tensor]] = None)
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L269)

**매개변수:**

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의 target modules 중 하나와 전달된 모듈의 키 이름이 일치하는지 확인하는 private helper method입니다.

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

#### delete_adapter[[peft.tuners.tuners_utils.BaseTuner.delete_adapter]]

```python
delete_adapter(adapter_name: str)
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L613)

**매개변수:**

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

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

#### disable_adapter_layers[[peft.tuners.tuners_utils.BaseTuner.disable_adapter_layers]]

```python
disable_adapter_layers()
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L589)

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

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

#### enable_adapter_layers[[peft.tuners.tuners_utils.BaseTuner.enable_adapter_layers]]

```python
enable_adapter_layers()
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L606)

Enable all adapters in-place

#### get_model_config[[peft.tuners.tuners_utils.BaseTuner.get_model_config]]

```python
get_model_config(model: nn.Module)
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L1443)

**매개변수:**

model (`nn.Module`) : 설정을 가져올 모델.

default (`dict|None`, *선택 사항*) --: 모델에 config 속성이 없는 경우 반환할 값.

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

#### inject_adapter[[peft.tuners.tuners_utils.BaseTuner.inject_adapter]]

```python
inject_adapter(model: nn.Module, adapter_name: str, autocast_adapter_dtype: bool = True, low_cpu_mem_usage: bool = False, state_dict: Optional[dict[str, torch.Tensor]] = None)
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L843)

**매개변수:**

model (`nn.Module`) : 튜닝할 모델.

adapter_name (`str`) : 어댑터 이름.

autocast_adapter_dtype (`bool`, *선택 사항*) : 어댑터의 dtype을 자동 캐스팅할지 여부입니다. 기본값은 `True`입니다.

low_cpu_mem_usage (`bool`, `optional`, 기본값 `False`) : meta device에 빈 어댑터 가중치를 생성합니다. 로딩 프로세스를 가속하는 데 유용합니다.

state_dict (`dict`, *선택 사항*, 기본값 `None`) : state_dict가 여기에 전달되면, state_dict의 항목을 기반으로 어댑터가 주입됩니다. 이는 예를 들어 체크포인트가 메타데이터 없이 생성되어 PEFT 방법의 정확한 `target_modules`를 알 수 없는 경우 유용할 수 있습니다. state_dict의 값은 사용되지 않으며, 어댑팅해야 할 올바른 레이어를 결정하는 데 키만 사용됩니다.

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

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

#### merge_adapter[[peft.tuners.tuners_utils.BaseTuner.merge_adapter]]

```python
merge_adapter(adapter_names: Optional[list[str]] = None, safe_merge: bool = False)
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L1385)

**매개변수:**

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[[peft.tuners.tuners_utils.BaseTuner.merge_and_unload]]

```python
merge_and_unload(progressbar: bool = False, safe_merge: bool = False, adapter_names: Optional[list[str]] = None)
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L786)

**매개변수:**

progressbar (`bool`) : 언로드 및 병합 과정을 나타내는 진행 표시줄을 표시할지 여부 (기본값: False).

safe_merge (`bool`) : 어댑터 가중치에 잠재적인 Nan이 있는지 확인하기 위한 안전한 병합 체크를 활성화할지 여부.

adapter_names (`List[str]`, *선택 사항*) : 병합할 어댑터 이름 목록입니다. None인 경우 모든 활성 어댑터가 병합됩니다. 기본값은 `None`입니다.

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

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

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

예:

```py
>>> 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[[peft.tuners.tuners_utils.BaseTuner.set_adapter]]

```python
set_adapter(adapter_name: str | list[str], inference_mode: bool = False)
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L1429)

**매개변수:**

adapter_name (str, list[str]) : 활성으로 설정할 어댑터의 이름

inference_mode (bool, optional) : 활성화된 어댑터를 고정할지 여부(즉, `requires_grad=False`). 기본값은 False입니다.

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

#### set_requires_grad[[peft.tuners.tuners_utils.BaseTuner.set_requires_grad]]

```python
set_requires_grad(adapter_names: str | Sequence[str], requires_grad: bool = True)
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L630)

**매개변수:**

adapter_names (`str` 또는 `Sequence[str]`) : 그라디언트를 활성화/비활성화할 어댑터의 이름.

requires_grad (`bool`, *선택 사항*) : 활성화(`True`, 기본값) 또는 비활성화(`False`) 여부를 지정합니다.

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

#### supports_lora_conversion[[peft.tuners.tuners_utils.BaseTuner.supports_lora_conversion]]

```python
supports_lora_conversion(adapter_name: str = 'default')
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L1552)

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

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

#### unload[[peft.tuners.tuners_utils.BaseTuner.unload]]

```python
unload()
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L824)

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

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

#### unmerge_adapter[[peft.tuners.tuners_utils.BaseTuner.unmerge_adapter]]

```python
unmerge_adapter()
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L1420)

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

## BaseTunerLayer[[peft.tuners.tuners_utils.BaseTunerLayer]]

#### peft.tuners.tuners_utils.BaseTunerLayer[[peft.tuners.tuners_utils.BaseTunerLayer]]

```python
peft.tuners.tuners_utils.BaseTunerLayer()
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L1918)

**매개변수:**

is_pluggable (`bool`, *선택 사항*) : 어댑터 레이어가 임의의 PyTorch 모듈에 연결될 수 있는지 여부

active_adapters (Union[List`str`, `str`], *optional*) : 활성 어댑터의 이름.

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

#### delete_adapter[[peft.tuners.tuners_utils.BaseTunerLayer.delete_adapter]]

```python
delete_adapter(adapter_name: str)
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L2179)

**매개변수:**

adapter_name (`str`) : 삭제할 어댑터의 이름

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

…

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

#### enable_adapters[[peft.tuners.tuners_utils.BaseTunerLayer.enable_adapters]]

```python
enable_adapters(enabled: bool)
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L2093)

**매개변수:**

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

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

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

#### get_additive_delta[[peft.tuners.tuners_utils.BaseTunerLayer.get_additive_delta]]

```python
get_additive_delta(adapter_name: str = 'default')
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L2351)

**매개변수:**

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[[peft.tuners.tuners_utils.BaseTunerLayer.get_base_layer]]

```python
get_base_layer()
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L1948)

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

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

#### get_base_weight[[peft.tuners.tuners_utils.BaseTunerLayer.get_base_weight]]

```python
get_base_weight()
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L1960)

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

…

#### set_adapter[[peft.tuners.tuners_utils.BaseTunerLayer.set_adapter]]

```python
set_adapter(adapter_names: str | list[str], inference_mode: bool = False)
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L2138)

**매개변수:**

adapter_names (`str` 또는 `list[str]`) : 활성으로 설정할 어댑터의 이름입니다.

inference_mode (bool, optional) : 활성화된 어댑터를 고정할지 여부(즉, `requires_grad=False`). 기본값은 False입니다.

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

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

#### set_base_weight[[peft.tuners.tuners_utils.BaseTunerLayer.set_base_weight]]

```python
set_base_weight(weight_data: torch.Tensor)
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L1969)

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

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

#### set_requires_grad[[peft.tuners.tuners_utils.BaseTunerLayer.set_requires_grad]]

```python
set_requires_grad(adapter_names: str | Sequence[str], requires_grad: bool = True)
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L2223)

**매개변수:**

adapter_names (`str` 또는 `Sequence[str]`) : 그라디언트를 활성화/비활성화할 어댑터의 이름.

requires_grad (`bool`, *선택 사항*) : 활성화(`True`, 기본값) 또는 비활성화(`False`) 여부를 지정합니다.

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

#### set_training[[peft.tuners.tuners_utils.BaseTunerLayer.set_training]]

```python
set_training(adapter_names: str | Sequence[str], training: bool = True)
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L2074)

**매개변수:**

adapter_names (`str` 또는 `Sequence[str]`) : 학습 모드를 업데이트할 어댑터의 이름입니다.

training (`bool`, *선택 사항*) : 학습 모드를 활성화(`True`, 기본값)하거나 비활성화(`False`)할지 여부.

…

#### supports_lora_conversion[[peft.tuners.tuners_utils.BaseTunerLayer.supports_lora_conversion]]

```python
supports_lora_conversion(adapter_name: str = 'default')
```

[소스](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/tuners_utils.py#L2343)

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

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

