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

이 모델은 2026-06-12에 Hugging Face Transformers에 기여되었습니다.

MiniMax-M3-VL

개요

MiniMax-M3-VL은 MiniMax-M3 계열의 비전-언어 모델입니다. CLIP 스타일의 비전 타워(Conv3d 패치 임베딩과 3D 회전 위치 임베딩)와 MiniMax-M3 텍스트 백본을 결합하며, 이 텍스트 백본은 SwiGLU-OAI 게이트형 전문가와 블록-스파스 어텐션을 위한 lightning index를 사용하는 혼합 dense/sparse Mixture-of-Experts 디코더입니다.

아키텍처

블록 스파스 어텐션(Lightning Indexer)

각 레이어는 GQA(num_key_value_heads = 4)를 사용하며, 헤드별 QK-norm과 첫 rotary_dim에 대한 부분 RoPE를 적용합니다. config.layer_types[i]는 "full_attention"(밀집 인과) 또는 "minimax_m3_sparse"를 선택하며, 후자의 경우 MiniMaxM3VLIndexer가 쿼리별로 메인 어텐션이 참조할 수 있는 키 블록을 결정합니다.

인덱서는 모든 키에 점수를 매긴 다음, index_block_size개의 키로 구성된 블록 단위로 해당 키별 점수를 max-pooling합니다. 따라서 선택은 키 블록 단위로 이루어집니다. 쿼리별로 상위 index_topk_blocks개의 키 블록과 항상 활성화되는 index_local_blocks 로컬 윈도우 블록(블록 수준 인과성 조건 하에서)을 유지한 뒤, 블록별 0/-inf 선택을 해당 블록 내 모든 키로 다시 전파합니다. 그 결과로 [B, 1, S_q, S_k] 형태의 가산 바이어스가 생성되며, 이는 인과 마스크에 합산됩니다. 이론적으로 이는 주意的한 키 블록에 대해서만 어텐션이 계산됨을 의미하지만, transformers는 이를 효율적으로 계산하는 커널을 지원하지 않습니다! kernels에 최대한 빨리 추가할 예정입니다!

비전 타워

MiniMaxM3VLVisionModel: 평탄화된 [N_patches, C·T·P·P] 입력에 대한 Conv3d 패치 임베딩과, 3D 회전 위치 임베딩(시간 / 높이 / 너비 밴드)을 가진 CLIP 스타일 인코더 레이어 스택으로 구성됩니다. MiniMaxM3VLPatchMerger는 2층 GELU MiniMaxM3VLMultiModalProjector가 시각 특징을 텍스트 히든 사이즈로 매핑하기 전에 spatial_merge_size²개의 패치를 채널 차원으로 그룹화합니다.

사용 예시

아래 예제는 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 디코딩 고급	SDPA prefill	MSA prefill	MSA prefill adv.
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×

체크포인트는 네이티브 MXFP8로 제공됩니다. 디코드 처리량의 경우, 검증된 가장 빠른 구성은 bf16(로드 시 디퀀트) + MSA 블록 스파스 어텐션 커널 + 텐서 & 전문가 병렬화 + reduce-overhead cudagraph 컴파일입니다 — 2048 토큰 프리필에서 8×B200 기준으로 대략 31 tok/s의 디코드를 달성합니다.

네이티브 FP8로 가중치를 유지하는 것은 메모리 사용량 절감 옵션일 뿐이며, 이 설정에서는 절대 더 빠르지 않습니다. FP8 Triton experts/linear 커널은 cudagraph가 핫 expert 경로에서 캡처할 수 없는 불투명한 인덕터 폴백 커널로 컴파일됩니다. 따라서 torch.compile(fullgraph=True) 환경에서도 네이티브 FP8 디코딩은 약 4.2 tok/s(≈bf16 경로보다 7배 느림)를 기록했습니다. bf16 가중치가 메모리에 맞지 않을 때만 FP8을 사용하세요.

config (sdpa 기준, TP+EP, 2048-token prefill, 8×B200)	decode
bf16 dequantize-at-load + MSA + compile/cudagraph	~31 tok/s
bf16 dequantize-at-load + sdpa + compile/cudagraph	~28 tok/s
네이티브 FP8 + compile/cudagraph	~4 tok/s (메모리 전용, 속도용 아님)

bf16로 역양자화하는 경우 GPU 간 균등 샤딩(TP/EP)과만 호환되며, device_map="auto"(파이프라인 배치 시 로드 시 OOM 발생)와는 호환되지 않습니다. torchrun을 사용하여 GPU당 하나의 프로세스를 실행하세요:

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

class transformers.MiniMaxM3VLConfig

MiniMaxM3VLTextConfig

class transformers.MiniMaxM3VLTextConfig

MiniMaxM3VLVisionConfig

class transformers.MiniMaxM3VLVisionConfig

MiniMaxM3VLProcessor

class transformers.MiniMaxM3VLProcessor

post_process_image_text_to_text

MiniMaxM3VLImageProcessor

class transformers.MiniMaxM3VLImageProcessor

get_number_of_image_patches

patchify

preprocess

리사이즈

MiniMaxM3VLVideoProcessor

class transformers.MiniMaxM3VLVideoProcessor

get_num_of_video_patches

MiniMaxM3VLVisionModel

class transformers.MiniMaxM3VLVisionModel

forward

MiniMaxM3VLTextModel

class transformers.MiniMaxM3VLTextModel

forward

MiniMaxM3VLModel

class transformers.MiniMaxM3VLModel

forward

MiniMaxM3VLForCausalLM

class transformers.MiniMaxM3VLForCausalLM

forward

MiniMaxM3SparseForConditionalGeneration

class transformers.MiniMaxM3SparseForConditionalGeneration

forward