| name | vmlx |
| description | Moteur d'inférence MLX local sur Apple Silicon (vMLX, Jinho Jang) — LLM/vision/image-gen/audio/multimodal Nemotron-Omni, 5-layer KV caching, JANG quantization, inférence distribuée multi-Mac, API Anthropic+OpenAI+Ollama native. Charge on-demand quand on travaille dans la stack ai-servers ou sur des fichiers vmlx. |
| paths | ["~/ai-servers/**","**/servers.yaml","**/*vmlx*"] |
vMLX — Moteur d'inférence MLX local (rule on-demand)
Provenance : transféré du skill intellisoins-mlx:vmlx (SKILL.md) le 2026-05-24, pour sortir le contenu de l'always-loaded des 6 projets qui activent intellisoins-mlx (ai-servers, master-IA, openclaw, Finances_Assurances, postgresml-build, organisateur-complet). Détail caching / JANG / API → sous-rules ~/.claude/rules/vmlx/.
Membre de la stack locale — voir aussi ~/.claude/rules/local-ai-stack.md.
Free, open-source MLX inference engine for Apple Silicon by Jinho Jang — vmlx.net.
Uniquely combines text, vision, image generation, audio, 5-layer KV caching, and agentic tools with native Anthropic + OpenAI + Ollama API compatibility.
Architecture du projet (mai 2026) :
- Engine Python + panel Electron legacy : repo principal jjang-ai/vmlx (Apache-2.0). Tags
v1.x.x. PyPI vmlx distribue cette ligne. Version actuelle : v1.5.49 (2026-05-24).
- vMLX v2 desktop app (Swift native, recommandé pour interaction) : même repo jjang-ai/vmlx, tags
v2.0.0-rc.x (rc) puis v2.0.0-beta.x (legacy). Pure SwiftUI, zero PyTorch hot-path, 50–95 t/s sur M-series (vs 11–60 t/s Python). Latest : v2.0.0-rc.1 (2026-05-04, Developer-ID notarized + stapled, hardened runtime, Apple Team ID 55KGF2S5AY, 24.3 MB DMG).
jjang-ai/mlxstudio : repo release-only (Electron installer distribution), en voie d'obsolescence depuis v1.4.0 qui annonce officiellement la migration Swift. À ne plus pointer pour les nouveaux usages.
Distinct from: vllm-mlx (waybarrios) — different project, different codebase.
Why use vMLX over alternatives
The performance advantage comes from context reuse: agent workflows repeat similar prompts (system prompts, tool schemas, codebase context), so vMLX's prefix cache turns 8K-token prefills from ~49s into 1-2s. Ollama and LM Studio recompute every prefill from scratch. That difference compounds over hundreds of agent turns.
Installation
pip install vmlx
pip install "vmlx[image]"
pip install "vmlx[jang]"
pip install "vmlx[audio]"
pip install "vmlx[image,jang,audio]"
uv tool install vmlx
pipx install vmlx
Or download MLX Studio native macOS app at vmlx.net/download (auto-installs engine via uv, no terminal needed).
Requirements: Python 3.10+, macOS 14+ (macOS 26 Tahoe for latest local inference), Apple Silicon M1+.
Note: sur macOS 14+, pip install vmlx direct échoue (externally-managed-environment). Utiliser uv tool install vmlx, pipx install vmlx, ou un venv.
Quick Start
vmlx serve mlx-community/Qwen3-8B-4bit
vmlx serve mlx-community/Llama-3.2-3B-Instruct-4bit --kv-quant q8
vmlx serve mlx-community/Qwen3-8B-4bit --speculative mlx-community/Qwen3-0.6B-4bit
vmlx serve JANGQ-AI/Nemotron-3-Nano-Omni-30B-A3B-JANGTQ4 --omni-backend stage2
Server binds http://0.0.0.0:8000 by default.
CLI Commands
vmlx serve <model>
vmlx convert <model> --bits 4
vmlx convert <model> -j JANG_3M
vmlx info <model>
vmlx doctor <model>
vmlx bench <model>
vmlx-worker --secret <secret>
API Compatibility
Three wire formats on a single port:
| Endpoint | Protocol |
|---|
/v1/chat/completions | OpenAI Chat |
/v1/messages | Anthropic Messages API |
/api/chat, /api/generate | Ollama |
/v1/responses | OpenAI Responses API |
/v1/completions | Text generation |
/v1/embeddings | Vector embeddings |
/v1/rerank | Document reranking (cross-encoder) |
/v1/images/generations | Flux Schnell/Dev, Z-Image Turbo |
/v1/images/edits | Qwen Image Edit (instruction-based, ~54 GB) |
/v1/audio/speech | Kokoro TTS |
/v1/audio/transcriptions | Whisper STT |
/v1/cluster/status|nodes|scan | Multi-Mac cluster management |
/v1/cache/stats | Cache statistics |
/health | Server health check |
Connect via OpenAI or Anthropic SDK
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="local")
import anthropic
client = anthropic.Anthropic(base_url="http://localhost:8000", api_key="local")
Works natively with Cursor, Continue, Aider, and Claude Code.
For full endpoint reference including image generation, audio, and Ollama format, see ~/.claude/rules/vmlx/api-reference.md.
Supported Architectures
53+ text architectures auto-detected: Llama 3/3.1/3.2/3.3/4, Qwen 2/2.5/3/3.5, Mistral/Mixtral, Gemma 3/4, Phi-4, DeepSeek V2/V3/V4/R1, GLM-4, MiniMax M2.5, Nemotron/Nemotron-H, StepFun, Jamba, GatedDeltaNet, Laguna 33B/3B, Mistral-Medium-3.5-128B. (DeepSeek V4 ajouté v1.3.96/97 — auto-route + force-thinking + default-system-prompt injection.)
- Nemotron-3-Nano-Omni (v1.4.0+) — multimodal text+image+audio+video, bundles MXFP4/JANGTQ4/JANGTQ2 (voir section dédiée plus bas)
- Laguna 33B/3B (v1.4.2+) — poolside agentic-coding MoE, hybrid SWA+full attention, 256 routed experts top-8 + 1 shared, dual-RoPE
- Mistral-Medium-3.5-128B (v1.4.2+) — dense GQA 96/8, 256K YaRN context, PIXTRAL vision tower
- 13 tool call parsers (auto-configured):
qwen, llama, mistral, hermes, deepseek, glm47, minimax, nemotron, granite, functionary, xlam, kimi, step3p5
- 3 reasoning parsers (extrait les
<think> blocks): qwen3 (Qwen3, QwQ, MiniMax, StepFun), deepseek_r1 (DeepSeek R1, Gemma 3, GLM, Phi-4), openai_gptoss (GLM Flash, GPT-OSS)
- Hybrid SSM/Mamba via BatchMambaCache (Nemotron-H, Jamba, GatedDeltaNet)
- Vision: Qwen-VL, Qwen3.5-VL, Pixtral, InternVL, LLaVA, Gemma 3n, Mistral-Medium-3.5 (PIXTRAL)
- Image gen: Flux Schnell/Dev, Z-Image Turbo (via mflux)
- Image edit: Qwen Image Edit (instruction-based, ~54 GB) —
vmlx serve qwen-image-edit
- Audio: Kokoro TTS, Whisper STT (via mlx-audio)
- Embeddings + reranking (cross-encoders)
Nemotron-3-Nano-Omni Multimodal (v1.4.0+)
Chat avec images + audio + video sur les bundles JANGQ-AI/Nemotron-3-Nano-Omni-30B-A3B-{MXFP4,JANGTQ4,JANGTQ2} via les 4 wire formats standard :
/v1/chat/completions (OpenAI)/v1/messages (Anthropic)/api/chat (Ollama)/v1/responses (OpenAI Responses, content types canoniques input_image / input_audio / input_video auto-normalisés vers chat-completions envelopes en v1.4.2+)
Two encoder backends
| Backend | Activation | Caractéristiques |
|---|
| Stage-1 PyTorch+MPS (default) | rien à faire | Bit-exact reference, plus lent — conserver pour validation |
| Stage-2 native MLX | VMLX_OMNI_BACKEND=stage2 env var ou --omni-backend stage2 flag CLI (v1.4.7+) | ~17× faster RADIO + ~15× faster Parakeet |
Note : Stage-2 a des "documented quality gaps still under upstream validation" — Stage-1 reste la référence bit-exact pour les usages où la fidélité prime.
Quick test
vmlx serve JANGQ-AI/Nemotron-3-Nano-Omni-30B-A3B-JANGTQ4 --omni-backend stage2
Modalités via content blocks (/v1/chat/completions)
client.chat.completions.create(
model="default",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image and what does the audio say?"},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}},
{"type": "input_audio", "input_audio": {"data": "<base64>", "format": "wav"}},
{"type": "video_url", "video_url": {"url": "file:///chemin/clip.mp4"}}
]
}]
)
Voir ~/.claude/rules/vmlx/api-reference.md pour le format complet (incl. Responses API canonique).
5-Layer KV Caching
The key advantage over Ollama and LM Studio for agent workloads:
| Layer | What it does |
|---|
| Prefix caching (L1) | Memory-aware cache qui réutilise les KV states d'anciens prompts — biggest win for agents |
| Paged multi-context | 256 concurrent sequences avec dedup content-addressable |
| KV quantization | q4 (~4× memory savings) ou q8 (~2×); précision totale pendant la génération |
| Continuous batching | 256 inference sequences simultanément |
| Persistent disk cache (L2) | États KV persistent sur SSD — survive aux restart serveur |
| Block disk cache | Variante L2 per-block appariée au paged KV cache |
Vision-language models work with the full 5-layer stack (unique to vMLX).
For detailed caching configuration, see ~/.claude/rules/vmlx/caching.md.
JANG Adaptive Mixed-Precision Quantization
JANG assigne des bit widths variables par layer selon la sensibilité — préserve les layers critiques (attention) à haute précision, compresse agressivement les tolérants (MLP). Amélioration dramatique vs MLX 4-bit uniforme sur gros modèles MoE.
Benchmark vedette — MiniMax M2.5 (200 questions MMLU):
| Quantization | MMLU | Size |
|---|
| JANG_2L (2-bit) | 74% | 89 GB |
| MLX 4-bit | 26.5% | 120 GB |
| MLX 3-bit | 24.5% | 93 GB |
| MLX 2-bit | 25% | 68 GB |
5 profiles disponibles: JANG_2M (~2.5 bits), JANG_2L (~2.7 bits qualité 2-bit), JANG_3M (~3.2 bits, recommandé), JANG_4M (~4.2 bits), JANG_6M (~6.2 bits, near-lossless).
Install with pip install "vmlx[jang]". Format originates from the companion project jjang-ai/jangq (GGUF-like for MLX). Modèles pré-quantifiés: JANGQ-AI on HuggingFace.
For JANG profile selection, model conversion, and tradeoffs, see ~/.claude/rules/vmlx/jang.md.
Distributed Inference (Multi-Mac)
Pipeline parallelism across multiple Macs pour les modèles qui ne rentrent pas sur une seule machine. Utile pour Qwen3-72B, Llama-3.3-70B, ou Qwen3.5-Coder-Rerank-397B-A27B sur plusieurs M3 Ultra.
pip install vmlx
vmlx-worker --secret mysecret
vmlx serve JANGQ-AI/Qwen3.5-Coder-Rerank-397B-A27B-JANG_2L \
--distributed --cluster-secret mysecret
Features clés:
- Pipeline parallelism: split des layers entre nodes, hidden state (~8KB/step) circule séquentiellement
- Auto-discovery: Bonjour mDNS, UDP broadcast, HTTP probes, Tailscale, cached peers, IP manuel
- Capability-scored election: le Mac le plus puissant devient coordinator automatiquement
- Any network works: Thunderbolt 5 (120 Gbps), 10GbE, 1GbE, WiFi, Tailscale — PP n'est pas bandwidth-bound
- Cluster API: endpoints REST
/v1/cluster/status, /v1/cluster/nodes, /v1/cluster/scan
- JANG support: chaque worker load sa layer range depuis JANG safetensors (mmap)
Why this matters: unified memory plafonne à 512 GB sur M3 Ultra; distributed inference étend le plafond sans tomber en disk swap.
API Gateway (MLX Studio desktop)
L'app desktop MLX Studio expose un API Gateway sur un port unique (défaut 8080) qui route les requêtes vers tous les modèles chargés par leur nom. Permet de faire tourner plusieurs modèles simultanément et les accéder via une seule URL.
curl http://localhost:8080/v1/chat/completions \
-d '{"model": "Qwen3.5-122B", "messages": [{"role": "user", "content": "Hi"}]}'
OLLAMA_HOST=http://localhost:8080 ollama run Qwen3.5-122B
Le gateway supporte les wire formats OpenAI, Anthropic, et Ollama.
Smelt Mode (Partial MoE Loading)
Charge seulement un sous-ensemble d'experts MoE en RAM ; le backbone reste résident, le routing est biaisé vers les experts chargés. Permet de faire tourner des MoE qui ne rentreraient pas autrement.
vmlx serve ./MyMoE-JANG_4M --smelt --smelt-experts 50
vmlx serve ./MyMoE-JANG_4M --smelt --smelt-experts 25
Benchmark Nemotron-Cascade-2-30B-A3B-JANG_4M (M3 Ultra 128 GB, 23 layers MoE × 128 experts) :
--smelt-experts | RAM active | Decode tok/s | RAM saving |
|---|
| off (baseline) | 17 408 MB | 89.9 | — |
50 | 9 529 MB | 66.5 | −45 % |
25 | 5 590 MB | * | −68 % |
* Réponses trop courtes pour mesure fiable à 25 %. Output cohérent dans les trois cas (pas de dégradation qualité).
Contraintes critiques :
- MoE seulement (pas de modèles denses) et format JANG seulement (pas MLX uniforme)
- Mutuellement exclusif avec VLM : vMLX auto-disable
--is-mllm avec warning. La vision tower n'est pas câblée au partial-expert loader → image input produirait des logits garbage. Pour VLM : utiliser un text-only ou désactiver smelt.
- Inspiration : Anemll flash-moe (streaming experts SSD via
pread()) ; vMLX prend une voie différente (Python/MLX, JANG, sous-ensemble fixe au démarrage).
Speculative + Prompt Lookup Decoding
Two acceleration modes (can combine with caching):
- Speculative decoding: small draft model generates tokens, main model validates in batch. Pair
Qwen3-8B with Qwen3-0.6B draft. Flag --speculative-model <model>. Typical gain 1.5–2×.
- Prompt Lookup Decoding (PLD): trouve les n-grams répétés dans le prompt comme candidats de spéculation. Pas de draft model requis. Flag
--enable-pld. Gain 20–90% sur code editing, JSON, schemas où l'output cite l'input.
Performance (M3 Ultra, 256 GB, Llama 3.2 3B 4-bit)
| Scenario | vMLX | LM Studio |
|---|
| 100K tokens cold TTFT | 0.65s | 131.06s |
| 100K tokens throughput | 154,121 tok/s | 686 tok/s |
| 2.5K tokens cached TTFT | 0.05s | N/A |
| Cache speedup at 2.5K | 9.7× | N/A |
Practical impact for agents: prefill 8K context drops from ~49s → 1–2s with warm cache.
Throughput defaults (v1.3.99+, inchangés en v1.5.49) — Macs 64 GB+
Defaults pour nouvelles sessions, optimisés pour saturer le pipeline prefill+decode :
| Setting | Avant | v1.3.99 |
|---|
| Prefill Batch Size | 512 | 1024 |
| Prefill Step Size | 1024 | 2048 |
| Completion Batch Size | 512 | 1024 |
| Cache Memory % | 10 (panel) / 30 (auto) | 20 |
| Max Cache Blocks | 500 | 1000 |
| Continuous Batching | ON | ON |
| Enable Prefix Cache | ON | ON |
| Use Paged KV Cache | ON | ON |
| Block Disk Cache (L2) | ON | ON |
Sessions existantes non affectées — appliquer via "Reset all parameters to defaults" en Server Settings. Macs <64 GB tombent dans LOW_MEM_CONFIG (8 / 32 / 15%).
Built-in Agentic Tools (20+)
vMLX ships 20+ tools callable by the model without external MCP setup:
- File I/O (read, write, list)
- Shell execution
- Git operations
- Web search
- Clipboard
The point is zero configuration for basic agent workflows — skip MCP entirely for local tools.
Hardware Guide
| RAM | Recommended models |
|---|
| 8 GB | Qwen3-0.6B, Llama-3.2-1B (4-bit) |
| 16 GB | Qwen3-4B, Llama-3.2-3B (4-bit/8-bit) |
| 32–64 GB | Qwen3-8B, DeepSeek-R1-8B, Nemotron-30B, Qwen3.5-MoE (Smelt) |
| 128 GB+ | Qwen3.5-35B-A3B, Qwen3-72B, Llama-3.3-70B, JANG_2L profiles |
| Multi-Mac | 70B+ dense via distributed inference |
vs Other MLX Inference Options
| Feature | vMLX | vllm-mlx (waybarrios) | Ollama 0.19 MLX | mlx-lm direct |
|---|
| Architectures | 53+ | 30+ | 4 (MLX runner) | 50+ |
| Prefix cache | ✅ 5-layer | ✅ paged | ❌ | ❌ |
| Anthropic API | ✅ native | ❌ | ❌ | ❌ |
| Ollama API | ✅ | ❌ | ✅ native | ❌ |
| Speculative + lookup | ✅ both | ❌ | ❌ | ❌ |
| JANG quantization | ✅ | ❌ | ❌ | ❌ |
| Mamba/SSM | ✅ | ❌ | ❌ | ✅ |
| Image generation | ✅ Flux/Z-Image | ❌ | ❌ | ❌ |
| Image editing | ✅ Qwen Image Edit | ❌ | ❌ | ❌ |
| Audio (TTS/STT) | ✅ Kokoro/Whisper | ❌ | ❌ | ❌ |
| Distributed | ✅ | ❌ | ❌ | ❌ |
| Built-in tools | ✅ 20+ | ❌ | ❌ | ❌ |
| VLM + full cache | ✅ | ✅ | ❌ | ❌ |
| Peak throughput | ~230 tok/s | 400–525 tok/s | 134 tok/s (int4) | ~106 tok/s |
| Ease of use | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ |
What's New v1.5.49 (2026-05-24)
- DSV4 Flash — cache prefix composite natif : chemin de cache prefix composite (SWA + CSA/HCA) activé par défaut, avec block indexing 256-token pour l'indexation des blocs KV.
- Routing VL natif-MTP Qwen3.6 : aligné dans l'engine registry ; parity local-path pour DSV4 / Qwen / Hy3 / Nemotron (chargement depuis chemin local cohérent entre familles).
- Séparation stricte des tokens : Max Output / Context / Thinking désormais séparés strictement sur UI / CLI / Anthropic / Ollama / Responses (plus de budget partagé ambigu).
https://api.github.com/repos/jjang-ai/vmlx/releases — consulté 2026-05-29, release 2026-05-24
Rollup v1.4.x
- Nemotron-Omni multimodal across all 4 API surfaces (v1.4.2) —
/v1/chat/completions, /v1/messages, /api/chat, /v1/responses
--omni-backend first-class CLI flag (v1.4.7) — équivalent runtime de VMLX_OMNI_BACKEND=stage2- Loaders Laguna 33B/3B + Mistral-Medium-3.5-128B (v1.4.2) —
loaders/load_laguna.py (MoE 256 routed top-8 + 1 shared, dual-RoPE, hybrid SWA+full attention) et loaders/load_mistral3.py (dense GQA 96/8 + 256K YaRN + PIXTRAL)
- SSM companion RAM leak guard (v1.4.5)
- Laguna + Mistral3 JANGTQ guard (v1.4.6)
- Hard deps ajoutées :
jang-tools (v1.4.3), torch (v1.4.4 — encoder Nemotron-Omni Stage-1), soundfile (v1.4.8/v1.4.9 — audio Stage-2)
- Swift v2 migration banner dans le panel Electron (annonce officielle de la migration vers v2.0.0-rc.1 Swift native, notarized stapled)
MLX Studio Desktop App (Electron, legacy)
Note : vMLX v2 (Swift native, recommandé) est dans le repo jjang-ai/vmlx tag v2.0.0-rc.x (release candidate) — précédé des v2.0.0-beta.x. L'app Electron ci-dessous est la voie legacy, en voie d'obsolescence depuis la bannière v1.4.0 "vMLX is moving to Swift".
App native macOS Electron : jjang-ai/vmlx releases v1.x.x (panel Electron + engine Python ensemble) ou télécharger l'installeur Electron via vmlx.net/download. Cinq modes:
| Mode | Description |
|---|
| Chat | Conversation, historique, thinking mode, tool calling, agentic coding |
| Server | Gérer les sessions de modèles (start, stop, configure, monitor) |
| Image | Génération et édition avec Flux, Kontext, Qwen, Fill models |
| Tools | Converter modèles, GGUF→MLX, inspector, diagnostics |
| API | Référence endpoints live avec code snippets copiables |
Menu bar affiche tous les modèles running, usage GPU memory, contrôles rapides. Auto-install du moteur vMLX via uv au premier lancement.
Pour Swift v2 desktop app (recommandé) : gh release download --repo jjang-ai/vmlx --pattern '*.dmg' v2.0.0-rc.1 ou voir releases v2 tag.
Sous-rules (détail on-demand)
| Sous-rule | Contenu | Paths trigger |
|---|
~/.claude/rules/vmlx/api-reference.md | Endpoints complets, options CLI serve/convert, VLM, agentic tools, intégration OpenClaw, troubleshooting | **/*vmlx*client*, **/*vmlx*api*, **/*vmlx*server*, **/openclaw.json, ~/.openclaw/** |
~/.claude/rules/vmlx/caching.md | 5 couches KV détaillées, configs par profil (agent/RAG/chat), métriques | **/*vmlx*cache*, **/*kv*cache*, **/*prefix*cache* |
~/.claude/rules/vmlx/jang.md | Quantization JANG : profils, conversion, tradeoffs, interaction Smelt/caching | **/*jangq*, **/*JANG_*, **/*.jangq |
