# DiffusionPipeline

Diffusion 모델은 UNet 또는 diffusion transformer(DiT), text encoder, variational autoencoder(VAE), scheduler와 같은 여러 구성 요소로 이루어져 있습니다. [DiffusionPipeline](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline)은 이러한 모든 구성 요소를 유연하게 수정할 수 있는 유연성을 유지하면서 하나의 사용하기 쉬운 API로 묶어 줍니다.

이 가이드에서는 [DiffusionPipeline](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline)를 로드하는 방법을 보여줍니다.

## 파이프라인 로드

[DiffusionPipeline](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline)는 `model_index.json` 파일을 스캔하여 클래스 이름을 확인하고, [QwenImagePipeline](/docs/diffusers/v0.43.0/ko/api/pipelines/qwenimage#diffusers.QwenImagePipeline)과 같은 모델 파이프라인 하위 클래스의 인스턴스를 자동으로 선택하여 반환하는 기본 파이프라인 클래스입니다.

[from_pretrained()](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained)에 모델 ID를 전달하여 파이프라인을 로드합니다.

```py
import torch
from diffusers import DiffusionPipeline

pipeline = DiffusionPipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

모든 모델은 [DiffusionPipeline](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline)를 상속하는 특정 파이프라인 하위 클래스를 가집니다. 하위 클래스는 일반적으로 좁은 범위에 초점을 맞추며 작업별로 특화되어 있습니다. 예를 들어 아래 표를 참고하세요.

| pipeline 하위 클래스 | 작업 |
|---|---|
| [QwenImagePipeline](/docs/diffusers/v0.43.0/ko/api/pipelines/qwenimage#diffusers.QwenImagePipeline) | 텍스트-이미지 |
| [QwenImageImg2ImgPipeline](/docs/diffusers/v0.43.0/ko/api/pipelines/qwenimage#diffusers.QwenImageImg2ImgPipeline) | 이미지-이미지 |
| [QwenImageInpaintPipeline](/docs/diffusers/v0.43.0/ko/api/pipelines/qwenimage#diffusers.QwenImageInpaintPipeline) | 인페인팅 |

모델 ID를 [from_pretrained()](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained)에 전달하여 서브클래스를 직접 사용할 수 있습니다.

```py
import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

> [!TIP]
> 단일 파일 모델의 로드 방법을 배우려면 [Single file format](./other-formats#single-file-format) 문서를 참조하세요.

### 로컬 파이프라인

Pipelines는 로컬에서도 실행할 수 있습니다. [snapshot_download](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/file_download#huggingface_hub.snapshot_download)를 사용하여 모델 저장소를 다운로드하세요.

```py
from huggingface_hub import snapshot_download

local_dir = snapshot_download(repo_id="Qwen/Qwen-Image")
```

그 경로를 [from_pretrained()](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained)에 전달하여 로드합니다.

```py
import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  local_dir, dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

로컬 경로를 감지하면 [from_pretrained()](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) 메서드는 Hub에서 파일을 다운로드하지 않습니다. 하지만 이는 모델에 적용된 업데이트도 다운로드하고 캐시에 저장하지 않는다는 뜻이기도 합니다.

## Pipeline 데이터 유형

`dtype` 인수를 [from_pretrained()](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained)에 전달하여 특정 데이터 타입으로 모델을 로드합니다. 이를 통해 서로 다른 정밀도로 다양한 모델을 로드할 수 있습니다. 예를 들어, 대규모 transformer 모델을 반정밀도로 로드하면 필요한 메모리 용량을 줄일 수 있습니다.

각 모델의 데이터 유형을 사전으로 `dtype`에 전달합니다. `default` 키를 사용하여 기본 데이터 유형을 설정합니다. 사전에 모델이 없고 `default`가 제공되지 않으면, 해당 모델은 전체 정밀도(`torch.float32`)로 로드됩니다.

```py
import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image",
  dtype={"transformer": torch.bfloat16, "default": torch.float16},
)
print(pipeline.transformer.dtype, pipeline.vae.dtype)
```

모든 모델을 동일한 데이터 타입으로 로드하는 경우 사전 사용이 필요하지 않습니다.

```py
import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16
)
print(pipeline.transformer.dtype, pipeline.vae.dtype)
```

## 장치 배치

`device_map` 인수는 파이프라인을 장치에 배치합니다. 런타임에서 Diffusers는 `"balanced"`, `"cpu"`, 그리고 현재 머신의 가속기 문자열(일반적으로 `"cuda"`, `"mps"` 또는 `"xpu"`)을 허용합니다.

| parameter | 설명 |
|---|---|
| accelerator 문자열 | 해당 파이프라인을 해당 장치에 배치합니다. `"cuda"`, `"mps"`, 또는 `"xpu"`와 같이 머신이 지원하는 가속기를 전달하세요. |
| `"balanced"` | Spreads는 파이프라인 구성 요소를 가시적인 GPU에 분산 배치합니다. 장치별 상한이 필요할 때는 `max_memory`와 함께 사용하세요. |
| `"cpu"` | 파이프라인을 CPU에 배치합니다. |

[from_pretrained()](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained)에서 `max_memory` 인수를 사용하여 각 디바이스에서 사용할 최대 메모리 양을 할당합니다. 기본적으로 Diffusers는 사용 가능한 최대 양을 사용합니다.

```py
import torch
from diffusers import DiffusionPipeline

max_memory = {0: "16GB", 1: "16GB"}
pipeline = DiffusionPipeline.from_pretrained(
  "Qwen/Qwen-Image",
  dtype=torch.bfloat16,
  device_map="balanced",
  max_memory=max_memory,
)
```

`hf_device_map` 속성을 사용하면 `device_map`에 액세스하고 이를 확인할 수 있습니다.

```py
print(pipeline.hf_device_map)
# {'transformer': 1, 'vae': 1, 'text_encoder': 0}
```

[reset_device_map()](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline.reset_device_map) 메서드를 사용하여 파이프라인의 `device_map`을 초기화합니다. `.to()`, [enable_sequential_cpu_offload()](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline.enable_sequential_cpu_offload), [enable_model_cpu_offload()](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline.enable_model_cpu_offload)와 같은 메서드를 사용하려면 이 작업이 필요합니다.

```py
pipeline.reset_device_map()
```

## 병렬 로딩

대형 모델은 로드하기 쉽게 [샤드](../optimization/memory#sharded-checkpoints)된 더 작은 파일로 나뉘어 있는 경우가 많습니다. Diffusers는 로딩 과정을 가속화하기 위해 샤드를 병렬로 로드하는 것을 지원합니다.

`HF_ENABLE_PARALLEL_LOADING`를 `"YES"`로 설정하여 샤드의 병렬 로딩을 활성화합니다.

`device_map` 인수는 모델 크기에 기반하여 대용량의 메모리를 사전에 할당하도록 `"cuda"`로 설정해야 합니다. 이렇게 하면 메모리 할당기의 워밍업 과정에서 나중에 발생할 수 있는 많은 수의 작은 할당 호출을 피할 수 있어 모델 로딩 시간이 크게 줄어듭니다.

```py
import os
import torch
from diffusers import DiffusionPipeline

os.environ["HF_ENABLE_PARALLEL_LOADING"] = "YES"

pipeline = DiffusionPipeline.from_pretrained(
  "Wan-AI/Wan2.2-I2V-A14B-Diffusers", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

## 파이프라인에서 모델 교체

[DiffusionPipeline](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline)는 유연하며 다른 모델이나 스케줄러를 로드하는 것을 지원합니다. 생성 속도나 품질을 최적화하기 위해 다양한 스케줄러를 실험해 볼 수 있고, 더 성능이 좋은 모델로 교체할 수도 있습니다.

VAE의 더 안정적인 버전을 사용하는 아래 예시를 확인해 보세요.

```py
import torch
from diffusers import DiffusionPipeline, AutoModel

vae = AutoModel.from_pretrained(
  "madebyollin/sdxl-vae-fp16-fix", dtype=torch.float16
)

pipeline = DiffusionPipeline.from_pretrained(
  "stabilityai/stable-diffusion-xl-base-1.0",
  vae=vae,
  dtype=torch.float16,
  device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

## 여러 파이프라인에서 모델 재사용

같은 모델을 사용하는 여러 파이프라인을 다룰 때, [from_pipe()](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline.from_pipe) 메서드를 사용하면 모델을 매번 다시 로드하는 대신 재사용할 수 있습니다. 이를 통해 메모리 사용량 증가 없이 여러 파이프라인을 사용할 수 있습니다.

메모리 사용량은 파이프라인의 개수와 무관하게 가장 높은 메모리 요구량을 가진 파이프라인에 의해 결정됩니다.

The example below loads a pipeline and then loads a second pipeline with [from_pipe()](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline.from_pipe) to use [perturbed-attention guidance (PAG)](../api/pipelines/pag) to improve generation quality.

> [!WARNING]
> [DiffusionPipeline](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline)은 PAG를 지원하지 않으므로 [AutoPipelineForText2Image](/docs/diffusers/v0.43.0/ko/api/pipelines/auto_pipeline#diffusers.AutoPipelineForText2Image)를 사용하세요. 자세한 내용은 [AutoPipeline](../tutorials/autopipeline) 문서를 참고하세요.

```py
import torch
from diffusers import AutoPipelineForText2Image

pipeline_sdxl = AutoPipelineForText2Image.from_pretrained(
  "stabilityai/stable-diffusion-xl-base-1.0", dtype=torch.float16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
image = pipeline_sdxl(prompt).images[0]
print(f"Max memory reserved: {torch.cuda.max_memory_allocated() / 1024**3:.2f} GB")
# Max memory reserved: 10.47 GB
```

두 번째 파이프라인에서 `enable_pag=True`를 설정하여 PAG를 활성화합니다. 두 번째 파이프라인은 첫 번째 파이프라인과 모델 가중치를 공유하므로 동일한 양의 메모리를 사용합니다.

```py
pipeline = AutoPipelineForText2Image.from_pipe(
  pipeline_sdxl, enable_pag=True
)
prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
image = pipeline(prompt).images[0]
print(f"Max memory reserved: {torch.cuda.max_memory_allocated() / 1024**3:.2f} GB")
# Max memory reserved: 10.47 GB
```

> [!WARNING]
> [from_pipe()](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline.from_pipe)로 생성된 파이프라인은 동일한 모델과 *state*를 공유합니다. 하나의 파이프라인에서 모델의 상태를 수정하면 동일한 모델을 공유하는 다른 모든 파이프라인에 영향을 미칩니다.

Some methods may not work correctly on pipelines created with [from_pipe()](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline.from_pipe). For example, [enable_model_cpu_offload()](/docs/diffusers/v0.43.0/ko/api/pipelines/overview#diffusers.DiffusionPipeline.enable_model_cpu_offload) relies on a unique model execution order, which may differ in the new pipeline. To ensure proper functionality, reapply these methods on the new pipeline.

## 다음 단계

pipeline가 로드되면 일반적으로 노이즈 제거 스케줄을 조정하거나, 가중치 형식을 변경하거나, 어댑터를 연결합니다.

- [Schedulers](./schedulers)는 디노이징 알고리즘의 교체 및 구성을 다룹니다.
- [모델 형식](./other-formats)은 GGUF, 단일 파일 체크포인트 및 기타 가중치 레이아웃을 다룹니다.
- [메모리 사용량 줄이기](../optimization/memory)는 오프로딩 및 기타 메모리 도구를 다룹니다.
- [LoRA](../tutorials/using_peft_for_inference)는 파이프라인에 어댑터를 로드하는 방법을 다룹니다.
- [Legacy checkpoints](./legacy_checkpoints#safety-checker)는 이전 버전의 Stable Diffusion 체크포인트에 대한 안전 검사기를 다룹니다.