# P-H3-Image

P-H3-Image est un modèle d’images de Pruna AI basé sur [MiniMax-H3](./minimax_h3), destiné à la génération d’images à partir de texte et à l’édition d’images par instructions. Vous pouvez trouver le point de contrôle sur [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]
```

Chaque requête passe d'abord par le [prompt upsampler](#prompt-upsampling). Avec chaque composant sur l'accélérateur, le pipeline nécessite environ 101 Go en bfloat16 à 8 mégapixels, les exemples utilisent donc le déchargement automatique : le [ComponentsManager](/docs/diffusers/main/fr/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) déplace chaque composant sur l'accélérateur lorsqu'un bloc en a besoin, et le pipeline s'exécute sur un GPU de 80 Go.

## Composants

| Composant | Classe |
|---|---|
| `transformer` | [MiniMaxH3Transformer3DModel](/docs/diffusers/main/fr/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration` (Qwen3-VL-4B) |
| `text_connector` | [PH3ImageTextConnector](/docs/diffusers/main/fr/api/pipelines/p_h3_image#diffusers.PH3ImageTextConnector) |
| `vae` | [AutoencoderKLPH3Image](/docs/diffusers/main/fr/api/models/autoencoderkl_p_h3_image#diffusers.AutoencoderKLPH3Image) |
| `tokenizer`, `processor` | Le tokenizer de l'encodeur de texte, et un `Qwen3VLProcessor` avec le processeur d'images de MiniMax-H3 |
| `scheduler`, `audio_scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/main/fr/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |
| `prompt_upsampler`, `prompt_upsampler_processor` | `Qwen3_5ForConditionalGeneration` (basé sur Qwen3.5-9B) et son processeur |

## Flux de travail

Le flux de travail est sélectionné sur l'entrée `image` :

- **`text2image`** génère à partir de `prompt`. `height` et `width` sont par défaut 2912 et sont arrondis aux multiples de 32. Le modèle fonctionne le mieux à 8 mégapixels, par exemple 2912x2912, 3872x2176 ou 2176x3872.
- **`image_conditioned`** modifie `image` selon l’instruction contenue dans `prompt` et fonctionne de manière optimale à 4 ou 8 mégapixels. L’image est encodée à environ `vision_pixels` (un mégapixel) pour l’encodeur de texte et à sa propre taille pour le VAE, mise à l’échelle vers le haut jusqu’à `reference_min_pixels` (un mégapixel) ou vers le bas jusqu’à `reference_max_pixels` (huit mégapixels) si elle se situe en dehors de cette plage. En l’absence de `height` et `width`, la modification est générée à la taille de la première image, qui est mise à l’échelle vers le haut jusqu’à `canvas_min_pixels` (quatre mégapixels) si elle est plus petite. Les valeurs transmises pour `height` et `width`, arrondies aux multiples de 32, modifient le canevas mais pas les images. `image` peut également être une liste d’au plus 8 images : la première est modifiée et les autres servent de références, comme `<Picture 2>`, `<Picture 3>` et ainsi de suite.

## Échantillonnage supérieur des prompts

P-H3-Image est conçu pour générer des prompts complets plutôt que de courtes requêtes, le pipeline exécute donc d'abord l'amplificateur de prompt sur chaque requête. Il analyse la requête puis rédige le prompt : un prompt texte-vers-image détaillé pour le ratio d'aspect de `height` et `width`, ou, lors d'une édition, un brief indiquant ce qu'il faut conserver et ce qu'il faut modifier dans les images. Le prompt rédigé est renvoyé en tant que sortie `prompt`.

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

`max_new_tokens` limite le raisonnement et le prompt ensemble, avec 1024 jetons par défaut pour le texte-vers-image et 1536 pour les modifications. Si l’upsampler ne renvoie pas un prompt utilisable, le pipeline lève une erreur au lieu de le rendre.

Pour afficher `prompt` tel quel, retirez l'étape des blocs. Le bloc retiré s'exécute également de manière autonome, par exemple pour afficher le prompt à un utilisateur avant son rendu :

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

Sans cette étape, un prompt d’édition, quelle que soit la forme écrite par l’upsampler, le bref en six sections ou un paragraphe commençant par `Edit <Picture 1>.`, est encodé tel quel ; toute autre instruction reçoit ce préfixe.

## Échantillonnage

- Les 8 étapes s'exécutent sur les `sample_sigmas` du point de contrôle. Passez `sigmas` pour utiliser une autre grille.
- Le modèle est distillé avec guidage, il n'y a donc ni guideur, ni `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)
```

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

Un ModularPipeline pour P-H3-Image, un modèle d’image basé sur MiniMax-H3, pour la génération d’images à partir de texte (`text2image`) et l’édition basée sur des instructions (`image_conditioned`).

L'image est une seule trame latente, débruitée dans une séquence compacte unique avec deux latents audio qui sont jetés.

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

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

Blocs de pipeline modulaires pour P-H3-Image : `text2image`, et édition basée sur des instructions (`image_conditioned`) lorsque `image` est transmis. `prompt` passe d'abord par l'amplificateur de prompt ; supprimez l'étape `prompt_upsampler` pour le rendre tel quel.

Workflows pris en charge :
- `text2image` : nécessite `prompt`
- `image_conditioned` : nécessite `prompt`, `image`

Composants : image_processor (`VaeImageProcessor`) prompt_upsampler (`Qwen3_5ForConditionalGeneration`) : Le modèle d’amélioration du prompt. prompt_upsampler_processor (`AutoProcessor`) : Son processeur. text_encoder (`Qwen3VLForConditionalGeneration`) text_connector (`PH3ImageTextConnector`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLPH3Image`) scheduler (`MiniMaxH3Scheduler`) audio_scheduler (`MiniMaxH3Scheduler`) transformer (`MiniMaxH3Transformer3DModel`)

