#
# Лицензия Apache License, Version 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 и дискретным планировщиком Euler на основе flow-matching.

> [!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/main/src/diffusers/pipelines/nucleusmoe_image/pipeline_nucleusmoe_image.py#L132)

**Параметры:**

transformer (`NucleusMoEImageTransformer2DModel`) : архитектура условного трансформера (MMDiT) для удаления шума из закодированных латентов изображения.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ru/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : планировщик, используемый в связке с `transformer` для удаления шума из закодированных латентов изображения.

vae ([AutoencoderKLQwenImage](/docs/diffusers/main/ru/api/models/autoencoderkl_qwenimage#diffusers.AutoencoderKLQwenImage)) : Модель вариационного автоэнкодера (VAE) для кодирования изображений в латентные представления и декодирования из них.

text_encoder (`Qwen3VLForConditionalGeneration`) : Текстовый энкодер для вычисления эмбеддингов промпта.

processor (`Qwen3VLProcessor`) : Процессор для токенизации текстовых входных данных.

Пайплайн для генерации изображений по тексту с использованием NucleusMoE.

Этот конвейер использует однопоточный DiT с слоями feed-forward типа Mixture-of-Experts, кросс-вниманием к текстовому энкодеру Qwen3-VL и дискретным планировщиком Euler на основе flow-matching.

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

[Источник](https://github.com/huggingface/diffusers/blob/main/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`, *optional*, по умолчанию 4.0) : Масштаб classifier-free guidance. Значения, большие 1, включают CFG.

return_index (`int`, *optional*) : Индекс слоя вывода текстового кодировщика, используемого для эмбеддингов промпта.

height (`int`, *необязательный*, по умолчанию `self.default_sample_size * self.vae_scale_factor`) : Высота генерируемого изображения в пикселях.

width (`int`, *необязательный*, по умолчанию `self.default_sample_size * self.vae_scale_factor`) : Ширина генерируемого изображения в пикселях.

num_inference_steps (`int`, *optional*, по умолчанию 50) : Количество шагов денойзинга.

sigmas (`list[float]`, *optional*) : Пользовательские сигмы для расписания денойзинга. Если не заданы, используется линейное расписание.

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`

`NucleusMoEImagePipelineOutput`, если `return_dict` равно True, иначе `tuple`, где первый элемент — список с сгенерированными изображениями.

Функция, вызываемая при обращении к конвейеру для генерации.

Примеры:
```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/main/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) : Максимальная длина токенов для закодированного запроса.

Кодируйте текстовые подсказки в эмбеддинги с помощью текстового энкодера 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/main/src/diffusers/pipelines/nucleusmoe_image/pipeline_output.py#L10)

**Параметры:**

images (`list[PIL.Image.Image]` или `np.ndarray`) : Список денойзированных изображений PIL длиной `batch_size` или массив numpy с формой `(batch_size, height, width, num_channels)`. Изображения PIL или массив numpy представляют денойзированные изображения диффузионного конвейера.

Класс вывода для пайплайнов NucleusMoE Image.