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-06-12 贡献至 Hugging Face Transformers。

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-norm，以及在前 rotary_dim 维上的 部分 RoPE。config.layer_types[i] 随后选择 "full_attention"（稠密因果）或 "minimax_m3_sparse"，其中 MiniMaxM3VLIndexer 会为每个查询决定主注意力可以查看哪些键块。

Indexer 会为每个 key 打分，然后 将这些逐 key 的分数按 index_block_size 个 key 为一块进行 max-pooling，因此选择操作以 key 块 为粒度进行：对于每个 query，它保留 top-index_topk_blocks 个 key 块，以及始终启用的 index_local_blocks 个局部窗口块（在块级因果性约束下），并将逐块的 0/-inf 选择结果广播回块内的每个 key。最终得到一个 [B, 1, S_q, S_k] 的加性偏置，将其叠加到因果掩码上。从理论上讲，这意味着注意力仅在选中的 key 块上计算，但 transformers 目前不支持能够高效计算此操作的 kernel！我们将尽快将其添加到 kernels 中！

视觉塔

一个 MiniMaxM3VLVisionModel：在展平的 [N_patches, C·T·P·P] 输入上应用 Conv3d 补丁嵌入，随后是一组 CLIP 风格的编码器层，这些层携带 3D 旋转 位置嵌入（时间 / 高度 / 宽度维度）。MiniMaxM3VLPatchMerger 在送入两层 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 预填充	MSA 预填充	MSA 预填充高级
2K	27.8 tok/s	31.0	+12%	303 毫秒	257 毫秒	1.18×
4K	23.4 tok/s	30.5	+30%	684 毫秒	460 毫秒	1.49×
8K	17.8 tok/s	29.6	+66%	1906 毫秒	976 毫秒	1.95×
16K	12.0 tok/s	27.6	+130%	6110 毫秒	2344 毫秒	2.61×

该检查点以原生 MXFP8 格式提供。就 解码吞吐量 而言，经过验证的最快配置为 bf16（加载时反量化）+ MSA 块稀疏注意力内核 + 张量 & 专家并行 + reduce-overhead cudagraph 编译 —— 在 8×B200 上，2048 个 token 的预填充下，解码速度约为 31 tok/s。

将权重保留在 原生 FP8 中仅是一种显存占用选项——在此配置下，它永远不会更快。 FP8 Triton 专家/线性算子会被降级为不透明的 inductor 回退算子，cudagraph 无法在热专家路径上对其进行捕获，因此即使在 torch.compile(fullgraph=True) 下，原生 FP8 解码的实测速度也仅为 ~4.2 tok/s（比 bf16 路径慢约 7 倍）。仅当 bf16 权重无法装入显存时，才使用 FP8。

config（sdpa 基线，TP+EP，2048 个 token 的预填充，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 启动一个进程：

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

后处理图像文本到文本

MiniMaxM3VLImageProcessor

类 transformers.MiniMaxM3VLImageProcessor

get_number_of_image_patches

patchify

预处理

调整大小

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