DiffusionPipeline

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

이 가이드에서는 DiffusionPipeline를 로드하는 방법을 보여줍니다.

파이프라인 로드

DiffusionPipeline는 model_index.json 파일을 스캔하여 클래스 이름을 확인하고, QwenImagePipeline과 같은 모델의 파이프라인 하위 클래스 인스턴스를 자동으로 선택하여 반환하는 기본 파이프라인 클래스입니다.

from_pretrained()에 모델 ID를 전달하여 파이프라인을 로드합니다.

import torch
from diffusers import DiffusionPipeline

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

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

pipeline 하위 클래스	작업
QwenImagePipeline	텍스트-이미지
QwenImageImg2ImgPipeline	이미지-이미지
QwenImageInpaintPipeline	인페인팅

모델 ID를 from_pretrained()에 전달하여 서브클래스를 직접 사용할 수 있습니다.

import torch
from diffusers import QwenImagePipeline

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

단일 파일 모델의 로드 방법을 배우려면 Single file format 문서를 참조하세요.

로컬 파이프라인

Pipelines는 로컬에서도 실행할 수 있습니다. snapshot_download를 사용하여 모델 저장소를 다운로드하세요.

from huggingface_hub import snapshot_download

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

그 경로를 from_pretrained()에 전달하여 로드합니다.

import torch
from diffusers import QwenImagePipeline

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

로컬 경로를 감지하면 from_pretrained() 메서드는 Hub에서 파일을 다운로드하지 않습니다. 하지만 이는 모델에 적용된 업데이트도 다운로드하고 캐시에 저장하지 않는다는 뜻이기도 합니다.

Pipeline 데이터 유형

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

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

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)

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

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()에서 max_memory 인수를 사용하여 각 디바이스에서 사용할 최대 메모리 양을 할당합니다. 기본적으로 Diffusers는 사용 가능한 최대 양을 사용합니다.

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에 액세스하고 이를 확인할 수 있습니다.

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

reset_device_map() 메서드를 사용하여 파이프라인의 device_map을 초기화합니다. .to(), enable_sequential_cpu_offload(), enable_model_cpu_offload()와 같은 메서드를 사용하려면 이 작업이 필요합니다.

pipeline.reset_device_map()

병렬 로딩

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

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

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

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는 유연하며 다른 모델이나 스케줄러를 로드하는 것을 지원합니다. 생성 속도나 품질을 최적화하기 위해 다양한 스케줄러를 실험해 볼 수 있고, 더 성능이 좋은 모델로 교체할 수도 있습니다.

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

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() 메서드를 사용하면 모델을 매번 다시 로드하는 대신 재사용할 수 있습니다. 이를 통해 메모리 사용량 증가 없이 여러 파이프라인을 사용할 수 있습니다.

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

The example below loads a pipeline and then loads a second pipeline with from_pipe() to use perturbed-attention guidance (PAG) to improve generation quality.

DiffusionPipeline은 PAG를 지원하지 않으므로 AutoPipelineForText2Image를 사용하세요. 자세한 내용은 AutoPipeline 문서를 참고하세요.

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를 활성화합니다. 두 번째 파이프라인은 첫 번째 파이프라인과 모델 가중치를 공유하므로 동일한 양의 메모리를 사용합니다.

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

from_pipe()로 생성된 파이프라인은 동일한 모델과 state를 공유합니다. 하나의 파이프라인에서 모델의 상태를 수정하면 동일한 모델을 공유하는 다른 모든 파이프라인에 영향을 미칩니다.

Some methods may not work correctly on pipelines created with from_pipe(). For example, 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는 디노이징 알고리즘의 교체 및 구성을 다룹니다.
모델 형식은 GGUF, 단일 파일 체크포인트 및 기타 가중치 레이아웃을 다룹니다.
메모리 사용량 줄이기는 오프로딩 및 기타 메모리 도구를 다룹니다.
LoRA는 파이프라인에 어댑터를 로드하는 방법을 다룹니다.
Legacy checkpoints는 이전 버전의 Stable Diffusion 체크포인트에 대한 안전 검사기를 다룹니다.

Update on GitHub