Hugging Face's logo

Diffusers documentation

MiniMax-H3-Image

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

MiniMax-H3-Image

MiniMax-H3-Image — это модель для работы с изображениями от MiniMax, основанная на MiniMax-H3, предназначенная для генерации изображений по текстовому описанию и редактирования изображений с опорой на референс. Чекпоинт доступен по адресу MiniMaxAI/MiniMax-H3-Image.

Как и MiniMax-H3, он интегрирован только в виде блоков Modular Diffusers: MiniMaxH3ImageBlocks и их MiniMaxH3ImageModularPipeline представляют собой всю интеграцию.

import torch
from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3-Image", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

Трансформер и текстовый энкодер занимают по ~62 ГБ в формате bfloat16 и не помещаются одновременно на GPU с 80 ГБ памяти, поэтому в примерах используется автоматическое выгружение (auto offloading): ComponentsManager перемещает каждый компонент на ускоритель в тот момент, когда блок в нём нуждается. При этом пиковое потребление памяти для изображения размером 4736x3552 составляет около 65 ГБ.

Текст в изображение:

prompt = (
    "An overhead photograph of a rustic farm-to-table spread on a weathered wooden table: a round loaf of sourdough "
    "on burlap, wedges of cheese on a dark board, a copper bowl of vegetables, vine tomatoes, olives and walnuts."
)
image = pipe(
    prompt=prompt, height=3552, width=4736, generator=torch.Generator().manual_seed(42), output="images"
)[0]

Редактирование опорного изображения:

from diffusers.utils import load_image

reference = load_image("https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/resolve/main/examples/reference1.png")
image = pipe(
    prompt="Keep everything in <Picture 1> as it is, but remove the headphones and have the two hosts fist bump.",
    image=reference,
    height=4096,
    width=4096,
    generator=torch.Generator().manual_seed(1234),
    output="images",
)[0]

Компоненты

КомпонентКласс
transformerMiniMaxH3ImageTransformer2DModel
text_encoderQwen3VLForConditionalGeneration
vaeAutoencoderKLMiniMaxH3Image
tokenizer, processorТокенизатор текстового энкодера и Qwen3VLProcessor
schedulerMiniMaxH3Scheduler

Текстовый энкодер — тот же самый, что используется в MiniMax-H3. Чекпоинт хранит собственную копию, чтобы репозиторий был самодостаточным; Hub дедуплицирует идентичные файлы между репозиториями, поэтому копия не занимает там дополнительное место.

Рабочие процессы

Рабочий процесс выбирается на входе image:

  • text2image генерирует изображение из prompt.
  • image_conditioned генерирует изображение по prompt и одному или нескольким опорным изображениям, переданным в качестве image. В промпте они упоминаются по порядку как <Picture 1>, <Picture 2> и так далее. Опорные изображения сохраняют свой исходный размер: каждое масштабируется только в том случае, если его короткая сторона выходит за пределы от 1024 до 2048 пикселей, и никогда не приводится к размеру генерируемого изображения.

Промпт используется дословно, без шаблона чата, и лучше всего работают длинные, полные описания. Промпт для редактирования обычно указывает, что следует сохранить, затем что изменить, а после этого полностью описывает целевое изображение.

Улучшение промпта

MiniMax-H3-Image-PE — это модель расширения промптов от MiniMax: она переписывает короткий запрос в детальное описание, с которым модель генерации изображений работает лучше всего, и рекомендует соотношение сторон. Кастомные блоки diffusers/minimax-h3-image-pe-blocks запускают её как отдельный конвейер. Для их работы требуется xgrammar и около 18 ГБ видеопамяти.

import torch
from diffusers import ModularPipeline

enhancer = ModularPipeline.from_pretrained("diffusers/minimax-h3-image-pe-blocks", trust_remote_code=True)
enhancer.load_components(dtype=torch.bfloat16, device_map="cuda")

state = enhancer(prompt="a cozy cabin in the snow")
prompt, aspect_ratio = state.get("prompt"), state.get("aspect_ratio")

Передайте эталонные изображения как image, чтобы расширить инструкцию для редактирования. Затем передайте prompt в пайплайн изображений, указав height и width, соответствующие aspect_ratio.

Размер изображения

