Model aliases
Rapid-MLX ships 158 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 in 0.10.3.
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). |
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.10.3
158 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 · Coder · VL · legacy) | 50 | Anchor family — includes MoE 35B-A3B / 122B, hero coder alias, VL variants. |
| Gemma 4 (dense · e2b / e4b · qat · assistant · optiq · DiffusionGemma) | 27 | Includes 3 DiffusionGemma / 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. |
| DeepSeek (R1-Distill · V4-Flash 2/4/8bit · Coder-V2-lite) | 6 | 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 | |
| Mistral (7B / 24B · Devstral · Ministral) | 4 + 2 + 1 | Devstral is the code variant; Ministral is the small chat SKU. |
| Qwopus | 3 | Community fork lineage. |
| Bonsai | 3 | Small hybrid-attention reasoners. |
| GLM 4 (Air · 4.7) | 2 + 1 | Plus one GLM-5.2 REAP-50 entry (research SKU). |
| Llama (3.1 · 3.2) | 2 + 2 | |
| 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 | 1 + 1 | |
| Others (Kimi K2.6 · Qwen 2 · Nemotron 3 · SmolLM3 · Nanbeige 4) | 5 | One alias each. |
Audio registry
Audio aliases live in a separate registry — start them the same way:
rapid-mlx serve whisper-large-v3. Registered in 0.10.3:
| 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 |
| 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 |
Audio requires the [audio] extra —
pip install "rapid-mlx[audio]==0.10.3". See the
extras page
for the full dep list.
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).