# PEFT

Diffusers는 [PeftAdapterMixin](/docs/diffusers/main/ko/api/loaders/peft#diffusers.loaders.PeftAdapterMixin) 클래스를 통해 [PEFT](https://huggingface.co/docs/peft/index) 라이브러리로 [LoRA](../../tutorials/using_peft_for_inference)와 같은 어댑터를 로드하는 것을 지원합니다. 이를 통해 Diffusers의 [UNet2DConditionModel](/docs/diffusers/main/ko/api/models/unet2d-cond#diffusers.UNet2DConditionModel), [SD3Transformer2DModel](/docs/diffusers/main/ko/api/models/sd3_transformer2d#diffusers.SD3Transformer2DModel)과 같은 모델링 클래스가 어댑터와 함께 작동할 수 있습니다.

> [!TIP]
> Diffusers에서 추론을 위해 PEFT를 사용하는 방법에 대한 개요는 [Inference with PEFT](../../tutorials/using_peft_for_inference) 튜토리얼을 참고하세요.

## PeftAdapterMixin[[diffusers.loaders.PeftAdapterMixin]]

#### diffusers.loaders.PeftAdapterMixin[[diffusers.loaders.PeftAdapterMixin]]

```python
diffusers.loaders.PeftAdapterMixin()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/peft.py#L61)

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

최신 버전의 PEFT를 설치하고 이 mixin을 사용하여 다음을 수행합니다:

- 모델에 새로운 어댑터를 연결합니다.
- 여러 어댑터를 연결하고 반복적으로 활성화/비활성화합니다.
- 모델의 모든 어댑터를 활성화/비활성화합니다.
- 활성 어댑터 목록을 가져옵니다.

#### active_adapters[[diffusers.loaders.PeftAdapterMixin.active_adapters]]

```python
active_adapters()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/peft.py#L649)

모델의 현재 활성 어댑터 목록을 가져옵니다.

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

#### add_adapter[[diffusers.loaders.PeftAdapterMixin.add_adapter]]

```python
add_adapter(adapter_config, adapter_name: str = 'default')
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/peft.py#L517)

**매개변수:**

adapter_config (`[~peft.PeftConfig]`) : 추가할 어댑터의 구성입니다. 지원되는 어댑터는 non-prefix tuning 및 adaption prompt 방법입니다.

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

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

어댑터와 PEFT 방법에 익숙하지 않으시다면, PEFT [문서](https://huggingface.co/docs/peft)에서 더 자세히 읽어보시길 권해드립니다.

#### delete_adapters[[diffusers.loaders.PeftAdapterMixin.delete_adapters]]

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

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/peft.py#L772)

**매개변수:**

adapter_names (`list[str, str]`) : 삭제할 어댑터의 이름(단일 문자열 또는 문자열 목록).

adapter의 LoRA 레이어를 기반 모델에서 삭제합니다.

예:

```py
from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_names="cinematic"
)
pipeline.unet.delete_adapters("cinematic")
```

#### disable_adapters[[diffusers.loaders.PeftAdapterMixin.disable_adapters]]

```python
disable_adapters()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/peft.py#L604)

모델에 연결된 모든 어댑터를 비활성화하고 기본 모델만으로 추론하도록 전환합니다.

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

#### disable_lora[[diffusers.loaders.PeftAdapterMixin.disable_lora]]

```python
disable_lora()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/peft.py#L726)

기저 모델의 활성 LoRA 레이어를 비활성화합니다.

예:

```py
from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_name="cinematic"
)
pipeline.unet.disable_lora()
```

#### enable_adapters[[diffusers.loaders.PeftAdapterMixin.enable_adapters]]

```python
enable_adapters()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/peft.py#L626)

모델에 연결된 어댑터를 활성화합니다. 모델은 `self.active_adapters()`를 사용하여 활성화할 어댑터 목록을 가져옵니다.

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

#### enable_lora[[diffusers.loaders.PeftAdapterMixin.enable_lora]]

