# DreamLite

DreamLite là một mô hình tạo ảnh từ văn bản và chỉnh sửa ảnh của ByteDance. Nó kết hợp một 2D U-Net tùy chỉnh (`DreamLiteUNetModel`) với bộ mã hóa đa phương thức `Qwen3-VL` làm bộ mã hóa prompt / hướng dẫn ảnh, và sử dụng VAE `AutoencoderTiny` (kiểu TAESD) để mã hóa/giải mã latent nhanh chóng.

Có hai pipeline được cung cấp:

| Pipeline | Các chế độ | CFG | Trường hợp sử dụng |
|---|---|---|---|
| [DreamLitePipeline](/docs/diffusers/main/vi/api/pipelines/dreamlite#diffusers.DreamLitePipeline) | text-to-image **và** chỉnh sửa ảnh (tự động chọn dựa trên việc `image` có phải là `None` hay không) | 3-branch dual CFG (`guidance_scale` trên nhánh text, `image_guidance_scale` trên nhánh image, theo phong cách InstructPix2Pix) | Chất lượng cao nhất |
| [DreamLiteMobilePipeline](/docs/diffusers/main/vi/api/pipelines/dreamlite#diffusers.DreamLiteMobilePipeline) | text-to-image **và** chỉnh sửa ảnh (tự động chọn dựa trên việc `image` có phải là `None` hay không) | Không có — đã được chưng cất, chỉ một lần chạy UNet forward cho mỗi bước | Trên thiết bị / độ trễ thấp |

Các checkpoint chính thức:

* Mô hình cơ sở: [carlofkl/DreamLite-base](https://huggingface.co/carlofkl/DreamLite-base)
* Mô hình di động đã được chưng cất: [carlofkl/DreamLite-mobile](https://huggingface.co/carlofkl/DreamLite-mobile)

> [!TIP]
> Cả hai pipeline đều tự động phát hiện chế độ text-to-image hay image-editing dựa trên việc có cung cấp đối số `image` hay không. Không có lớp `Img2Img` riêng biệt.

> [!TIP]
> Khi nạp ảnh đầu vào để chỉnh sửa, hãy ưu tiên dùng `diffusers.utils.load_image(...)` thay vì `PIL.Image.open(...)` thô. `load_image` thực thi việc chuyển đổi sang RGB và áp dụng định hướng EXIF, cả hai đều là những giả định của pipeline. Việc dùng `Image.open` đơn thuần trên nguồn RGBA / bảng màu / xoay EXIF sẽ âm thầm tạo ra điều kiện latent khác biệt và làm giảm chất lượng đầu ra.

## Văn bản sang hình ảnh (Cơ bản)

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

## Chỉnh sửa hình ảnh (Cơ bản)

Truyền một `image` để vào chế độ chỉnh sửa. Cả `guidance_scale` (nhánh văn bản) và `image_guidance_scale` (nhánh hình ảnh) đều được kích hoạt ở đây.

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

## Văn bản sang hình ảnh (Di động)

Pipeline di động được chưng cất và bỏ qua hoàn toàn CFG — chỉ một bước forward của UNet cho mỗi bước. Nó nhận cùng các đối số `prompt` / `height` / `width` / `num_inference_steps`, nhưng **bỏ qua** `guidance_scale` và `image_guidance_scale` nếu được truyền vào (một cảnh báo sẽ được ghi log).

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

## Chỉnh sửa hình ảnh (Di động)

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

## Ghi chú và hạn chế

* Cả hai pipeline đều ép `batch_size = 1` bên trong; `num_images_per_prompt` kiểm soát số lượng mẫu được lấy từ cùng một prompt thay vì xử lý song song theo batch.
* Bộ mã hóa prompt là `Qwen3-VL`, một mô hình đa phương thức. Do đó, việc tải toàn bộ pipeline đòi hỏi bộ nhớ GPU đủ lớn cho cả U-Net và bộ mã hóa văn bản Qwen3-VL (~4 GB + ~0,7 GB ở bf16 cho bản phát hành cơ sở).
* VAE là `AutoencoderTiny` và có `encoder_block_out_channels`; `vae_scale_factor` được suy ra từ nó khi khởi tạo pipeline.

## DreamLitePipeline[[diffusers.DreamLitePipeline]]

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

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

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

DreamLite pipeline cho việc tạo ảnh từ văn bản và chỉnh sửa ảnh dựa trên hướng dẫn.

Cùng một pipeline hỗ trợ cả hai chế độ; chế độ hoạt động được tự động phát hiện từ các đầu vào:

- `image is None` -> text-to-image (một CFG duy nhất trên văn bản).
- `image is not None` -> chỉnh sửa từ ảnh sang ảnh / theo hướng dẫn (CFG kép: văn bản + ảnh).

Components: text_encoder ([*~transformers.Qwen3VLForConditionalGeneration*]): Bộ mã hóa văn bản/thị giác đa phương thức được sử dụng để tạo các embedding điều kiện. tokenizer ([*~transformers.AutoTokenizer*]): Bộ phân từ cho chế độ chỉ văn bản (generate). processor ([*~transformers.Qwen3VLProcessor*]): Bộ xử lý đa phương thức cho chế độ chỉnh sửa (mẫu văn bản + hình ảnh). vae ([*~diffusers.AutoencoderTiny*]): VAE nhỏ thân thiện với thiết bị di động để mã hóa/giải mã latent. unet ([*~diffusers.DreamLiteUNetModel*]): DreamLite UNet (GQA + qk_norm + conv tách biệt theo chiều sâu). scheduler ([*~diffusers.FlowMatchEulerDiscreteScheduler*]): Scheduler Euler khớp dòng với dịch chuyển động.

Lưu ý: `batch_size` hiện bị ép thành `1`; `num_images_per_prompt` được hỗ trợ.

#### __call__[[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)
```

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

**Tham số:**

prompt : Prompt văn bản.

negative_prompt : Prompt văn bản tiêu cực (mặc định là chuỗi rỗng).

image : Ảnh đầu vào tùy chọn. Nếu được cung cấp, pipeline sẽ chạy ở chế độ **chỉnh sửa / image-to-image** với dual classifier-free guidance; nếu không, nó sẽ chạy ở chế độ **text-to-image**.

height : Độ phân giải đầu ra (chiều cao). Mặc định là `default_sample_size * vae_scale_factor` (1024). Mặc định này áp dụng cho cả T2I và I2I; truyền một giá trị rõ ràng để ghi đè.

width : Độ phân giải đầu ra (chiều rộng). Mặc định là `default_sample_size * vae_scale_factor` (1024). Giá trị mặc định này áp dụng cho cả T2I và I2I; truyền một giá trị rõ ràng để ghi đè.

guidance_scale : Thang độ CFG trên nhánh văn bản (cả hai chế độ).

image_guidance_scale : Thang CFG bổ sung trên nhánh hình ảnh (chỉ ở chế độ chỉnh sửa).

num_inference_steps : Số bước khử nhiễu.

sigmas : Sigmas FlowMatch tường minh tùy chọn; mặc định là linspace đều.

num_images_per_prompt : Số lượng ảnh đầu ra cho mỗi prompt (lưu ý: `batch_size` được ép bằng 1).

generator : Bộ tạo ngẫu nhiên.

output_type : `"pil"`, `"np"`, `"pt"` hoặc `"latent"`.

return_dict : Nếu là True, trả về một [DreamLitePipelineOutput](/docs/diffusers/main/vi/api/pipelines/dreamlite#diffusers.DreamLitePipelineOutput); nếu không, trả về một tuple `(images,)`.

max_sequence_length : Số lượng tối đa các token của prompt người dùng được giữ lại sau khi loại bỏ phần tiền tố của chat-template. Chỉ áp dụng cho chế độ `generate` (chế độ `edit` sử dụng padding gốc của bộ xử lý đa phương thức).

text_pad_embedding : Nhúng pad học được tùy chọn cho các vị trí bị che.

**Trả về:**

[DreamLitePipelineOutput](/docs/diffusers/main/vi/api/pipelines/dreamlite#diffusers.DreamLitePipelineOutput) hoặc `tuple`.

Chạy pipeline DreamLite.

## DreamLiteMobilePipeline[[diffusers.DreamLiteMobilePipeline]]

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

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

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

Pipeline **Mobile** của DreamLite: một biến thể đã được chưng cất, không sử dụng classifier-free-guidance của [DreamLitePipeline](/docs/diffusers/main/vi/api/pipelines/dreamlite#diffusers.DreamLitePipeline) để suy luận nhanh với ít bước (mặc định là 4 bước).

Chế độ hoạt động được tự động phát hiện từ các đầu vào (giống như pipeline cơ sở):

- `image is None` -> text-to-image.
- `image is not None` -> chỉnh sửa theo hướng dẫn từ ảnh sang ảnh.

Vì classifier-free guidance đã được **loại bỏ**, `guidance_scale` và `image_guidance_scale` được chấp nhận để đảm bảo tương thích API với [DreamLitePipeline](/docs/diffusers/main/vi/api/pipelines/dreamlite#diffusers.DreamLitePipeline) nhưng bị bỏ qua trong vòng lặp khử nhiễu. `negative_prompt` được cố ý không có.

Components (giống với pipeline cơ sở): text_encoder ([*~transformers.Qwen3VLForConditionalGeneration*]): Bộ mã hóa văn bản/thị giác đa phương tiện. tokenizer ([*~transformers.AutoTokenizer*]): Bộ phân từ cho chế độ chỉ văn bản (generate). processor ([*~transformers.Qwen3VLProcessor*]): Bộ xử lý đa phương tiện cho chế độ chỉnh sửa. vae ([*~diffusers.AutoencoderTiny*]): VAE nhỏ thân thiện với thiết bị di động. unet ([*~diffusers.DreamLiteUNetModel*]): DreamLite UNet. scheduler ([*~diffusers.FlowMatchEulerDiscreteScheduler*]): Bộ lập lịch Euler khớp dòng với dịch chuyển động.

Lưu ý: `batch_size` hiện bị ép thành `1`; `num_images_per_prompt` được hỗ trợ.

#### __call__[[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)
```

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

**Tham số:**

prompt : Prompt văn bản.

image : Ảnh đầu vào tùy chọn. Nếu được cung cấp, sẽ chạy ở chế độ **chỉnh sửa / ảnh-to-ảnh**; nếu không, sẽ chạy ở chế độ **văn-bản-to-ảnh**.

height : Độ phân giải đầu ra (chiều cao). Mặc định là `default_sample_size * vae_scale_factor` (1024).

width : Độ phân giải đầu ra (chiều rộng). Mặc định là `default_sample_size * vae_scale_factor` (1024).

num_inference_steps : Số bước khử nhiễu. Mặc định là **4** (đã chưng cất).

guidance_scale : Được chấp nhận để đảm bảo tính tương thích API với [DreamLitePipeline](/docs/diffusers/main/vi/api/pipelines/dreamlite#diffusers.DreamLitePipeline); **bị bỏ qua** vì CFG đã được chưng cất.

image_guidance_scale : Được chấp nhận để đảm bảo tính tương thích API với [DreamLitePipeline](/docs/diffusers/main/vi/api/pipelines/dreamlite#diffusers.DreamLitePipeline); **bị bỏ qua** vì CFG đã được chưng cất.

sigmas : Sigmas FlowMatch tường minh tùy chọn; mặc định là linspace đều.

num_images_per_prompt : Số lượng ảnh đầu ra cho mỗi prompt (lưu ý: `batch_size` được ép bằng 1).

generator : Bộ tạo ngẫu nhiên.

output_type : `"pil"`, `"np"`, `"pt"` hoặc `"latent"`.

return_dict : Nếu là True, trả về [DreamLitePipelineOutput](/docs/diffusers/main/vi/api/pipelines/dreamlite#diffusers.DreamLitePipelineOutput); nếu không, trả về `(images,)`.

max_sequence_length : Số lượng tối đa các token của prompt người dùng được giữ lại sau khi loại bỏ phần tiền tố của chat-template. Chỉ áp dụng cho chế độ `generate` (chế độ `edit` sử dụng padding gốc của bộ xử lý đa phương thức).

text_pad_embedding : Nhúng pad học được tùy chọn cho các vị trí bị che.

**Trả về:**

[DreamLitePipelineOutput](/docs/diffusers/main/vi/api/pipelines/dreamlite#diffusers.DreamLitePipelineOutput) hoặc `tuple`.

Chạy pipeline DreamLite Mobile đã được chưng cất.

## DreamLitePipelineOutput[[diffusers.DreamLitePipelineOutput]]

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

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

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

**Tham số:**

images (`List[PIL.Image.Image]` hoặc `np.ndarray`) : Danh sách các hình ảnh PIL đã khử nhiễu có độ dài `batch_size` hoặc mảng NumPy có hình dạng `(batch_size, height, width, num_channels)`. Các hình ảnh PIL hoặc mảng NumPy thể hiện các hình ảnh đã khử nhiễu của pipeline khuếch tán.

Lớp đầu ra cho các pipeline DreamLite.