#
# Licenciado sob a Apache License, Versão 2.0 (a "Licença");
# você não pode usar este arquivo, exceto em conformidade com a Licença.
# Você pode obter uma cópia da Licença em
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# A menos que exigido pela lei aplicável ou acordado por escrito, o software
# distribuído sob a Licença é distribuído em uma base "COMO ESTÁ",
# SEM GARANTIAS OU CONDIÇÕES DE QUALQUER TIPO, expressas ou implícitas.
# Consulte a Licença para o idioma específico que rege as permissões e
# limitações sob a Licença. -->

# NucleusMoE-Image

[NucleusMoE-Image](https://huggingface.co/NucleusAI/NucleusMoE-Image) é um modelo de texto para imagem que combina um DiT de fluxo único com camadas feed-forward Mixture-of-Experts, atenção cruzada para um codificador de texto Qwen3-VL e um agendador discreto Euler de flow-matching.

> [!TIP]
> Certifique-se de consultar o [guia](../../using-diffusers/schedulers) de Schedulers para aprender a explorar o compromisso entre a velocidade e a qualidade do scheduler, e veja a seção [reutilização de componentes entre pipelines](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) para aprender a carregar eficientemente os mesmos componentes em vários pipelines.

## NucleusMoEImagePipeline[[diffusers.NucleusMoEImagePipeline]]

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

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

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

**Parâmetros:**

transformer (`NucleusMoEImageTransformer2DModel`) : Arquitetura de Transformer condicional (MMDiT) para desruidar os latentes de imagem codificados.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Um scheduler a ser usado em combinação com `transformer` para desruidar os latentes da imagem codificada.

vae ([AutoencoderKLQwenImage](/docs/diffusers/v0.43.0/pt/api/models/autoencoderkl_qwenimage#diffusers.AutoencoderKLQwenImage)) : Modelo de Autoencoder Variacional (VAE) para codificar e decodificar imagens para e a partir de representações latentes.

text_encoder (`Qwen3VLForConditionalGeneration`) : Codificador de texto para calcular incorporações de prompt.

processor (`Qwen3VLProcessor`) : Processador para tokenizar entradas de texto.

Pipeline para geração de texto para imagem usando NucleusMoE.

Este pipeline usa um DiT de fluxo único com camadas feed-forward de Mixture-of-Experts, atenção cruzada para um codificador de texto Qwen3-VL e um agendador discreto Euler de 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'])
```

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

**Parâmetros:**

prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para orientar a geração da imagem. Se não definido, é necessário passar `prompt_embeds`.

negative_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts que não devem orientar a geração da imagem. Se não definido, uma string vazia é usada quando `true_cfg_scale > 1`.

guidance_scale (`float`, *opcional*, padrão 4.0) : Escala de orientação sem classificador. Valores maiores que 1 ativam o CFG.

return_index (`int`, *opcional*) : Índice da camada da saída do codificador de texto a ser usada para os embeddings do prompt.

height (`int`, *opcional*, padrão `self.default_sample_size * self.vae_scale_factor`) : A altura em pixels da imagem gerada.

width (`int`, *opcional*, padrão `self.default_sample_size * self.vae_scale_factor`) : A largura, em pixels, da imagem gerada.

num_inference_steps (`int`, *opcional*, padrão 50) : O número de etapas de desruidamento.

sigmas (`list[float]`, *opcional*) : Sigmas personalizados para o agendamento de desruidamento. Se não definido, um agendamento linear é utilizado.

num_images_per_prompt (`int`, *opcional*, padrão 1) : O número de imagens a serem geradas por prompt.

generator (`torch.Generator` ou `list[torch.Generator]`, *opcional*) : Um ou uma lista de geradores torch para tornar a geração determinística.

latents (`torch.Tensor`, *opcional*) : Latentes ruidosos pré-gerados para serem usados como entradas para a geração de imagens.

prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto pré-gerados.

prompt_embeds_mask (`torch.Tensor`, *opcional*) : Máscara de atenção para embeddings de texto pré-gerados.

negative_prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto negativo pré-gerados.

negative_prompt_embeds_mask (`torch.Tensor`, *opcional*) : Máscara de atenção para embeddings de texto negativo pré-gerados.

output_type (`str`, *opcional*, padrão `"pil"`) : O formato de saída da imagem gerada. Escolha entre `"pil"`, `"np"` ou `"latent"`.

return_dict (`bool`, *opcional*, padrão `True`) : Se deve ou não retornar um `NucleusMoEImagePipelineOutput` em vez de uma tupla simples.

attention_kwargs (`dict`, *opcional*) : Kwargs passados para o processador de atenção.

callback_on_step_end (`Callable`, *opcional*) : Uma função chamada no final de cada etapa de desruidamento.

callback_on_step_end_tensor_inputs (`list`, *opcional*) : Entradas de Tensor para a função `callback_on_step_end`.

max_sequence_length (`int`, padrão 512) : Comprimento máximo da sequência para o prompt de texto.

**Retorna:** `NucleusMoEImagePipelineOutput` ou `tuple`

`NucleusMoEImagePipelineOutput` se `return_dict` for True, caso contrário, uma `tuple` em que o primeiro elemento é uma lista com as imagens geradas.

Função invocada ao chamar o pipeline para geração.

Exemplos:
```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)
```

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

**Parâmetros:**

prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts a serem codificados.

device (`torch.device`, *opcional*) : Dispositivo Torch para os tensores resultantes.

num_images_per_prompt (`int`, padrão 1) : Número de imagens a serem geradas por prompt.

prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto pré-gerados. Pula a codificação quando fornecidos.

prompt_embeds_mask (`torch.Tensor`, *opcional*) : Máscara de atenção para incorporações pré-geradas.

max_sequence_length (`int`, padrão 1024) : Comprimento máximo de tokens para o prompt codificado.

Codifique os prompts de texto em embeddings usando o codificador de texto do 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)
```

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

**Parâmetros:**

images (`list[PIL.Image.Image]` ou `np.ndarray`) : Lista de imagens PIL desruidas de comprimento `batch_size` ou array numpy de forma `(batch_size, height, width, num_channels)`. As imagens PIL ou o array numpy apresentam as imagens desruidas do pipeline de difusão.

Classe de saída para pipelines de imagem NucleusMoE.