# PEFT[[transformers.integrations.PeftAdapterMixin]]

[PeftAdapterMixin](/docs/transformers/main/ko/main_classes/peft#transformers.integrations.PeftAdapterMixin)은 Transformers에서 어댑터를 관리하기 위한 [PEFT](https://huggingface.co/docs/peft/index) 라이브러리의 함수를 제공합니다. 이 mixin은 프롬프트 학습이 아닌 모든 PEFT 방법(LoRA, IA3, AdaLoRA 등)을 지원합니다. 프롬프트 튜닝 방법(프롬프트 튜닝, 프롬프트 학습)은 torch 모듈에 주입할 수 없으므로 지원하지 않습니다.

#### transformers.integrations.PeftAdapterMixin[[transformers.integrations.PeftAdapterMixin]]

```python
transformers.integrations.PeftAdapterMixin()
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L57)

PEFT 라이브러리에서 지원하는 어댑터 가중치를 로드하고 사용하는 데 필요한 모든 함수를 포함하는 클래스입니다. 어댑터와 트랜스포머 기반 모델에 이를 주입하는 방법에 대한 자세한 내용은 PEFT 라이브러리 문서(https://huggingface.co/docs/peft/index)를 참고하세요.

현재 지원되는 PEFT 방법은 모두 프롬프트 학습이 아닌 방법(LoRA, IA³ 등)입니다. 프롬프트 튜닝, 프롬프트 학습과 같은 다른 PEFT 모델은 이러한 어댑터가 torch 모듈에 "주입(inject)"될 수 없으므로 지원 범위에서 제외됩니다. 이러한 방법을 사용하려면 PEFT 라이브러리의 사용 가이드를 참조하세요.

이 mixin을 사용하면 올바른 PEFT 버전(>= 0.20.0)이 설치되어 있으면 다음을 수행할 수 있습니다:

- 로컬 경로 또는 원격 Hub 저장소에 저장된 어댑터를 로드하고 모델에 주입합니다
- 모델에 새로운 어댑터를 연결하고 Trainer를 사용하거나 직접 학습합니다.
- 여러 어댑터를 연결하고 반복적으로 활성화/비활성화하기
- 모델의 모든 어댑터를 활성화/비활성화합니다.
- 활성 어댑터의 `state_dict`를 가져옵니다.

#### load_adapter[[transformers.integrations.PeftAdapterMixin.load_adapter]]

```python
load_adapter(peft_model_id: str | None = None, adapter_name: str | None = None, peft_config: dict[str, typing.Any] | None = None, adapter_state_dict: dict[str, 'torch.Tensor'] | None = None, low_cpu_mem_usage: bool = False, is_trainable: bool = False, hotswap: typing.Union[bool, typing.Literal['auto']] = 'auto', local_files_only: bool = False, adapter_kwargs: dict[str, typing.Any] | None = None, load_config: typing.Optional[ForwardRef('LoadStateDictConfig')] = None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L80)

**매개변수:**

peft_model_id (`str`, *선택 사항*) : Hub에서 찾을 모델의 식별자 또는 저장된 어댑터 설정 파일과 어댑터 가중치에 대한 로컬 경로입니다.

adapter_name (`str`, *선택 사항*) : 사용할 어댑터 이름입니다. 설정하지 않으면 "default" 이름을 사용합니다.

load_config (`LoadStateDictConfig`, *선택*) : 어댑터 가중치를 가져올 때 재사용할 로드 구성입니다. 일반적으로 `from_pretrained`에서 가져옵니다.

kwargs (`dict[str, Any]`, *선택*) : 키워드 인수로 전달되는 추가 `LoadStateDictConfig` 필드.

peft_config (`dict[str, Any]`, *선택*) : 추가할 어댑터의 설정입니다. 지원되는 어댑터는 프롬프트 학습이 아닌 모든 설정(LoRA, IA³ 등)입니다. 사용자가 PEFT 상태 딕셔너리를 직접 전달하는 경우에 이 인수가 사용됩니다.

adapter_state_dict (`dict[str, torch.Tensor]`, *선택 사항*) : 로드할 어댑터의 state dict입니다. 사용자가 PEFT state dict를 직접 전달하는 경우에 이 인수가 사용됩니다.

low_cpu_mem_usage (`bool`, *선택 사항*, 기본값 `False`) : PEFT 어댑터를 로드할 때 메모리 사용량을 줄입니다. 로드 과정도 빨라집니다.

is_trainable (`bool`, *선택 사항*, 기본값 `False`) : 어댑터가 학습 가능해야 하는지 여부입니다. `False`인 경우, 어댑터는 고정(frozen)되며 추론에만 사용할 수 있습니다.

hotswap : (`"auto"` 또는 `bool`, *선택*, 기본값 `"auto"`) 기존 (LoRA) 어댑터를 새로 로드한 어댑터로 제자리에서 교체할지 여부입니다. 즉, 추가 어댑터를 로드하는 대신 기존 어댑터의 가중치를 새 어댑터의 가중치로 대체합니다. 이는 더 빠르고 메모리 효율적일 수 있습니다. 그러나 hotswapping의 주요 이점은 모델이 torch.compile로 컴파일된 경우, 새 어댑터를 로드할 때 모델의 재컴파일이 필요하지 않다는 점입니다. hotswapping을 사용할 때 전달하는 `adapter_name`은 이미 로드된 어댑터의 이름이어야 합니다. 새 어댑터와 기존 어댑터의 rank와/또는 LoRA alpha(즉, scaling)가 다른 경우, 어댑터를 로드하기 전에 추가 메서드를 호출해야 합니다: ```py model = AutoModel.from_pretrained(...) max_rank = ...  # the highest rank among all LoRAs that you want to load # call *before* compiling and loading the LoRA adapter model.enable_peft_hotswap(target_rank=max_rank) model.load_adapter(file_name_1, adapter_name="default") # optionally compile the model now model = torch.compile(model, ...) output_1 = model(...) # now you can hotswap the 2nd adapter, use the same name as for the 1st # hotswap is activated by default since enable_peft_hotswap was called model.load_adapter(file_name_2, adapter_name="default") output_2 = model(...) ``` 기본적으로 hotswap은 비활성화되어 있으며 `hotswap=True`를 전달해야 합니다. 먼저 `enable_peft_hotswap`을 호출했다면 활성화됩니다. 이 경우에도 `hotswap=False`를 전달하여 수동으로 비활성화할 수 있습니다. hotswapping에는 여기 문서화된 몇 가지 제한 사항이 있습니다: https://huggingface.co/docs/peft/main/en/package_reference/hotswap

adapter_kwargs (`dict[str, Any]`, *선택*) : 어댑터 설정의 `from_pretrained` 메서드와 `find_adapter_config_file` 메서드에 함께 전달되는 추가 키워드 인자입니다.

파일 또는 원격 Hub 폴더에서 어댑터 가중치를 로드합니다. 어댑터와 PEFT 메서드에 익숙하지 않으시다면, PEFT 공식 문서에서 더 자세히 알아보세요: https://huggingface.co/docs/peft

어댑터 가중치를 로드하려면 백엔드로 PEFT가 설치되어 있어야 합니다.

#### add_adapter[[transformers.integrations.PeftAdapterMixin.add_adapter]]

```python
add_adapter(adapter_config, adapter_name: str | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L390)

**매개변수:**

adapter_config (`~peft.PeftConfig`) : 추가할 어댑터의 설정입니다. 지원되는 어댑터는 프롬프트 학습이 아닌 방법(LoRA, IA³ 등)입니다.

adapter_name (`str`, *선택 사항*, 기본값 `"default"`) : 추가할 어댑터의 이름입니다. 이름을 전달하지 않으면 어댑터에 기본 이름이 할당됩니다.

어댑터와 PEFT 방법에 익숙하지 않으시다면, PEFT 공식 문서에서 더 자세히 읽어보시길 권합니다: https://huggingface.co/docs/peft

학습을 위해 현재 모델에 새로운 어댑터를 추가합니다. 어댑터 이름이 전달되지 않으면, PEFT 라이브러리의 관례를 따르기 위해 기본 이름이 어댑터에 할당됩니다(PEFT에서는 기본 어댑터 이름으로 "default"를 사용합니다).

새로 추가된 어댑터는 자동으로 활성화되지 않습니다. 활성화하려면 `model.set_adapter`를 사용하세요.

#### set_adapter[[transformers.integrations.PeftAdapterMixin.set_adapter]]

```python
set_adapter(adapter_name: list[str] | str)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L430)

