Transformers documentation

MiniMax-M3-VL

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Ce modèle a été contribué à Hugging Face Transformers le 2026-06-12.

MiniMax-M3-VL

Aperçu

MiniMax-M3-VL est le membre vision-langage de la famille MiniMax-M3. Il associe une tour vision de type CLIP (incorporation de patches Conv3d avec des embeddings de position rotatifs 3D) au backbone texte MiniMax-M3, un décodeur Mixture-of-Experts dense/sparse mixte qui utilise des experts à porte SwiGLU-OAI et un indexateur lightning pour une attention bloc-sparse.

Architecture

Attention à blocs creux (Lightning Indexer)

Chaque couche est GQA (num_key_value_heads = 4) avec une normalisation QK par tête et un RoPE partiel sur les premiers rotary_dim. config.layer_types[i] sélectionne ensuite "full_attention" (causale dense) ou "minimax_m3_sparse", où un MiniMaxM3VLIndexer détermine, pour chaque requête, quel bloc de clés l'attention principale peut voir.

L’indexeur attribue un score à chaque clé, puis max-pool ces scores par clé en blocs de index_block_size clés, de sorte que la sélection s’effectue à la granularité d’un bloc de clés : pour chaque requête, il conserve les index_topk_blocks meilleurs blocs de clés ainsi que le bloc de fenêtre locale index_local_blocks toujours actif (sous causalité au niveau des blocs), puis diffuse le choix 0/-inf par bloc sur chaque clé du bloc. Le résultat est un biais additif [B, 1, S_q, S_k] additionné au masque causal. En théorie, cela signifie que l’attention n’est calculée que sur les blocs de clés sélectionnés, mais transformers ne prend pas en charge les noyaux qui calculent cela efficacement ! Nous l’ajoutons à kernels dès que possible !

Tour de vision

Un MiniMaxM3VLVisionModel : un Conv3d d'encodage de patches sur une entrée aplatie [N_patches, C·T·P·P], une pile de couches d'encodeur de type CLIP portant un 3D rotary d'encodage de position (bandes temps / hauteur / largeur). Un MiniMaxM3VLPatchMerger regroupe spatial_merge_size² patches dans la dimension des canaux avant que le MiniMaxM3VLMultiModalProjector à 2 couches GELU ne projette les caractéristiques visuelles dans la taille cachée du texte.

Exemples d'utilisation

L'exemple ci-dessous exécute le modèle sur une image réelle chargée avec load_image().

import torch
from transformers import AutoModelForImageTextToText, AutoProcessor
from transformers.image_utils import load_image


model = AutoModelForImageTextToText.from_pretrained(
    "MiniMaxAI/MiniMax-M3-preview", dtype=torch.bfloat16, device_map="auto",
)
processor = AutoProcessor.from_pretrained("MiniMaxAI/MiniMax-M3-preview")

image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/bee.jpg")
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image"},
            {"type": "text", "text": "Describe this image briefly."},
        ],
    }
]
text = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
inputs = processor(images=[image], text=text, return_tensors="pt").to(model.device)

generated_ids = model.generate(**inputs, max_new_tokens=32, do_sample=False)
print(processor.batch_decode(generated_ids, skip_special_tokens=True)[0])

Exemple Apple

Cet exemple interroge le modèle sur une image de pommes, en chargeant à nouveau une image réelle avec load_image().

import torch
from transformers import AutoModelForImageTextToText, AutoProcessor
from transformers.image_utils import load_image


model = AutoModelForImageTextToText.from_pretrained(
    "MiniMaxAI/MiniMax-M3-preview", dtype=torch.bfloat16, device_map="auto",
)
processor = AutoProcessor.from_pretrained("MiniMaxAI/MiniMax-M3-preview")

image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/bee.jpg")
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image"},
            {"type": "text", "text": "How many apples are in this image, and what color are they?"},
        ],
    }
]
text = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
inputs = processor(images=[image], text=text, return_tensors="pt").to(model.device)

generated_ids = model.generate(**inputs, max_new_tokens=32, do_sample=False)
print(processor.batch_decode(generated_ids, skip_special_tokens=True)[0])

Configuration d'inférence la plus rapide

ctx	Décodeur SDPA	Décodage MSA	MSA décodage av.	Préremplissage SDPA	Préremplissage MSA	Préremplissage avancé MSA
2K	27,8 tok/s	31.0	+12%	303 ms	257 ms	1.18×
4K	23,4 tok/s	30.5	+30%	684 ms	460 ms	1.49×
8K	17,8 tok/s	29.6	+66%	1906 ms	976 ms	1.95×
16K	12,0 tok/s	27.6	+130%	6110 ms	2344 ms	2.61×

Le checkpoint est fourni en MXFP8 natif. Pour le débit de décodage, la configuration validée la plus rapide est bf16 (déquantifié au chargement) + le noyau d’attention MSA block-sparse + parallélisme de tenseurs et d’experts + une compilation cudagraph reduce-overhead — environ 31 tok/s de décodage sur 8×B200 avec un préremplissage de 2048 jetons.

