#
# Лицензия Apache License, Version 2.0 («Лицензия»);
# вы можете использовать этот файл только в соответствии с Лицензией.
# Вы можете получить копию Лицензии по адресу
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Если это не требуется применимым законодательством или не оговорено письменно, программное
# распространяется по Лицензии на условиях «КАК ЕСТЬ»,
# БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ ИЛИ УСЛОВИЙ, прямо указанных или подразумеваемых.
# См. Лицензию для получения конкретных условий, регулирующих разрешения и
# ограничениями Лицензии. -->

# PRX Pixel

PRXPixel — это модель генерации изображений из текста в пиксельном пространстве от Photoroom. Трансформер `PRXTransformer2DModel` объёмом около 7B выполняет денойзинг сырых RGB-изображений напрямую — VAE не требуется. Модель использует текстовый энкодер Qwen3-VL в качестве условия и применяет flow matching, при котором трансформер предсказывает чистое изображение на каждом шаге (x-prediction). Разрешение генерации передаётся в модуляцию временного шага, чтобы модель знала целевой размер.

## Доступные модели

| Модель | Разрешение | Описание | Рекомендуемые параметры | Рекомендуемый dtype |
|:-----:|:---------:|:----------:|:----------:|:----------:|
| [`Photoroom/prxpixel-t2i`](https://huggingface.co/Photoroom/prxpixel-t2i) | 1024 | Модель в пиксельном пространстве ~7B с текстовым энкодером Qwen3-VL | 28 шагов, cfg=5.0 | `torch.bfloat16` |

## Загрузка конвейера

[PRXPixelPipeline](/docs/diffusers/main/ru/api/pipelines/prx_pixel#diffusers.PRXPixelPipeline) требует `transformers >= 4.57` (версию, в которой была представлена `Qwen3VLTextModel`). Загрузите его с помощью [from_pretrained()](/docs/diffusers/main/ru/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")
```

## Оптимизация памяти

Для сред с ограниченной памятью:

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

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L98)

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

transformer (`PRXTransformer2DModel`) : Денойзер PRX с ~7B параметрами. Для PRXPixel он собирается с `in_channels=3`, бутылочным горлышком `img_in` и `resolution_embeds=True`, и обучается предсказывать чистое изображение `x0`.

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

text_encoder (`PreTrainedModel`): текстовый бэкбон Qwen3-VL, используемый для кодирования промптов (визуальная башня отбрасывается). Должен возвращать `last_hidden_state`.

tokenizer (`PreTrainedTokenizerBase`) : Токенизатор для `text_encoder` (обычно загружается через `AutoTokenizer`).

default_sample_size (`int`, *необязательный*, по умолчанию 1024) : Высота/ширина по умолчанию, используемые, если в `__call__` они не переданы.

prompt_max_tokens (`int`, *необязательный*, по умолчанию 256) : Количество текстовых токенов, до которого промпт дополняется или обрезается перед кодированием.

noise_scale (`float`, *optional*, по умолчанию 2.0) : Масштаб, применяемый к начальному гауссовому шуму. PRXPixel обучается с неединичным масштабом начального шума, поэтому сэмплирование должно начинаться с `randn * noise_scale`.

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

PRXPixel — это автономный конвейер генерации изображений по тексту в пиксельном пространстве. Он выполняет денойзинг сырых RGB-данных напрямую с помощью модели `PRXTransformer2DModel` на ~7 млрд параметров и не использует VAE (генерация происходит полностью в пиксельном пространстве, поэтому результат денойзинга *является* изображением). Промпты кодируются текстовым энкодером Qwen3-VL (зрительная башня отбрасывается). В отличие от [PRXPipeline](/docs/diffusers/main/ru/api/pipelines/prx#diffusers.PRXPipeline), трансформер обучен с использованием x-prediction: на каждом шаге он предсказывает чистое изображение `x0`, которое преобразуется в скорость flow-matching перед шагом планировщика. Сэмплирование начинается с `randn * noise_scale` (по умолчанию `noise_scale=2.0`), а разрешение по умолчанию составляет 1024 пикселя.

Эта модель наследуется от [DiffusionPipeline](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline). См. документацию родительского класса для общих методов, которые библиотека реализует для всех пайплайнов (например, загрузка или сохранение, запуск на конкретном устройстве и т. д.)

Примеры:
```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")
```

#### __call__[[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'])
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L406)

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

prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать `prompt_embeds`.

negative_prompt (`str`, *необязательный*, по умолчанию `""`) : Промпт или промпты, которые не должны направлять генерацию изображения. Игнорируется, если не используется направляющая (то есть игнорируется, если `guidance_scale` меньше `1`).

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

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

num_inference_steps (`int`, *optional*, по умолчанию 28) : Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода.

timesteps (`list[int]`, *optional*) : Пользовательские шаги для процесса денойзинга с планировщиками, поддерживающими аргумент `timesteps` в их методе `set_timesteps`. Если не определено, будет использоваться поведение по умолчанию при передаче `num_inference_steps`. Должны быть в порядке убывания.

guidance_scale (`float`, *optional*, по умолчанию 4.0) : Масштаб руководства, определённый в [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` определяется как `w` из уравнения 2 в [Imagen Paper](https://huggingface.co/papers/2205.11487). Масштаб руководства активируется при установке `guidance_scale > 1`. Более высокий масштаб руководства способствует генерации изображений, тесно связанных с текстовым `prompt`, обычно за счёт снижения качества изображения.

num_images_per_prompt (`int`, *необязательный*, по умолчанию 1) : Количество изображений, генерируемых на один запрос.

generator (`torch.Generator` или `list[torch.Generator]`, *необязательный*) : Один или список [генераторов torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) для обеспечения детерминированности генерации.

latents (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные зашумленные латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации изображений. Можно использовать, чтобы скорректировать одну и ту же генерацию с разными промптами. Если не предоставлены, тензор латентов будет сгенерирован путём выборки с использованием переданного случайного `generator`.

prompt_embeds (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, текстовые эмбеддинги будут сгенерированы из входного аргумента `prompt`.

negative_prompt_embeds (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные отрицательные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены и `guidance_scale > 1`, отрицательные эмбеддинги будут сгенерированы из пустой строки.

prompt_attention_mask (`torch.BoolTensor`, *необязательный*) : Предварительно сгенерированная маска внимания для `prompt_embeds`. Если не предоставлена, маска внимания будет сгенерирована из входного аргумента `prompt`.

negative_prompt_attention_mask (`torch.BoolTensor`, *необязательный*) : Предварительно сгенерированная маска внимания для `negative_prompt_embeds`. Если не указана и `guidance_scale > 1`, маска внимания будет сгенерирована из пустой строки.

output_type (`str`, *необязательный*, по умолчанию `"pil"`) : Формат вывода для генерируемого изображения. Выберите между [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` или `np.array`.

return_dict (`bool`, *необязательный*, по умолчанию `True`) : Возвращать ли [PRXPipelineOutput](/docs/diffusers/main/ru/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) вместо обычного кортежа.

use_resolution_binning (`bool`, *необязательный*, по умолчанию `True`) : Если установлено в `True`, запрашиваемые высота и ширина сначала сопоставляются с ближайшими разрешениями с использованием предопределённых диапазонов соотношений сторон. После декодирования полученных латентов в изображения они масштабируются обратно до запрошенного разрешения. Полезно для генерации несимметричных изображений с оптимальными разрешениями.

callback_on_step_end (`Callable`, *необязательный*) : функция, вызываемая в конце каждого шага денойзинга во время инференса. Функция вызывается со следующими аргументами: `callback_on_step_end(self, step, timestep, callback_kwargs)`. `callback_kwargs` будет содержать список всех тензоров, как указано в `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, *optional*) : Список тензорных входных данных для функции `callback_on_step_end`. Тензоры, указанные в списке, будут переданы в качестве аргумента `callback_kwargs`. Вы сможете включать только те тензоры, которые перечислены в атрибуте `._callback_tensor_inputs`.

**Возвращает:** [PRXPipelineOutput](/docs/diffusers/main/ru/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) или `tuple`

[PRXPipelineOutput](/docs/diffusers/main/ru/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput), если `return_dict` равно True, иначе — `tuple. При возврате кортежа первым элементом является список с сгенерированными изображениями.

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

Примеры:
```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)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L324)

Убедитесь, что все входные данные имеют правильный формат.

#### 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)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L263)

Кодируйте текстовый промпт с помощью стандартного текстового энкодера и токенизатора или используйте предварительно вычисленные эмбеддинги.

#### 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)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L378)

Подготовьте начальные латенты для процесса диффузии.

PRXPixel обучается с начальным масштабом шума, отличным от единицы, поэтому сэмплированный шум умножается на `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)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_output.py#L24)

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

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

Класс вывода для конвейеров PRX.