Model aliases
Rapid-MLX ships 175 text aliases plus a separate audio registry (kokoro / whisper / parakeet / vibevoice / voxcpm / chatterbox / dia). An alias is a short, stable name that resolves to a canonical HuggingFace MLX repo and auto-applies the right tool-call parser, reasoning parser, hybrid-cache flag, MoE flag, spec-decode eligibility, and PFlash tier.
vllm_mlx/aliases.json
in the engine repo (audio lives at
vllm_mlx/audio/aliases.json).
The table on this page mirrors what
rapid-mlx models prints.
Naming convention
Every text alias follows the same template:
<family>-<version>-<params>-<modality?>-<technique?>-<quant>
| Segment | Meaning | Examples |
|---|---|---|
| family | Model family | qwen, gemma, llama, mistral, deepseek, phi, hermes |
| version | Major version | 3.5, 3.6, -4, -r1, -v4-flash |
| params | Parameter count (MoE includes active) | 4b, 12b, 27b, 35b-a3b (35B total / 3B active) |
| modality (optional) | Non-text variants | -vl (vision), -coder (code) |
| technique (optional) | Training-time modifier | -qat (QAT), -distill, -thinking, -assistant (MTP assistant drafter) |
| quant (mandatory) | Quantization tier | -4bit, -6bit, -8bit, -mxfp4, -mxfp4-q8, -qat-4bit |
The quant suffix is mandatory on every alias — qwen3.5-4b-4bit,
not qwen3.5-4b. This mirrors the LM Studio
…-MLX-4bit HuggingFace convention. -qat
is a technique suffix, not a quant — it stacks before the
quant, so a QAT-trained Gemma 4 12B at 4-bit is
gemma-4-12b-qat-4bit.
Registry schema
Every text entry in aliases.json is a closed dict with a
fixed key set. Adding an unknown key (e.g. architecture,
family, quantization, or notes) will
fail alias loading — copy the field set from the closest existing
neighbour when adding a new alias.
| Key | Type | Meaning |
|---|---|---|
hf_path | string | HuggingFace repo id in org/name form. The only mandatory field. |
tool_call_parser | string | Which tool-call parser to auto-select at serve time (hermes, qwen3_coder, gemma4, harmony, deepseek, …). |
reasoning_parser | string | Which reasoning parser to auto-select (qwen3, gemma4, deepseek_r1, gpt_oss, harmony, vibethinker, glm4, minimax, ui_tars). |
is_hybrid | bool | Hybrid-attention (Mamba / linear-attention / DiffusionGemma / Granite 4 H) — disables spec-decode / suffix. |
is_hybrid_explicit | bool | Whether the hybrid flag was set intentionally (as opposed to defaulted). |
is_moe | bool | Mixture-of-experts model. |
supports_spec_decode | bool | Whether spec-decode routes are eligible. |
pflash_tier | string | PFlash long-prompt compression tier — verified, unknown, avoid, neutral, n/a. |
What rapid-mlx models prints
The rapid-mlx models table has 7 columns. Column
semantics match the schema fields above:
| Column | Meaning |
|---|---|
| Alias | The short name you pass to serve / chat / pull. |
| Tools | Tool-call parser that will be auto-selected (or —). |
| Reasoning | Reasoning parser that will be auto-selected (or —). |
| Spec-Decode | ✓ when spec-decode is eligible; ✗ hybrid when a hybrid architecture rules it out; ✗ when the alias opts out. |
| Suffix Tier | Suffix-decoding recommendation: verified, neutral, avoid, unknown, n/a. |
| DFlash | DFlash drafter registry status (— when no registered drafter for this alias). |
| DDTree | DDTree runtime status (— when not enabled). |
Note: the individual spec-decode knobs (Spec-Decode / Suffix Tier /
DFlash / DDTree) have since been consolidated under a single
--speculative-config option. The exact column layout of
rapid-mlx models may differ from the description above;
run it locally for the authoritative view.
Run rapid-mlx models
locally for the live view — the browse-friendly UI at
models.rapidmlx.com
renders the same data as a filterable grid.
Text families in 0.12.18
175 text aliases across the following families (count from a byte-exact
read of vllm_mlx/aliases.json):
| Family | # aliases | Notes |
|---|---|---|
| Qwen 3 (3.5 · 3.6 · 3.8 · Coder · Coder-Next 80B · VL · legacy) | 54 | Anchor family — includes MoE 35B-A3B / 122B, the Coder-Next 80B (qwen3-coder-next-80b-4bit / -8bit, HF-pull), hero coder alias, VL variants, plus the 3.8-27B pair (qwen3.8-27b-4bit / -mixed-3.5bpw). |
| Gemma 4 (dense · e2b / e4b · qat · assistant · optiq · DiffusionGemma · EmbeddingGemma) | 31 | Includes the DiffusionGemma and EmbeddingGemma aliases. |
| GPT-OSS (20B · 120B · MXFP4-Q4/Q8 · safeguard) | 10 | Harmony-native tool + reasoning parsers. |
| UI-TARS | 9 | ByteDance vision-grounded UI automation agent. Custom ui_tars tool parser. |
| Tmax (9B / 27B, 4/6/8-bit + bf16) | 7 | Hybrid Gated-DeltaNet agent model (Ai2). First-mover MLX quants. |
| Mistral (24B · Small-4 119B · Devstral) | 6 | Devstral is the code variant; Small-4 119B is the large MoE SKU. |
| DeepSeek (R1-Distill · V4-Flash 2/4/8bit + 0731 MXFP4 · Coder-V2-lite) | 7 | V4-Flash is single-node-large; R1-Distill covers the 32B slot. |
| Gemma 3 (1B–27B · qat) | 6 | Kept for continuity; new work targets Gemma 4. |
| Phi 4 (mini + mini-flash 4bit variants) | 4 | |
| Llama (3.1 · 3.2) | 4 | |
| Qwopus | 3 | Community fork lineage. |
| GLM (4.5-Air · 4.7 · 5.2 REAP) | 3 | GLM-5.2 is a REAP-50 research SKU. |
| Liquid (LFM2 24B-A2B · LFM2.5 8B-A1B / 2.6B / 1.2B) | 4 | LiquidAI on-device family, lfm parser. HF-pull — see the Liquid page. |
| MiniMax (M2.5 / M2.7 MXFP4) | 2 | Uses the minimax parser pair. |
| Granite 4 (H-Micro / Tiny) | 2 | Hybrid architecture; spec-decode disabled. |
| VibeThinker (1.5B / 3B) | 2 | Low-RAM reasoner — 4-bit fits a 4 GB Mac. |
| Holo3 | 2 | Hybrid MoE 35B-A3B; operator-owned deployment target. |
| Hermes 3 · 4 | 2 | |
| Hunyuan 3 (Hy3) | 1 | Tencent 295B MoE preview, Ultra-only. hy_v3 parser; HF-pull — see the Hunyuan page. |
| Bonsai (Ternary 1.7B · 8B · 27B) | 3 | 2-bit ternary Qwen 3.5-class reasoners. Flagship bonsai-27b-2bit fits a 16 GB Mac (7.9 GB) and is R2-mirrored — see the Bonsai section. |
| MiniCPM (MiniCPM5 1B · optiq) | 2 | OpenBMB on-device family; minicpm parser. |
| Muse (Glimmer 30B) | 2 | 4-bit + bf16; custom muse tool + reasoning parser. |
| Ling (3.0 Tiny) | 1 | InclusionAI MoE; R2-mirrored. glm47 tool parser. |
| Others (Kimi K2.6 · Qwen 2.5 · Nemotron 3 / 3.5-Lightning · SmolLM3 · Nanbeige 4 · North-Mini-Code) | 8 | One alias each, except Nemotron (3-Nano + 3.5-Lightning) and North-Mini-Code (4-bit + bf16). |
Audio registry
Audio aliases live in a separate registry — start them the same way:
rapid-mlx serve whisper-large-v3. Registered in 0.12.18:
| Kind | Aliases |
|---|---|
| TTS · kokoro | kokoro, kokoro-82m, kokoro-82m-bf16, kokoro-82m-4bit, kokoro-82m-8bit, kokoro-4bit, kokoro-8bit |
| TTS · vibevoice / voxcpm / chatterbox / dia | vibevoice, vibevoice-realtime, voxcpm, chatterbox, chatterbox-4bit, dia |
| TTS · qwen3-tts | qwen3-tts, qwen3-tts-4bit, qwen3-tts-6bit, qwen3-tts-clone, qwen3-tts-customvoice, qwen3-tts-voicedesign, qwen3-tts-voicedesign-4bit, qwen3-tts-voicedesign-8bit |
| TTS · cloning (indextts / f5) | f5-tts-zh, indextts, indextts-1.5 |
| STT · whisper | whisper, whisper-1, whisper-large-v3, whisper-large-v3-turbo, whisper-medium, whisper-small, whisper-base, whisper-tiny |
| STT · parakeet | parakeet, parakeet-tdt-0.6b, parakeet-tdt-0.6b-v2, parakeet-v3, parakeet-tdt-0.6b-v3 |
| STT · sensevoice | sensevoice, sensevoice-small |
| STT · qwen3-asr | qwen3-asr, qwen3-asr-0.6b, qwen3-asr-1.7b |
| Forced alignment · qwen3-aligner | qwen3-aligner, qwen3-forced-aligner |
Audio requires the [audio] extra —
pip install "rapid-mlx[audio]==0.12.18". See the
extras page
for the full dep list.
Video generation registry
Video aliases live in vllm_mlx/aliases.json alongside the text
aliases, tagged modality: video-gen — which is why the 175 text
count above and the file's raw key count differ. They serve through the
asynchronous /v1/videos job API, not /v1/chat/completions.
Registered in 0.12.18:
| Line | Aliases |
|---|---|
| Wan 2.2 | wan2.2-i2v-a14b-q8, wan2.2-t2v-a14b-bf16, wan2.2-ti2v-5b-bf16, wan2.2-ti2v-5b-q8 |
| CogVideoX-Fun | cogvideox-fun-5b-bf16, cogvideox-fun-5b-q4, cogvideox-fun-5b-q8 |
| LTX-2.3 | ltx-2.3-mlx-q4 |
| LTX-2.5 | ltx-2.5-mlx-q8 |
Video requires the [video] extra plus ffmpeg and Python 3.11+ —
pip install "rapid-mlx[video]==0.12.18". See the
video family page.
The (unmapped) column
rapid-mlx ls (aka models --cached) shows every
HF repo already on disk. Repos that have no matching alias in
aliases.json render as (unmapped) in the
Alias column — you can still serve them by their full
org/name HF path (e.g.
rapid-mlx serve mlx-community/Holo3-35B-A3B-8bit).