# P-H3-Image

P-H3-Image es un modelo de imágenes de Pruna AI basado en [MiniMax-H3](./minimax_h3), para la generación de imágenes a partir de texto y la edición de imágenes basada en instrucciones. Puedes encontrar el checkpoint en [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]
```

Cada solicitud pasa primero por el [prompt upsampler](#prompt-upsampling). Con cada componente en el acelerador, el pipeline necesita aproximadamente 101 GB en bfloat16 a 8 megapíxeles, por lo que los ejemplos usan auto offloading: el [ComponentsManager](/docs/diffusers/v0.43.0/es/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) mueve cada componente al acelerador cuando un bloque lo necesita, y el pipeline se ejecuta en una GPU de 80 GB.

## Componentes

| Componente | Clase |
|---|---|
| `transformer` | [MiniMaxH3Transformer3DModel](/docs/diffusers/v0.43.0/es/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration` (Qwen3-VL-4B) |
| `text_connector` | [PH3ImageTextConnector](/docs/diffusers/v0.43.0/es/api/pipelines/p_h3_image#diffusers.PH3ImageTextConnector) |
| `vae` | [AutoencoderKLPH3Image](/docs/diffusers/v0.43.0/es/api/models/autoencoderkl_p_h3_image#diffusers.AutoencoderKLPH3Image) |
| `tokenizer`, `processor` | El tokenizador del codificador de texto y un `Qwen3VLProcessor` con el procesador de imágenes de MiniMax-H3 |
| `scheduler`, `audio_scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/v0.43.0/es/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |
| `prompt_upsampler`, `prompt_upsampler_processor` | `Qwen3_5ForConditionalGeneration` (basado en Qwen3.5-9B) y su procesador |

## Flujos de trabajo

El flujo de trabajo se selecciona en la entrada `image`:

- **`text2image`** genera a partir de `prompt`. `height` y `width` tienen un valor predeterminado de 2912 y se redondean a múltiplos de 32. El modelo funciona mejor con 8 megapíxeles, por ejemplo 2912x2912, 3872x2176 o 2176x3872.
- **`image_conditioned`** edita `image` según la instrucción en `prompt` y funciona mejor con 4 o 8 megapíxeles. La imagen se codifica a unos `vision_pixels` (un megapíxel) para el codificador de texto y a su propio tamaño para el VAE, escalándose hacia arriba hasta `reference_min_pixels` (un megapíxel) o hacia abajo hasta `reference_max_pixels` (ocho megapíxeles) si está fuera de ese rango. Sin `height` y `width`, la edición se genera con el tamaño de la primera imagen, que se escala hacia arriba hasta `canvas_min_pixels` (cuatro megapíxeles) si es más pequeña. Si se pasan `height` y `width`, redondeados a múltiplos de 32, cambian el lienzo pero no las imágenes. `image` también puede ser una lista de hasta 8 imágenes: la primera se edita y las demás son referencias, como `<Picture 2>`, `<Picture 3>` y así sucesivamente.

## Ampliación de prompts

P-H3-Image está diseñado para renderizar prompts completos en lugar de solicitudes cortas, por lo que la pipeline ejecuta primero el prompt upsampler en cada solicitud. Reflexiona sobre la solicitud y luego escribe el prompt: un prompt detallado de texto a imagen para la relación de aspecto de `height` y `width`, o, al editar, un breve de qué conservar y qué cambiar en las imágenes. El prompt que escribió se devuelve como la salida `prompt`.

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

`max_new_tokens` limita el razonamiento y el prompt juntos, con un valor predeterminado de 1024 tokens para texto a imagen y 1536 para ediciones. Si el amplificador no devuelve un prompt utilizable, la canalización lanza un error en lugar de renderizarlo.

Para renderizar `prompt` tal como se indica, extrae el paso de los bloques. El bloque extraído también se ejecuta de forma independiente, por ejemplo, para mostrar el prompt a un usuario antes de renderizarlo:

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

Sin el paso, un prompt de edición en cualquiera de las dos formas que escribe el upsampler, el breve de seis secciones o un párrafo que comienza con `Edit <Picture 1>.`, se codifica tal como está escrito; cualquier otra instrucción recibe ese prefijo.

## Muestreo

- Los 8 pasos se ejecutan sobre `sample_sigmas` del checkpoint. Pasa `sigmas` para usar otra cuadrícula.
- El modelo está destilado con guía, por lo que no hay un guionista, `negative_prompt` ni `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)
```

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/p_h3_image/modular_pipeline.py#L22)

Un ModularPipeline para P-H3-Image, un modelo de imágenes basado en MiniMax-H3, para la generación de imágenes a partir de texto (`text2image`) y la edición basada en instrucciones (`image_conditioned`).

La imagen es un único marco latente, desruidado en una secuencia empaquetada con dos latentes de audio que se descartan.

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

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/p_h3_image/modular_blocks_p_h3_image.py#L376)

Bloques de pipeline modulares para P-H3-Image: `text2image` y edición basada en instrucciones (`image_conditioned`) cuando se pasa `image`. `prompt` pasa primero por el prompt upsampler; elimina el paso `prompt_upsampler` para renderizarlo tal como se proporciona.

Flujos de trabajo admitidos:
- `text2image`: requiere `prompt`
- `image_conditioned`: requiere `prompt`, `image`

Componentes: image_processor (`VaeImageProcessor`) prompt_upsampler (`Qwen3_5ForConditionalGeneration`): El amplificador de prompts. prompt_upsampler_processor (`AutoProcessor`): Su procesador. text_encoder (`Qwen3VLForConditionalGeneration`) text_connector (`PH3ImageTextConnector`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLPH3Image`) scheduler (`MiniMaxH3Scheduler`) audio_scheduler (`MiniMaxH3Scheduler`) transformer (`MiniMaxH3Transformer3DModel`)

