Muse Glimmer MLX su Mac: guida al backend SGLang

Meta ha rilasciato Muse Glimmer 30B il 10 agosto 2026 come modello multimodale dense a pesi aperti. Per molti utenti Mac, però, il debutto è stato subito complicato: diversi runtime MLX restituivano l'errore model type muse_glimmer not supported, perché i loader esistenti non conoscevano ancora questa architettura.

Il backend MLX di SGLang offre una strada funzionante. Bisogna compilare il progetto dai sorgenti, usare Python 3.11 e impostare una variabile d'ambiente. In cambio si ottiene un'API compatibile con OpenAI, pronta per agenti di coding e interfacce chat. Questa guida raccoglie in un unico flusso i passaggi e le soluzioni emersi nella roadmap issue #19137 di SGLang.

Requisiti: Mac, memoria e software necessari

Muse Glimmer 30B è un modello multimodale dense da 30 miliardi di parametri. Con quantizzazione MLX a 4 bit, i soli pesi richiedono circa 16-18 GB; aggiungendo la KV cache per una finestra di contesto da 32K token, servono all'incirca 18-20 GB di memoria operativa. La roadmap di SGLang limita inoltre l'uso della memoria alla dimensione del working set massimo consigliato da Metal (PR #21539): nella pratica, quindi, il limite è inferiore alla memoria unificata totale del Mac.

Come ha osservato un utente Reddit su r/opencodeCLI all'uscita dei pesi:

"I Mac con 32 GB o più di memoria unificata dovrebbero essere adatti a quantizzazioni più elevate."

Servono inoltre macOS 13.5 o successivo, per il supporto Metal, Xcode Command Line Tools e Homebrew. Il backend MLX di SGLang è stato verificato esclusivamente con Python 3.11: altre versioni sono note per causare problemi, come avverte esplicitamente la roadmap.

Passaggio 1: installare Python 3.11, uv e MLX

L'installazione di SGLang su Mac parte da due pacchetti Homebrew e da un ambiente virtuale Python 3.11 gestito con uv.

1. Installa le dipendenze Homebrew:

brew install ffmpeg uv

ffmpeg gestisce le pipeline di elaborazione audio e multimodali; uv è il gestore veloce di pacchetti Python consigliato dalla roadmap di SGLang per creare l'ambiente virtuale.

1. Clona il repository di SGLang:

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

1. Crea e attiva un ambiente Python 3.11:

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

Non usare Python 3.12 o 3.13. La roadmap documenta che gli import degli stub Triton si interrompono con Python 3.12+; il problema è stato corretto nella PR #21551, ma non è stato ancora verificato completamente. Anche la catena di compilazione MLX è testata soltanto con la 3.11.

1. Installa le versioni più recenti dei pacchetti runtime MLX:

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

La roadmap avverte in particolare che versioni datate di mlx o mlx-lm provocano tracce di profiling molto rumorose e fallimenti nel rilevamento dell'architettura. La PR #22162 li ha aggiunti come dipendenze esplicite di SGLang. mlx-vlm è necessario per modelli multimodali come Muse Glimmer: senza, all'avvio comparirà l'errore model type muse_glimmer not supported.

Passaggio 2: compilare SGLang dai sorgenti con il backend MLX

Il normale pacchetto pip install sglang non include il supporto MLX. Su Mac devi quindi compilare dai sorgenti usando gli extra Apple MPS.

1. Sostituisci il file pyproject.toml:

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

Il file pyproject_other.toml rimuove le dipendenze riservate a CUDA, che non vengono compilate su macOS, e le sostituisce con alternative compatibili con MPS.

1. Installa SGLang in modalità editable con gli extra MPS:

uv pip install -e "python[all_mps]"

Il comando compila gli stub dei kernel Metal e installa il percorso runtime per Apple Silicon. La build richiede alcuni minuti, in base al Mac; la parte più lenta è la compilazione Metal di sgl-kernel (PR #23449).

1. Verifica l'installazione:

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

Se l'import viene eseguito senza errori Triton, il percorso MPS è configurato correttamente.

Passaggio 3: scaricare il modello Muse Glimmer in formato MLX

MLX Community ha pubblicato su Hugging Face una build di Muse Glimmer quantizzata a 4 bit:

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

Se huggingface-cli non è installato, aggiungilo prima:

pip install huggingface-hub

Il download pesa circa 16-17 GB. Per impostazione predefinita, huggingface-cli download salva il modello in ~/.cache/huggingface/hub/. SGLang può risolvere direttamente l'ID del repository Hugging Face in --model-path, oppure puoi indicare la directory della cache locale.

Memoria necessaria, in breve:

Un Mac da 32 GB può quindi caricare il modello, ma offre poco margine per finestre di contesto ampie. Se il server parte e poi va in crash al primo prompt lungo, riduci --context-length a 8192 o 16384.

Passaggio 4: avviare il server SGLang

Dopo avere installato le dipendenze e scaricato il modello, il comando di avvio è una sola riga. La variabile d'ambiente, però, è essenziale:

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

Cosa fa ogni parametro:

• SGLANG_USE_MLX=1 abilita il backend di esecuzione MLX nativo invece di ricadere su PyTorch MPS o CPU. Senza questa variabile, il server si avvia ma gira a una frazione della velocità.
• --model-path indica il modello a 4 bit in formato MLX. La PR #25191 di SGLang ha aggiunto il rilevamento automatico di quantization_config per il formato MLX, quindi il formato dovrebbe essere riconosciuto senza ulteriori opzioni.
• --context-length limita la finestra di contesto massima. Riduci il valore se la memoria è sotto pressione. Muse Glimmer supporta teoricamente fino a 262K token secondo i test della community e le note di rilascio di Meta, ma su un Mac con memoria unificata il limite pratico è decisamente più basso.

Per utenti avanzati: SGLang supporta anche la quantizzazione al volo a partire dai pesi BF16 con --quantization mlx_q4 o mlx_q8 (PR #24907). L'avvio richiede più tempo rispetto al caricamento di un modello 4 bit già pronto: usala solo se devi controllare il processo di quantizzazione.

Passaggio 5: testare l'API compatibile con OpenAI

Quando il server stampa Server is ready, prova l'endpoint compatibile con OpenAI tramite una richiesta 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
  }'

Una risposta riuscita restituisce un oggetto JSON con il completamento. Su un M5 Pro con il modello a 4 bit, i benchmark della roadmap di SGLang indicano circa 17,6 token al secondo nella decodifica per singolo utente.

Importante: imposta max_tokens su un valore generoso, 200 o più. Muse Glimmer segue un'impostazione reasoning-first, in cui i token della chain of thought possono consumare una parte rilevante del budget di output. Se il modello sembra produrre risposte vuote o troncate, la causa più comune è un valore di max_tokens troppo basso: il ragionamento esaurisce il budget prima che compaia la risposta.

Variabili MLX per il tuning: a cosa servono

SGLang espone tre variabili d'ambiente specifiche per MLX, documentate nel riferimento ufficiale delle variabili d'ambiente. Per tutte, l'impostazione iniziale è disattivata o prudente.

Esempio con il tuning abilitato:

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

Si tratta di funzioni sperimentali indicate nella roadmap. Se l'attivazione di uno dei flag di fusione dei kernel causa un crash, disabilitalo e segnala il problema: il backend MLX è ancora in sviluppo attivo.

Errori comuni e relative soluzioni

"Model type muse_glimmer not supported"

È l'errore più frequente nei primi giorni. Significa che il runtime MLX, mlx-lm o mlx-vlm, non riconosce il tipo di architettura muse_glimmer. Soluzione:

pip install mlx-lm mlx-vlm --upgrade

Se l'errore persiste, verifica che il checkout di SGLang includa la PR per il supporto MLX dense di Qwen3 (#25754), che ha aggiunto riscritture dell'architettura per i modelli transformer dense. Potrebbe essere necessario eseguire git pull sul branch main più recente per ottenere il supporto architetturale richiesto.

Crash degli stub Triton con Python 3.12

La configurazione di SGLang importa stub Triton incompatibili con Python 3.12+. Ricrea l'ambiente virtuale usando 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 ha corretto il percorso di import di Triton, ma Python 3.11 resta l'unica versione verificata completamente.

Il server parte ma usa la CPU

Se la generazione è estremamente lenta, sotto 2 token al secondo, SGLang probabilmente è passato alla CPU perché SGLANG_USE_MLX=1 non è stato esportato. Verifica così:

echo $SGLANG_USE_MLX

Se il comando non restituisce nulla, esporta la variabile prima di avviare il server oppure anteponila direttamente al comando di avvio.

Crash per memoria MLX o riavvio del sistema

Superare il working set consigliato da Metal può causare il crash del server o, nei casi più gravi, il riavvio completo di macOS. La roadmap ha aggiunto un limite al working set con la PR #21539 per attenuare il problema, ma finestre di contesto molto ampie possono comunque superare la soglia. Soluzioni:

• Riduci --context-length a 8192 o meno
• Imposta SGLANG_MLX_CLEAR_CACHE_STEPS=64 per pulire la cache più spesso
• Usa il modello a 4 bit invece della quantizzazione al volo dai pesi BF16
• Chiudi le altre applicazioni che usano intensamente la GPU, in particolare Safari con accelerazione hardware

Cicli nel tool calling o risultati vuoti

Discussioni della community su r/LocalLLaMA segnalano che il tool calling di Muse Glimmer è incoerente tra le diverse quantizzazioni. Utenti che provano sia varianti MLX sia GGUF riportano loop nel tool calling. Non è un problema specifico di MLX: si manifesta su vari runtime. Quando usi il function calling, imposta max_tokens a 500 o più, testa prima workflow con una sola chiamata e valuta Qwen 3.6 27B se per te il tool calling affidabile è una necessità prioritaria.

FAQ

Il backend MLX di SGLang supporta la speculative decoding per Muse Glimmer?

Non ancora. La roadmap di SGLang indica la speculative decoding EAGLE come pianificata, ma non implementata per il backend MLX. Su Mac sei limitato alla normale decodifica autoregressiva, a circa 17,6 token al secondo su M5 Pro con Q4, secondo i benchmark riportati nella discussione della roadmap.

Per Muse Glimmer su Mac conviene usare MLX o GGUF?

MLX è il percorso nativo per Apple Silicon: usa Metal direttamente e sfrutta la memoria unificata senza copie esplicite tra CPU e GPU. GGUF tramite llama.cpp è l'alternativa se il runtime MLX non supporta ancora l'architettura muse_glimmer. Le due opzioni principali sono la build MLX Community a 4 bit e la build GGUF di Unsloth, disponibile su Hugging Face. Quando funziona, MLX offre in genere una decodifica più veloce; GGUF ha una compatibilità più ampia con gli strumenti, tra cui LM Studio e Ollama.

Come si confronta SGLang MLX con mlx-lm o Ollama per il serving?

SGLang offre un server API compatibile con OpenAI, radix caching e le variabili di tuning descritte sopra. mlx-lm è più semplice: carica il modello e genera testo con meno opzioni di configurazione, ma senza un'astrazione server. Un utente Reddit su r/LocalLLM ha segnalato un tag Ollama muse-glimmer:30b-mlx con un proprio livello API. Se ti serve un'API pronta all'uso per agenti di coding come OpenCode CLI, SGLang o Ollama sono le scelte pratiche; per una generazione rapida e occasionale, mlx-lm è sufficiente.