**매개변수:**

adapter_name (`Union[list[str], str]`) : 설정할 어댑터의 이름입니다. 여러 어댑터를 설정하려면 문자열 목록을 사용할 수도 있습니다.

어댑터와 PEFT 방법에 익숙하지 않으시다면, PEFT 공식 문서에서 더 자세히 읽어보시길 권합니다: https://huggingface.co/docs/peft

…

#### disable_adapters[[transformers.integrations.PeftAdapterMixin.disable_adapters]]

```python
disable_adapters()
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L471)

어댑터와 PEFT 방법에 익숙하지 않으시다면, PEFT 공식 문서에서 더 자세히 읽어보시길 권합니다: https://huggingface.co/docs/peft

모델에 연결된 모든 어댑터를 비활성화합니다. 이렇게 하면 기본 모델만으로 추론이 수행됩니다.

#### enable_adapters[[transformers.integrations.PeftAdapterMixin.enable_adapters]]

```python
enable_adapters()
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L490)

어댑터와 PEFT 방법에 익숙하지 않으시다면, PEFT 공식 문서에서 더 자세히 읽어보시길 권합니다: https://huggingface.co/docs/peft

모델에 연결된 어댑터를 활성화합니다.

#### enable_peft_hotswap[[transformers.integrations.PeftAdapterMixin.enable_peft_hotswap]]