Configuraciones: reference_min_pixels (predeterminado: 1048576) reference_max_pixels (predeterminado: 8388608) canvas_min_pixels (predeterminado:
4194304) vision_pixels (valor predeterminado: 1000000) sample_sigmas (valor predeterminado: [1.0, 0.984753, 0.967905, 0.951688,
0.925372, 0.881923, 0.810083, 0.528718, 0.0]): La cuadrícula de muestreo del checkpoint, que se utiliza cuando no se pasa `sigmas`.

Entradas: image (`Image | list`, *opcional*): La imagen a editar, o una lista de un máximo de 8 imágenes: la primera se edita y las demás son referencias. height (`int`, *opcional*): Altura de la imagen generada en píxeles, redondeada a un múltiplo de 32. El valor predeterminado para `text2image` es 2912, que funciona mejor a 8 megapíxeles. Una edición usa por defecto el tamaño de la primera imagen, al menos `canvas_min_pixels`, y funciona mejor a 4 u 8 megapíxeles. width (`int`, *opcional*): Ancho de la imagen generada en píxeles, redondeado a un múltiplo de 32. El valor predeterminado para `text2image` es 2912, que funciona mejor a 8 megapíxeles. Una edición usa por defecto el tamaño de la primera imagen, al menos `canvas_min_pixels`, y funciona mejor a 4 u 8 megapíxeles. prompt (`str`): El prompt, o la instrucción de edición cuando se pasa `image`. Una sola cadena. max_new_tokens (`int`, *opcional*, predeterminado a 1536 o 1024, según el flujo de trabajo): El número máximo de tokens que puede generar el amplificador, incluida su razonamiento. vision_images (`list`, *opcional*): Las imágenes de la edición redimensionadas para el codificador de texto, con la imagen a editar primero. reference_images (`list`, *opcional*): Las imágenes de la edición redimensionadas para el VAE, con la imagen a editar primero. condition_latents (`list`, *opcional*): Los latentes de condicionamiento de las imágenes de la edición. Sus formas definen la geometría de los bloques de referencia. generator (`Generator`, *opcional*): El generador de la solicitud. El ruido de condicionamiento se extrae de él primero, una extracción por condición, antes del ruido de las filas generadas. latents (`Tensor`): Ruido de imagen pregenerado de forma `(1, latent_channels, 1, latent_height, latent_width)`, usado en lugar de la extracción. sigmas (`list`, *opcional*): Una cuadrícula de muestreo personalizada, estrictamente decreciente y que termina en 0. El valor predeterminado es `sample_sigmas` del punto de control. **denoiser_input_fields (`None`, *opcional*): La descripción estructural de la secuencia empaquetada que el transformer lee por nombre: `token_tags`, `position_ids` y los tres tensores de índice de fila. attention_kwargs (`dict`, *opcional*): Kwargs adicionales para los procesadores de atención. output_type (`str`, *opcional*, predeterminado a pil): Formato de salida: 'pil', 'np', 'pt'.

Salidas: imágenes (`list`): Imágenes generadas.

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

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/condition_embedders/condition_embedder_p_h3_image.py#L22)

**Parámetros:**

hidden_state_indices (`tuple[int, ...]`, por defecto `(13, 19, 25, 31, 36)`) : Qué entradas de `hidden_states` del codificador de texto se leen, según la numeración de `output_hidden_states` (`0` es la salida de la incrustación, `i` la salida de la capa decodificadora `i`, y la última el estado oculto final normalizado).

text_hidden_size (`int`, por defecto `2560`) : El tamaño oculto del codificador de texto.

out_channels (`int`, por defecto `5120`) : El número de canales que lee el transformer de condicionamiento de MiniMax-H3.

Mapea los estados ocultos del codificador de texto Qwen3-VL de P-H3-Image a la condición de texto que lee su transformer.

Los estados ocultos listados en `hidden_state_indices` se concatenan, estandarizan, proyectan linealmente y desestandarizan. El primer token es un sumidero de atención con el mismo condicionamiento para cada prompt, por lo que se reemplaza por `sink_embedding`.

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

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

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/condition_embedders/condition_embedder_p_h3_image.py#L61)

**Parámetros:**

hidden_states (`tuple[torch.Tensor, ...]`) : Los estados ocultos del codificador de texto, tal como los devuelve `output_hidden_states=True`: un tensor de forma `(batch_size, num_tokens, text_hidden_size)` por entrada.

**Devuelve:** `torch.Tensor`

la señal de condicionamiento, de forma `(batch_size, num_tokens, out_channels)`, en el dtype de los parámetros del conector.