#
# 根据 Apache 许可证 2.0 版本（“许可证”）授权
# 您只能在遵守许可证的情况下使用本文件。
# 您可以在以下位置获取许可证副本
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 除非适用法律要求或双方书面同意，软件
# 根据许可证分发，本软件按“原样”
# 不附带任何明示或暗示的保证或条件。
# 请参阅许可证中关于权限的具体语言
# 许可证下的限制。-->

# NucleusMoE-Image

[NucleusMoE-Image](https://huggingface.co/NucleusAI/NucleusMoE-Image) 是一个文生图模型，它将单流 DiT 与 Mixture-of-Experts 前馈层相结合，并采用针对 Qwen3-VL 文本编码器的交叉注意力机制以及 flow-matching Euler 离散调度器。

> [!TIP]
> 请务必参阅 [调度器指南](../../using-diffusers/schedulers)，了解如何探索调度器速度与质量之间的权衡，并查看 [跨流水线复用组件](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) 部分，了解如何高效地将相同组件加载到多个流水线中。

## NucleusMoEImagePipeline[[diffusers.NucleusMoEImagePipeline]]

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

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

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/nucleusmoe_image/pipeline_nucleusmoe_image.py#L132)

**参数：**

transformer (`NucleusMoEImageTransformer2DModel`)：用于对编码后的图像潜变量进行去噪的条件 Transformer（MMDiT）架构。

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler))：用于与 `transformer` 配合，对编码后的图像潜变量进行去噪的调度器。

vae ([AutoencoderKLQwenImage](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl_qwenimage#diffusers.AutoencoderKLQwenImage))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，以及从潜在表示解码为图像。

text_encoder (`Qwen3VLForConditionalGeneration`)：用于计算提示嵌入的文本编码器。

processor (`Qwen3VLProcessor`)：用于对文本输入进行分词的处理器。

使用 NucleusMoE 进行文本到图像生成的 Pipeline。

该流水线采用单流 DiT，其前馈层使用混合专家（Mixture-of-Experts）结构，并通过交叉注意力机制与 Qwen3-VL 文本编码器交互，同时使用 flow-matching Euler 离散调度器。

#### __调用__[[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[str] = ['latents'])
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/nucleusmoe_image/pipeline_nucleusmoe_image.py#L379)

**参数：**

prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则必须传入 `prompt_embeds`。

negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，当 `true_cfg_scale > 1` 时将使用空字符串。

guidance_scale (`float`, *可选*，默认值为 4.0)：Classifier-free guidance 的缩放系数。大于 1 的值会启用 CFG。

return_index (`int`, *可选*) : 用于提示嵌入的文本编码器输出的层索引。

height (`int`，*可选*，默认为 `self.default_sample_size * self.vae_scale_factor`)：生成图像的高度（以像素为单位）。

width (`int`，*可选*，默认为 `self.default_sample_size * self.vae_scale_factor`)：生成图像的宽度（以像素为单位）。

num_inference_steps (`int`，*可选*，默认值为 50)：去噪步数。

sigmas (`list[float]`, *可选*) : 用于去噪调度的自定义 sigmas。如果未定义，则使用线性调度。

num_images_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的图像数量。

generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：一个或一组 torch 生成器，用于使生成过程具有确定性。

latents (`torch.Tensor`, *可选*) : 预生成的噪声潜变量，用作图像生成的输入。

prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。

prompt_embeds_mask (`torch.Tensor`, *可选*) : 用于预生成文本嵌入的注意力掩码。

negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负文本嵌入。

negative_prompt_embeds_mask (`torch.Tensor`, *可选*) : 用于预生成的负文本嵌入的注意力掩码。

output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。可选 `"pil"`、`"np"` 或 `"latent"`。

return_dict (`bool`，*可选*，默认为 `True`)：是否返回 `NucleusMoEImagePipelineOutput` 而不是普通元组。

attention_kwargs (`dict`，*可选*)：传递给注意力处理器的关键字参数。

callback_on_step_end (`Callable`，*可选*)：在每个去噪步骤结束时调用的函数。

callback_on_step_end_tensor_inputs (`list`，*可选*)：`callback_on_step_end` 函数的 Tensor 输入。

max_sequence_length (`int`，默认值为 512)：文本提示词的最大序列长度。

**返回：** `NucleusMoEImagePipelineOutput` 或 `tuple`

如果 `return_dict` 为 True，则返回 `NucleusMoEImagePipelineOutput`；否则返回一个 `tuple`，其中第一个元素是包含生成图像的列表。

调用生成 pipeline 时调用的函数。

示例：
```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)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/nucleusmoe_image/pipeline_nucleusmoe_image.py#L187)

**参数：**

prompt (`str` 或 `list[str]`，*可选*)：要编码的提示词或提示词列表。

device (`torch.device`，*可选*)：用于生成张量的 Torch 设备。

num_images_per_prompt (`int`，默认为 1)：每个提示词生成的图像数量。

prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。提供时将跳过编码步骤。

prompt_embeds_mask (`torch.Tensor`, *可选*) : 预生成嵌入的注意力掩码。

max_sequence_length (`int`，默认为 1024)：编码提示词的最大 token 长度。

使用 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)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/nucleusmoe_image/pipeline_output.py#L10)

**参数：**

images (`list[PIL.Image.Image]` 或 `np.ndarray`)：长度为 `batch_size` 的去噪 PIL 图像列表，或形状为 `(batch_size, height, width, num_channels)` 的 numpy 数组。PIL 图像或 numpy 数组表示扩散流水线生成的去噪图像。

NucleusMoE 图像流水线的输出类。