wehub/jundot--omlx

Fork 0

Files

T

wehub-resource-sync e9a2f726c9

CI / test (3.13) (push) Waiting to run

Details

CI / test (3.12) (push) Waiting to run

Details

CI / test (3.11) (push) Waiting to run

Details

chore: import upstream snapshot with attribution

2026-07-13 13:29:51 +08:00

19 KiB

Raw Permalink Blame History

oMLX

Inférence LLM, optimisée pour votre Mac
Batching continu et cache KV à plusieurs niveaux, géré directement depuis votre barre de menus.

junkim.dot@gmail.com · https://omlx.ai/me

Installation · Démarrage rapide · Fonctionnalités · Modèles · Configuration CLI · Benchmarks · oMLX.ai

English · 中文 · 한국어 · 日本語 · Français

Chaque serveur LLM que j'ai essayé m'obligeait à choisir entre commodité et contrôle. Je voulais garder des modèles du quotidien en mémoire, permuter automatiquement les plus lourds à la demande, définir des limites de contexte — et tout gérer depuis la barre de menus.

oMLX persiste le cache KV sur un niveau chaud en RAM et un niveau froid sur SSD — même quand le contexte change en cours de conversation, tout le contexte passé reste en cache et réutilisable entre les requêtes, rendant les LLM locaux vraiment pratiques pour du vrai travail de code avec des outils comme Claude Code. C'est pour ça que je l'ai construit.

Installation

Application macOS

Téléchargez le .dmg depuis les Releases, glissez-le dans Applications, c'est tout. L'application inclut une mise à jour automatique intégrée, les futures mises à jour se font en un clic. L'application macOS installe aussi un shim CLI léger dans ~/.omlx/bin/omlx, ce qui permet de contrôler le serveur géré par l'app depuis le terminal ou Apple Shortcuts.

Homebrew

brew tap jundot/omlx https://github.com/jundot/omlx
brew install omlx

# Mettre à jour vers la dernière version
brew update && brew upgrade omlx

# Lancer en service en arrière-plan (redémarre automatiquement en cas de crash)
brew services start omlx

# Optionnel : support MCP (Model Context Protocol)
/opt/homebrew/opt/omlx/libexec/bin/pip install mcp

Les kernels natifs personnalisés optionnels pour GLM-5.2 / MiniMax M3 nécessitent actuellement un build HEAD :

brew install omlx --HEAD --with-custom-kernel

Depuis les sources

git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e .          # Core uniquement
pip install -e ".[mcp]"   # Avec support MCP (Model Context Protocol)

# Optionnel : kernels natifs personnalisés GLM-5.2 / MiniMax M3
OMLX_WITH_CUSTOM_KERNEL=1 pip install -e .

Nécessite macOS 15.0+ (Sequoia), Python 3.10+, et Apple Silicon (M1/M2/M3/M4).

Démarrage rapide

Application macOS

Lancez oMLX depuis votre dossier Applications. L'écran de bienvenue vous guide en trois étapes — répertoire des modèles, démarrage du serveur, et premier téléchargement de modèle. C'est tout. Pour connecter OpenClaw, OpenCode, Codex ou Hermes Agent, voir Intégrations.

CLI

omlx serve --model-dir ~/models

Le serveur détecte automatiquement les LLM, VLM, modèles d'embedding et rerankers depuis les sous-répertoires. N'importe quel client compatible OpenAI peut se connecter à http://localhost:8000/v1. Une interface de chat intégrée est aussi disponible à http://localhost:8000/admin/chat.

Service Homebrew

Si vous avez installé via Homebrew, vous pouvez lancer oMLX en service géré en arrière-plan :

brew services start omlx    # Démarrer (redémarre automatiquement en cas de crash)
brew services stop omlx     # Arrêter
brew services restart omlx  # Redémarrer
brew services info omlx     # Vérifier le statut

Le service lance omlx serve avec les paramètres par défaut (~/.omlx/models, port 8000). Pour personnaliser, définissez des variables d'environnement (OMLX_MODEL_DIR, OMLX_PORT, etc.) ou lancez omlx serve --model-dir /votre/chemin une fois pour sauvegarder les paramètres dans ~/.omlx/settings.json.

Les logs sont écrits à deux endroits :

Log du service : $(brew --prefix)/var/log/omlx.log (stdout/stderr)
Log du serveur : ~/.omlx/logs/server.log (log applicatif structuré)

