Diffusers documentation

MiniMax-H3-Image

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.43.0).
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-H3를 기반으로 한 MiniMax의 이미지 모델로, 텍스트 기반 이미지 생성 및 참조 이미지 편집에 사용됩니다. 체크포인트는 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)

transformer와 text encoder는 bfloat16에서 각각 약 62 GB로, 80 GB GPU에 함께 올라가지 않으므로 예제에서는 auto offloading을 사용합니다. ComponentsManager는 블록이 해당 구성 요소를 필요로 할 때 이를 accelerator로 이동합니다. 4736x3552 이미지의 경우 피크 메모리가 약 65 GB까지 올라갑니다.

텍스트-이미지:

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는 저장소 간에 동일한 파일을 중복 제거하므로, 이 사본은 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가 필요하며, GPU 메모리 약 18 GB가 필요합니다.

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로 전달하세요. 그런 다음 aspect_ratio와 일치하는 height와 width를 지정하여 prompt를 이미지 파이프라인에 전달하세요.

이미지 크기

height와 width는 반환되는 이미지의 크기를 나타내며 기본값은 2048입니다. 모델은 4 메가픽셀 이상으로 생성합니다. 요청된 크기가 더 작으면 동일한 종횡비인 더 큰 캔버스에서 생성한 뒤 원래 크기로 다시 조정되므로, 1024x1024 요청은 2048x2048 요청과 동일한 비용이 발생합니다. min_generation_area는 픽셀 단위로 해당 임계값을 설정합니다. 요청한 크기로 항상 생성하려면 1024를 전달하세요. 어느 경우든 캔버스의 각 변은 32의 배수로 반올림됩니다.

MiniMax는 1:1 비율에 4096x4096, 4:3 비율에 4736x3552, 3:2 비율에 5024x3360, 16:9 비율에 5472x3072, 21:9 비율에 6272x2688을 권장하며, 세로 형식의 경우 동일한 크기의 높이와 너비를 서로 바꾸어 사용하도록 권장합니다.

샘플링

  • 체크포인트는 sample_sigmas에 대해 6단계로 샘플링하며, 트랜스포머에는 단계마다 하나의 출력 헤드가 있으므로 num_inference_steps가 없습니다.
  • 모델은 guidance-distilled이므로 guider, negative_prompt 또는 guidance_scale이 없습니다.

MiniMaxH3ImageModularPipeline

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

MiniMax-H3-Image용 ModularPipeline: 텍스트-이미지 생성(text2image) 및 참조 이미지 편집(image_conditioned)

MiniMax-H3-Image는 오디오 없이 텍스트 행, 참조 이미지 행, 생성된 이미지 행(단일 latent 프레임)으로 구성된 하나의 packed sequence 위에서 MiniMax-H3 transformer를 실행합니다. 체크포인트는 두 번 증류됩니다. 가이던스가 가중치에 내장되어 있어 guider, negative_prompt, guidance_scale이 없으며, transformer의 출력 헤드 하나당 한 단계씩 고정된 6단계 그리드에서 샘플링하므로 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가 전달될 때의 참조 이미지 편집(image_conditioned).

지원되는 워크플로:

  • text2image: prompt 필수
  • image_conditioned: prompt, image 필수

구성 요소: image_processor (VaeImageProcessor) text_encoder (Qwen3VLForConditionalGeneration) tokenizer (Qwen2Tokenizer) processor (Qwen3VLProcessor) vae (AutoencoderKLMiniMaxH3Image) scheduler (MiniMaxH3Scheduler) transformer (MiniMaxH3ImageTransformer2DModel)

Configs: 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]): 체크포인트의 단계별 출력 헤드가 증류(distill)된 샘플링 그리드입니다.

입력: 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