# MiniMax-H3-Image MiniMax-H3-Image — это модель для работы с изображениями от MiniMax, основанная на [MiniMax-H3](./minimax_h3), предназначенная для генерации изображений по текстовому описанию и редактирования изображений с опорой на референс. Чекпоинт доступен по адресу [MiniMaxAI/MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image). Как и MiniMax-H3, он интегрирован только в виде блоков [Modular Diffusers](../../modular_diffusers/overview): [MiniMaxH3ImageBlocks](/docs/diffusers/main/ru/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageBlocks) и их [MiniMaxH3ImageModularPipeline](/docs/diffusers/main/ru/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageModularPipeline) представляют собой всю интеграцию. ```py 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](/docs/diffusers/main/ru/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) перемещает каждый компонент на ускоритель в тот момент, когда блок в нём нуждается. При этом пиковое потребление памяти для изображения размером 4736x3552 составляет около 65 ГБ. Текст в изображение: ```py 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] ``` Редактирование опорного изображения: ```py 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 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] ``` ## Компоненты | Компонент | Класс | |---|---| | `transformer` | [MiniMaxH3ImageTransformer2DModel](/docs/diffusers/main/ru/api/models/minimax_h3_image_transformer2d#diffusers.MiniMaxH3ImageTransformer2DModel) | | `text_encoder` | `Qwen3VLForConditionalGeneration` | | `vae` | [AutoencoderKLMiniMaxH3Image](/docs/diffusers/main/ru/api/models/autoencoderkl_minimax_h3_image#diffusers.AutoencoderKLMiniMaxH3Image) | | `tokenizer`, `processor` | Токенизатор текстового энкодера и `Qwen3VLProcessor` | | `scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/main/ru/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) | Текстовый энкодер — тот же самый, что используется в [MiniMax-H3](./minimax_h3). Чекпоинт хранит собственную копию, чтобы репозиторий был самодостаточным; Hub дедуплицирует идентичные файлы между репозиториями, поэтому копия не занимает там дополнительное место. ## Рабочие процессы Рабочий процесс выбирается на входе `image`: - **`text2image`** генерирует изображение из `prompt`. - **`image_conditioned`** генерирует изображение по `prompt` и одному или нескольким опорным изображениям, переданным в качестве `image`. В промпте они упоминаются по порядку как ``, `` и так далее. Опорные изображения сохраняют свой исходный размер: каждое масштабируется только в том случае, если его короткая сторона выходит за пределы от 1024 до 2048 пикселей, и никогда не приводится к размеру генерируемого изображения. Промпт используется дословно, без шаблона чата, и лучше всего работают длинные, полные описания. Промпт для редактирования обычно указывает, что следует сохранить, затем что изменить, а после этого полностью описывает целевое изображение. ## Улучшение промпта [MiniMax-H3-Image-PE](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image-PE) — это модель расширения промптов от MiniMax: она переписывает короткий запрос в детальное описание, с которым модель генерации изображений работает лучше всего, и рекомендует соотношение сторон. Кастомные блоки `diffusers/minimax-h3-image-pe-blocks` запускают её как отдельный конвейер. Для их работы требуется `xgrammar` и около 18 ГБ видеопамяти. ```py 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]] #### diffusers.MiniMaxH3ImageModularPipeline[[diffusers.MiniMaxH3ImageModularPipeline]] ```python diffusers.MiniMaxH3ImageModularPipeline(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) ``` [Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3_image/modular_pipeline.py#L27) A ModularPipeline for MiniMax-H3-Image: text-to-image (`text2image`) and reference-image editing (`image_conditioned`). MiniMax-H3-Image выполняет трансформер MiniMax-H3 без аудио по одной упакованной последовательности строк текста, строк эталонных изображений и строк сгенерированного изображения, представляющего собой единственную латентную рамку. Чекпоинт дважды дистиллирован: guidance вшит в веса, поэтому нет guider, нет `negative_prompt` и нет `guidance_scale`, а сэмплирование происходит на фиксированной сетке из шести шагов с одним выходным слоем трансформера на каждый шаг, поэтому нет и `num_inference_steps`. ```py import torch from diffusers import ModularPipeline pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3-Image") pipe.load_components(dtype=torch.bfloat16) ``` ## MiniMaxH3ImageBlocks[[diffusers.MiniMaxH3ImageBlocks]] #### diffusers.MiniMaxH3ImageBlocks[[diffusers.MiniMaxH3ImageBlocks]] ```python diffusers.MiniMaxH3ImageBlocks() ``` [Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3_image/modular_blocks_minimax_h3_image.py#L371) Модульные блоки конвейера для 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]): сетка дискретизации, на которой были дистиллированы выходные слои по шагам для данного контрольного файла. Inputs: image (`Image | list`, *необязательный*): эталонное изображение для редактирования или список таких изображений. В промпте они упоминаются по порядку как ``, ``, ... 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'. Вывод: изображения (`list`): сгенерированные изображения.