Diffusers documentation
P-H3-Image
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 ГБ.
Компоненты
| Компонент | Класс |
|---|---|
transformer | MiniMaxH3Transformer3DModel |
text_encoder | Qwen3VLForConditionalGeneration (Qwen3-VL-4B) |
text_connector | PH3ImageTextConnector |
vae | AutoencoderKLPH3Image |
tokenizer, processor | Токенизатор текстового энкодера, а также Qwen3VLProcessor с обработчиком изображений MiniMax-H3 |
scheduler, audio_scheduler | MiniMaxH3Scheduler |
prompt_upsampler, prompt_upsampler_processor | Qwen3_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
< source >( 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 )
A ModularPipeline for P-H3-Image, an image model based on MiniMax-H3, for text-to-image (text2image) and
instruction-based editing (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
Модульные блоки конвейера для P-H3-Image: text2image и редактирование по инструкции (image_conditioned), когда передан image. prompt сначала проходит через prompt upsampler; чтобы отобразить его в исходном виде, удалите шаг prompt_upsampler.
Поддерживаемые рабочие процессы:
text2image: требуетсяpromptimage_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
< source >( hidden_state_indices: tuple = (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
< source >( hidden_states: tuple ) → 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), в типе данных параметров коннектора.