Diffusers documentation
MiniMax-H3-Image
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]구성 요소
| 컴포넌트 | 클래스 |
|---|---|
transformer | MiniMaxH3ImageTransformer2DModel |
text_encoder | Qwen3VLForConditionalGeneration |
vae | AutoencoderKLMiniMaxH3Image |
tokenizer, processor | 텍스트 인코더의 토크나이저와 Qwen3VLProcessor |
scheduler | MiniMaxH3Scheduler |
텍스트 인코더는 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
< 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 )
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도 없습니다.
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):
생성된 이미지.