Fonctionnalités

Prend en charge les LLM texte, les modèles vision-langage (VLM), les modèles OCR, les embeddings et les rerankers sur Apple Silicon.

Tableau de bord Admin

Interface web sur /admin pour le monitoring en temps réel, la gestion des modèles, le chat, les benchmarks et les réglages par modèle. Disponible en anglais, coréen, japonais, chinois, français et russe. Toutes les dépendances CDN sont incluses pour un fonctionnement entièrement hors-ligne.

Modèles vision-langage (VLM)

Exécutez des VLM avec le même stack de batching continu et cache KV à plusieurs niveaux que les LLM texte. Supporte le chat multi-images, les entrées images en base64/URL/fichier, et l'appel d'outils avec contexte visuel. Les modèles OCR (DeepSeek-OCR, DOTS-OCR, GLM-OCR) sont auto-détectés avec des prompts optimisés.

Cache KV à deux niveaux (Chaud + Froid)

Gestion de cache KV par blocs inspirée de vLLM, avec partage de préfixe et Copy-on-Write. Le cache opère sur deux niveaux :

Niveau chaud (RAM) : Les blocs fréquemment accédés restent en mémoire pour un accès rapide.
Niveau froid (SSD) : Quand le cache chaud se remplit, les blocs sont déversés sur SSD au format safetensors. À la prochaine requête avec un préfixe correspondant, ils sont restaurés depuis le disque plutôt que recalculés — même après un redémarrage du serveur.

Batching continu

Gère les requêtes concurrentes via le BatchGenerator de mlx-lm. Le nombre maximum de requêtes simultanées est configurable via CLI ou le panneau d'administration.

Optimisation Claude Code

Support du context scaling pour faire tourner des modèles avec un contexte réduit avec Claude Code. Ajuste les compteurs de tokens reportés pour que l'auto-compactage se déclenche au bon moment, et un keep-alive SSE évite les timeouts de lecture pendant les longs prefills.

Service multi-modèles

Chargez des LLM, VLM, modèles d'embedding et rerankers sur le même serveur. Les modèles sont gérés via une combinaison de contrôles automatiques et manuels :

Éviction LRU : Les modèles les moins récemment utilisés sont évincés automatiquement quand la mémoire est faible.
Chargement/déchargement manuel : Les badges de statut interactifs dans le panneau d'admin permettent de charger ou décharger des modèles à la demande.
Épinglage de modèles : Épinglez les modèles fréquemment utilisés pour les garder toujours chargés.
TTL par modèle : Définissez un délai d'inactivité par modèle pour le décharger automatiquement après une période sans activité.
Contrôle mémoire processus : La limite mémoire totale (par défaut : RAM système - 8 Go) évite les OOM système.

Paramètres par modèle

Configurez les paramètres d'échantillonnage, les kwargs du template de chat, le TTL, l'alias du modèle, le type de modèle, et plus encore — directement depuis le panneau d'admin. Les modifications s'appliquent immédiatement sans redémarrage du serveur.

Alias de modèle : définissez un nom personnalisé visible par l'API. /v1/models retourne l'alias, et les requêtes acceptent l'alias comme le nom du répertoire.
Type de modèle : forcez manuellement un modèle en LLM ou VLM indépendamment de l'auto-détection.
Profils : enregistrez des ensembles nommés de paramètres par modèle et basculez entre eux depuis le panneau d'admin. Un profil peut éventuellement être exposé comme son propre modèle : /v1/models liste alors aussi <modèle>:<profil> (par ex. qwen3-8b:thinking), qui s'exécute sur le même moteur que le modèle de base avec les paramètres du profil appliqués à chaque requête — sans mémoire supplémentaire ni rechargement. Lorsque le modèle de base possède un alias, l'identifiant exposé est annoncé sous la forme <alias>:<profil> ; la forme avec le nom du répertoire continue de fonctionner, comme pour le modèle de base.

Chat intégré

Chattez directement avec n'importe quel modèle chargé depuis le panneau d'admin. Supporte l'historique de conversation, le changement de modèle, le mode sombre, l'affichage des raisonnements, et l'upload d'images pour les modèles VLM/OCR.

Téléchargement de modèles

Recherchez et téléchargez des modèles MLX depuis HuggingFace directement dans le tableau de bord. Parcourez les fiches modèles, vérifiez les tailles de fichiers, et téléchargez en un clic.

