#
# Sous licence Apache License, Version 2.0 (la « Licence ») ;
# vous ne pouvez utiliser ce fichier que conformément à la Licence.
# Vous pouvez obtenir un exemplaire de la Licence à
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Sauf exigence légale ou accord écrit
# distribué sous la Licence est distribué sur une base « EN L'ÉTAT »,
# SANS AUCUNE GARANTIE NI CONDITION, explicite ou implicite.
# Voir la Licence pour le langage spécifique régissant les autorisations et
# limitations under the License. -->

# PRX Pixel

PRXPixel est un modèle de génération d'images à partir de texte dans l'espace des pixels, développé par Photoroom. Un `PRXTransformer2DModel` d'environ 7B débruite directement des images RGB brutes — aucun VAE n'est nécessaire. Le modèle est conditionné par un encodeur de texte Qwen3-VL et utilise le flow matching, où le transformer prédit l'image propre à chaque étape (x-prediction). La résolution de génération est intégrée à la modulation du timestep, ce qui permet au modèle de connaître la taille cible.

## Modèles disponibles

| Modèle | Résolution | Description | Paramètres suggérés | dtype recommandé |
|:-----:|:---------:|:----------:|:----------:|:----------:|
| [`Photoroom/prxpixel-t2i`](https://huggingface.co/Photoroom/prxpixel-t2i) | 1024 | Modèle de l'espace des pixels ~7B avec encodeur de texte Qwen3-VL | 28 étapes, cfg=5.0 | `torch.bfloat16` |

## Chargement du pipeline

[PRXPixelPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/prx_pixel#diffusers.PRXPixelPipeline) nécessite `transformers >= 4.57` (la version qui a introduit `Qwen3VLTextModel`). Chargez-le avec [from_pretrained()](/docs/diffusers/v0.43.0/fr/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) :

```py
import torch
from diffusers import PRXPixelPipeline

pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

prompt = "A front-facing portrait of a lion in the golden savanna at sunset."
image = pipe(prompt, num_inference_steps=28, guidance_scale=5.0).images[0]
image.save("prxpixel_output.png")
```

## Optimisation de la mémoire

Pour les environnements à mémoire limitée :

```py
import torch
from diffusers import PRXPixelPipeline

pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", dtype=torch.bfloat16)
pipe.enable_model_cpu_offload()

# Or use sequential CPU offload for even lower memory
pipe.enable_sequential_cpu_offload()
```

## PRXPixelPipeline[[diffusers.PRXPixelPipeline]]

#### diffusers.PRXPixelPipeline[[diffusers.PRXPixelPipeline]]

```python
diffusers.PRXPixelPipeline(transformer: PRXTransformer2DModel, scheduler: FlowMatchEulerDiscreteScheduler, text_encoder: PreTrainedModel, tokenizer: transformers.models.auto.tokenization_auto.AutoTokenizer | transformers.tokenization_utils_base.PreTrainedTokenizerBase, default_sample_size: int | None = 1024, prompt_max_tokens: int = 256, noise_scale: float = 2.0)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L98)

**Paramètres :**

transformer (`PRXTransformer2DModel`) : le débruiteur PRX d’environ 7 Md de paramètres. Pour PRXPixel, il est construit avec `in_channels=3`, un goulot d’étranglement `img_in` et `resolution_embeds=True`, et il est entraîné à prédire l’image propre `x0`.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/fr/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : planificateur de type flow-matching utilisé pour débruyer les latents (dans l'espace des pixels).

text_encoder (`PreTrainedModel`) : le backbone texte Qwen3-VL utilisé pour encoder les prompts (la tour de vision est écartée). Doit retourner un `last_hidden_state`.

tokenizer (`PreTrainedTokenizerBase`) : Tokenizer pour `text_encoder` (généralement chargé via `AutoTokenizer`).

default_sample_size (`int`, *facultatif*, valeur par défaut 1024) : Hauteur/largeur par défaut utilisée lorsqu'aucune valeur n'est fournie à `__call__`.

prompt_max_tokens (`int`, *facultatif*, valeur par défaut 256) : Nombre de jetons de texte auquel le prompt est rembourré/tronqué avant l'encodage.

noise_scale (`float`, *facultatif*, valeur par défaut 2.0) : Échelle appliquée au bruit gaussien initial. PRXPixel s’entraîne avec une échelle de bruit initial non unitaire, il faut donc commencer l’échantillonnage à partir de `randn * noise_scale`.

Pipeline pour la génération d'images à partir de texte avec le modèle PRXPixel.

PRXPixel est un pipeline autonome de génération d’images à partir de texte dans l’espace des pixels. Il débruite directement des données RGB brutes à l’aide d’un `PRXTransformer2DModel` d’environ 7 milliards de paramètres et ne comporte pas de VAE (la génération s’effectue entièrement dans l’espace des pixels, de sorte que la sortie débruitée *est* l’image). Les prompts sont encodés par un encodeur de texte Qwen3-VL (la tour de vision est écartée). Contrairement à [PRXPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/prx#diffusers.PRXPipeline), le transformeur est entraîné avec une prédiction x : à chaque étape, il prédit l’image propre `x0`, qui est convertie en vitesse de flow-matching avant l’étape du planificateur. L’échantillonnage démarre à partir de `randn * noise_scale` (`noise_scale=2.0` par défaut) et la résolution par défaut est de 1024 px.

Ce modèle hérite de [DiffusionPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/overview#diffusers.DiffusionPipeline). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous les pipelines (téléchargement ou sauvegarde, exécution sur un appareil particulier, etc.).

Exemples :
```py
>>> import torch
>>> from diffusers import PRXPixelPipeline

>>> pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> prompt = "A front-facing portrait of a lion in the golden savanna at sunset."
>>> image = pipe(prompt, num_inference_steps=28, guidance_scale=5.0).images[0]
>>> image.save("prxpixel_output.png")
```

#### __appel__[[diffusers.PRXPixelPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, negative_prompt: str = '', height: int | None = None, width: int | None = None, num_inference_steps: int = 28, timesteps: list[int] = None, guidance_scale: float = 4.0, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, negative_prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, output_type: str | None = 'pil', return_dict: bool = True, use_resolution_binning: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L406)

**Paramètres :**

prompt (`str` ou `list[str]`, *facultatif*) : Le prompt ou les prompts pour guider la génération d’image. S’il n’est pas défini, il faut passer `prompt_embeds` à la place.

negative_prompt (`str`, *facultatif*, valeur par défaut `""`) : Le prompt ou les prompts à ne pas utiliser pour guider la génération d'image. Ignoré lorsque la guidance n'est pas utilisée (c'est-à-dire ignoré si `guidance_scale` est inférieur à `1`).

height (`int`, *facultatif*, par défaut `default_sample_size`) : La hauteur en pixels de l'image générée.

width (`int`, *facultatif*, par défaut `default_sample_size`) : La largeur en pixels de l'image générée.

num_inference_steps (`int`, *facultatif*, valeur par défaut 28) : Le nombre d'étapes de débruitage. Un plus grand nombre d'étapes de débruitage conduit généralement à une image de meilleure qualité, au prix d'une inférence plus lente.

timesteps (`list[int]`, *facultatif*) : Étapes de temps personnalisées à utiliser pour le processus de débruitage avec les planificateurs qui prennent en charge un argument `timesteps` dans leur méthode `set_timesteps`. S'il n'est pas défini, le comportement par défaut lorsque `num_inference_steps` est passé sera utilisé. Doit être dans l'ordre décroissant.

guidance_scale (`float`, *facultatif*, valeur par défaut 4.0) : Échelle de guidage telle que définie dans [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` est défini comme `w` de l'équation 2. de [Imagen Paper](https://huggingface.co/papers/2205.11487). L'échelle de guidage est activée en définissant `guidance_scale > 1`. Une échelle de guidage plus élevée encourage la génération d'images étroitement liées au `prompt` texte, généralement au détriment de la qualité de l'image.

num_images_per_prompt (`int`, *facultatif*, valeur par défaut 1) : Le nombre d'images à générer par invite.

generator (`torch.Generator` ou `list[torch.Generator]`, *facultatif*) : Un ou une liste de [générateurs torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) pour rendre la génération déterministe.

latents (`torch.Tensor`, *facultatif*) : Latents bruités pré-générés, échantillonnés à partir d'une distribution gaussienne, à utiliser comme entrées pour la génération d'images. Peut être utilisé pour ajuster la même génération avec des prompts différents. S'il n'est pas fourni, un tenseur de latents sera généré par échantillonnage à l'aide du `generator` aléatoire fourni.

prompt_embeds (`torch.FloatTensor`, *facultatif*) : Incrustations de texte pré-générées. Peut être utilisé pour ajuster facilement les entrées de texte, *par ex.* pondération des prompts. Si non fourni, les incrustations de texte seront générées à partir de l'argument d'entrée `prompt`.

negative_prompt_embeds (`torch.FloatTensor`, *facultatif*) : Embeddings de texte négatifs pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, *par ex.* le pondération des prompts. S'il n'est pas fourni et que `guidance_scale > 1`, les embeddings négatifs seront générés à partir d'une chaîne vide.

prompt_attention_mask (`torch.BoolTensor`, *facultatif*) : Masque d'attention pré-généré pour `prompt_embeds`. S'il n'est pas fourni, le masque d'attention sera généré à partir de l'argument d'entrée `prompt`.

negative_prompt_attention_mask (`torch.BoolTensor`, *facultatif*) : Masque d'attention pré-généré pour `negative_prompt_embeds`. S'il n'est pas fourni et que `guidance_scale > 1`, le masque d'attention sera généré à partir d'une chaîne vide.

output_type (`str`, *facultatif*, par défaut `"pil"`) : Le format de sortie de l'image générée. Choisissez entre [PIL](https://pillow.readthedocs.io/en/stable/) : `PIL.Image.Image` ou `np.array`.

return_dict (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut retourner un [PRXPipelineOutput](/docs/diffusers/v0.43.0/fr/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) plutôt qu'un simple tuple.

use_resolution_binning (`bool`, *facultatif*, valeur par défaut `True`) : Si défini sur `True`, la hauteur et la largeur demandées sont d'abord mappées sur les résolutions les plus proches à l'aide de bins de ratio d'aspect prédéfinis. Après le décodage des latents produits en images, celles-ci sont redimensionnées pour revenir à la résolution demandée. Utile pour générer des images non carrées à des résolutions optimales.

callback_on_step_end (`Callable`, *facultatif*) : Une fonction appelée à la fin de chaque étape de débruitage pendant l’inférence. La fonction est appelée avec les arguments suivants : `callback_on_step_end(self, step, timestep, callback_kwargs)`. `callback_kwargs` contiendra une liste de tous les tenseurs, comme spécifié par `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, *facultatif*) : La liste des entrées de tenseurs pour la fonction `callback_on_step_end`. Les tenseurs spécifiés dans la liste seront passés en tant qu'argument `callback_kwargs`. Vous ne pourrez inclure que les tenseurs répertoriés dans l'attribut `._callback_tensor_inputs`.

**Retourne :** [PRXPipelineOutput](/docs/diffusers/v0.43.0/fr/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) ou `tuple`

[PRXPipelineOutput](/docs/diffusers/v0.43.0/fr/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) si `return_dict` est True, sinon un `tuple. En cas de retour d'un tuple, le premier élément est une liste contenant les images générées.

Fonction appelée lors de l'appel du pipeline pour la génération.

Exemples :
```py
>>> import torch
>>> from diffusers import PRXPixelPipeline

>>> pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> prompt = "A front-facing portrait of a lion in the golden savanna at sunset."
>>> image = pipe(prompt, num_inference_steps=28, guidance_scale=5.0).images[0]
>>> image.save("prxpixel_output.png")
```

#### check_inputs[[diffusers.PRXPixelPipeline.check_inputs]]

```python
check_inputs(prompt: str | list[str], height: int, width: int, guidance_scale: float, callback_on_step_end_tensor_inputs: list[str] | None = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L324)

Vérifiez que toutes les entrées sont au format correct.

#### encode_prompt[[diffusers.PRXPixelPipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], device: typing.Optional[torch.device] = None, do_classifier_free_guidance: bool = True, negative_prompt: str = '', num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, negative_prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, tokenizer_max_length: int | None = None, skip_text_cleaning: bool = False)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L263)

Encodez le prompt de texte à l'aide d'un encodeur et d'un tokeniseur de texte standard, ou utilisez des embeddings précalculés.

#### prepare_latents[[diffusers.PRXPixelPipeline.prepare_latents]]

```python
prepare_latents(batch_size: int, num_channels_latents: int, height: int, width: int, dtype: dtype, device: device, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L378)

Préparez les latents initiaux pour le processus de diffusion.

PRXPixel s’entraîne avec une échelle de bruit initial non unitaire, de sorte que le bruit échantillonné est multiplié par `self.config.noise_scale`.

## PRXPipelineOutput[[diffusers.pipelines.prx.PRXPipelineOutput]]

#### diffusers.pipelines.prx.PRXPipelineOutput[[diffusers.pipelines.prx.PRXPipelineOutput]]

```python
diffusers.pipelines.prx.PRXPipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/prx/pipeline_output.py#L24)

**Paramètres :**

images (`list[PIL.Image.Image]` ou `np.ndarray`) : liste d'images PIL débruitées de longueur `batch_size` ou tableau numpy de forme `(batch_size, height, width, num_channels)`. Les images PIL ou le tableau numpy présentent les images débruitées du pipeline de diffusion.

Classe de sortie pour les pipelines PRX.