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

Эта модель была добавлена в Hugging Face Transformers 12.06.2026.

MiniMax-M3-VL

Обзор

MiniMax-M3-VL — это мультимодальная модель семейства MiniMax-M3, работающая с изображениями и текстом. Она сочетает в себе визуальный блок в стиле CLIP (встраивание патчей с помощью Conv3d и 3D-ротационные позиционные встраивания) с текстовым бэкбоном MiniMax-M3, который представляет собой гибридный плотный/разреженный декодер Mixture-of-Experts, использующий гейтированные эксперты SwiGLU-OAI и молниеносный индексатор для блочно-разреженного внимания.

Архитектура

Блок-разреженное внимание (Lightning Indexer)

Каждый слой использует GQA (num_key_value_heads = 4) с нормализацией QK для каждой головы и частичным RoPE на первых rotary_dim. Затем config.layer_types[i] выбирает "full_attention" (плотное причинно-следственное) или "minimax_m3_sparse", где MiniMaxM3VLIndexer определяет для каждого запроса, какой блок ключей может видеть основное внимание.

Индексер вычисляет оценку для каждого ключа, затем применяет max-pooling к этим оценкам, группируя ключи в блоки по index_block_size, поэтому выбор происходит с гранулярностью блока ключей: для каждого запроса сохраняются топ-index_topk_blocks блоков ключей, а также всегда активный блок локального окна index_local_blocks (при блочной каузальности), после чего выбор 0/-inf для каждого блока распространяется на все ключи в этом блоке. Результатом является аддитивный bias размера [B, 1, S_q, S_k], который суммируется с каузальной маской. Теоретически это означает, что внимание вычисляется только по выбранным блокам ключей, но transformers не поддерживает ядра, которые делают это эффективно! Мы добавляем это в kernels как можно скорее!

Башня зрения

Модель MiniMaxM3VLVisionModel: встраивание патчей через Conv3d по сглаженному входу [N_patches, C·T·P·P], а также стек кодировщиков в стиле CLIP с 3D-поворотным встраиванием позиций (полосы для времени / высоты / ширины). Модуль MiniMaxM3VLPatchMerger объединяет spatial_merge_size² патчей в размерность каналов перед тем, как двухслойный проектор MiniMaxM3VLMultiModalProjector с активацией GELU отображает визуальные признаки в размер скрытых состояний текста.

Примеры использования

Приведённый ниже пример запускает модель на реальном изображении, загруженном с помощью 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])

Пример Apple

В этом примере модель спрашивают об изображении яблок, снова загружая реальное изображение с помощью 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])

Самая быстрая конфигурация инференса

ctx	Декодирование SDPA	Декодирование MSA	Расширенный режим декодирования MSA	Prefill в SDPA	Prefill MSA	MSA prefill adv.
2K	27,8 ток/с	31.0	+12%	303 мс	257 мс	1.18×
4K	23,4 ток/с	30.5	+30%	684 мс	460 мс	1.49×
8K	17,8 ток/с	29.6	+66%	1906 мс	976 мс	1.95×
16K	12,0 ток/с	27.6	+130%	6110 мс	2344 мс	2.61×

Чекпоинт поставляется в нативном формате MXFP8. Для throughput декодирования самая быстрая проверенная конфигурация — bf16 (деквантование при загрузке) + блочно-разреженное ядро внимания MSA + тензорная и экспертная параллельность + компиляция reduce-overhead с cudagraph — примерно 31 ток/с при декодировании на 8×B200 с prefill из 2048 токенов.

Хранение весов в нативном FP8 — это вариант, направленный только на экономию памяти, и он никогда не быстрее в данной конфигурации. Ядра экспертов/линейных слоёв FP8 на Triton компилируются в непрозрачные fallback-ядра индуктора, которые cudagraph не может захватить на горячем пути эксперта, поэтому декодирование в нативном FP8 показало ~4,2 ток/с (примерно в 7 раз медленнее, чем путь в bf16) даже при использовании torch.compile(fullgraph=True). Используйте FP8 только в том случае, если веса в bf16 не помещаются в память.

config (sdpa baseline, TP+EP, prefill 2048 токенов, 8×B200)	decode
bf16 dequantize-at-load + MSA + compile/cudagraph	~31 ток/с
bf16 dequantize-at-load + sdpa + compile/cudagraph	~28 ток/с
нативный FP8 + compile/cudagraph	~4 ток/с (только память, не для скорости)

Декуантизация в bf16 совместима только с равномерным шардированием по GPU (TP/EP), а не с device_map="auto" (при загрузке возникает OOM из-за пайплайн-размещения). Запускайте по одному процессу на каждый GPU с помощью 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

Обзор

Архитектура

Блок-разреженное внимание (Lightning Indexer)

Башня зрения

Примеры использования

Пример Apple

Самая быстрая конфигурация инференса

MiniMaxM3VLConfig

класс transformers.MiniMaxM3VLConfig

MiniMaxM3VLTextConfig

класс transformers.MiniMaxM3VLTextConfig

MiniMaxM3VLVisionConfig

класс transformers.MiniMaxM3VLVisionConfig

MiniMaxM3VLProcessor

класс transformers.MiniMaxM3VLProcessor

post_process_image_text_to_text

MiniMaxM3VLImageProcessor

класс transformers.MiniMaxM3VLImageProcessor

get_number_of_image_patches

patchify

preprocess

resize

MiniMaxM3VLVideoProcessor

класс transformers.MiniMaxM3VLVideoProcessor

get_num_of_video_patches

MiniMaxM3VLVisionModel

класс transformers.MiniMaxM3VLVisionModel

forward

MiniMaxM3VLTextModel

класс transformers.MiniMaxM3VLTextModel

forward

MiniMaxM3VLModel

класс transformers.MiniMaxM3VLModel

forward

MiniMaxM3VLForCausalLM

класс transformers.MiniMaxM3VLForCausalLM

forward

MiniMaxM3SparseForConditionalGeneration

класс transformers.MiniMaxM3SparseForConditionalGeneration

forward