# MiniMaxAI/MiniMax-M3 — vLLM serving recipe

> MiniMax M3 vision-language MoE (427B total / 26B active) for frontier coding, agent toolchains, and 1M-token reasoning via MSA sparse attention — native multimodal (image + video + computer use); BF16 plus MXFP8, NVIDIA Blackwell NVFP4, and AMD MI355X MXFP4 variants. Runs on NVIDIA (Hopper/Blackwell) and AMD CDNA4/CDNA3.

Configuration: hardware `h200` (8× H200) · strategy `single_node_tp` (Tensor Parallel) · variant `default` (BF16) · features `tool_calling`, `reasoning`

- Interactive page: https://recipes.vllm.ai/MiniMaxAI/MiniMax-M3
- This configuration as JSON: https://recipes.vllm.ai/MiniMaxAI/MiniMax-M3.json?hardware=h200

The commands below were rendered for exactly this configuration and take precedence over any example in the guide.

## Other configurations

Change the query string (the same parameters as the page URL) and fetch this URL again. Unknown or incompatible values fall back to the recipe default, so check the Configuration line.

- `hardware`: `h100`, `h200`, `b200`, `gb200`, `b300`, `gb300`, `mi300x`, `mi325x`, `mi350x`, `mi355x`
- `variant`: `default`, `mxfp8`, `nvfp4`, `mxfp4`
- `strategy`: `single_node_tp`, `single_node_tep`, `single_node_dep`, `multi_node_tp`, `multi_node_tp_pp`, `multi_node_tep`, `multi_node_dep`, `pd_cluster` (multi-node strategies also need `nodes=<n>`)
- `features`: comma-separated list of `tool_calling`, `reasoning`, `spec_decoding`, `text_only`, `thinking_always_on`, `encoder_parallel` (default: `tool_calling`, `reasoning`)
- `preset`: a tuned, evidence-backed configuration (`baseline` opts out of a default one). Each sets its own hardware and strategy:
  - `h200_agentx` — AgentX TP8 (h200 · TP · Agentic (InferenceX AgentX) · opt-in): `hardware=h200&variant=mxfp8&strategy=single_node_tp&preset=h200_agentx`
  - `b200_agentx` — AgentX TP4 (b200 · TP · Agentic (InferenceX AgentX) · opt-in): `hardware=b200&variant=nvfp4&strategy=single_node_tp&preset=b200_agentx`
  - `b200_agentx_c10` — AgentX active-seq caps (b200 · TP · Agentic (InferenceX AgentX) · opt-in): `hardware=b200&variant=nvfp4&strategy=single_node_tp&preset=b200_agentx_c10`
  - `b300_agentx` — AgentX (b300 · TP · Agentic (InferenceX AgentX) · opt-in): `hardware=b300&variant=nvfp4&strategy=single_node_tp&preset=b300_agentx`
  - `gb200_agentx` — AgentX TP4 (gb200 · TP · Agentic (InferenceX AgentX) · opt-in): `hardware=gb200&variant=nvfp4&strategy=single_node_tp&preset=gb200_agentx`
  - `gb200_agentx_tp8` — AgentX TP8 (gb200 · Multi-node TP · Agentic (InferenceX AgentX) · opt-in): `hardware=gb200&variant=nvfp4&strategy=multi_node_tp&preset=gb200_agentx_tp8`
  - `mi355x_agentx` — AgentX (mi355x · TP · Agentic (InferenceX AgentX) · opt-in): `hardware=mi355x&variant=mxfp4&strategy=single_node_tp&preset=mi355x_agentx`

## Install

Requires vLLM >= 0.24.0 (not released yet — nightly wheel).

vLLM 0.24.0 isn't released yet — nightly required. Nightly wheels are CUDA 13 (cu130) only; the host needs an r580+ NVIDIA driver.

```bash
uv venv
source .venv/bin/activate
uv pip install -U vllm --pre \
  --extra-index-url https://wheels.vllm.ai/nightly/cu130 \
  --extra-index-url https://download.pytorch.org/whl/cu130 \
  --index-strategy unsafe-best-match
```

