Hugging Face's logo

Diffusers documentation

P-H3-Image

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

P-H3-Image

P-H3-Image é um modelo de imagem da Pruna AI baseado no 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.

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. 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 move cada componente para o acelerador quando um bloco precisa dele, e o pipeline é executado em uma GPU de 80 GB.

Componentes

ComponenteClasse
transformerMiniMaxH3Transformer3DModel
text_encoderQwen3VLForConditionalGeneration (Qwen3-VL-4B)
text_connectorPH3ImageTextConnector
vaeAutoencoderKLPH3Image
tokenizer, processorO tokenizer do codificador de texto e um Qwen3VLProcessor com o processador de imagens do MiniMax-H3
scheduler, audio_schedulerMiniMaxH3Scheduler
prompt_upsampler, prompt_upsampler_processorQwen3_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 <Picture 2>, <Picture 3> 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.

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:

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 <Picture 1>., é 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

classe diffusers.PH3ImageModularPipeline

< >

( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )

Uma ModularPipeline para 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.

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

classe diffusers.PH3ImageBlocks

< >

( )

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 upsampler do prompt. prompt_upsampler_processor (AutoProcessor): Seu processador. 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 (padrão: 1000000) sample_sigmas (padrão: [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.

Entradas: image (Image | list, opcional): A imagem a ser editada, ou uma lista de no máximo 8 imagens: a primeira é editada, as demais 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

classe diffusers.PH3ImageTextConnector

< >

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

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 do transformador de condicionamento do MiniMax-H3.

Mapeia os estados ocultos do codificador de texto Qwen3-VL do P-H3-Image para a condição de texto que seu transformer lê.

Os estados ocultos listados em hidden_state_indices são concatenados, padronizados, projetados linearmente e despadronizados. O primeiro token é um attention sink com a mesma condição para todos os prompts, portanto é substituído por sink_embedding.

forward

< >

( hidden_states: tuple[torch.Tensor, ...] ) → torch.Tensor

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.

Update on GitHub

←Ovis-Image PAG→