# DreamLite

DreamLite는 ByteDance의 텍스트-이미지 생성 및 이미지 편집 모델입니다. 커스텀 2D U-Net인 `DreamLiteUNetModel`을 `Qwen3-VL` 멀티모달 인코더와 결합하여 프롬프트/이미지 지시 인코더로 사용하며, 빠른 잠재 공간 인코딩/디코딩을 위해 `AutoencoderTiny`(TAESD 스타일) VAE를 사용합니다.

두 개의 파이프라인이 노출됩니다:

| Pipeline | 모드 | CFG | 사용 사례 |
|---|---|---|---|
| [DreamLitePipeline](/docs/diffusers/main/ko/api/pipelines/dreamlite#diffusers.DreamLitePipeline) | 텍스트-이미지 **및** 이미지 편집(`image`가 `None`인지에 따라 자동 선택) | 3-branch dual CFG (텍스트 브랜치에 `guidance_scale`, 이미지 브랜치에 `image_guidance_scale`, InstructPix2Pix 방식) | 최고의 품질 |
| [DreamLiteMobilePipeline](/docs/diffusers/main/ko/api/pipelines/dreamlite#diffusers.DreamLiteMobilePipeline) | 텍스트-이미지 **및** 이미지 편집(`image`가 `None`인지에 따라 자동 선택) | 없음 — 증류된 단일 UNet 포워드, 단계당 | 온디바이스 / 낮은 지연 시간 |

공식 체크포인트:

* 기본 모델: [carlofkl/DreamLite-base](https://huggingface.co/carlofkl/DreamLite-base)
* 디스틸된 모바일 모델: [carlofkl/DreamLite-mobile](https://huggingface.co/carlofkl/DreamLite-mobile)

> [!TIP]
> 두 파이프라인 모두 `image` 인자가 제공되었는지에 따라 텍스트-이미지 생성 모드와 이미지 편집 모드를 자동으로 감지합니다. 별도의 `Img2Img` 클래스는 없습니다.

> [!TIP]
> 이미지 편집을 위해 입력 이미지를 로드할 때는 `PIL.Image.open(...)`보다 `diffusers.utils.load_image(...)`를 사용하는 것이 좋습니다. `load_image`는 RGB 변환을 강제하고 EXIF 방향을 적용하며, 이 두 가지는 파이프라인이 전제로 합니다. RGBA / 팔레트 / EXIF 회전된 소스에 대해 단순히 `Image.open`을 사용하면 잠재적 조건이 조용히 달라져 출력 품질이 저하됩니다.

## 텍스트-이미지 (Base)

```python
import torch
from diffusers import DreamLitePipeline

pipe = DreamLitePipeline.from_pretrained("carlofkl/DreamLite-base", revision="diffusers", dtype=torch.bfloat16)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

image = pipe(
    prompt="a dog running on the grass",
    negative_prompt="",
    height=1024,
    width=1024,
    num_inference_steps=28,
    generator=torch.Generator("cpu").manual_seed(42),
).images[0]
image.save("dreamlite_t2i.png")
```

## 이미지 편집 (Base)

`image`를 전달하여 편집 모드로 진입합니다. 여기서는 `guidance_scale`(텍스트 브랜치)과 `image_guidance_scale`(이미지 브랜치)이 모두 활성화됩니다.

```python
import torch
from diffusers import DreamLitePipeline
from diffusers.utils import load_image

pipe = DreamLitePipeline.from_pretrained("carlofkl/DreamLite-base", revision="diffusers", dtype=torch.bfloat16)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

source = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cat.png")

image = pipe(
    prompt="turn the cat into a corgi",
    image=source,
    height=1024,
    width=1024,
    num_inference_steps=28,
    generator=torch.Generator("cpu").manual_seed(42),
).images[0]
image.save("dreamlite_edit.png")
```

## 텍스트-이미지 (모바일)

모바일 파이프라인은 증류(distilled)되어 CFG를 완전히 건너뛰며, 각 단계마다 UNet 포워드를 한 번만 실행합니다. 동일한 `prompt` / `height` / `width` / `num_inference_steps` 인수를 받지만, `guidance_scale`와 `image_guidance_scale`이 전달된 경우 **무시**합니다(경고가 기록됩니다).

```python
import torch
from diffusers import DreamLiteMobilePipeline

pipe = DreamLiteMobilePipeline.from_pretrained("carlofkl/DreamLite-mobile", revision="diffusers", dtype=torch.bfloat16)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

image = pipe(
    prompt="a dog running on the grass",
    height=1024,
    width=1024,
    num_inference_steps=4,
    generator=torch.Generator("cpu").manual_seed(42),
).images[0]
image.save("dreamlite_mobile_t2i.png")
```

## 이미지 편집 (모바일)

```python
import torch
from diffusers import DreamLiteMobilePipeline
from diffusers.utils import load_image

pipe = DreamLiteMobilePipeline.from_pretrained("carlofkl/DreamLite-mobile", revision="diffusers", dtype=torch.bfloat16)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

source = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cat.png")

image = pipe(
    prompt="turn the cat into a corgi",
    image=source,
    height=1024,
    width=1024,
    num_inference_steps=4,
    generator=torch.Generator("cpu").manual_seed(42),
).images[0]
image.save("dreamlite_mobile_edit.png")
```

## 참고 및 제한 사항

* 두 파이프라인 모두 내부적으로 `batch_size = 1`을 강제합니다. `num_images_per_prompt`은 병렬 배치 처리가 아니라 동일한 프롬프트에서 몇 개의 샘플을 추출할지를 제어합니다.
* 프롬프트 인코더는 멀티모달 모델인 `Qwen3-VL`입니다. 따라서 전체 파이프라인을 로드하려면 U-Net과 Qwen3-VL 텍스트 인코더 모두에 충분한 GPU 메모리가 필요합니다(기본 릴리스 기준, bf16에서 약 4 GB + 약 0.7 GB).
* VAE는 `AutoencoderTiny`이며 `encoder_block_out_channels`을 노출합니다. `vae_scale_factor`는 파이프라인 초기화 시점에 이 값에서 파생됩니다.

## DreamLitePipeline[[diffusers.DreamLitePipeline]]

#### diffusers.DreamLitePipeline[[diffusers.DreamLitePipeline]]

```python
diffusers.DreamLitePipeline(text_encoder: Qwen3VLForConditionalGeneration, tokenizer: AutoTokenizer, processor: Qwen3VLProcessor, vae: AutoencoderTiny, unet: DreamLiteUNetModel, scheduler: FlowMatchEulerDiscreteScheduler)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/dreamlite/pipeline_dreamlite.py#L155)

DreamLite 파이프라인은 텍스트-이미지 생성 및 지시 기반 이미지 편집을 위한 것입니다.

동일한 파이프라인이 두 가지 모드를 모두 지원합니다. 동작 모드는 입력 값에서 자동으로 감지됩니다:

- `image is None` -> 텍스트-투-이미지 (텍스트에 단일 CFG 적용).
- `image is not None` -> 이미지-투-이미지 / 지시 편집 (이중 CFG: 텍스트 + 이미지).

Components: text_encoder ([*~transformers.Qwen3VLForConditionalGeneration*]): 조건부 임베딩을 생성하는 데 사용되는 멀티모달 텍스트/비전 인코더. tokenizer ([*~transformers.AutoTokenizer*]): 텍스트 전용(generate) 모드용 토크나이저. processor ([*~transformers.Qwen3VLProcessor*]): 편집 모드(텍스트 + 이미지 템플릿)용 멀티모달 프로세서. vae ([*~diffusers.AutoencoderTiny*]: 모바일 친화적인 소형 VAE로, 잠재 공간 인코딩/디코딩에 사용됩니다. unet ([*~diffusers.DreamLiteUNetModel*]): DreamLite UNet (GQA + qk_norm + depthwise-separable convs). scheduler ([*~diffusers.FlowMatchEulerDiscreteScheduler*]): 동적 시프트를 지원하는 Flow-matching Euler 스케줄러.

참고: `batch_size`는 현재 `1`로 고정되어 있으며, `num_images_per_prompt`는 지원됩니다.

#### __호출__[[diffusers.DreamLitePipeline.__call__]]

```python
__call__(prompt: typing.Optional[str] = None, negative_prompt: typing.Optional[str] = None, image: typing.Optional[PIL.Image.Image] = None, height: typing.Optional[int] = None, width: typing.Optional[int] = None, guidance_scale: float = 3.5, image_guidance_scale: float = 1.5, num_inference_steps: int = 30, sigmas: typing.Optional[typing.List[float]] = None, num_images_per_prompt: typing.Optional[int] = 1, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, output_type: typing.Optional[str] = 'pil', return_dict: bool = True, max_sequence_length: int = 200, text_pad_embedding: typing.Optional[torch.Tensor] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/dreamlite/pipeline_dreamlite.py#L388)

**매개변수:**

prompt : 텍스트 프롬프트.

negative_prompt : Negative text prompt (기본값은 빈 문자열).

image : Optional input image. If provided, the pipeline runs in **edit / image-to-image** mode with dual classifier-free guidance; otherwise it runs in **text-to-image** mode.

height : 출력 해상도(높이). 기본값은 `default_sample_size * vae_scale_factor`(1024)입니다. T2I와 I2I 모두 동일한 기본값이 적용되며, 명시적인 값을 전달하여 오버라이드할 수 있습니다.

width : 출력 해상도(너비). 기본값은 `default_sample_size * vae_scale_factor`(1024)입니다. T2I와 I2I 모두 동일한 기본값이 적용되며, 명시적인 값을 전달하여 오버라이드할 수 있습니다.

guidance_scale : 텍스트 브랜치의 CFG scale (모든 모드).

image_guidance_scale : 이미지 브랜치에 추가되는 CFG 스케일(편집 모드 전용).

num_inference_steps : 노이즈 제거 단계 수.

sigmas : 선택 사항인 명시적 FlowMatch 시그마; 기본값은 균등한 linspace입니다.

num_images_per_prompt : 프롬프트당 출력 이미지 수 (참고: `batch_size`는 1로 고정됩니다).

generator : 랜덤 생성기.

output_type : `"pil"`, `"np"`, `"pt"` 또는 `"latent"`.

return_dict : True인 경우 [DreamLitePipelineOutput](/docs/diffusers/main/ko/api/pipelines/dreamlite#diffusers.DreamLitePipelineOutput)를 반환하고, 그렇지 않으면 튜플 `(images,)`을 반환합니다.

max_sequence_length : 채팅 템플릿 접두사를 제거한 후 유지되는 사용자 프롬프트 토큰의 최대 수. `generate` 모드에만 적용됩니다(`edit` 모드는 멀티모달 프로세서의 네이티브 패딩을 사용).

text_pad_embedding : 선택 사항. 마스킹된 위치를 위한 학습된 패드 임베딩입니다.

**반환값:**

[DreamLitePipelineOutput](/docs/diffusers/main/ko/api/pipelines/dreamlite#diffusers.DreamLitePipelineOutput) 또는 `tuple`.

DreamLite 파이프라인을 실행합니다.

## DreamLiteMobilePipeline[[diffusers.DreamLiteMobilePipeline]]

#### diffusers.DreamLiteMobilePipeline[[diffusers.DreamLiteMobilePipeline]]

```python
diffusers.DreamLiteMobilePipeline(text_encoder: Qwen3VLForConditionalGeneration, tokenizer: AutoTokenizer, processor: Qwen3VLProcessor, vae: AutoencoderTiny, unet: DreamLiteUNetModel, scheduler: FlowMatchEulerDiscreteScheduler)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/dreamlite/pipeline_dreamlite_mobile.py#L156)

DreamLite **Mobile** 파이프라인: [DreamLitePipeline](/docs/diffusers/main/ko/api/pipelines/dreamlite#diffusers.DreamLitePipeline)의 증류된, classifier-free-guidance가 없는 변형으로, 빠른 few-step 추론(기본 4단계)을 지원합니다.

작동 모드는 입력 값에서 자동 감지됩니다(기본 파이프라인과 동일):

- `image is None` -> 텍스트-투-이미지.
- `image is not None` -> 이미지-투-이미지 / 지시 편집.

Classifier-free guidance가 **디스틸링되어 제거**되었으므로, `guidance_scale`와 `image_guidance_scale`는 [DreamLitePipeline](/docs/diffusers/main/ko/api/pipelines/dreamlite#diffusers.DreamLitePipeline)과의 API 호환성을 위해 허용되지만 디노이징 루프에서는 무시됩니다. `negative_prompt`는 의도적으로 존재하지 않습니다.

Components (기본 파이프라인과 동일): text_encoder ([*~transformers.Qwen3VLForConditionalGeneration*]): 멀티모달 텍스트/비전 인코더. tokenizer ([*~transformers.AutoTokenizer*]): 텍스트 전용(generate) 모드용 토크나이저. processor ([*~transformers.Qwen3VLProcessor*]): 편집 모드용 멀티모달 프로세서. vae ([*~diffusers.AutoencoderTiny*]): 모바일 친화적인 소형 VAE. unet ([*~diffusers.DreamLiteUNetModel*]): DreamLite UNet. scheduler ([*~diffusers.FlowMatchEulerDiscreteScheduler*]): 동적 시프트를 지원하는 플로우 매칭 오일러 스케줄러.

참고: `batch_size`는 현재 `1`로 고정되어 있으며, `num_images_per_prompt`는 지원됩니다.

#### __호출__[[diffusers.DreamLiteMobilePipeline.__call__]]

```python
__call__(prompt: typing.Union[str, typing.List[str]] = None, image: typing.Optional[PIL.Image.Image] = None, height: typing.Optional[int] = None, width: typing.Optional[int] = None, num_inference_steps: int = 4, guidance_scale: typing.Optional[float] = None, image_guidance_scale: typing.Optional[float] = None, sigmas: typing.Optional[typing.List[float]] = None, num_images_per_prompt: typing.Optional[int] = 1, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, output_type: typing.Optional[str] = 'pil', return_dict: bool = True, max_sequence_length: int = 200, text_pad_embedding: typing.Optional[torch.Tensor] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/dreamlite/pipeline_dreamlite_mobile.py#L384)

**매개변수:**

prompt : 텍스트 프롬프트.

image : 선택 입력 이미지. 제공되면 **edit / image-to-image** 모드로 실행되며, 그렇지 않으면 **text-to-image** 모드로 실행됩니다.

height : 출력 해상도(높이). 기본값은 `default_sample_size * vae_scale_factor`(1024)입니다.

width : 출력 해상도(너비). 기본값은 `default_sample_size * vae_scale_factor`(1024)입니다.

num_inference_steps : 노이즈 제거 단계 수. 기본값은 **4**(디스틸드)입니다.

guidance_scale : [DreamLitePipeline](/docs/diffusers/main/ko/api/pipelines/dreamlite#diffusers.DreamLitePipeline)와의 API 호환성을 위해 허용되었습니다. CFG가 증류되어 **무시**됩니다.

image_guidance_scale : [DreamLitePipeline](/docs/diffusers/main/ko/api/pipelines/dreamlite#diffusers.DreamLitePipeline)와의 API 호환성을 위해 허용되었습니다. CFG가 증류되어 **무시**됩니다.

sigmas : 선택 사항인 명시적 FlowMatch 시그마; 기본값은 균등한 linspace입니다.

num_images_per_prompt : 프롬프트당 출력 이미지 수 (참고: `batch_size`는 1로 고정됩니다).

generator : 랜덤 생성기.

output_type : `"pil"`, `"np"`, `"pt"` 또는 `"latent"`.

return_dict : True인 경우 [DreamLitePipelineOutput](/docs/diffusers/main/ko/api/pipelines/dreamlite#diffusers.DreamLitePipelineOutput)를 반환하고, 그렇지 않으면 `(images,)`를 반환합니다.

max_sequence_length : 채팅 템플릿 접두사를 제거한 후 유지되는 사용자 프롬프트 토큰의 최대 수. `generate` 모드에만 적용됩니다(`edit` 모드는 멀티모달 프로세서의 네이티브 패딩을 사용).

text_pad_embedding : 선택 사항. 마스킹된 위치를 위한 학습된 패드 임베딩입니다.

**반환값:**

[DreamLitePipelineOutput](/docs/diffusers/main/ko/api/pipelines/dreamlite#diffusers.DreamLitePipelineOutput) 또는 `tuple`.

디스틸된 DreamLite Mobile 파이프라인을 실행합니다.

## DreamLitePipelineOutput[[diffusers.DreamLitePipelineOutput]]

#### diffusers.DreamLitePipelineOutput[[diffusers.DreamLitePipelineOutput]]

```python
diffusers.DreamLitePipelineOutput(images: typing.Union[typing.List[PIL.Image.Image], numpy.ndarray])
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/dreamlite/pipeline_output.py#L25)

**매개변수:**

images (`List[PIL.Image.Image]` 또는 `np.ndarray`) : 길이가 `batch_size`인 denoised PIL 이미지 목록 또는 shape이 `(batch_size, height, width, num_channels)`인 NumPy 배열입니다. PIL 이미지 또는 NumPy 배열은 diffusion pipeline의 denoised 이미지를 나타냅니다.

DreamLite 파이프라인의 출력 클래스입니다.