Intégrations

Configurez OpenClaw, OpenCode, Codex, Hermes Agent et Pi directement depuis le tableau de bord en un clic. Aucune édition manuelle de config requise.

Benchmark de performance

Benchmarking en un clic depuis le panneau d'admin. Mesure le prefill (PP) et la génération de tokens (TG) en tokens par seconde, avec des tests de hit partiel sur le cache de préfixe pour des chiffres réalistes.

Application barre de menus macOS

Application native Swift / SwiftUI dans la barre de menus (pas Electron). Démarrez, arrêtez et surveillez le serveur sans ouvrir un terminal. Inclut des statistiques de service persistantes (survivent aux redémarrages), un redémarrage automatique en cas de crash, et une mise à jour automatique via Sparkle.

Compatibilité API

Remplacement direct des APIs OpenAI et Anthropic. Supporte les statistiques d'usage en streaming (stream_options.include_usage), le thinking adaptatif Anthropic, et les entrées visuelles (base64, URL).

Endpoint	Description
`POST /v1/chat/completions`	Complétion de chat (streaming)
`POST /v1/completions`	Complétion de texte (streaming)
`POST /v1/messages`	API Messages Anthropic
`POST /v1/embeddings`	Embeddings texte
`POST /v1/rerank`	Reranking de documents
`GET /v1/models`	Lister les modèles disponibles

Appel d'outils et sorties structurées

Supporte tous les formats d'appel de fonctions disponibles dans mlx-lm, la validation de schéma JSON, et l'intégration d'outils MCP. L'appel d'outils nécessite que le template de chat du modèle supporte le paramètre tools. Les familles de modèles suivantes sont auto-détectées via les parseurs intégrés de mlx-lm :

Famille de modèles	Format
Llama, Qwen, DeepSeek, etc.	JSON `<tool_call>`
Série Qwen3.5	XML `<function=...>`
Gemma	`<start_function_call>`
GLM (4.7, 5)	XML `<arg_key>/<arg_value>`
MiniMax	`<minimax:tool_call>`
Mistral	`[TOOL_CALLS]`
Kimi K2	`<\|tool_calls_section_begin\|>`
Longcat	`<longcat_tool_call>`

Les modèles non listés ci-dessus peuvent quand même fonctionner si leur template de chat accepte tools et que leur sortie utilise un format XML <tool_call> reconnu. Pour le streaming avec outils, le texte de l'assistant est émis de façon incrémentale tandis que les balises de contrôle des appels d'outils sont supprimées du contenu visible ; les appels d'outils structurés sont émis après parsing du tour complet.

Modèles

Pointez --model-dir vers un répertoire contenant des sous-répertoires de modèles au format MLX. L'organisation en deux niveaux (ex. mlx-community/nom-du-modèle/) est aussi supportée.

~/models/
├── Step-3.5-Flash-8bit/
├── Qwen3-Coder-Next-8bit/
├── gpt-oss-120b-MXFP4-Q8/
├── Qwen3.5-122B-A10B-4bit/
└── bge-m3/

Les modèles sont auto-détectés par type. Vous pouvez aussi télécharger des modèles directement depuis le tableau de bord.

Type	Modèles
LLM	Tout modèle supporté par mlx-lm
VLM	Série Qwen3.5, GLM-4V, Pixtral, et autres modèles mlx-vlm
OCR	DeepSeek-OCR, DOTS-OCR, GLM-OCR
Embedding	BERT, BGE-M3, ModernBERT
Reranker	ModernBERT, XLM-RoBERTa

Configuration CLI

# Limite mémoire pour les modèles chargés
omlx serve --model-dir ~/models --max-model-memory 32GB

# Limite mémoire au niveau du processus (par défaut : auto = RAM - 8 Go)
omlx serve --model-dir ~/models --max-process-memory 80%

# Activer le cache SSD pour les blocs KV
omlx serve --model-dir ~/models --paged-ssd-cache-dir ~/.omlx/cache

# Définir la taille du cache chaud en mémoire
omlx serve --model-dir ~/models --hot-cache-max-size 20%

# Ajuster le nombre max de requêtes simultanées (par défaut : 8)
omlx serve --model-dir ~/models --max-concurrent-requests 16

# Avec les outils MCP
omlx serve --model-dir ~/models --mcp-config mcp.json

