NucleusMoE-Image

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

请务必参阅调度器指南，了解如何探索调度器速度与质量之间的权衡，并查看跨流水线复用组件部分，了解如何高效地将相同组件加载到多个流水线中。

NucleusMoEImagePipeline

class diffusers.NucleusMoEImagePipeline

< source >

( transformer: NucleusMoEImageTransformer2DModelscheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImagetext_encoder: Qwen3VLForConditionalGenerationprocessor: Qwen3VLProcessor )

参数

transformer (NucleusMoEImageTransformer2DModel) — 用于对编码后的图像潜变量进行去噪的条件 Transformer（MMDiT）架构。
scheduler (FlowMatchEulerDiscreteScheduler) — 用于与 transformer 配合，对编码后的图像潜变量进行去噪的调度器。
vae (AutoencoderKLQwenImage) — 变分自编码器（VAE）模型，用于将图像编码为潜在表示，以及从潜在表示解码为图像。
text_encoder (Qwen3VLForConditionalGeneration) — 用于计算提示嵌入的文本编码器。
processor (Qwen3VLProcessor) — 用于对文本输入进行分词的处理器。

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

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

call

< source >

( prompt: str | list[str] = Nonenegative_prompt: str | list[str] = Noneguidance_scale: float = 4.0height: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Nonenum_images_per_prompt: int = 1max_sequence_length: int | None = Nonereturn_index: int | None = Nonegenerator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents'] ) → NucleusMoEImagePipelineOutput or tuple

参数

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 函数的张量输入。
max_sequence_length (int，默认为 512) — 文本提示词的最大序列长度。

返回值

NucleusMoEImagePipelineOutput 或 tuple

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

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

示例：

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

< source >

( prompt: str | list[str] = Nonedevice: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int | None = Nonereturn_index: int | None = None )

参数

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 文本编码器将文本提示编码为嵌入。