# P-H3-Image P-H3-Image é um modelo de imagem da Pruna AI baseado no [MiniMax-H3](./minimax_h3), para geração de imagens a partir de texto e edição de imagens baseada em instruções. Você pode encontrar o checkpoint em [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 solicitação passa primeiro pelo [prompt upsampler](#prompt-upsampling). Com todos os componentes no acelerador, o pipeline precisa de cerca de 101 GB em bfloat16 a 8 megapixels, portanto os exemplos usam offloading automático: o [ComponentsManager](/docs/diffusers/main/pt/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) move cada componente para o acelerador quando um bloco precisa dele, e o pipeline é executado em uma GPU de 80 GB. ## Componentes | Componente | Classe | |---|---| | `transformer` | [MiniMaxH3Transformer3DModel](/docs/diffusers/main/pt/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel) | | `text_encoder` | `Qwen3VLForConditionalGeneration` (Qwen3-VL-4B) | | `text_connector` | [PH3ImageTextConnector](/docs/diffusers/main/pt/api/pipelines/p_h3_image#diffusers.PH3ImageTextConnector) | | `vae` | [AutoencoderKLPH3Image](/docs/diffusers/main/pt/api/models/autoencoderkl_p_h3_image#diffusers.AutoencoderKLPH3Image) | | `tokenizer`, `processor` | O tokenizer do codificador de texto e um `Qwen3VLProcessor` com o processador de imagens do MiniMax-H3 | | `scheduler`, `audio_scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/main/pt/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) | | `prompt_upsampler`, `prompt_upsampler_processor` | `Qwen3_5ForConditionalGeneration` (baseado no Qwen3.5-9B) e seu processador | ## Fluxos de trabalho O workflow é selecionado na entrada `image`: - **`text2image`** gera a partir de `prompt`. `height` e `width` têm valores padrão de 2912 e são arredondados para múltiplos de 32. O modelo funciona melhor em 8 megapixels, por exemplo, 2912x2912, 3872x2176 ou 2176x3872. - **`image_conditioned`** edita `image` com base na instrução em `prompt` e funciona melhor em 4 ou 8 megapixels. A imagem é codificada em aproximadamente `vision_pixels` (um megapixel) para o codificador de texto e em seu próprio tamanho para o VAE, sendo ampliada para `reference_min_pixels` (um megapixel) ou reduzida para `reference_max_pixels` (oito megapixels) quando estiver fora dessa faixa. Sem `height` e `width`, a edição é gerada no tamanho da primeira imagem, que é ampliada para `canvas_min_pixels` (quatro megapixels) se for menor. Ao passar `height` e `width`, arredondados para múltiplos de 32, a tela é alterada, mas não as imagens. `image` também pode ser uma lista de até 8 imagens: a primeira é editada e as demais são referências, como ``, `` e assim por diante. ## Ampliação de prompt P-H3-Image é projetado para renderizar prompts completos, em vez de solicitações curtas, portanto o pipeline executa o prompt upsampler primeiro em cada solicitação. Ele analisa a solicitação e, em seguida, escreve o prompt: um prompt detalhado de texto para imagem para a proporção de aspecto de `height` e `width`, ou, ao editar, um resumo do que manter e do que alterar nas imagens. O prompt que ele escreveu retorna como a saída `prompt`. ```py out = pipe(prompt=prompt, height=3360, width=2496, output=["images", "prompt"]) print(out["prompt"]) ``` `max_new_tokens` limita o raciocínio e o prompt juntos, com 1024 tokens para texto-para-imagem e 1536 para edições por padrão. Se o upsampler não retornar um prompt utilizável, o pipeline levanta um erro em vez de renderizá-lo. Para renderizar `prompt` como fornecido, remova o passo dos blocos. O bloco removido também é executado de forma independente, por exemplo, para exibir o prompt a um usuário antes de renderizá-lo: ```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] ``` Sem o passo, um prompt de edição em qualquer forma que o upsampler escreva, o resumo de seis seções ou um parágrafo que começa com `Edit .`, é codificado como escrito; qualquer outra instrução recebe esse prefixo. ## Amostragem - Os 8 passos são executados sobre os `sample_sigmas` do checkpoint. Passe `sigmas` para usar outra grade. - O modelo é destilado por orientação, portanto não há um guia, `negative_prompt` ou `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) ``` [Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/p_h3_image/modular_pipeline.py#L22) Uma ModularPipeline para o P-H3-Image, um modelo de imagem baseado no MiniMax-H3, para geração de imagem a partir de texto (`text2image`) e edição baseada em instruções (`image_conditioned`). A imagem é um único quadro latente, desruidado em uma sequência empacotada com dois latentes de áudio que são descartados. ```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() ``` [Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/p_h3_image/modular_blocks_p_h3_image.py#L376) Blocos de pipeline modulares para P-H3-Image: `text2image` e edição baseada em instruções (`image_conditioned`) quando `image` é passado. `prompt` passa primeiro pelo prompt upsampler; remova a etapa `prompt_upsampler` para renderizá-lo como fornecido. Fluxos de trabalho suportados: - `text2image`: requer `prompt` - `image_conditioned`: requer `prompt`, `image` Componentes: image_processor (`VaeImageProcessor`) prompt_upsampler (`Qwen3_5ForConditionalGeneration`): O prompt upsampler. prompt_upsampler_processor (`AutoProcessor`): Seu processor. text_encoder (`Qwen3VLForConditionalGeneration`) text_connector (`PH3ImageTextConnector`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLPH3Image`) scheduler (`MiniMaxH3Scheduler`) audio_scheduler (`MiniMaxH3Scheduler`) transformer (`MiniMaxH3Transformer3DModel`) Configs: reference_min_pixels (padrão: 1048576) reference_max_pixels (padrão: 8388608) canvas_min_pixels (padrão: 4194304) vision_pixels (default: 1000000) sample_sigmas (default: [1.0, 0.984753, 0.967905, 0.951688, 0.925372, 0.881923, 0.810083, 0.528718, 0.0]): A grade de amostragem do checkpoint, usada quando `sigmas` não é passado. Inputs: image (`Image | list`, *opcional*): A imagem a ser editada, ou uma lista de no máximo 8 imagens: a primeira é editada, as outras são referências. height (`int`, *opcional*): Altura da imagem gerada em pixels, arredondada para um múltiplo de 32. O padrão é 2912 para `text2image`, que funciona melhor em 8 megapixels. Uma edição usa o tamanho da primeira imagem como padrão, no mínimo `canvas_min_pixels`, e funciona melhor em 4 ou 8 megapixels. width (`int`, *opcional*): Largura da imagem gerada em pixels, arredondada para um múltiplo de 32. O padrão é 2912 para `text2image`, que funciona melhor em 8 megapixels. Uma edição usa o tamanho da primeira imagem como padrão, no mínimo `canvas_min_pixels`, e funciona melhor em 4 ou 8 megapixels. prompt (`str`): O prompt, ou a instrução de edição quando `image` é passado. Uma única string. max_new_tokens (`int`, *opcional*, padrão 1536 ou 1024, dependendo do fluxo de trabalho): O número máximo de tokens que o upsampler pode gerar, incluindo seu raciocínio. vision_images (`list`, *opcional*): As imagens da edição redimensionadas para o codificador de texto, com a imagem a ser editada em primeiro lugar. reference_images (`list`, *opcional*): As imagens da edição redimensionadas para o VAE, com a imagem a ser editada em primeiro lugar. condition_latents (`list`, *opcional*): Os latentes de condicionamento das imagens da edição. Suas formas definem a geometria dos blocos de referência. generator (`Generator`, *opcional*): O gerador da solicitação. O ruído de condicionamento é extraído dele primeiro, uma extração por condição, antes do ruído das linhas geradas. latents (`Tensor`): Ruído de imagem pré-gerado com a forma `(1, latent_channels, 1, latent_height, latent_width)`, usado no lugar da extração. sigmas (`list`, *opcional*): Uma grade de amostragem personalizada, estritamente decrescente e terminando em 0. O padrão é o `sample_sigmas` do checkpoint. **denoiser_input_fields (`None`, *opcional*): A descrição estrutural da sequência empacotada que o transformer lê por nome: `token_tags`, `position_ids` e os três tensores de índice de linha. attention_kwargs (`dict`, *opcional*): Kwargs adicionais para os processadores de atenção. output_type (`str`, *opcional*, padrão pil): Formato de saída: 'pil', 'np', 'pt'. Saídas: imagens (`list`): Imagens geradas. ## 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) ``` [Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/condition_embedders/condition_embedder_p_h3_image.py#L22) **Parâmetros:** hidden_state_indices (`tuple[int, ...]`, padrão `(13, 19, 25, 31, 36)`) : Quais entradas dos `hidden_states` do codificador de texto são lidas, na numeração de `output_hidden_states` (`0` é a saída de incorporação, `i` é a saída da camada de decodificador `i`, e a última é o estado oculto final normalizado). text_hidden_size (`int`, padrão `2560`) : O tamanho oculto do codificador de texto. out_channels (`int`, padrão `5120`) : O número de canais que o transformer do MiniMax-H3 lê para o condicionamento. Mapeia os estados ocultos do codificador de texto Qwen3-VL do P-H3-Image para a condição de texto que o transformer dele lê. Os estados ocultos listados em `hidden_state_indices` são concatenados, padronizados, projetados linearmente e despadronizados. O primeiro token é um sink de atenção com a mesma condição para todos os prompts, portanto, ele é substituído por `sink_embedding`. #### forward[[diffusers.PH3ImageTextConnector.forward]] ```python forward(hidden_states: tuple[torch.Tensor, ...]) ``` [Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/condition_embedders/condition_embedder_p_h3_image.py#L61) **Parâmetros:** hidden_states (`tuple[torch.Tensor, ...]`) : Os estados ocultos do codificador de texto, conforme retornados por `output_hidden_states=True`: um tensor de forma `(batch_size, num_tokens, text_hidden_size)` por entrada. **Retorna:** `torch.Tensor` o condicionamento, de forma `(batch_size, num_tokens, out_channels)`, no dtype dos parâmetros do conector.