Diffusers documentation
MiniMax-H3-Image
MiniMax-H3-Image
MiniMax-H3-Image es un modelo de imágenes de MiniMax basado en MiniMax-H3, para la generación de imágenes a partir de texto y la edición de imágenes de referencia. Puedes encontrar el punto de control en MiniMaxAI/MiniMax-H3-Image.
Al igual que MiniMax-H3, se integra únicamente como bloques de Modular Diffusers: MiniMaxH3ImageBlocks y su MiniMaxH3ImageModularPipeline constituyen toda la integración.
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)El transformer y el codificador de texto ocupan unos 62 GB cada uno en bfloat16 y no caben juntos en una GPU de 80 GB, por lo que los ejemplos utilizan auto offloading: el ComponentsManager mueve cada componente al acelerador cuando un bloque lo necesita. Una imagen de 4736x3552 alcanza entonces un pico de unos 65 GB.
Texto a imagen:
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]Edición de una imagen de referencia:
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 | Clase |
|---|---|
transformer | MiniMaxH3ImageTransformer2DModel |
text_encoder | Qwen3VLForConditionalGeneration |
vae | AutoencoderKLMiniMaxH3Image |
tokenizer, processor | El tokenizador del codificador de texto y un Qwen3VLProcessor |
scheduler | MiniMaxH3Scheduler |
El codificador de texto es el mismo que utiliza MiniMax-H3. El checkpoint conserva su propia copia para que el repositorio sea autosuficiente; el Hub deduplica archivos idénticos entre repositorios, por lo que la copia no ocupa almacenamiento adicional allí.
Flujos de trabajo
El flujo de trabajo se selecciona en la entrada image:
text2imagegenera a partir deprompt.image_conditionedgenera a partir deprompty una o más imágenes de referencia pasadas comoimage. El prompt se refiere a ellas en orden como<Picture 1>,<Picture 2>, y así sucesivamente. Las referencias conservan su propio tamaño: cada una se redimensiona solo cuando su lado corto está fuera del rango de 1024 a 2048 píxeles, y nunca al tamaño de la imagen generada.
El prompt se utiliza tal cual, sin plantilla de chat, y funcionan mejor las descripciones largas y completas. Un prompt de edición suele nombrar qué conservar, luego qué cambiar y, a continuación, describe la imagen objetivo por completo.
Mejora de prompts
MiniMax-H3-Image-PE es el modelo de expansión de prompts de MiniMax: reescribe una solicitud breve en el tipo de descripción detallada con la que el modelo de imágenes funciona mejor, y recomienda una relación de aspecto. Los bloques personalizados diffusers/minimax-h3-image-pe-blocks lo ejecutan como un pipeline propio. Requieren xgrammar y aproximadamente 18 GB de memoria 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")Pasa las imágenes de referencia como image para expandir una instrucción de edición. Luego, pasa prompt a la pipeline de imagen, con una height y un width que coincidan con aspect_ratio.
Tamaño de la imagen
height y width son el tamaño de la imagen devuelta y su valor predeterminado es 2048. El modelo genera a 4 megapíxeles o más: una solicitud más pequeña se genera en un lienzo más grande con la misma relación de aspecto y se redimensiona de nuevo, por lo que una solicitud de 1024x1024 cuesta lo mismo que una de 2048x2028. min_generation_area establece ese umbral en píxeles; pase 1024 para generar siempre en el tamaño solicitado. De cualquier manera, los lados del lienzo se redondean a múltiplos de 32.
MiniMax recomienda 4096x4096 para 1:1, 4736x3552 para 4:3, 5024x3360 para 3:2, 5472x3072 para 16:9 y 6272x2688 para 21:9, o los mismos tamaños con la altura y el ancho intercambiados para formatos verticales.
Muestreo
- Los checkpoints muestrean en 6 pasos sobre sus
sample_sigmas, y el transformer tiene una cabeza de salida por paso, por lo que no haynum_inference_steps. - El modelo está destilado con guía, por lo que no hay un guionista,
negative_promptniguidance_scale.
MiniMaxH3ImageModularPipeline
clase 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 )
Un ModularPipeline para MiniMax-H3-Image: texto a imagen (text2image) y edición de imagen de referencia
(image_conditioned).
MiniMax-H3-Image ejecuta el transformer MiniMax-H3 sin audio sobre una secuencia empaquetada de filas de texto, las filas de las imágenes de referencia y las filas de la imagen generada, que es un único marco latente. El checkpoint se destila dos veces: la guía está integrada en los pesos, por lo que no hay un guider, ni negative_prompt ni guidance_scale, y muestrea en una cuadrícula fija de seis pasos con una cabeza de salida del transformer por paso, por lo que tampoco hay num_inference_steps.
MiniMaxH3ImageBlocks
Bloques de pipeline modulares para MiniMax-H3-Image: text2image y edición con imagen de referencia (image_conditioned) cuando se pasa image.
Flujos de trabajo admitidos:
text2image: requierepromptimage_conditioned: requiereprompt,image
Componentes:
image_processor (VaeImageProcessor) text_encoder (Qwen3VLForConditionalGeneration) tokenizer
(Qwen2Tokenizer) processor (Qwen3VLProcessor) vae (AutoencoderKLMiniMaxH3Image) scheduler
(MiniMaxH3Scheduler) transformer (MiniMaxH3ImageTransformer2DModel)
Configuraciones: reference_min_short_edge (predeterminado: 1024) reference_max_short_edge (predeterminado: 2048) vision_min_short_edge (predeterminado: 1024) vision_max_short_edge (predeterminado: 1024) sample_sigmas (predeterminado: [1.0, 0.9675236940383911, 0.8875485062599182, 0.75, 0.5327739119529724, 0.23200887441635132, 0.0]): La cuadrícula de muestreo en la que se destilaron las cabezas de salida por paso del punto de control.
Entradas:
image (Image | list, opcional):
La imagen de referencia de la edición, o una lista de ellas. El prompt se refiere a ellas en orden como <Picture 1>, <Picture 2>, …
prompt (str):
El prompt para guiar la generación, una sola cadena de texto.
vision_images (list, opcional):
Las imágenes de referencia redimensionadas para el codificador de texto.
reference_images (list, opcional):
Las imágenes de referencia redimensionadas para el VAE.
generator (Generator, opcional):
El generador de la solicitud. Se extrae una muestra posterior por referencia de él.
height (int):
Altura de la imagen devuelta en píxeles.
width (int):
Ancho de la imagen devuelta en píxeles.
min_generation_area (int, opcional, predeterminado a 4194304):
El área más pequeña, en píxeles, a la que se genera una imagen. Un height x width más pequeño se genera en un lienzo escalado a este área y se redimensiona de vuelta a height x width después de la decodificación. Pasa 1024 para generar siempre en el tamaño solicitado.
reference_latents (list, opcional):
Los latentes de condicionamiento de las imágenes de referencia. Su forma es de donde proviene la geometría de cada referencia.
latents (Tensor):
Ruido pregenerado de forma (1, latent_channels, latent_height, latent_width), usado en lugar de la extracción.
reference_noise (list, opcional):
Ruido pregenerado para las imágenes de referencia, un tensor de la forma de cada entrada de reference_latents, usado en lugar de las extracciones.
*denoiser_input_fields (None,opcional):
La descripción estructural de la secuencia empaquetada que el transformer lee por nombre: token_tags, position_ids y los dos tensores de índices de fila.
output_type (str,opcional*, predeterminado a pil):
Formato de salida: ‘pil’, ‘np’, ‘pt’.
Salidas:
images (list):
Imágenes generadas.