```python
enable_lora()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/peft.py#L749)

기저 모델의 활성 LoRA 레이어를 활성화합니다.

예:

```py
from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_name="cinematic"
)
pipeline.unet.enable_lora()
```

#### enable_lora_hotswap[[diffusers.loaders.PeftAdapterMixin.enable_lora_hotswap]]

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

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/peft.py#L810)

**매개변수:**

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

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

LoRA 어댑터의 핫스왑을 가능하게 합니다.

…

#### load_lora_adapter[[diffusers.loaders.PeftAdapterMixin.load_lora_adapter]]

```python
load_lora_adapter(pretrained_model_name_or_path_or_dict, prefix = 'transformer', hotswap: bool = False, **kwargs)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/peft.py#L84)

**매개변수:**

pretrained_model_name_or_path_or_dict (`str` 또는 `os.PathLike` 또는 `dict`) : 다음 중 하나일 수 있습니다: - Hub에 호스팅된 사전 학습 모델의 *model id*(예: `google/ddpm-celebahq-256`) 문자열. - [ModelMixin.save_pretrained()](/docs/diffusers/main/ko/api/models/overview#diffusers.ModelMixin.save_pretrained)로 저장된 모델 가중치를 포함하는 *디렉터리* 경로(예: `./my_model_directory`). - [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).

prefix (`str`, *선택 사항*) : state dict를 필터링할 접두사.

cache_dir (`str | os.PathLike`, *선택 사항*) : 표준 캐시를 사용하지 않을 경우, 다운로드된 사전 학습 모델 구성이 캐시되는 디렉터리의 경로입니다.

force_download (`bool`, *선택 사항*, 기본값 `False`) : 캐시된 버전이 존재하더라도 모델 가중치 및 구성 파일의 (재)다운로드를 강제할지 여부.

proxies (`dict[str, str]`, *선택 사항*) : 프로토콜 또는 엔드포인트별로 사용할 프록시 서버의 사전입니다. 예를 들어, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`와 같습니다. 각 요청에 프록시가 사용됩니다.

local_files_only (`bool`, *선택 사항*, 기본값 `False`) : 로컬 모델 가중치와 구성 파일만 로드할지 여부를 지정합니다. `True`로 설정하면 Hub에서 모델을 다운로드하지 않습니다.

token (`str` 또는 *bool*, *선택 사항*) : 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다. `True`인 경우, `diffusers-cli login`에서 생성된 토큰(`~/.huggingface`에 저장됨)이 사용됩니다.

revision (`str`, *선택 사항*, 기본값 `"main"`) : 사용할 특정 모델 버전입니다. Git에서 허용하는 브랜치 이름, 태그 이름, 커밋 ID 또는 기타 식별자일 수 있습니다.

subfolder (`str`, *선택 사항*, 기본값 `""`) : Hub 또는 로컬의 더 큰 모델 저장소 내에서 모델 파일의 서브폴더 위치입니다.

network_alphas (`dict[str, float]`) : 안정된 학습과 언더플로우 방지를 위해 사용되는 네트워크 알파 값입니다. 이 값은 kohya-ss 트레이너 스크립트의 `--network_alpha` 옵션과 동일한 의미를 가집니다. [이 링크](https://github.com/darkstorm2150/sd-scripts/blob/main/docs/train_network_README-en.md#execute-learning)를 참조하세요.

low_cpu_mem_usage (`bool`, *선택 사항*) : 무작위 가중치를 초기화하지 않고 사전 학습된 LoRA 가중치만 로드하여 모델 로딩 속도를 높입니다.

hotswap : (`bool`, *선택 사항*) 기본값은 `False`입니다. 기존 (LoRA) 어댑터를 새로 로드한 어댑터로 제자리에서 교체할지 여부입니다. 즉, 추가 어댑터를 로드하는 대신 기존 어댑터의 가중치를 새 어댑터의 가중치로 대체합니다. 이는 더 빠르고 메모리 효율적일 수 있습니다. 그러나 핫스왑의 주요 이점은 모델이 torch.compile로 컴파일된 경우, 새 어댑터를 로드할 때 모델의 재컴파일이 필요하지 않다는 점입니다. 핫스왑을 사용할 때 전달하는 `adapter_name`은 이미 로드된 어댑터의 이름이어야 합니다. 새 어댑터와 기존 어댑터의 랭크와/또는 LoRA 알파(즉, 스케일링)가 다른 경우, 어댑터를 로드하기 전에 추가 메서드를 호출해야 합니다: ```py pipeline = ...  # load diffusers pipeline max_rank = ...  # the highest rank among all LoRAs that you want to load # call *before* compiling and loading the LoRA adapter pipeline.enable_lora_hotswap(target_rank=max_rank) pipeline.load_lora_weights(file_name) # optionally compile the model now ``` 텍스트 인코더의 어댑터 핫스왑은 아직 지원되지 않습니다. 이 기법에는 몇 가지 추가 제한 사항이 있으며, 여기에서 문서화되어 있습니다: https://huggingface.co/docs/peft/main/en/package_reference/hotswap

metadata : LoRA 어댑터 메타데이터. 제공된 경우, state dict를 통해 추론된 메타데이터는 `LoraConfig` 초기화에 사용되지 않습니다.

LoRA 어댑터를 기본 모델에 로드합니다.

#### save_lora_adapter[[diffusers.loaders.PeftAdapterMixin.save_lora_adapter]]

```python
save_lora_adapter(save_directory, adapter_name: str = 'default', upcast_before_saving: bool = False, safe_serialization: bool = True, weight_name: str | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/peft.py#L393)

**매개변수:**

save_directory (`str` 또는 `os.PathLike`) : LoRA 파라미터를 저장할 디렉터리입니다. 존재하지 않으면 생성됩니다.

adapter_name : (`str`, 기본값 "default"): 직렬화할 어댑터의 이름입니다. 기본 모델에 여러 개의 어댑터가 로드된 경우 유용합니다.

upcast_before_saving (`bool`, 기본값 `False`) : 직렬화 전에 기본 모델을 `torch.float32`로 변환할지 여부.

safe_serialization (`bool`, *선택 사항*, 기본값 `True`) : `safetensors` 또는 `pickle`를 사용한 전통적인 PyTorch 방식으로 모델을 저장할지 여부.

weight_name : (`str`, *선택 사항*, 기본값 `None`): state dict를 직렬화할 파일의 이름.

기저 모델에 해당하는 LoRA 매개변수를 저장합니다.

#### set_adapter[[diffusers.loaders.PeftAdapterMixin.set_adapter]]

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

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/peft.py#L555)

**매개변수:**

adapter_name (str | list[str])) : 설정할 어댑터 목록 또는 단일 어댑터인 경우의 어댑터 이름.

모델이 해당 어댑터만 사용하도록 강제하여 특정 어댑터를 설정하고, 다른 어댑터는 비활성화합니다.

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

#### set_adapters[[diffusers.loaders.PeftAdapterMixin.set_adapters]]

```python
set_adapters(adapter_names: list[str] | str, weights: float | dict | list[float] | list[dict] | list[None] | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/loaders/peft.py#L461)

**매개변수:**

adapter_names (`list[str]` 또는 `str`) : 사용할 어댑터의 이름들.

weights (`Union[List[float], float]`, *선택 사항*) : UNet과 함께 사용할 어댑터 가중치입니다. `None`인 경우 모든 어댑터의 가중치는 `1.0`으로 설정됩니다.

확산 네트워크(예: unet, transformer 등)에서 사용할 현재 활성 어댑터를 설정합니다.

예:

```py
from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_name="cinematic"
)
pipeline.load_lora_weights("nerijs/pixel-art-xl", weight_name="pixel-art-xl.safetensors", adapter_name="pixel")
pipeline.unet.set_adapters(["cinematic", "pixel"], weights=[0.5, 0.5])
```