sjswerdloff/MiniMax-M3-NVFP4-mlx

MiniMax-M3 — NVFP4 quantization for Apple Silicon

This is an NVFP4-quantized version of MiniMaxAI/MiniMax-M3, prepared for inference with mlxcel on Apple Silicon. The quantization is mode="nvfp4", group_size=16, bits=4, applied to the routed-expert weights via mlxcel's gather_qmm path.

Important caveats

• mlxcel-targeted. This repository will not load with transformers out of the box. The base model relies on custom Python modules (configuration_minimax_m3_vl.py, image_processor.py, video_processor.py, processing_minimax.py) which are not mirrored here. For HF/Transformers use, work from the upstream MiniMaxAI/MiniMax-M3 BF16 repo instead.
• Language-model inference only — VL is deferred. The upstream MiniMax-M3 is a vision-language model (image-text-to-text) and the vision-tower weights are present in this artifact's safetensors shards. However, mlxcel's current MiniMax-M3 wiring covers only the language model: the vision tower and its projector are not yet reachable from inference. This is why the pipeline_tag here is text-generation rather than upstream's image-text-to-text. VL support in mlxcel is on the roadmap; the weights in this repo are intended to be re-usable once that lands, so this should not require a re-quantization.
• Hardware requirements. Total weight size is ~238 GB. You will need enough unified memory on an Apple Silicon machine to hold both the weights and a working set for inference. A Mac Studio M3 Ultra with 512 GB unified memory is the current reference platform; smaller machines are unlikely to be able to load this model.

Architecture

MiniMax-M3 (see upstream for full specs):

• 60 layers — 3 dense + 57 MoE
• 128 routed experts per MoE layer, top-4 routing, 1 shared expert
• 64 attention heads, 4 KV heads, head_dim=128
• Partial RoPE on the first 64 of 128 head dims (rope_theta=5000000)
• Per-head Q/K RMSNorm (head_dim slice, not full projection)
• Gemma-style RMSNorm convention (scale = 1 + weight)
• SwiGLU with α=1.702, limit=7.0 (GPT-OSS variant), clamped (up+1)
• Mixture-of-Softmax-Attention (MSA) with sparse-block indexing for long context
• Vocabulary 200 064; supports up to 1 048 576 (1 M) context tokens

Usage with mlxcel

MiniMax-M3 support is being upstreamed in clement/add-minimax-m3-nvfp4 (against lablup/mlxcel). Until the PR is merged, build mlxcel from that branch.

# Build mlxcel from the M3 branch
git clone https://github.com/sjswerdloff/mlxcel.git
cd mlxcel
git checkout clement/add-minimax-m3-nvfp4
make release    # or: cargo build --release

# Run inference
./target/release/mlxcel \
    --model-path /path/to/MiniMax-M3-NVFP4-mlx \
    --prompt "The capital of France is"

What's in this repo

• 16 safetensors shards (model-{00001..00016}-of-00016.safetensors)
• model.safetensors.index.json — weight map
• config.json, generation_config.json
• chat_template.jinja — supports MiniMax-M3's <mm:think> reasoning blocks, tool-calling, system/developer role split
• Tokenizer: tokenizer.json, tokenizer_config.json, vocab.json, merges.txt, added_tokens.json, special_tokens_map.json
• preprocessor_config.json (vestigial — vision path not wired in mlxcel)

License

This repository inherits the MiniMax Community License from the base model (see LICENSE). Key points:

• Free for non-commercial use, including modification and redistribution
• Commercial use requires prominent "Built with MiniMax M3" attribution
• Commercial use generating > USD 20 M/year requires prior written authorization from MiniMax (api@minimax.io)
• See LICENSE for the full text and prohibited-use appendix

Credits

• Base model: MiniMaxAI/MiniMax-M3
• Quantization, conversion, and mlxcel MiniMax-M3 support: Stuart Swerdloff, using mlxcel