Model aliases

An alias is a short, stable model name — qwen3.5-4b-4bit — that resolves to a Hugging Face MLX repo and applies that model's tool-call parser, reasoning parser and performance defaults. Rapid-MLX ships 197 text aliases plus image, video, embedding and audio registries. Find one and serve it:

$ rapid-mlx models --search qwen         # filter the catalog
$ rapid-mlx recipe                       # the two picks for this Mac
$ rapid-mlx info qwen3.5-9b-4bit         # what an alias turns on
$ rapid-mlx serve qwen3.5-9b-4bit

Not in the catalog? Serve the Hugging Face org/name directly (Bring your own model), or give it your own short name with rapid-mlx alias set <name> <org/name> (alias list / alias remove manage them).

Naming convention

Text aliases follow one template:

<family>-<version>-<params>-<modality?>-<technique?>-<quant>

Most aliases end in their quant — qwen3.5-4b-4bit — so the precision is visible in the name. A few short names (qwen3.6-35b, gpt-oss-20b, qwen3-0.6b, tmax-9b) point at the standard build of that model; rapid-mlx info shows which repo each resolves to. -qat is a technique, not a quant — it stacks before the quant, as in gemma-4-12b-qat-4bit.

Registry schema

Each entry in aliases.json is either a bare repo id or an object with a closed set of keys: an unknown key fails alias loading, so copy the field set from the closest existing alias when adding one. The keys most entries use:

The full key list — DFlash / DDTree drafters, suffix tier, vision memory floor, chat-template id and more — is the _ALLOWED_PROFILE_KEYS set in rapid_mlx/model_aliases.py.

What rapid-mlx models prints

The main table lists text and embedding aliases; image, video and audio models follow in their own tables. --modality picks one table, --search filters by name, --json gives stable machine-readable output, and --cached (or rapid-mlx ls) shows only what is downloaded.

The model picker shows the same catalog with a RAM filter.

Text families

197 text aliases across these families (image, video, audio and embedding aliases are counted in their own registries):

Audio registry

Audio aliases live in a separate registry — start them the same way: rapid-mlx serve whisper-large-v3. The 44 audio aliases:

Audio requires the [audio] extra — pip install "rapid-mlx[audio]==0.15.7". See the extras page for the full dep list.

Video generation registry

Video aliases live in rapid_mlx/aliases.json with modality: video-gen and serve through the asynchronous /v1/videos job API, not /v1/chat/completions. The 10 video aliases:

Video requires the [video] extra plus ffmpeg and Python 3.11+ — pip install "rapid-mlx[video]==0.15.7". See the video family page.

Image generation registry

Image aliases (modality: image-gen) serve through /v1/images/generations (and /v1/images/edits where the model edits). They need the [image] extra and Python 3.11+ — pip install "rapid-mlx[image]==0.15.7".

Embedding aliases

Embedding aliases attach to a chat server with --embedding-model and answer on /v1/embeddings. embeddinggemma-2-4bit and embeddinggemma-2-bf16 (EmbeddingGemma 2, text and code) need the [vision] runtime — start there for a new index; see the EmbeddingGemma 2 page. The older embeddinggemma-300m-6bit and embeddinggemma-300m-8bit need the [embeddings] extra.

The (unmapped) column

rapid-mlx ls (or models --cached) shows every Hugging Face repo already on disk. A repo with no matching alias shows as (unmapped) in the Alias column — serve it by its full org/name (e.g. rapid-mlx serve mlx-community/Holo3-35B-A3B-8bit), or name it with rapid-mlx alias set.

Next steps