Transformers documentation

MiniMax-M3-VL

Transformers

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年6月12日に Hugging Face Transformers に貢献されました。

MiniMax-M3-VL

概要

MiniMax-M3-VL は、MiniMax-M3 ファミリーのビジョン・言語モデルです。CLIP スタイルのビジョン・タワー（3D 回転位置埋め込みを備えた Conv3d パッチ埋め込み）と、MiniMax-M3 テキスト・バックボーンを組み合わせます。このバックボーンは、SwiGLU-OAI ゲート付きエキスパートとブロックスパース注意のためのライトニング・インデクサーを使用する、密結合/スパース混合型の 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デコード adv.	SDPAプリフィル	MSAプリフィル	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 によるエキスパート/線形カーネルは、不透明な inductor フォールバックカーネルとして低レベル化され、ホットなエキスパートパスでは cudagraph がキャプチャできません。そのため、torch.compile(fullgraph=True) を使用した場合でも、ネイティブ FP8 のデコードは約 4.2 tok/s（bf16 パスより約 7 倍遅い）に留まります。FP8 は、bf16 の重みがメモリに収まらない場合にのみ使用してください。

config (sdpa ベースライン、TP+EP、2048トークンのプリフィル、8×B200)	decode
bf16 のロード時デクアンタイズ + MSA + compile/cudagraph	~31 tok/s
bf16 でのロード時デクアンタイズ + sdpa + compile/cudagraph	~28 tok/s
ネイティブ FP8 + compile/cudagraph	~4 tok/s（メモリのみ、速度を目的としない）

bf16 へのデクォンタイズは、GPU 間の偶数シャード（TP/EP）でのみ動作し、device_map="auto"（パイプライン配置はロード時に OOM する）では動作しません。torchrun を使用して、GPU ごとに 1 プロセスを起動してください。

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

class transformers.MiniMaxM3VLTextConfig

MiniMaxM3VLVisionConfig

class transformers.MiniMaxM3VLVisionConfig

MiniMaxM3VLProcessor

クラス 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

クラス transformers.MiniMaxM3VLForCausalLM

forward

MiniMaxM3SparseForConditionalGeneration

クラス transformers.MiniMaxM3SparseForConditionalGeneration

forward