Conserver les poids en FP8 natif n’est qu’une option de réduction de l’empreinte mémoire — il n’est jamais plus rapide sur cette configuration. Les noyaux Triton d’experts/linéaires FP8 sont compilés en noyaux de repli inducteur opaques que cudagraph ne peut pas capturer sur le chemin chaud des experts, si bien que le décodage en FP8 natif mesuré ~4,2 tok/s (≈7× plus lent que le chemin bf16) même sous torch.compile(fullgraph=True). N’utilisez le FP8 que lorsque les poids bf16 ne tiennent pas.

config (référence sdpa, TP+EP, préremplissage de 2048 jetons, 8×B200)	decode
Désquantification bf16 au chargement + MSA + compile/cudagraph	~31 tok/s
bf16 dequantize-at-load + sdpa + compile/cudagraph	~28 tok/s
FP8 natif + compile/cudagraph	~4 tok/s (mémoire uniquement, pas pour la vitesse)

La déquantisation en bf16 n’est compatible qu’avec un sharding pair entre les GPU (TP/EP), et non avec device_map="auto" (le placement par pipeline provoque une OOM au chargement). Lancez un processus par GPU avec torchrun :

torchrun --nproc_per_node=8 fastest_m3_vl.py

# fastest_m3_vl.py
import os, sys
import torch
import torch.distributed as dist
from transformers import (
    AutoModelForImageTextToText,
    AutoTokenizer,
    CompileConfig,
    FineGrainedFP8Config,
)
from transformers.distributed import DistributedConfig

# The indexer feeds SDPA an additive float mask; the cuDNN SDP backend segfaults on it (B200).
torch.backends.cuda.enable_cudnn_sdp(False)

model = AutoModelForImageTextToText.from_pretrained(
    "MiniMaxAI/MiniMax-M3-preview",
    dtype=torch.bfloat16,
    # Dequantize the native MXFP8 weights to bf16 at load (the speed win); needs even TP/EP sharding.
    quantization_config=FineGrainedFP8Config(dequantize=True),
    distributed_config=DistributedConfig(
        tp_size=int(os.environ["WORLD_SIZE"]),
        ep_size=int(os.environ["WORLD_SIZE"]),
    ),
    attn_implementation="kernels-staging/msa@v0",  # MSA block-sparse attention kernel
)
model.eval()

tokenizer = AutoTokenizer.from_pretrained("MiniMaxAI/MiniMax-M3-preview")
messages = [{"role": "user", "content": "Summarize the history of computing."}]
inputs = tokenizer.apply_chat_template(
    messages, add_generation_prompt=True, return_tensors="pt", return_dict=True
).to(f"cuda:{os.environ.get('LOCAL_RANK', '0')}")

generated_ids = model.generate(
    **inputs,
    max_new_tokens=128,
    do_sample=False,
    # Static cache + reduce-overhead cudagraph capture is what pushes decode to ~31 tok/s.
    cache_implementation="static",
    compile_config=CompileConfig(mode="reduce-overhead", fullgraph=True),
)
if int(os.environ.get("RANK", "0")) == 0:
    print(tokenizer.decode(generated_ids[0, inputs["input_ids"].shape[1]:], skip_special_tokens=True))

# cudagraph-captured NCCL collectives deadlock the NCCL/CUDA destructors at teardown; the output is
# already produced, so hard-exit to skip the hanging cleanup.
if dist.is_initialized():
    sys.stdout.flush()
    os._exit(0)

Transformers

MiniMax-M3-VL

Aperçu

Architecture

Attention à blocs creux (Lightning Indexer)

Tour de vision

Exemples d'utilisation

Exemple Apple

Configuration d'inférence la plus rapide

MiniMaxM3VLConfig

classe transformers.MiniMaxM3VLConfig

MiniMaxM3VLTextConfig

classe transformers.MiniMaxM3VLTextConfig

MiniMaxM3VLVisionConfig

classe transformers.MiniMaxM3VLVisionConfig

MiniMaxM3VLProcessor

classe transformers.MiniMaxM3VLProcessor

post_process_image_text_to_text

MiniMaxM3VLImageProcessor

classe transformers.MiniMaxM3VLImageProcessor

get_number_of_image_patches

patchify

prétraiter

redimensionner

MiniMaxM3VLVideoProcessor

classe transformers.MiniMaxM3VLVideoProcessor

get_num_of_video_patches

MiniMaxM3VLVisionModel

classe transformers.MiniMaxM3VLVisionModel

forward

MiniMaxM3VLTextModel

classe transformers.MiniMaxM3VLTextModel

forward

MiniMaxM3VLModel

classe transformers.MiniMaxM3VLModel

forward

MiniMaxM3VLForCausalLM

classe transformers.MiniMaxM3VLForCausalLM

forward

MiniMaxM3SparseForConditionalGeneration

classe transformers.MiniMaxM3SparseForConditionalGeneration

forward