Docker image: `vllm/vllm-openai:minimax-m3`

## Serve

```bash
vllm serve MiniMaxAI/MiniMax-M3 \
  --block-size 128 \
  --max-model-len 65536 \
  --tensor-parallel-size 8 \
  --tool-call-parser minimax_m3 \
  --enable-auto-tool-choice \
  --reasoning-parser minimax_m3
```

Docker equivalent:

```bash
docker run --gpus all \
  --privileged --ipc=host -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:minimax-m3 MiniMaxAI/MiniMax-M3 \
  --block-size 128 \
  --max-model-len 65536 \
  --tensor-parallel-size 8 \
  --tool-call-parser minimax_m3 \
  --enable-auto-tool-choice \
  --reasoning-parser minimax_m3
```

## Guide

> Background reference. Commands in it are examples and may target another configuration — use the Serve section above.

### Overview

[MiniMax-M3](https://huggingface.co/MiniMaxAI/MiniMax-M3) is a frontier
vision-language MoE model from [MiniMax](https://www.minimax.io/).

- **MSA (MiniMax Sparse Attention)** — scalable sparse-attention architecture
  that lifts the context window to **1M tokens**. MiniMax reports per-token
  compute at 1M context reduced to ~1/20 of the previous generation, with
  >9× prefill and >15× decode speedup vs dense baselines.
- **Frontier coding and agent capabilities** — SWE-Bench Pro 59.0%,
  Terminal-Bench 2.1 66.0%, SWE-fficiency 34.8%, KernelBench Hard 28.8%,
  MCP Atlas 74.2%.
- **Native multimodal** — image + video inputs, plus computer-use; trained
  multimodally from step 0.
- **Two reasoning modes** — `thinking` (complex reasoning / agents) and
  `non-thinking` (latency-sensitive), switchable per request.

### Prerequisites

- **OS:** Linux
- **Python:** 3.10 - 3.13
- **NVIDIA:** compute capability >= 9.0 (Hopper) recommended; 8x H200 / H20
  for a tight single-node BF16 fit, or multi-node TP for long-context headroom
- **AMD:** MI350X/MI355X (gfx950), MI300X/MI325X (gfx942), ROCm 7.2+. BF16
  needs TP=8; the MXFP8 variant runs from TP=4.
- **`--block-size 128` is mandatory on every platform** (MSA sparse/index cache).

#### Docker (NVIDIA)

MiniMax-M3 support has not yet shipped in a stable vLLM release — use the
dedicated Docker image:

```bash
docker pull vllm/vllm-openai:minimax-m3
```

#### Docker (AMD ROCm)

Use the nightly image, which is the image the AMD variants of this recipe pin:

```bash
docker pull vllm/vllm-openai-rocm:nightly
```

```bash
docker run --rm -it --device /dev/kfd --device /dev/dri --group-add video \
  --cap-add SYS_PTRACE --security-opt seccomp=unconfined --ipc=host \
  --shm-size=16g -p 8000:8000 \
  --entrypoint /bin/bash \
  vllm/vllm-openai-rocm:nightly
```

### Launching the Server

#### NVIDIA — TP8 (8x H200 / H20)

```bash
vllm serve MiniMaxAI/MiniMax-M3 \
  --tensor-parallel-size 8 \
  --block-size 128 \
  --tool-call-parser minimax_m3 \
  --reasoning-parser minimax_m3 \
  --enable-auto-tool-choice
```

##### TP8 + Expert Parallel

```bash
vllm serve MiniMaxAI/MiniMax-M3 \
  --tensor-parallel-size 8 \
  --enable-expert-parallel \
  --block-size 128 \
  --tool-call-parser minimax_m3 \
  --reasoning-parser minimax_m3 \
  --enable-auto-tool-choice
```

##### DP8 + Expert Parallel

```bash
vllm serve MiniMaxAI/MiniMax-M3 \
  --data-parallel-size 8 \
  --enable-expert-parallel \
  --block-size 128 \
  --tool-call-parser minimax_m3 \
  --reasoning-parser minimax_m3 \
  --enable-auto-tool-choice
```

#### AMD ROCm (MI350X/MI355X (gfx950), MI300X/MI325X (gfx942))

On AMD MI300X / MI325X / MI355X, run with CUDA graphs and set the following
before any of the serve commands below. It avoids the MiniMax-M3 decode breakable-cudagraph path that would
otherwise force eager execution (per @hongxiayang):

```bash
export VLLM_USE_BREAKABLE_CUDAGRAPH=0
```

For gfx950: Prefer using the MXFP8 variant `MiniMaxAI/MiniMax-M3-MXFP8` for TP=4 and a smaller
footprint. Use TP=8 for lower latency or long context length, or the default bf16 model.

##### TP8 (Text or Vision)

```bash
vllm serve MiniMaxAI/MiniMax-M3 \
  --tensor-parallel-size 8 \
  --block-size 128 \
  --attention-backend TRITON_ATTN \
  --mm-encoder-tp-mode data \
  --mm-encoder-attn-backend ROCM_AITER_FA \
  --tool-call-parser minimax_m3 \
  --reasoning-parser minimax_m3 \
  --enable-auto-tool-choice
```

Add the vision-encoder flags (`--mm-encoder-tp-mode data
--mm-encoder-attn-backend ROCM_AITER_FA`) for multimodal serving.

##### TP8 + `--quantization fp8_per_channel`

Online **per-channel FP8 (PTPC)** quantization of the BF16 checkpoint halves the
weight footprint (≈100 → **≈50 GiB/GPU**, ~1.75× more KV cache) and lifts
batched throughput with **gsm8k unchanged from BF16** (lossless); 
These env vars and the flag are for the **BF16 checkpoint only**.

```bash
export VLLM_USE_BREAKABLE_CUDAGRAPH=0
export VLLM_ROCM_USE_AITER=1
export VLLM_ROCM_USE_AITER_MOE=0

vllm serve MiniMaxAI/MiniMax-M3 \
  --tensor-parallel-size 8 \
  --block-size 128 \
  --attention-backend TRITON_ATTN \
  --quantization fp8_per_channel \
  --tool-call-parser minimax_m3 \
  --reasoning-parser minimax_m3 \
  --enable-auto-tool-choice
```

##### TP8 + Expert Parallel

```bash
vllm serve MiniMaxAI/MiniMax-M3 \
  --tensor-parallel-size 8 \
  --enable-expert-parallel \
  --block-size 128 \
  --attention-backend TRITON_ATTN \
  --mm-encoder-tp-mode data \
  --mm-encoder-attn-backend ROCM_AITER_FA \
  --tool-call-parser minimax_m3 \
  --reasoning-parser minimax_m3 \
  --enable-auto-tool-choice
```

##### DP8 + Expert Parallel

```bash
vllm serve MiniMaxAI/MiniMax-M3 \
  --data-parallel-size 8 \
  --enable-expert-parallel \
  --block-size 128 \
  --attention-backend TRITON_ATTN \
  --mm-encoder-tp-mode data \
  --mm-encoder-attn-backend ROCM_AITER_FA \
  --tool-call-parser minimax_m3 \
  --reasoning-parser minimax_m3 \
  --enable-auto-tool-choice
```

### FP8 KV Cache

Add `--kv-cache-dtype fp8` to any command for ~1.5× the KV pool — lossless
in our testing across the full native context. Especially worth it for high
concurrency or long context, where KV is the binding constraint.

### Context Length & GPU Memory

The full **1M-token** window (`context_length: 1048576`) needs a large KV
cache. To save GPU memory, you can optionally cap the context with
`--max-model-len`:

```bash
vllm serve MiniMaxAI/MiniMax-M3 \
  --tensor-parallel-size 8 \
  --block-size 128 \
  --max-model-len 131072        # 128K instead of the full 1M
```

AMD ROCm notes: Native context is 512K. To go past it, supply a YaRN rope_scaling on the text config
(a top-level override silently misses the decoder's config) and allow the long max length.
TP=8 + fp8 KV is the practical combo at 1M:

```bash
VLLM_ALLOW_LONG_MAX_MODEL_LEN=1 \
  vllm serve MiniMaxAI/MiniMax-M3 \
  --block-size 128 \
  --kv-cache-dtype fp8 \
  --tensor-parallel-size 8 \
  --max-model-len 1048576 \
  --attention-backend TRITON_ATTN \
  --mm-encoder-tp-mode data \
  --mm-encoder-attn-backend ROCM_AITER_FA \
  --tool-call-parser minimax_m3 \
  --enable-auto-tool-choice \
  --reasoning-parser minimax_m3 \
  --hf-overrides '{"text_config":{"rope_scaling":{"rope_type":"yarn","factor":2.0,"original_max_position_embeddings":524288}}}'
```

- Set `--max-model-len` to the longest prompt + output you actually serve
  (e.g. `32768`, `131072`, `262144`). A smaller window frees KV-pool headroom
  for higher concurrency and lets the model fit on fewer GPUs; if you need the
  full 1M window, consider scaling out with multi-node TP instead.

### Client Usage

Recommended sampling parameters (from the model card):

- `temperature = 1.0`
- `top_p = 0.95`
- `top_k = 40`

Default system prompt:

```
You are a helpful assistant. Your name is MiniMax-M3 and is built by MiniMax.
```

Example chat request:

```bash
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M3",
    "temperature": 1.0,
    "top_p": 0.95,
    "messages": [
      {"role": "system", "content": "You are a helpful assistant. Your name is MiniMax-M3 and is built by MiniMax."},
      {"role": "user", "content": "Explain MSA sparse attention in 3 bullets."}
    ]
  }'
```

### Thinking Modes

M3 reasoning is controlled by the `thinking_mode`, there are three values:

- **`enabled`** — the model thinks before every response, including after tool results. 
  Use for complex reasoning and agents.
- **`disabled`** — no thinking; the model answers directly. Use for
  latency-sensitive turns.
- **`adaptive`** *(default when unset)* — the model decides whether to think
  based on the task.

Pass it per request through `chat_template_kwargs`. The same value also tunes
the `minimax_m3` reasoning parser, so `reasoning` and `content` are
split correctly in every mode.

```python

# Start the MiniMax-M3 model by referring to the command above first.

from openai import OpenAI

client = OpenAI(api_key="EMPTY", base_url="http://localhost:8000/v1")

response = client.chat.completions.create(
    model="MiniMaxAI/MiniMax-M3",
    messages=[{"role": "user", "content": "Prove there are infinitely many primes."}],
    extra_body={"chat_template_kwargs": {"thinking_mode": "enabled"}},
)
msg = response.choices[0].message
print(msg.reasoning)  # the <mm:think> block
print(msg.content)  # the final answer
```

### Benchmarking

```bash
vllm bench serve \
  --backend vllm \
  --model MiniMaxAI/MiniMax-M3 \
  --endpoint /v1/completions \
  --dataset-name random \
  --random-input 2048 \
  --random-output 1024 \
  --max-concurrency 10 \
  --num-prompt 100
```

### Quantized Variant (MXFP8)

[`MiniMaxAI/MiniMax-M3-MXFP8`](https://huggingface.co/MiniMaxAI/MiniMax-M3-MXFP8)
is an MXFP8 checkpoint quantized by NVIDIA from the original FP16 weights —
roughly half the VRAM of the BF16 release. Select the **mxfp8** variant above,
or pass the repo id directly to `vllm serve`:

```bash
vllm serve MiniMaxAI/MiniMax-M3-MXFP8 \
  --tensor-parallel-size 8 \
  --block-size 128 \
  --tool-call-parser minimax_m3 \
  --reasoning-parser minimax_m3 \
  --enable-auto-tool-choice
```

For best MXFP8 throughput, prefer Blackwell (B200/B300) for native MX tensor cores,
or AMD CDNA4 (MI350X/MI355X, gfx950) for native MXFP8 matrix cores.

On AMD MI300X, the **mxfp8** variant stacks two accuracy-safe scheduling
levers from the InferenceX MI300X tuning recipe and avoids the high-concurrency
expert-parallel regression by using plain TP8:

```bash
export VLLM_ENGINE_READY_TIMEOUT_S=3600
export VLLM_USE_BREAKABLE_CUDAGRAPH=0
export VLLM_ROCM_USE_AITER=1
export VLLM_ROCM_USE_AITER_MHA=0
export TORCH_BLAS_PREFER_HIPBLASLT=1
export NCCL_MIN_NCHANNELS="${NCCL_MIN_NCHANNELS:-112}"
export GPU_MAX_HW_QUEUES="${GPU_MAX_HW_QUEUES:-2}"

vllm serve MiniMaxAI/MiniMax-M3-MXFP8 \
  --tensor-parallel-size 8 \
  --block-size 128 \
  --language-model-only \
  --max-model-len "$MAX_MODEL_LEN" \
  --attention-backend TRITON_ATTN \
  --async-scheduling \
  --max-num-batched-tokens 16384 \
  --tool-call-parser minimax_m3 \
  --reasoning-parser minimax_m3 \
  --enable-auto-tool-choice
```

On AMD MI355X the **mxfp8** variant additionally enables the AITER kernels,
the fused shared-experts MoE, and INT4 QuickReduce, and pulls the nightly ROCm
image (`vllm/vllm-openai-rocm:nightly`) — selected automatically in the command
builder. If you launch by hand:

```bash
export VLLM_USE_BREAKABLE_CUDAGRAPH=0
export VLLM_ROCM_USE_AITER=1
export VLLM_ROCM_USE_AITER_FUSION_SHARED_EXPERTS=1
export VLLM_ROCM_QUICK_REDUCE_QUANTIZATION=INT4

vllm serve MiniMaxAI/MiniMax-M3-MXFP8 \
  --tensor-parallel-size 8 \
  --block-size 128 \
  --attention-backend TRITON_ATTN \
  --tool-call-parser minimax_m3 \
  --reasoning-parser minimax_m3 \
  --enable-auto-tool-choice
```

#### MXFP8 high-concurrency options on MI355X

The command above is the default serving configuration and is tuned for the
general case. **AITER page-16 sparse paged attention** helps specifically at **long context and
high concurrency**. It maps MiniMax-M3's top-k 128-token MSA blocks onto AITER page-16 block tables
and runs AITER Gluon paged attention over only the selected KV pages.

The high-concurrency configuration is:

```bash
# Long context + high concurrency only (isl >= 8k, conc >= 64). Regresses
# short-context / low-concurrency serving.
export VLLM_USE_BREAKABLE_CUDAGRAPH=0
export VLLM_ROCM_USE_AITER=1
export VLLM_ROCM_USE_AITER_FUSION_SHARED_EXPERTS=1
export VLLM_ROCM_SHUFFLE_KV_CACHE_LAYOUT=1
export VLLM_ROCM_QUICK_REDUCE_QUANTIZATION=INT4
export VLLM_ROCM_QUICK_REDUCE_CAST_BF16_TO_FP16=0
export VLLM_ROCM_QUICK_REDUCE_QUANTIZATION_MIN_SIZE_KB=256

vllm serve MiniMaxAI/MiniMax-M3-MXFP8 \
  --tensor-parallel-size 4 \
  --block-size 128 \
  --language-model-only \
  --moe-backend aiter \
  --kv-cache-dtype fp8 \
  --max-num-batched-tokens 32768 \
  --attention-backend TRITON_ATTN \
  --linear-backend emulation \
  --tool-call-parser minimax_m3 \
  --reasoning-parser minimax_m3 \
  --enable-auto-tool-choice
```

Note: Outside the long-context/high-batch
regime the shuffled layout costs more than it saves; leave it at `0`:

```bash
export VLLM_ROCM_SHUFFLE_KV_CACHE_LAYOUT=0
```

### Quantized Variant (NVFP4 on Blackwell)

[`nvidia/MiniMax-M3-NVFP4`](https://huggingface.co/nvidia/MiniMax-M3-NVFP4)
is an NVFP4 checkpoint quantized by NVIDIA with ModelOpt. It requires a vLLM
build with MiniMax-M3 NVFP4 support (vllm-project/vllm PR #46380).

Select the **nvfp4** variant and **B200** hardware in the command builder, or
launch the tested B200 baseline directly:

```bash
VLLM_FLOAT32_MATMUL_PRECISION=high \
  vllm serve nvidia/MiniMax-M3-NVFP4 \
  --tensor-parallel-size 8 \
  --trust-remote-code \
  --block-size 128 \
  --tool-call-parser minimax_m3 \
  --reasoning-parser minimax_m3 \
  --enable-auto-tool-choice
```

Pair it with EAGLE3 speculative decoding (the *Spec decoding* feature) for
faster decode — the validated B200 benchmark runs the NVFP4 target against the
`Inferact/MiniMax-M3-EAGLE3` draft head (3 speculative tokens):

```bash
VLLM_FLOAT32_MATMUL_PRECISION=high \
  vllm serve nvidia/MiniMax-M3-NVFP4 \
  --tensor-parallel-size 8 \
  --trust-remote-code \
  --block-size 128 \
  --language-model-only \
  --speculative-config '{"method": "eagle3", "model": "Inferact/MiniMax-M3-EAGLE3", "num_speculative_tokens": 3, "attention_backend": "FLASH_ATTN"}'
```

For long-context or high-batch workloads where draft KV memory is the binding
constraint, swap in the **GQA** variant:

```bash
VLLM_FLOAT32_MATMUL_PRECISION=high \
  vllm serve nvidia/MiniMax-M3-NVFP4 \
  --tensor-parallel-size 8 \
  --trust-remote-code \
  --block-size 128 \
  --language-model-only \
  --speculative-config '{"method": "eagle3", "model": "Inferact/MiniMax-M3-EAGLE3-GQA", "num_speculative_tokens": 3, "attention_backend": "FLASH_ATTN"}'
```

You may also consider FlashInfer for draft attention if it performs better for
your workload, and local argmax reduction to reduce communication traffic:

```bash
--speculative-config '{"method":"eagle3","model":"Inferact/MiniMax-M3-EAGLE3-GQA","num_speculative_tokens":3,"attention_backend":"FLASHINFER","use_local_argmax_reduction":true}'
```

### GB200: InferenceX AgentX aggregated (Dynamo + vLLM)

The GB200 AgentX lane in [SemiAnalysis InferenceX](https://inferencex.semianalysis.com/)
(`minimaxm3-fp4-gb200-dynamo-vllm-agentic-agg-mtp`,
[SemiAnalysisAI/InferenceX#4281](https://github.com/SemiAnalysisAI/InferenceX/pull/4281))
serves the NVFP4 checkpoint with the GQA EAGLE3 draft as aggregated vLLM
workers behind the Dynamo frontend's KV-aware router. Its measured points are
two opt-in presets: [AgentX TP4](https://recipes.vllm.ai/MiniMaxAI/MiniMax-M3.md?hardware=gb200&variant=nvfp4&strategy=single_node_tp&preset=gb200_agentx), one worker per 4-GPU
tray, whose larger points add host KV offload; and
[AgentX TP8](https://recipes.vllm.ai/MiniMaxAI/MiniMax-M3.md?hardware=gb200&variant=nvfp4&strategy=multi_node_tp&preset=gb200_agentx_tp8), one worker across two trays. Each
point renders the worker's engine flags, environment and pinned image. The
TP4 preset's runbook has the etcd, NATS, Dynamo worker and frontend steps
that the command builder doesn't render.

### Quantized Variant (MXFP4 on MI355X)

[`amd/MiniMax-M3-MXFP4`](https://huggingface.co/amd/MiniMax-M3-MXFP4)
uses static OCP MXFP4 weights and dynamic OCP MXFP4 activations produced with
AMD Quark. It targets AMD Instinct MI355X (gfx950) and requires a ROCm
nightly containing the Quark MXFP4 fix from vLLM PR #45794.

Select the **mxfp4** variant and **MI355X** hardware in the command builder,
or launch the tested TP8 baseline directly:

```bash
vllm serve amd/MiniMax-M3-MXFP4 \
  --tensor-parallel-size 8 \
  --trust-remote-code \
  --block-size 128 \
  --attention-backend TRITON_ATTN \
  --mm-encoder-tp-mode data \
  --mm-encoder-attn-backend ROCM_AITER_FA \
  --tool-call-parser minimax_m3 \
  --enable-auto-tool-choice \
  --reasoning-parser minimax_m3
```

#### MXFP4 AgentX on MI355X

The opt-in [AgentX preset](https://recipes.vllm.ai/MiniMaxAI/MiniMax-M3.md?hardware=mi355x&variant=mxfp4&strategy=single_node_tp&preset=mi355x_agentx) follows
[InferenceX #4418](https://github.com/SemiAnalysisAI/InferenceX/pull/4418) on its
pinned ROCm image: TP4 at concurrency 1, 4, 5, 8, 10, 12, 15, 20, 24 and 32
enables monokernel; TP2 at 1 and 2 uses ordinary decode. Both use Model Runner V2,
the three-token GQA EAGLE3 draft and real target verification, with no offload.
These text-only MXFP4 settings are workload-specific; the general serving
configuration remains unchanged. Synthetic acceptance is for throughput
reproduction only, as described in the preset's runbook.

### Troubleshooting

- **`--block-size` mismatch.** MSA's sparse block size is 128; the vLLM KV
  cache block size must match. Using the default (16) misaligns the sparse
  attention indexing (on AMD it crashes with `No common block size for 16`).
- **Parsers.** `--tool-call-parser` and `--reasoning-parser` both use
  `minimax_m3` — distinct from `minimax_m2` used by earlier releases.
- **Long context KV cache.** See *Context Length & GPU Memory* above — cap
  `--max-model-len` or scale to multi-node TP if you OOM.
- **Vision encoder.** The encoder is small, so at high TP the *Encoder
  Parallel* option runs it data-parallel (`--mm-encoder-tp-mode data`) to
  avoid TP comm overhead; it also turns on the vision-encoder attention
  backend (FlashInfer on NVIDIA, `--mm-encoder-attn-backend FLASHINFER`;
  AITER FlashAttention on AMD, `ROCM_AITER_FA`) and the host-shared-memory
  multimodal processor cache (`--mm-processor-cache-type shm`). For **text-only** workloads enable *Text only*
  (`--language-model-only`) to skip loading the encoder and free VRAM — it is
  mutually exclusive with Encoder Parallel.


### EAGLE3 Speculative Decoding

Two Inferact draft heads are available as selectable modes in the *Spec decoding*
feature — both use `method: eagle3` with 3 speculative tokens and share
MiniMax-M3's embedding table and LM head:

| Mode | Repo | KV heads | Draft KV cache |
|------|------|----------|----------------|
| **MHA** (default) | `Inferact/MiniMax-M3-EAGLE3` | 64 | baseline |
| **GQA** | `Inferact/MiniMax-M3-EAGLE3-GQA` | 4 | **16× smaller** |

The GQA head uses Grouped Query Attention (4 KV heads grouped from 64 query
heads) — the only architectural difference from the MHA head. The 16× reduction
in draft KV state makes it preferable when draft memory is the binding constraint
(long-context serving or large batch sizes).

### References

- [Model card](https://huggingface.co/MiniMaxAI/MiniMax-M3)
- [MXFP8 variant](https://huggingface.co/MiniMaxAI/MiniMax-M3-MXFP8)
- [NVFP4 variant](https://huggingface.co/nvidia/MiniMax-M3-NVFP4)
- [AMD MXFP4 variant](https://huggingface.co/amd/MiniMax-M3-MXFP4)
- [EAGLE3 draft head (MHA)](https://huggingface.co/Inferact/MiniMax-M3-EAGLE3)
- [EAGLE3 draft head (GQA)](https://huggingface.co/Inferact/MiniMax-M3-EAGLE3-GQA)
- [MiniMax](https://www.minimax.io/)
- [MiniMax Agent](https://agent.minimax.io/)
- [MiniMax Platform](https://platform.minimax.io/)
- [Previous release: MiniMax-M2.7](https://huggingface.co/MiniMaxAI/MiniMax-M2.7)