Configurations : reference_min_pixels (par défaut : 1048576) reference_max_pixels (par défaut : 8388608) canvas_min_pixels (par défaut :
4194304) vision_pixels (défaut : 1000000) sample_sigmas (défaut : [1.0, 0.984753, 0.967905, 0.951688,
0.925372, 0.881923, 0.810083, 0.528718, 0.0]) : la grille d'échantillonnage du checkpoint, utilisée lorsque `sigmas` n'est pas transmis.

Entrées : image (`Image | list`, *facultatif*) : L'image à éditer, ou une liste d'au maximum 8 images : la première est éditée, les autres servent de références. height (`int`, *facultatif*) : Hauteur de l'image générée en pixels, arrondie à un multiple de 32. La valeur par défaut est 2912 pour `text2image`, ce qui fonctionne le mieux à 8 mégapixels. Pour une édition, la valeur par défaut est la taille de la première image, au minimum `canvas_min_pixels`, et fonctionne le mieux à 4 ou 8 mégapixels. width (`int`, *facultatif*) : Largeur de l'image générée en pixels, arrondie à un multiple de 32. La valeur par défaut est 2912 pour `text2image`, ce qui fonctionne le mieux à 8 mégapixels. Pour une édition, la valeur par défaut est la taille de la première image, au minimum `canvas_min_pixels`, et fonctionne le mieux à 4 ou 8 mégapixels. prompt (`str`) : Le prompt, ou l'instruction d'édition lorsque `image` est transmis. Une seule chaîne de caractères. max_new_tokens (`int`, *facultatif*, valeurs par défaut 1536 ou 1024, selon le flux de travail) : Le nombre maximal de jetons que l'amplificateur peut générer, son raisonnement inclus. vision_images (`list`, *facultatif*) : Les images de l'édition redimensionnées pour l'encodeur de texte, l'image à éditer en premier. reference_images (`list`, *facultatif*) : Les images de l'édition redimensionnées pour le VAE, l'image à éditer en premier. condition_latents (`list`, *facultatif*) : Les latents de conditionnement des images de l'édition. Leurs formes définissent la géométrie des blocs de référence. generator (`Generator`, *facultatif*) : Le générateur de la requête. Le bruit de conditionnement est d'abord tiré de celui-ci, un tirage par condition, avant le bruit des lignes générées. latents (`Tensor`) : Bruit d'image pré-généré de forme `(1, latent_channels, 1, latent_height, latent_width)`, utilisé à la place du tirage. sigmas (`list`, *facultatif*) : Une grille d'échantillonnage personnalisée, strictement décroissante et se terminant à 0. La valeur par défaut est `sample_sigmas` du point de contrôle. **denoiser_input_fields (`None`, *facultatif*) : La description structurelle de la séquence compacte que le transformateur lit par nom : `token_tags`, `position_ids` et les trois tenseurs d'indices de lignes. attention_kwargs (`dict`, *facultatif*) : Arguments supplémentaires pour les processeurs d'attention. output_type (`str`, *facultatif*, valeur par défaut pil) : Format de sortie : 'pil', 'np', 'pt'.

Sorties : images (`list`) : Images générées.

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

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

**Paramètres :**

hidden_state_indices (`tuple[int, ...]`, par défaut `(13, 19, 25, 31, 36)`) : Quelles entrées des `hidden_states` de l'encodeur de texte sont lues, selon la numérotation de `output_hidden_states` (`0` est la sortie des embeddings, `i` la sortie de la couche décodeur `i`, et la dernière la dernière état caché normalisé final).

text_hidden_size (`int`, par défaut `2560`) : La taille cachée de l'encodeur de texte.

out_channels (`int`, par défaut `5120`) : Le nombre de canaux du transformer de conditionnement de MiniMax-H3.

Cartographie les états cachés de l'encodeur de texte Qwen3-VL de P-H3-Image vers la condition de texte que son transformateur lit.

Les états cachés listés dans `hidden_state_indices` sont concaténés, standardisés, projetés linéairement puis déstandardisés. Le premier jeton est un puits d'attention avec le même conditionnement pour chaque invite, il est donc remplacé par `sink_embedding`.

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

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

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

**Paramètres :**

hidden_states (`tuple[torch.Tensor, ...]`) : Les états cachés de l'encodeur de texte, tels que renvoyés par `output_hidden_states=True` : un tenseur de forme `(batch_size, num_tokens, text_hidden_size)` par entrée.

**Retourne :** `torch.Tensor`

le conditionnement, de forme `(batch_size, num_tokens, out_channels)`, dans le dtype des paramètres du connecteur.