#
# Được cấp phép theo Giấy phép Apache, Phiên bản 2.0 (gọi là "Giấy phép");
# bạn có thể không sử dụng tệp này ngoại trừ tuân thủ theo Giấy phép.
# Bạn có thể nhận được một bản sao của Giấy phép tại
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Trừ khi được yêu cầu bởi luật pháp có hiệu lực hoặc được thỏa thuận bằng văn bản, phần mềm
# được phân phối theo Giấy phép được phân phối trên cơ sở
# KHÔNG CÓ BẢO HÀNH HOẶC ĐIỀU KIỆN DƯỚI BẤT KỲ HÌNH THỨC NÀO, dù được nêu rõ hay ngụ ý.
# Xem Giấy phép để biết ngôn ngữ cụ thể điều chỉnh các quyền và
# giới hạn theo Giấy phép. -->

# NucleusMoE-Image

[NucleusMoE-Image](https://huggingface.co/NucleusAI/NucleusMoE-Image) là một mô hình text-to-image kết hợp DiT single-stream với các lớp feed-forward Mixture-of-Experts, cross-attention tới text encoder Qwen3-VL và flow-matching Euler discrete scheduler.

> [!TIP]
> Hãy chắc chắn xem qua [hướng dẫn](../../using-diffusers/schedulers) về Schedulers để tìm hiểu cách khám phá sự đánh đổi giữa tốc độ và chất lượng của scheduler, và xem phần [tái sử dụng các thành phần giữa các pipeline](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) để tìm hiểu cách nạp các thành phần giống nhau vào nhiều pipeline một cách hiệu quả.

## NucleusMoEImagePipeline[[diffusers.NucleusMoEImagePipeline]]

#### diffusers.NucleusMoEImagePipeline[[diffusers.NucleusMoEImagePipeline]]

```python
diffusers.NucleusMoEImagePipeline(transformer: NucleusMoEImageTransformer2DModel, scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLQwenImage, text_encoder: Qwen3VLForConditionalGeneration, processor: Qwen3VLProcessor)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/nucleusmoe_image/pipeline_nucleusmoe_image.py#L132)

**Tham số:**

transformer (`NucleusMoEImageTransformer2DModel`) : Kiến trúc Transformer có điều kiện (MMDiT) để khử nhiễu các latents ảnh đã mã hóa.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/vi/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Một trình lập lịch được sử dụng kết hợp với `transformer` để khử nhiễu các latent ảnh đã mã hóa.

vae ([AutoencoderKLQwenImage](/docs/diffusers/main/vi/api/models/autoencoderkl_qwenimage#diffusers.AutoencoderKLQwenImage)) : Mô hình Variational Auto-Encoder (VAE) để mã hóa và giải mã hình ảnh sang và từ các biểu diễn ẩn.

text_encoder (`Qwen3VLForConditionalGeneration`) : Bộ mã hóa văn bản để tính toán nhúng (embedding) của prompt.

processor (`Qwen3VLProcessor`) : Bộ xử lý để mã hóa token cho các đầu vào văn bản.

Pipeline để tạo ảnh từ văn bản sử dụng NucleusMoE.

Pipeline này sử dụng DiT single-stream với các lớp feed-forward Mixture-of-Experts, cross-attention đến text encoder Qwen3-VL và flow-matching Euler discrete scheduler.

#### __call__[[diffusers.NucleusMoEImagePipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, negative_prompt: str | list[str] = None, guidance_scale: float = 4.0, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, num_images_per_prompt: int = 1, max_sequence_length: int | None = None, return_index: int | None = None, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'])
```

[Nguồn](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/nucleusmoe_image/pipeline_nucleusmoe_image.py#L379)

**Tham số:**

prompt (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt để hướng dẫn việc tạo ảnh. Nếu không được định nghĩa, cần phải truyền `prompt_embeds`.

negative_prompt (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt không được dùng để hướng dẫn tạo ảnh. Nếu không được định nghĩa, một chuỗi rỗng sẽ được sử dụng khi `true_cfg_scale > 1`.

guidance_scale (`float`, *optional*, mặc định là 4.0) : Thang độ hướng dẫn không có điều kiện (classifier-free guidance). Các giá trị lớn hơn 1 sẽ kích hoạt CFG.

return_index (`int`, *tuỳ chọn*) : Chỉ số lớp của đầu ra bộ mã hóa văn bản cần dùng cho các nhúng (embeddings) của prompt.

height (`int`, *tùy chọn*, mặc định là `self.default_sample_size * self.vae_scale_factor`) : Chiều cao của hình ảnh được tạo ra, tính bằng pixel.

width (`int`, *tùy chọn*, mặc định là `self.default_sample_size * self.vae_scale_factor`) : Độ rộng tính bằng pixel của hình ảnh được tạo ra.

num_inference_steps (`int`, *tuỳ chọn*, mặc định là 50) : Số bước khử nhiễu.

sigmas (`list[float]`, *optional*) : Các sigma tùy chỉnh cho lịch trình khử nhiễu. Nếu không được định nghĩa, một lịch trình tuyến tính sẽ được sử dụng.

num_images_per_prompt (`int`, *tuỳ chọn*, mặc định là 1) : Số lượng hình ảnh cần tạo cho mỗi prompt.

generator (`torch.Generator` hoặc `list[torch.Generator]`, *tùy chọn*) : Một hoặc một danh sách các torch generator để làm cho quá trình sinh trở nên tất định.

latents (`torch.Tensor`, *tùy chọn*) : Các latents nhiễu đã được tạo trước để sử dụng làm đầu vào cho việc tạo ảnh.

prompt_embeds (`torch.Tensor`, *tùy chọn*) : Các vector nhúng văn bản đã được tạo trước.

prompt_embeds_mask (`torch.Tensor`, *tùy chọn*) : Mặt nạ chú ý cho các nhúng văn bản được tạo trước.

negative_prompt_embeds (`torch.Tensor`, *tùy chọn*) : Các vector nhúng văn bản âm đã được tạo trước.

negative_prompt_embeds_mask (`torch.Tensor`, *tùy chọn*) : Mặt nạ chú ý cho các vector nhúng văn bản âm được tạo trước.

output_type (`str`, *tùy chọn*, mặc định là `"pil"`) : Định dạng đầu ra của hình ảnh được tạo ra. Chọn giữa `"pil"`, `"np"` hoặc `"latent"`.

return_dict (`bool`, *tùy chọn*, mặc định là `True`) : Có nên trả về một `NucleusMoEImagePipelineOutput` thay vì một tuple thông thường hay không.

attention_kwargs (`dict`, *tùy chọn*) : Các Kwargs được truyền cho bộ xử lý chú ý.

callback_on_step_end (`Callable`, *tùy chọn*) : Một hàm được gọi vào cuối mỗi bước khử nhiễu.

callback_on_step_end_tensor_inputs (`list`, *tùy chọn*) : Đầu vào Tensor cho hàm `callback_on_step_end`.

max_sequence_length (`int`, mặc định là 512) : Độ dài tối đa của chuỗi cho prompt văn bản.

**Trả về:** `NucleusMoEImagePipelineOutput` hoặc `tuple`

`NucleusMoEImagePipelineOutput` nếu `return_dict` là True, ngược lại là một `tuple` trong đó phần tử đầu tiên là một danh sách chứa các hình ảnh đã tạo.

Hàm được gọi khi gọi pipeline cho việc sinh.

Ví dụ:
```py
>>> import torch
>>> from diffusers import NucleusMoEImagePipeline

>>> pipe = NucleusMoEImagePipeline.from_pretrained("NucleusAI/NucleusMoE-Image", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> image = pipe(prompt, num_inference_steps=50).images[0]
>>> image.save("nucleus_moe.png")
```

#### encode_prompt[[diffusers.NucleusMoEImagePipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str] = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int | None = None, return_index: int | None = None)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/nucleusmoe_image/pipeline_nucleusmoe_image.py#L187)

**Tham số:**

prompt (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt cần mã hóa.

device (`torch.device`, *tùy chọn*) : Thiết bị Torch cho các tensor kết quả.

num_images_per_prompt (`int`, mặc định là 1) : Số lượng hình ảnh cần tạo cho mỗi prompt.

prompt_embeds (`torch.Tensor`, *tùy chọn*) : Các vector nhúng văn bản đã được tạo trước. Bỏ qua bước mã hóa nếu được cung cấp.

prompt_embeds_mask (`torch.Tensor`, *tùy chọn*) : Mặt nạ chú ý cho các embedding được tạo trước.

max_sequence_length (`int`, mặc định là 1024) : Độ dài token tối đa cho prompt đã được mã hóa.

Mã hóa các prompt văn bản thành các embedding bằng trình mã hóa văn bản Qwen3-VL.

## NucleusMoEImagePipelineOutput[[diffusers.pipelines.nucleusmoe_image.pipeline_output.NucleusMoEImagePipelineOutput]]

#### diffusers.pipelines.nucleusmoe_image.pipeline_output.NucleusMoEImagePipelineOutput[[diffusers.pipelines.nucleusmoe_image.pipeline_output.NucleusMoEImagePipelineOutput]]

```python
diffusers.pipelines.nucleusmoe_image.pipeline_output.NucleusMoEImagePipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)
```

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

**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 ảnh NucleusMoE.