Hugging Face's logo

Diffusers documentation

DreamLite

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

DreamLite

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

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

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

공식 체크포인트:

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

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

텍스트-이미지 (Base)

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(이미지 브랜치)이 모두 활성화됩니다.

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가 전달된 경우 무시합니다(경고가 기록됩니다).

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")

이미지 편집 (모바일)

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

< >

( text_encoder: Qwen3VLForConditionalGenerationtokenizer: AutoTokenizerprocessor: Qwen3VLProcessorvae: AutoencoderTinyunet: DreamLiteUNetModelscheduler: FlowMatchEulerDiscreteScheduler )

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]): 동적 시프트를 갖춘 플로우 매칭 오일러 스케줄러.

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

__call__

< >

( prompt: typing.Optional[str] = Nonenegative_prompt: typing.Optional[str] = Noneimage: typing.Optional[PIL.Image.Image] = Noneheight: typing.Optional[int] = Nonewidth: typing.Optional[int] = Noneguidance_scale: float = 3.5image_guidance_scale: float = 1.5num_inference_steps: int = 30sigmas: typing.Optional[typing.List[float]] = Nonenum_images_per_prompt: typing.Optional[int] = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Noneoutput_type: typing.Optional[str] = 'pil'return_dict: bool = Truemax_sequence_length: int = 200text_pad_embedding: typing.Optional[torch.Tensor] = None )

매개변수

  • 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 sigmas입니다. 기본값은 균등한 linspace입니다.
  • num_images_per_prompt — 프롬프트당 출력 이미지 수 (참고: batch_size는 1로 고정됩니다).
  • generator — 랜덤 생성기.
  • output_type — "pil", "np", "pt" 또는 "latent".
  • return_dict — True인 경우 DreamLitePipelineOutput를 반환하고, 그렇지 않으면 튜플 (images,)을 반환합니다.
  • max_sequence_length — 채팅 템플릿 접두사를 제거한 후 유지되는 사용자 프롬프트 토큰의 최대 수. generate 모드에만 적용됩니다(edit 모드는 멀티모달 프로세서의 네이티브 패딩을 사용).
  • text_pad_embedding — 마스킹된 위치를 위한 선택적 학습된 패드 임베딩.

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

DreamLiteMobilePipeline

class diffusers.DreamLiteMobilePipeline

< >

( text_encoder: Qwen3VLForConditionalGenerationtokenizer: AutoTokenizerprocessor: Qwen3VLProcessorvae: AutoencoderTinyunet: DreamLiteUNetModelscheduler: FlowMatchEulerDiscreteScheduler )

DreamLite Mobile 파이프라인: DreamLitePipeline의 증류된, classifier-free-guidance가 없는 변형으로, 빠른 few-step 추론(기본 4단계)을 지원합니다.

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

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

Classifier-free guidance가 디스틸링되어 제거되었으므로, guidance_scale와 image_guidance_scale는 DreamLitePipeline과의 API 호환성을 위해 허용되지만 디노이징 루프에서는 무시됩니다. negative_prompt는 의도적으로 포함되지 않았습니다.

컴포넌트(기본 파이프라인과 동일): text_encoder ([~transformers.Qwen3VLForConditionalGeneration]): 멀티모달 텍스트/비전 인코더. tokenizer ([~transformers.AutoTokenizer]): 텍스트 전용(generate) 모드용 토크나이저. processor ([~transformers.Qwen3VLProcessor]): 편집 모드용 멀티모달 프로세서. vae ([~diffusers.AutoencoderTiny]): 모바일에 적합한 소형 VAE. unet ([~diffusers.DreamLiteUNetModel]): DreamLite UNet. scheduler ([~diffusers.FlowMatchEulerDiscreteScheduler]): 동적 시프트를 지원하는 Flow-matching Euler 스케줄러.

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

__call__

< >

( prompt: typing.Union[str, typing.List[str]] = Noneimage: typing.Optional[PIL.Image.Image] = Noneheight: typing.Optional[int] = Nonewidth: typing.Optional[int] = Nonenum_inference_steps: int = 4guidance_scale: typing.Optional[float] = Noneimage_guidance_scale: typing.Optional[float] = Nonesigmas: typing.Optional[typing.List[float]] = Nonenum_images_per_prompt: typing.Optional[int] = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Noneoutput_type: typing.Optional[str] = 'pil'return_dict: bool = Truemax_sequence_length: int = 200text_pad_embedding: typing.Optional[torch.Tensor] = None )

매개변수

  • 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와의 API 호환성을 위해 허용되지만, CFG가 증류(distilled)되었기 때문에 무시됩니다.
  • image_guidance_scale — DreamLitePipeline와의 API 호환성을 위해 허용되지만, CFG가 증류(distilled)되었기 때문에 무시됩니다.
  • sigmas — 선택적 명시적 FlowMatch sigmas입니다. 기본값은 균등한 linspace입니다.
  • num_images_per_prompt — 프롬프트당 출력 이미지 수 (참고: batch_size는 1로 고정됩니다).
  • generator — 랜덤 생성기.
  • output_type — "pil", "np", "pt" 또는 "latent".
  • return_dict — True인 경우 DreamLitePipelineOutput를 반환하고, 그렇지 않으면 (images,)를 반환합니다.
  • max_sequence_length — 채팅 템플릿 접두사를 제거한 후 유지되는 사용자 프롬프트 토큰의 최대 수. generate 모드에만 적용됩니다(edit 모드는 멀티모달 프로세서의 네이티브 패딩을 사용).
  • text_pad_embedding — 마스킹된 위치를 위한 선택적 학습된 패드 임베딩.

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

DreamLitePipelineOutput

클래스 diffusers.DreamLitePipelineOutput

< >

( images: typing.Union[typing.List[PIL.Image.Image], numpy.ndarray] )

매개변수

  • images (List[PIL.Image.Image] 또는 np.ndarray) — batch_size 길이의 denoised PIL 이미지 목록 또는 (batch_size, height, width, num_channels) 형태의 NumPy 배열. PIL 이미지 또는 NumPy 배열은 diffusion 파이프라인의 denoised 이미지를 나타냅니다.

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

Update on GitHub

←DiT EasyAnimate→