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.2).

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

Model ini disumbangkan ke Hugging Face Transformers pada 2026-06-12.

MiniMax-M3-VL

Ikhtisar

MiniMax-M3-VL adalah anggota vision-language dari keluarga MiniMax-M3. Model ini menggabungkan vision tower bergaya CLIP (patch embedding Conv3d dengan 3D rotary position embeddings) dengan backbone teks MiniMax-M3, yaitu decoder Mixture-of-Experts campuran dense/sparse yang menggunakan expert SwiGLU-OAI yang di-gate dan lightning indexer untuk block-sparse attention.

Arsitektur

Perhatian blok-sparse (Lightning Indexer)

Setiap lapisan menggunakan GQA (num_key_value_heads = 4) dengan QK-norm per-head dan partial RoPE pada rotary_dim pertama. config.layer_types[i] kemudian memilih "full_attention" (causal padat) atau "minimax_m3_sparse", di mana MiniMaxM3VLIndexer menentukan, untuk setiap query, blok key mana yang boleh dilihat oleh perhatian utama.

Indexer memberikan skor pada setiap key, kemudian menggunakan max-pooling pada skor per-key tersebut menjadi blok-blok berisi index_block_size key, sehingga seleksi dilakukan pada granularitas blok key: untuk setiap query, sistem mempertahankan top-index_topk_blocks blok key serta blok jendela lokal index_local_blocks yang selalu aktif (di bawah kausalitas tingkat blok), lalu menyebarkan pilihan 0/-inf per blok kembali ke setiap key di dalam blok tersebut. Hasilnya adalah bias aditif [B, 1, S_q, S_k] yang dijumlahkan ke mask kausal. Secara teori, ini berarti perhatian hanya dihitung pada blok-blok key yang terpilih, tetapi transformers belum mendukung kernel yang menghitung ini secara efisien! Kami akan menambahkannya ke kernels segera!

Menara visi

A MiniMaxM3VLVisionModel: patch embedding Conv3d pada input yang diratakan [N_patches, C·T·P·P], tumpukan lapisan encoder bergaya CLIP yang membawa position embedding 3D rotary (pita waktu / tinggi / lebar). MiniMaxM3VLPatchMerger mengelompokkan spatial_merge_size² patch ke dimensi channel sebelum MiniMaxM3VLMultiModalProjector GELU 2-lapis memetakan fitur visual ke ukuran hidden teks.

Contoh penggunaan

Contoh di bawah ini menjalankan model pada gambar asli yang dimuat dengan 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])

Contoh Apple

Contoh ini meminta model tentang gambar apel, sekali lagi memuat gambar asli dengan 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])

Konfigurasi inferensi tercepat

ctx	Decode SDPA	MSA decode	MSA decode adv.	Prefill SDPA	Prefill MSA	MSA prefill adv.
2K	27,8 tok/dtk	31.0	+12%	303 ms	257 ms	1.18×
4K	23,4 tok/dtk	30.5	+30%	684 ms	460 ms	1.49×
8K	17,8 tok/dtk	29.6	+66%	1906 ms	976 ms	1.95×
16K	12,0 tok/dtk	27.6	+130%	6110 ms	2344 ms	2.61×

Checkpoint ini dikirim dalam format MXFP8 native. Untuk throughput decode, konfigurasi tercepat yang telah divalidasi adalah bf16 (didekuantisasi saat load) + kernel perhatian blok-sparse MSA + paralelisme tensor & expert + kompilasi cudagraph reduce-overhead — sekitar 31 tok/s decode pada 8×B200 dengan prefill 2048 token.

Menjaga bobot dalam FP8 native adalah opsi jejak memori saja — tidak pernah lebih cepat pada setup ini. Kernel Triton untuk expert/linear FP8 diturunkan sebagai kernel fallback inductor yang tidak transparan, sehingga cudagraph tidak dapat menangkapnya pada jalur expert yang panas, sehingga decode FP8-native terukur ~4,2 tok/s (≈7× lebih lambat daripada jalur bf16) bahkan di bawah torch.compile(fullgraph=True). Gunakan FP8 hanya jika bobot bf16 tidak muat.

config (baseline sdpa, TP+EP, prefill 2048-token, 8×B200)	decode
bf16 dequantize-at-load + MSA + compile/cudagraph	~31 tok/dtk
bf16 dequantize-at-load + sdpa + compile/cudagraph	~28 tok/dtk
FP8 native + compile/cudagraph	~4 tok/detik (hanya memori, bukan untuk kecepatan)

Dequantisasi ke bf16 hanya cocok dengan sharding genap di antara GPU (TP/EP), bukan dengan device_map="auto" (penempatan pipeline OOM saat load). Jalankan satu proses per GPU dengan 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

Ikhtisar

Arsitektur

Perhatian blok-sparse (Lightning Indexer)

Menara visi

Contoh penggunaan

Contoh Apple

Konfigurasi inferensi tercepat

MiniMaxM3VLConfig

kelas transformers.MiniMaxM3VLConfig

MiniMaxM3VLTextConfig

kelas transformers.MiniMaxM3VLTextConfig

MiniMaxM3VLVisionConfig

kelas transformers.MiniMaxM3VLVisionConfig

MiniMaxM3VLProcessor

kelas transformers.MiniMaxM3VLProcessor

post_process_image_text_to_text

MiniMaxM3VLImageProcessor

kelas transformers.MiniMaxM3VLImageProcessor

get_number_of_image_patches

patchify

praproses

resize

MiniMaxM3VLVideoProcessor

kelas transformers.MiniMaxM3VLVideoProcessor

get_num_of_video_patches

MiniMaxM3VLVisionModel

kelas transformers.MiniMaxM3VLVisionModel

forward

MiniMaxM3VLTextModel

kelas transformers.MiniMaxM3VLTextModel

forward

MiniMaxM3VLModel

kelas transformers.MiniMaxM3VLModel

forward

MiniMaxM3VLForCausalLM

kelas transformers.MiniMaxM3VLForCausalLM

forward

MiniMaxM3SparseForConditionalGeneration

kelas transformers.MiniMaxM3SparseForConditionalGeneration

forward