height и width задают размер возвращаемого изображения и по умолчанию равны 2048. Модель генерирует изображения разрешением 4 мегапикселя и выше: если запрошенный размер меньше, генерация выполняется на более крупном холсте с тем же соотношением сторон, после чего изображение масштабируется обратно, поэтому запрос 1024x1024 обходится так же, как запрос 2048x2048. Параметр min_generation_area задаёт этот порог в пикселях; передайте 1024, чтобы всегда генерировать в запрошенном размере. В любом случае стороны холста округляются до кратных 32.

MiniMax рекомендует размеры 4096x4096 для соотношения 1:1, 4736x3552 для 4:3, 5024x3360 для 3:2, 5472x3072 для 16:9 и 6272x2688 для 21:9, либо те же размеры с переставленными высотой и шириной для портретных форматов.

Выборка

  • Чекпоинт выполняет сэмплирование за 6 шагов по своим sample_sigmas, а трансформер имеет один выходной слой на каждый шаг, поэтому параметра num_inference_steps нет.
  • Модель получена с помощью дистилляции с наведением, поэтому в ней нет наводящего элемента, negative_prompt или guidance_scale.

MiniMaxH3ImageModularPipeline

класс diffusers.MiniMaxH3ImageModularPipeline

< >

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

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

MiniMax-H3-Image выполняет трансформер MiniMax-H3 без аудио по одной упакованной последовательности строк текста, строк эталонных изображений и строк сгенерированного изображения, представляющего собой единственную латентную рамку. Чекпоинт дважды дистиллирован: guidance вшит в веса, поэтому нет guider, нет negative_prompt и нет guidance_scale, а сэмплирование происходит на фиксированной сетке из шести шагов с одним выходным слоем трансформера на каждый шаг, поэтому нет и num_inference_steps.

import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3-Image")
pipe.load_components(dtype=torch.bfloat16)

MiniMaxH3ImageBlocks

класс diffusers.MiniMaxH3ImageBlocks

< >

( )

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

Поддерживаемые рабочие процессы:

  • text2image: требуется prompt
  • image_conditioned: требуется prompt, image

Компоненты: image_processor (VaeImageProcessor) text_encoder (Qwen3VLForConditionalGeneration) tokenizer (Qwen2Tokenizer) processor (Qwen3VLProcessor) vae (AutoencoderKLMiniMaxH3Image) scheduler (MiniMaxH3Scheduler) transformer (MiniMaxH3ImageTransformer2DModel)

Конфигурации: reference_min_short_edge (по умолчанию: 1024) reference_max_short_edge (по умолчанию: 2048) vision_min_short_edge (по умолчанию: 1024) vision_max_short_edge (по умолчанию: 1024) sample_sigmas (по умолчанию: [1.0, 0.9675236940383911, 0.8875485062599182, 0.75, 0.5327739119529724, 0.23200887441635132, 0.0]): сетка сэмплирования, на которой были дистиллированы выходные головы по шагам для данного чекпоинта.

Входные данные: image (Image | list, необязательный): Справочное изображение для редактирования или список таких изображений. В промпте они упоминаются по порядку как <Picture 1>, <Picture 2>, … prompt (str): Промпт для управления генерацией, одна строка. vision_images (list, необязательный): Справочные изображения, изменённые по размеру для текстового энкодера. reference_images (list, необязательный): Справочные изображения, изменённые по размеру для VAE. generator (Generator, необязательный): Генератор запроса. Из него извлекается одна апостериорная выборка на каждое справочное изображение. height (int): Высота возвращаемого изображения в пикселях. width (int): Ширина возвращаемого изображения в пикселях. min_generation_area (int, необязательный, по умолчанию 4194304): Минимальная площадь, в пикселях, при которой генерируется изображение. Если height x width меньше, изображение генерируется на холсте, масштабированном до этой площади, и затем возвращается к размеру height x width после декодирования. Передайте 1024, чтобы всегда генерировать в запрошенном размере. reference_latents (list, необязательный): Условные латенты справочных изображений. Их форма определяет геометрию каждого справочного изображения. latents (Tensor): Предварительно сгенерированный шум формы (1, latent_channels, latent_height, latent_width), используемый вместо извлечения. reference_noise (list, необязательный): Предварительно сгенерированный шум для справочных изображений, один тензор формы каждого элемента reference_latents, используемый вместо извлечений. *denoiser_input_fields (None,необязательный): Структурное описание упакованной последовательности, которую трансформер читает по имени: token_tags, position_ids и два тензора индексов строк. output_type (str,необязательный*, по умолчанию pil): Формат вывода: ‘pil’, ‘np’, ‘pt’.

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

Update on GitHub

←Marigold NucleusMoE-Image→