Diffusers documentation
MiniMax-H3-Image
MiniMax-H3-Image
MiniMax-H3-Image é um modelo de imagem da MiniMax baseado no MiniMax-H3, para geração de imagem a partir de texto e edição de imagem de referência. Você pode encontrar o checkpoint em MiniMaxAI/MiniMax-H3-Image.
Assim como o MiniMax-H3, ele é integrado apenas como blocos de Modular Diffusers: MiniMaxH3ImageBlocks e seu MiniMaxH3ImageModularPipeline constituem toda a integração.
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)O transformer e o codificador de texto têm cerca de 62 GB cada em bfloat16 e não cabem juntos em uma GPU de 80 GB, portanto, os exemplos usam auto offloading: o ComponentsManager move cada componente para o acelerador quando um bloco precisa dele. Uma imagem de 4736x3552 então atinge um pico de cerca de 65 GB.
Texto para imagem:
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]Editando uma imagem de referência:
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]Componentes
| Componente | Classe |
|---|---|
transformer | MiniMaxH3ImageTransformer2DModel |
text_encoder | Qwen3VLForConditionalGeneration |
vae | AutoencoderKLMiniMaxH3Image |
tokenizer, processor | O tokenizer do codificador de texto e um Qwen3VLProcessor |
scheduler | MiniMaxH3Scheduler |
O codificador de texto é o mesmo utilizado pelo MiniMax-H3. O checkpoint mantém uma cópia própria para que o repositório seja autocontido; o Hub deduplica arquivos idênticos entre repositórios, portanto a cópia não ocupa armazenamento extra lá.
Fluxos de trabalho
O workflow é selecionado na entrada image:
text2imagegera a partir deprompt.image_conditionedgera a partir deprompte uma ou mais imagens de referência passadas comoimage. O prompt se refere a elas em ordem como<Picture 1>,<Picture 2>, e assim por diante. As referências mantêm seu próprio tamanho: cada uma é redimensionada apenas quando sua borda curta está fora de 1024 a 2048 pixels, e nunca para o tamanho da imagem gerada.
O prompt é usado literalmente, sem template de chat, e descrições longas e completas funcionam melhor. Um prompt de edição geralmente nomeia o que preservar, depois o que alterar e, em seguida, descreve a imagem de destino por completo.
Melhoria de prompt
MiniMax-H3-Image-PE é o modelo de expansão de prompt da MiniMax: ele reescreve uma solicitação curta no tipo de descrição detalhada com a qual o modelo de imagem funciona melhor e recomenda uma proporção de aspecto. Os blocos personalizados diffusers/minimax-h3-image-pe-blocks o executam como um pipeline próprio. Eles precisam de xgrammar e de cerca de 18 GB de memória de GPU.
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")Passe as imagens de referência como image para expandir uma instrução de edição. Em seguida, passe prompt para o pipeline de imagem, com height e width que correspondam a aspect_ratio.
Tamanho da imagem
height e width são o tamanho da imagem retornada e, por padrão, são 2048. O modelo gera em 4 megapixels ou mais: uma solicitação menor é gerada em um canvas maior com a mesma proporção de aspecto e redimensionada de volta, portanto, uma solicitação de 1024x1024 custa o mesmo que uma de 2048x2048. min_generation_area define esse limite em pixels; passe 1024 para sempre gerar no tamanho solicitado. De qualquer forma, os lados do canvas são arredondados para múltiplos de 32.
A MiniMax recomenda 4096x4096 para 1:1, 4736x3552 para 4:3, 5024x3360 para 3:2, 5472x3072 para 16:9 e 6272x2688 para 21:9, ou os mesmos tamanhos com altura e largura invertidos para formatos retrato.
Amostragem
- O checkpoint amostra em 6 etapas sobre seu
sample_sigmas, e o transformer possui uma cabeça de saída por etapa, portanto não hánum_inference_steps. - O modelo é destilado por orientação, portanto não há um guia,
negative_promptouguidance_scale.
MiniMaxH3ImageModularPipeline
classe 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 )
Uma ModularPipeline para MiniMax-H3-Image: texto para imagem (text2image) e edição de imagem de referência
(image_conditioned).
MiniMax-H3-Image executa o transformer MiniMax-H3 sem áudio sobre uma sequência empacotada de linhas de texto, as linhas das imagens de referência e as linhas da imagem gerada, que é um único frame latente. O checkpoint é destilado duas vezes: o guidance é incorporado nos pesos, portanto não há guider, nem negative_prompt e nem guidance_scale, e ele amostra em uma grade fixa de seis passos com uma cabeça de saída do transformer por passo, portanto também não há num_inference_steps.
MiniMaxH3ImageBlocks
Blocos de pipeline modulares para MiniMax-H3-Image: text2image e edição de imagem de referência (image_conditioned) quando image é passado.
Fluxos de trabalho suportados:
text2image: requerpromptimage_conditioned: requerprompt,image
Componentes:
image_processor (VaeImageProcessor) text_encoder (Qwen3VLForConditionalGeneration) tokenizer
(Qwen2Tokenizer) processor (Qwen3VLProcessor) vae (AutoencoderKLMiniMaxH3Image) scheduler
(MiniMaxH3Scheduler) transformer (MiniMaxH3ImageTransformer2DModel)
Configs: reference_min_short_edge (padrão: 1024) reference_max_short_edge (padrão: 2048) vision_min_short_edge (padrão: 1024) vision_max_short_edge (padrão: 1024) sample_sigmas (padrão: [1.0, 0.9675236940383911, 0.8875485062599182, 0.75, 0.5327739119529724, 0.23200887441635132, 0.0]): A grade de amostragem na qual as cabeças de saída por etapa do checkpoint foram destiladas.
Entradas:
image (Image | list, opcional):
A imagem de referência da edição, ou uma lista delas. O prompt se refere a elas em ordem como <Picture 1>, <Picture 2>, …
prompt (str):
O prompt para orientar a geração, uma única string.
vision_images (list, opcional):
As imagens de referência redimensionadas para o codificador de texto.
reference_images (list, opcional):
As imagens de referência redimensionadas para o VAE.
generator (Generator, opcional):
O gerador da solicitação. Uma amostra posterior por referência é extraída dele.
height (int):
Altura da imagem retornada em pixels.
width (int):
Largura da imagem retornada em pixels.
min_generation_area (int, opcional, padrão 4194304):
A menor área, em pixels, na qual uma imagem é gerada. Um height x width menor é gerado em um
canvas ampliado para essa área e redimensionado de volta para height x width após a decodificação. Passe 1024 para sempre
gerar no tamanho solicitado.
reference_latents (list, opcional):
Os latentes de condicionamento das imagens de referência. Sua forma é de onde a geometria de cada referência vem.
latents (Tensor):
Ruído pré-gerado de forma (1, latent_channels, latent_height, latent_width), usado no lugar da
extração.
reference_noise (list, opcional):
Ruído pré-gerado para as imagens de referência, um tensor da forma de cada entrada de reference_latents, usado no lugar das extrações.
*denoiser_input_fields (None,opcional):
A descrição estrutural da sequência empacotada que o transformer lê por nome: token_tags, position_ids e os dois tensores de índice de linha.
output_type (str,opcional*, padrão pil):
Formato de saída: ‘pil’, ‘np’, ‘pt’.
Saídas:
imagens (list):
Imagens geradas.