```python
enable_peft_hotswap(target_rank: int = 128, check_compiled: typing.Literal['error', 'warn', 'ignore'] = 'error')
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L353)

**매개변수:**

target_rank (`int`, *선택 사항*, 기본값 `128`) : 로드될 모든 어댑터 중 가장 높은 랭크입니다.

check_compiled (`str`, *선택 사항*, 기본값 `"error"`) : 모델이 이미 컴파일된 경우를 처리하는 방법입니다. 일반적으로 이 상황을 피해야 합니다. 옵션은 다음과 같습니다: - "error" (기본값): 오류를 발생시킵니다 - "warn": 경고를 표시합니다 - "ignore": 아무 동작도 하지 않습니다

다른 랭크를 가진 PEFT 어댑터를 핫스왑하거나, 모델이 컴파일된 경우 재컴파일을 트리거하지 않고 핫스왑할 수 있는 가능성을 활성화합니다.

현재 hotswapping은 LoRA만 지원합니다.

이 메서드를 호출하는 것은 어댑터를 핫스왑할 때, 그리고 모델이 컴파일된 경우 또는 로드된 어댑터의 랭크가 서로 다른 경우에만 필요합니다. 모든 랭크가 동일하고 모델이 컴파일되지 않은 경우, 이 메서드를 먼저 호출하지 않아도 핫스왑이 정상적으로 작동합니다.

#### active_adapters[[transformers.integrations.PeftAdapterMixin.active_adapters]]

```python
active_adapters()
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L508)

어댑터와 PEFT 방법에 익숙하지 않으시다면, PEFT 공식 문서에서 더 자세히 읽어보시길 권합니다: https://huggingface.co/docs/peft

모델의 현재 활성 어댑터를 가져옵니다. 멀티 어댑터 추론(여러 어댑터를 조합하여 추론을 수행하는 경우)에서는 사용자가 적절히 처리할 수 있도록 모든 활성 어댑터의 목록을 반환합니다.

이전 PEFT 버전(멀티 어댑터 추론을 지원하지 않는 버전)의 경우, `module.active_adapter`는 단일 문자열을 반환합니다.

#### get_adapter_state_dict[[transformers.integrations.PeftAdapterMixin.get_adapter_state_dict]]

```python
get_adapter_state_dict(adapter_name: str | None = None, state_dict: dict | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L537)

**매개변수:**

adapter_name (`str`, *선택 사항*) : state dict를 가져올 adapter의 이름입니다. 이름을 전달하지 않으면 활성 adapter가 사용됩니다.

state_dict (중첩된 사전, `torch.Tensor`, *선택 사항*) : 모델의 상태 사전입니다. 기본적으로 `self.state_dict()`를 사용하지만, 모델의 상태 사전을 복원할 때 특별한 조치가 필요한 경우(예: 모델 병렬화를 사용하는 경우) 사용할 수 있습니다.

어댑터와 PEFT 방법에 익숙하지 않으시다면, PEFT 공식 문서에서 더 자세히 읽어보시길 권합니다: https://huggingface.co/docs/peft

지정된 adapter_name 어댑터의 가중치 텐서만 포함해야 하는 어댑터 상태 딕셔너리를 가져옵니다. adapter_name이 전달되지 않으면 활성 어댑터가 사용됩니다.

#### delete_adapter[[transformers.integrations.PeftAdapterMixin.delete_adapter]]

```python
delete_adapter(adapter_names: list[str] | str)
```

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/peft.py#L622)

**매개변수:**

adapter_names (`Union[list[str], str]`) : 삭제할 어댑터의 이름입니다.

기저 모델에서 PEFT 어댑터를 삭제합니다.