# P-H3-Image

P-H3-Image — это модель для работы с изображениями от Pruna AI, основанная на [MiniMax-H3](./minimax_h3), предназначенная для генерации изображений по текстовому описанию и редактирования изображений по инструкциям. Чекпоинт доступен по адресу [PrunaAI/P-H3-Image](https://huggingface.co/PrunaAI/P-H3-Image).

```py
import torch
from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu"

pipe = ModularPipeline.from_pretrained("PrunaAI/P-H3-Image", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

prompt = (
    "A German Expressionist oil painting of a Berlin street at night in the manner of Ernst Ludwig Kirchner, "
    "with gaunt figures hurrying past a glowing gas lamp."
)
image = pipe(prompt=prompt, height=3360, width=2496, generator=torch.Generator().manual_seed(3), output="images")[0]
edited = pipe(prompt="let it snow on the street", image=image, output="images")[0]
```

Каждый запрос сначала проходит через [prompt upsampler](#prompt-upsampling). При размещении всех компонентов на ускорителе конвейеру требуется около 101 ГБ в формате bfloat16 для разрешения 8 мегапикселей, поэтому в примерах используется автоматическое выгружение: [ComponentsManager](/docs/diffusers/v0.43.0/ru/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) перемещает каждый компонент на ускоритель, когда блок в нём нуждается, и конвейер работает на GPU объёмом 80 ГБ.

## Компоненты

| Компонент | Класс |
|---|---|
| `transformer` | [MiniMaxH3Transformer3DModel](/docs/diffusers/v0.43.0/ru/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration` (Qwen3-VL-4B) |
| `text_connector` | [PH3ImageTextConnector](/docs/diffusers/v0.43.0/ru/api/pipelines/p_h3_image#diffusers.PH3ImageTextConnector) |
| `vae` | [AutoencoderKLPH3Image](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl_p_h3_image#diffusers.AutoencoderKLPH3Image) |
| `tokenizer`, `processor` | Токенизатор текстового энкодера и `Qwen3VLProcessor` с обработчиком изображений MiniMax-H3 |
| `scheduler`, `audio_scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |
| `prompt_upsampler`, `prompt_upsampler_processor` | `Qwen3_5ForConditionalGeneration` (на базе Qwen3.5-9B) и его процессор |

## Рабочие процессы

Рабочий процесс выбирается на входе `image`:

- **`text2image`** генерирует изображение из `prompt`. Значения `height` и `width` по умолчанию равны 2912 и округляются до кратных 32. Модель лучше всего работает при разрешении 8 мегапикселей, например 2912x2912, 3872x2176 или 2176x3872.
- **`image_conditioned`** редактирует `image` по инструкции из `prompt` и лучше всего работает при разрешении 4 или 8 мегапикселей. Изображение кодируется примерно в `vision_pixels` (один мегапиксель) для текстового энкодера и в собственном размере для VAE, при этом при выходе за пределы диапазона оно масштабируется до `reference_min_pixels` (один мегапиксель) или до `reference_max_pixels` (восемь мегапикселей). Если не указаны `height` и `width`, результат редактирования генерируется в размере первого изображения, которое при необходимости масштабируется до `canvas_min_pixels` (четыре мегапикселя). Переданные `height` и `width`, округленные до кратных 32, изменяют размер холста, но не самих изображений. `image` также может быть списком из не более чем 8 изображений: первое редактируется, а остальные используются как референсы, например `<Picture 2>`, `<Picture 3>` и так далее.

## Увеличение размера промпта

P-H3-Image предназначен для обработки полных промптов, а не коротких запросов, поэтому конвейер сначала запускает апсемплер промпта для каждого запроса. Он анализирует запрос, а затем формирует промпт: детальный текст для генерации изображения с соотношением сторон `height` и `width` или, при редактировании, краткое описание того, что следует сохранить, а что изменить на изображениях. Сформированный промпт возвращается как вывод `prompt`.

```py
out = pipe(prompt=prompt, height=3360, width=2496, output=["images", "prompt"])
print(out["prompt"])
```

`max_new_tokens` ограничивает суммарную длину рассуждений и промпта: по умолчанию 1024 токена для генерации изображений по тексту и 1536 для редактирования. Если апсемплер не возвращает пригодный для использования промпт, конвейер выбрасывает ошибку, а не пытается отрисовать изображение.

Чтобы отобразить `prompt` в исходном виде, извлеките шаг из блоков. Извлечённый блок также может выполняться самостоятельно, например, чтобы показать промпт пользователю перед его отображением:

```py
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")

blocks = ModularPipeline.from_pretrained("PrunaAI/P-H3-Image").blocks
upsampler_block = blocks.sub_blocks.pop("prompt_upsampler")

upsampler = upsampler_block.init_pipeline("PrunaAI/P-H3-Image", components_manager=manager)
upsampler.load_components(dtype=torch.bfloat16)
upsampled = upsampler(prompt=prompt, height=3360, width=2496, output="prompt")

pipe = blocks.init_pipeline("PrunaAI/P-H3-Image", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)
image = pipe(prompt=upsampled, height=3360, width=2496, output="images")[0]
```

Без этого шага подсказка для редактирования в любом из форматов, которые записывает апскейлер, — шестисекционный бриф или абзац, начинающийся с `Edit <Picture 1>.`, — кодируется в том виде, в каком она написана; любое другое указание получает этот префикс.

## Выборка

- 8 шагов выполняются по `sample_sigmas` контрольной точки. Передайте `sigmas`, чтобы использовать другую сетку.
- Модель получена с помощью дистилляции с наведением, поэтому в ней нет наводящего элемента, `negative_prompt` или `guidance_scale`.

## PH3ImageModularPipeline[[diffusers.PH3ImageModularPipeline]]

#### diffusers.PH3ImageModularPipeline[[diffusers.PH3ImageModularPipeline]]

```python
diffusers.PH3ImageModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/p_h3_image/modular_pipeline.py#L22)

A ModularPipeline for P-H3-Image, an image model based on MiniMax-H3, for text-to-image (`text2image`) and instruction-based editing (`image_conditioned`).

Изображение представляет собой единственную латентную рамку, очищенную от шума в одной упакованной последовательности с двумя латентными аудио, которые отбрасываются.

```py
import torch
from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")

pipe = ModularPipeline.from_pretrained("PrunaAI/P-H3-Image", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)
prompt = (
    "A German Expressionist oil painting of a Berlin street at night in the manner of Ernst Ludwig Kirchner, "
    "with gaunt figures hurrying past a glowing gas lamp."
)
image = pipe(prompt=prompt, height=3360, width=2496, output="images")[0]
```

## PH3ImageBlocks[[diffusers.PH3ImageBlocks]]

#### diffusers.PH3ImageBlocks[[diffusers.PH3ImageBlocks]]

```python
diffusers.PH3ImageBlocks()
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/p_h3_image/modular_blocks_p_h3_image.py#L376)

Модульные блоки конвейера для P-H3-Image: `text2image` и редактирование по инструкции (`image_conditioned`), когда передан `image`. `prompt` сначала проходит через prompt upsampler; чтобы отобразить его в исходном виде, удалите шаг `prompt_upsampler`.

Поддерживаемые рабочие процессы:
- `text2image`: требуется `prompt`
- `image_conditioned`: требуется `prompt`, `image`

Компоненты: image_processor (`VaeImageProcessor`) prompt_upsampler (`Qwen3_5ForConditionalGeneration`): модуль улучшения промпта. prompt_upsampler_processor (`AutoProcessor`): его процессор. text_encoder (`Qwen3VLForConditionalGeneration`) text_connector (`PH3ImageTextConnector`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLPH3Image`) scheduler (`MiniMaxH3Scheduler`) audio_scheduler (`MiniMaxH3Scheduler`) transformer (`MiniMaxH3Transformer3DModel`)

Конфигурации: reference_min_pixels (по умолчанию: 1048576) reference_max_pixels (по умолчанию: 8388608) canvas_min_pixels (по умолчанию:
4194304) vision_pixels (по умолчанию: 1000000) sample_sigmas (по умолчанию: [1.0, 0.984753, 0.967905, 0.951688,
0.925372, 0.881923, 0.810083, 0.528718, 0.0]): сетка дискретизации чекпоинта, используемая, если `sigmas` не передан.

Входные данные: image (`Image | list`, *необязательный*): Изображение для редактирования или список из не более чем 8 изображений: первое редактируется, остальные используются как референсы. height (`int`, *необязательный*): Высота сгенерированного изображения в пикселях, округленная до кратного 32. По умолчанию для `text2image` составляет 2912, что оптимально для 8 мегапикселей. Для редактирования по умолчанию используется размер первого изображения, не менее `canvas_min_pixels`, оптимально 4 или 8 мегапикселей. width (`int`, *необязательный*): Ширина сгенерированного изображения в пикселях, округленная до кратного 32. По умолчанию для `text2image` составляет 2912, что оптимально для 8 мегапикселей. Для редактирования по умолчанию используется размер первого изображения, не менее `canvas_min_pixels`, оптимально 4 или 8 мегапикселей. prompt (`str`): Промпт или инструкция по редактированию, если передан `image`. Строка. max_new_tokens (`int`, *необязательный*, по умолчанию 1536 или 1024 в зависимости от рабочего процесса): Максимальное количество токенов, которое может сгенерировать апскейлер, включая его рассуждения. vision_images (`list`, *необязательный*): Изображения для редактирования, изменённые по размеру для текстового энкодера, изображение для редактирования первым. reference_images (`list`, *необязательный*): Изображения для редактирования, изменённые по размеру для VAE, изображение для редактирования первым. condition_latents (`list`, *необязательный*): Латенты условий для изображений редактирования. Их формы задают геометрию референсных блоков. generator (`Generator`, *необязательный*): Генератор запроса. Шум условий извлекается из него первым, одно извлечение на каждое условие, до шума сгенерированных строк. latents (`Tensor`): Предсгенерированный шум изображения формы `(1, latent_channels, 1, latent_height, latent_width)`, используется вместо извлечения. sigmas (`list`, *необязательный*): Пользовательская сетка сэмплирования, строго убывающая и заканчивающаяся на 0. По умолчанию `sample_sigmas` из чекпоинта. **denoiser_input_fields (`None`, *необязательный*): Структурное описание упакованной последовательности, которую трансформер читает по имени: `token_tags`, `position_ids` и три тензора индексов строк. attention_kwargs (`dict`, *необязательный*): Дополнительные kwargs для процессоров внимания. output_type (`str`, *необязательный*, по умолчанию pil): Формат вывода: 'pil', 'np', 'pt'.

Вывод: изображения (`list`): сгенерированные изображения.

## PH3ImageTextConnector[[diffusers.PH3ImageTextConnector]]

#### diffusers.PH3ImageTextConnector[[diffusers.PH3ImageTextConnector]]

```python
diffusers.PH3ImageTextConnector(hidden_state_indices: tuple[int, ...] = (13, 19, 25, 31, 36), text_hidden_size: int = 2560, out_channels: int = 5120)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/condition_embedders/condition_embedder_p_h3_image.py#L22)

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

hidden_state_indices (`tuple[int, ...]`, по умолчанию `(13, 19, 25, 31, 36)`) : какие записи из `hidden_states` текстового энкодера читаются, в нумерации `output_hidden_states` (`0` — выход эмбеддинга, `i` — выход декодерного слоя `i`, а последняя — финальное нормированное скрытое состояние).

text_hidden_size (`int`, по умолчанию `2560`) : Размер скрытого слоя текстового энкодера.

out_channels (`int`, по умолчанию `5120`) : Количество каналов, которые читает трансформер MiniMax-H3 для условного сигнала.

Отображает скрытые состояния текстового энкодера Qwen3-VL модели P-H3-Image в текстовые условия, которые читает её трансформер.

Скрытые состояния, перечисленные в `hidden_state_indices`, конкатенируются, стандартизируются, проецируются линейно и дестандартизируются. Первый токен является attention sink с одинаковым условием для каждого промпта, поэтому он заменяется на `sink_embedding`.

#### forward[[diffusers.PH3ImageTextConnector.forward]]

```python
forward(hidden_states: tuple[torch.Tensor, ...])
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/condition_embedders/condition_embedder_p_h3_image.py#L61)

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

hidden_states (`tuple[torch.Tensor, ...]`) : Скрытые состояния текстового энкодера, как их возвращает `output_hidden_states=True`: один тензор формы `(batch_size, num_tokens, text_hidden_size)` на каждый элемент.

**Возвращает:** `torch.Tensor`

условие, с формой `(batch_size, num_tokens, out_channels)`, в типе данных параметров коннектора.