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 — это модель для работы с изображениями от Pruna AI, основанная на MiniMax-H3, предназначенная для генерации изображений по текстовому описанию и редактирования изображений по инструкциям. Чекпоинт доступен по адресу 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]

Каждый запрос сначала проходит через prompt upsampler. При размещении всех компонентов на ускорителе конвейеру требуется около 101 ГБ в формате bfloat16 для разрешения 8 мегапикселей, поэтому в примерах используется автоматическое выгружение: ComponentsManager перемещает каждый компонент на ускоритель, когда блок в нём нуждается, и конвейер работает на GPU объёмом 80 ГБ.

Компоненты

КомпонентКласс
transformerMiniMaxH3Transformer3DModel
text_encoderQwen3VLForConditionalGeneration (Qwen3-VL-4B)
text_connectorPH3ImageTextConnector
vaeAutoencoderKLPH3Image
tokenizer, processorТокенизатор текстового энкодера, а также Qwen3VLProcessor с обработчиком изображений MiniMax-H3
scheduler, audio_schedulerMiniMaxH3Scheduler
prompt_upsampler, prompt_upsampler_processorQwen3_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.

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

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

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

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

< >

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

Модульный ModularPipeline для P-H3-Image, модели изображений на базе MiniMax-H3, предназначенной для генерации изображений по тексту (text2image) и редактирования по инструкциям (image_conditioned).

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

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

< >

( )

Модульные блоки конвейера для 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, необязательный): Пользовательская сетка сэмплирования, строго убывающая и заканчивающаяся нулем. По умолчанию используются sample_sigmas из чекпоинта. *denoiser_input_fields (None,необязательный): Структурное описание упакованной последовательности, которую трансформер читает по именам: token_tags, position_ids и три тензора индексов строк. attention_kwargs (dict,необязательный): Дополнительные аргументы для процессоров внимания. output_type (str,необязательный*, по умолчанию pil): Формат вывода: ‘pil’, ‘np’, ‘pt’.

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

PH3ImageTextConnector

класс diffusers.PH3ImageTextConnector

< >

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

Параметры

  • 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

< >

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

Параметры

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

Возвращает

torch.Tensor

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

Update on GitHub

←Ovis-Image PAG→