# Endpoint miroir HuggingFace (pour les régions restreintes)
omlx serve --model-dir ~/models --hf-endpoint https://hf-mirror.com

# Authentification par clé API
omlx serve --model-dir ~/models --api-key votre-clé-secrète
# Localhost uniquement : désactivez la vérification via les paramètres globaux du panneau d'admin

Tous les paramètres peuvent aussi être configurés depuis le panneau d'admin web sur /admin. Les paramètres sont sauvegardés dans ~/.omlx/settings.json, et les flags CLI ont la priorité.

Architecture

Serveur FastAPI (API OpenAI / Anthropic)
    │
    ├── EnginePool (multi-modèles, éviction LRU, TTL, chargement/déchargement manuel)
    │   ├── BatchedEngine (LLMs, batching continu)
    │   ├── VLMEngine (modèles vision-langage)
    │   ├── EmbeddingEngine
    │   └── RerankerEngine
    │
    ├── ProcessMemoryEnforcer (limite mémoire totale, vérifications TTL)
    │
    ├── Scheduler (FCFS, concurrence configurable)
    │   └── mlx-lm BatchGenerator
    │
    └── Stack de cache
        ├── PagedCacheManager (GPU, par blocs, CoW, partage de préfixe)
        ├── Hot Cache (niveau RAM, write-back)
        └── PagedSSDCacheManager (niveau froid SSD, format safetensors)

Développement

Serveur CLI

git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e ".[dev]"
pytest -m "not slow"

Application macOS

L'application SwiftUI native vit dans apps/omlx-mac/. Nécessite Xcode 26.5+ et Python 3.11+. venvstacks est déclaré comme dépendance dev, donc pip install -e ".[dev]" (ou uv sync --dev) installe la version épinglée. Le script de build retombe sur uvx venvstacks ou pipx run venvstacks si vous préférez un runner d'outils global.

# Préparer un oMLX.app exécutable (xcodebuild + couches Python venvstacks + signature ad-hoc)
apps/omlx-mac/Scripts/build.sh release

# Le résultat atterrit dans apps/omlx-mac/build/Stage/oMLX.app
open apps/omlx-mac/build/Stage/oMLX.app

# Forcer une reconstruction de venvstacks (sinon mis en cache par empreinte)
apps/omlx-mac/Scripts/build.sh release --rebuild-donor

# Préparer avec les kernels natifs personnalisés optionnels GLM-5.2 / MiniMax M3
apps/omlx-mac/Scripts/build.sh release --with-custom-kernel

Le premier build à froid prend 10–20 minutes (assemblage des couches Python venvstacks). Les builds suivants réutilisent packaging/_export/ et finissent en environ 4 minutes. Voir packaging/README.md pour la configuration des couches et apps/omlx-mac/ pour les sources Swift.

Contribuer

Les contributions sont les bienvenues ! Voir le Guide de contribution pour les détails.

Corrections de bugs et améliorations
Optimisations de performance
Améliorations de la documentation

Licence

Apache 2.0

Remerciements

MLX et mlx-lm par Apple
mlx-vlm — inférence de modèles vision-langage sur Apple Silicon
vllm-mlx — oMLX a démarré à partir de vllm-mlx v0.1.0 et a considérablement évolué avec le service multi-modèles, le cache KV à plusieurs niveaux, le support VLM avec cache paginé complet, un panneau d'admin, et une app dans la barre de menus macOS
venvstacks — couches d'environnements Python portables pour le bundle de l'app macOS
mlx-embeddings — support des modèles d'embedding sur Apple Silicon
dflash-mlx — décodage spéculatif par diffusion par blocs sur Apple Silicon

19 KiB Raw Permalink Blame History Unescape Escape

oMLX

Installation

Application macOS

Homebrew

Depuis les sources

Démarrage rapide

Application macOS

CLI

Service Homebrew

Fonctionnalités

Tableau de bord Admin

Modèles vision-langage (VLM)

Cache KV à deux niveaux (Chaud + Froid)

Batching continu

Optimisation Claude Code

Service multi-modèles

Paramètres par modèle

Chat intégré

Téléchargement de modèles

Intégrations

Benchmark de performance

Application barre de menus macOS

Compatibilité API

Appel d'outils et sorties structurées

Modèles

Configuration CLI

Développement

Serveur CLI

Application macOS

Contribuer

Licence

Remerciements

19 KiB

Raw Permalink Blame History