Configurer Muse Glimmer MLX sur Mac : guide du backend SGLang

Lors de la sortie de Muse Glimmer 30B par Meta, le 10 août 2026, les utilisateurs de Mac se sont rapidement heurtés à la même erreur : model type muse_glimmer not supported. Ce modèle multimodal dense à poids ouverts était simplement trop récent pour les chargeurs MLX déjà disponibles.

Le backend MLX de SGLang offre une solution fonctionnelle. Il faut compiler SGLang depuis les sources, rester sur Python 3.11 et définir une variable d’environnement essentielle. En échange, vous obtenez une API compatible OpenAI, directement exploitable par des agents de code ou des interfaces de chat. Ce guide regroupe les étapes et correctifs issus de l’issue de roadmap #19137 de SGLang.

Préparer son Mac avant l’installation

Muse Glimmer 30B est un modèle multimodal dense de 30 milliards de paramètres. En quantification MLX 4 bits, les seuls poids occupent environ 16 à 18 Go. Avec le cache KV pour une fenêtre de contexte de 32K tokens, comptez plutôt 18 à 20 Go de mémoire de travail. La roadmap de SGLang limite aussi l’usage mémoire à la taille de working set recommandée par Metal (PR #21539) : en pratique, la limite est donc inférieure à la mémoire unifiée totale de votre machine.

Comme le résumait un utilisateur de r/opencodeCLI à la publication des poids :

"Les Mac dotés d’au moins 32 Go de mémoire unifiée devraient pouvoir faire tourner des quantifications plus élevées."

Il vous faut également macOS 13.5 ou une version ultérieure pour la prise en charge de Metal, les Xcode Command Line Tools et Homebrew. Le backend MLX de SGLang n’a été validé qu’avec Python 3.11 ; d’autres versions sont connues pour casser l’installation, comme le rappelle explicitement la roadmap.

Étape 1 : installer Python 3.11, uv et MLX

L’installation de SGLang sur Mac commence par deux paquets Homebrew, puis par un environnement virtuel Python 3.11 géré avec uv.

1. Installer les dépendances Homebrew :

brew install ffmpeg uv

ffmpeg sert aux pipelines de traitement audio et multimodal. uv est le gestionnaire de paquets Python rapide recommandé par la roadmap de SGLang pour créer l’environnement virtuel.

1. Cloner le dépôt SGLang :

git clone https://github.com/sgl-project/sglang.git
cd sglang

1. Créer et activer un environnement Python 3.11 :

uv venv -p 3.11 my-venv
source my-venv/bin/activate
python -m pip install --upgrade pip

N’utilisez pas Python 3.12 ni 3.13. L’issue de roadmap indique que les imports de stubs Triton cassent avec Python 3.12+ — problème corrigé dans la PR #21551, mais pas encore entièrement validé — et la chaîne de compilation MLX n’est testée qu’avec Python 3.11.

1. Installer les dernières versions des paquets d’exécution MLX :

pip install mlx mlx-lm mlx-vlm --upgrade

La roadmap avertit précisément que des versions anciennes de mlx ou mlx-lm entraînent des traces de profilage bruyantes et des échecs de détection d’architecture. La PR #22162 les a ajoutés comme dépendances explicites de SGLang. mlx-vlm est indispensable aux modèles multimodaux comme Muse Glimmer ; sans lui, l’erreur model type muse_glimmer not supported apparaîtra au lancement.

Étape 2 : compiler SGLang avec le backend MLX

La prise en charge de MLX n’est pas incluse dans le paquet standard pip install sglang. Il faut installer SGLang depuis les sources avec les extras Apple MPS.

1. Remplacer le pyproject.toml :

cp python/pyproject.toml python/pyproject.toml.bak
cp python/pyproject_other.toml python/pyproject.toml

Le fichier pyproject_other.toml retire les dépendances réservées à CUDA, qui ne se compilent pas sous macOS, et les remplace par des alternatives compatibles MPS.

1. Installer SGLang en mode éditable avec les extras MPS :

uv pip install -e "python[all_mps]"

Cette commande compile les stubs de kernels Metal et installe le chemin d’exécution Apple Silicon. La compilation dure plusieurs minutes selon votre Mac ; les builds Metal de sgl-kernel (PR #23449) constituent la partie la plus lente.

1. Vérifier l’installation :

python -c "import sglang; print(sglang.__version__)"

Si cet import passe sans erreur Triton, le chemin MPS est correctement configuré.

Étape 3 : télécharger Muse Glimmer au format MLX

MLX Community propose sur Hugging Face une version 4 bits quantifiée de Muse Glimmer :

huggingface-cli download mlx-community/Muse-Glimmer-30B-4bit

Si huggingface-cli n’est pas installé, ajoutez d’abord le paquet correspondant :

pip install huggingface-hub

Le téléchargement représente environ 16 à 17 Go. Par défaut, huggingface-cli download place le modèle dans ~/.cache/huggingface/hub/. SGLang peut résoudre directement l’identifiant de dépôt Hugging Face dans --model-path, mais vous pouvez aussi indiquer le chemin du cache local.

Les besoins mémoire en bref :

Un Mac avec 32 Go peut donc charger le modèle, mais sa marge pour les grandes fenêtres de contexte reste limitée. Si le serveur démarre puis plante au premier prompt long, réduisez --context-length à 8192 ou 16384.

Étape 4 : démarrer le serveur SGLang

Une fois les dépendances installées et le modèle téléchargé, une seule commande suffit. La variable d’environnement est toutefois indispensable :

SGLANG_USE_MLX=1 python -m sglang.launch_server \
  --model-path mlx-community/Muse-Glimmer-30B-4bit \
  --port 30000 \
  --context-length 32768

Rôle des paramètres :

• SGLANG_USE_MLX=1 active le backend d’exécution MLX natif, au lieu d’un repli vers PyTorch MPS ou le CPU. Sans cette variable, le serveur démarre mais ne tourne qu’à une fraction de sa vitesse.
• --model-path désigne le modèle 4 bits au format MLX. La PR #25191 de SGLang a ajouté la détection automatique de quantization_config au format MLX ; aucun indicateur supplémentaire ne devrait donc être nécessaire.
• --context-length fixe la fenêtre de contexte maximale. Réduisez cette valeur en cas de pression mémoire. Muse Glimmer prend théoriquement en charge jusqu’à 262K tokens, selon les tests communautaires et les notes de publication de Meta, mais les limites réelles sont bien plus basses sur un Mac à mémoire unifiée.

Pour aller plus loin : SGLang sait aussi quantifier à la volée des poids BF16 avec --quantization mlx_q4 ou mlx_q8 (PR #24907). Le démarrage est plus long que lors du chargement d’un modèle 4 bits déjà construit ; utilisez cette option uniquement si vous devez maîtriser le processus de quantification.

Étape 5 : tester l’API compatible OpenAI

Dès que le serveur affiche Server is ready, testez l’endpoint compatible OpenAI avec une requête curl :

curl http://localhost:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-glimmer",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain how GQA reduces KV cache size in one sentence."}
    ],
    "max_tokens": 200
  }'

Une réponse réussie renvoie un objet JSON contenant la complétion. Sur un M5 Pro avec le modèle 4 bits, les données de benchmark de la roadmap SGLang indiquent environ 17.6 tokens/seconde en décodage pour un seul utilisateur.

À retenir : prévoyez une valeur généreuse pour max_tokens (200 ou plus). Muse Glimmer adopte une conception orientée raisonnement : les tokens de chaîne de pensée peuvent consommer une large part du budget de sortie. Si le modèle semble renvoyer des réponses vides ou tronquées, la cause la plus fréquente est un max_tokens trop faible : le raisonnement épuise tout le budget avant l’apparition de la réponse.

Variables de réglage propres à MLX

SGLang expose trois variables d’environnement spécifiques à MLX, documentées dans la référence officielle des variables d’environnement. Toutes sont désactivées par défaut ou définies sur des valeurs prudentes.

Exemple avec les réglages activés :

SGLANG_USE_MLX=1 \
SGLANG_MLX_USE_CUSTOM_ROPE=true \
SGLANG_MLX_FUSE_SWIGLU=true \
SGLANG_MLX_CLEAR_CACHE_STEPS=128 \
python -m sglang.launch_server \
  --model-path mlx-community/Muse-Glimmer-30B-4bit \
  --port 30000 \
  --context-length 32768

Ces fonctions restent expérimentales dans la roadmap. Si l’activation de l’un des indicateurs de fusion de kernels provoque un plantage, désactivez-le et signalez le problème : le backend MLX est toujours en développement actif.

Erreurs fréquentes : causes et correctifs

« Model type muse_glimmer not supported »

C’est l’erreur la plus fréquente au lancement. Elle indique que votre runtime MLX, mlx-lm ou mlx-vlm, ne reconnaît pas le type d’architecture muse_glimmer. Correctif :

pip install mlx-lm mlx-vlm --upgrade

Si l’erreur persiste, vérifiez que votre copie de SGLang inclut la PR de prise en charge MLX dense de Qwen3 (#25754), qui a ajouté des réécritures d’architecture pour les modèles transformer denses. Un git pull de la branche main la plus récente peut être nécessaire pour récupérer la prise en charge requise.

Plantage des stubs Triton avec Python 3.12

Le setup de SGLang importe des stubs Triton incompatibles avec Python 3.12+. Recréez l’environnement virtuel avec Python 3.11 :

deactivate
rm -rf my-venv
uv venv -p 3.11 my-venv
source my-venv/bin/activate
uv pip install -e "python[all_mps]"

La PR #21551 a corrigé le chemin d’import de Triton, mais Python 3.11 reste l’unique version entièrement validée.

Le serveur démarre, mais calcule sur le CPU

Si la génération est extrêmement lente, sous les 2 tokens/seconde, SGLang a probablement basculé sur le CPU parce que SGLANG_USE_MLX=1 n’a pas été exportée. Vérifiez-la :

echo $SGLANG_USE_MLX

Si la commande ne renvoie rien, exportez la variable avant de lancer le serveur ou placez-la directement en préfixe de la commande de lancement.

Crash mémoire MLX ou redémarrage du système

Dépasser la taille de working set recommandée par Metal peut provoquer un crash du serveur ou, dans les cas graves, un redémarrage complet de macOS. La roadmap a ajouté une limitation du working set dans la PR #21539 pour atténuer ce risque, mais les grandes fenêtres de contexte peuvent toujours franchir cette limite. Correctifs :

• Réduisez --context-length à 8192 ou moins
• Définissez SGLANG_MLX_CLEAR_CACHE_STEPS=64 afin de vider le cache plus souvent
• Utilisez le modèle 4 bits plutôt qu’une quantification à la volée depuis des poids BF16
• Fermez les autres applications gourmandes en GPU, notamment Safari avec l’accélération matérielle

Boucles d’outils ou résultats vides

Des discussions sur r/LocalLLaMA signalent un appel d’outils inconstant selon les quantifications de Muse Glimmer ; des utilisateurs testant les variantes MLX comme GGUF rapportent des boucles d’appel d’outils. Le problème n’est pas propre à MLX : il semble toucher plusieurs runtimes. Réglez max_tokens sur 500 ou plus pour le function calling, commencez par des workflows à appel unique, et envisagez Qwen 3.6 27B si la fiabilité de l’appel d’outils est votre priorité.

Questions fréquentes

Le backend MLX de SGLang gère-t-il le décodage spéculatif pour Muse Glimmer ?

Pas encore. La roadmap de SGLang mentionne le décodage spéculatif EAGLE comme prévu, mais non implémenté pour le backend MLX. Sur Mac, vous êtes limité au décodage autorégressif standard, à environ 17.6 tokens/seconde sur un M5 Pro en Q4, d’après les benchmarks de la discussion de roadmap.

Pour Muse Glimmer sur Mac, faut-il choisir MLX ou GGUF ?

MLX est la voie native sur Apple Silicon : il utilise Metal directement et tire parti de la mémoire unifiée sans copies explicites entre CPU et GPU. GGUF via llama.cpp constitue la solution de repli si votre runtime MLX ne prend pas encore en charge l’architecture muse_glimmer. La version 4 bits de MLX Community et la version GGUF d’Unsloth, disponible sur Hugging Face, sont les deux principales options. MLX offre généralement un décodage plus rapide une fois opérationnel ; GGUF bénéficie d’une compatibilité plus large avec les outils, dont LM Studio et Ollama.

Comment SGLang MLX se compare-t-il à mlx-lm ou Ollama pour servir le modèle ?

SGLang fournit un serveur d’API compatible OpenAI, avec cache radix et les variables de réglage décrites plus haut. mlx-lm est plus simple : il charge le modèle et génère du texte avec moins d’options de configuration, mais sans abstraction de serveur. Un utilisateur de r/LocalLLM a signalé un tag Ollama muse-glimmer:30b-mlx, accompagné de sa propre couche API. Si vous avez besoin d’une API prête à l’emploi pour des agents de code comme OpenCode CLI, SGLang ou Ollama sont les choix pratiques ; pour une génération ponctuelle rapide, mlx-lm suffit.