Mac'te Muse Glimmer MLX Kurulumu: SGLang Backend Rehberi

Meta, 10 Ağustos 2026'da açık ağırlıklara sahip yoğun multimodal modeli Muse Glimmer 30B'yi yayımladı. Ancak Mac kullanıcıları ilk andan itibaren bir engelle karşılaştı: mevcut yükleyiciler mimariyi henüz tanımadığı için pek çok MLX çalışma zamanı model type muse_glimmer not supported hatası veriyordu.

Çalışan seçeneklerden biri SGLang'in MLX backend'i. Kurulum için kaynak koddan derleme, Python 3.11'e sabitleme ve tek bir ortam değişkeni gerekiyor. Ardından coding agent'ların ve sohbet arayüzlerinin doğrudan kullanabileceği OpenAI uyumlu bir API sunuyor. Bu rehber, SGLang'in roadmap issue #19137 başlığındaki adımları ve çözümleri tek yerde topluyor.

Başlamadan Önce Gerekenler

Muse Glimmer 30B, 30 milyar parametreli yoğun bir multimodal model. 4-bit MLX quantization ile yalnızca ağırlıklar yaklaşık 16-18 GB yer kaplıyor; 32K token context window için KV cache de hesaba katıldığında çalışma belleği ihtiyacı yaklaşık 18-20 GB'a ulaşıyor. SGLang roadmap'i ayrıca belleği Metal'in recommended-max-working-set boyutuna göre sınırlandırıyor (PR #21539). Bu nedenle pratik üst sınır, toplam unified memory miktarınızdan daha düşük.

Ağırlıkların yayımlanmasının ardından r/opencodeCLI topluluğundaki bir Reddit kullanıcısının belirttiği gibi:

"32 GB veya daha fazla unified memory'e sahip Mac'ler, daha yüksek quantization seviyeleri için kullanılabilir olmalı."

Ayrıca macOS 13.5 veya sonrası, Xcode Command Line Tools ve Homebrew gerekli. SGLang'in MLX backend'i yalnızca Python 3.11 ile doğrulandı; roadmap açıkça uyardığı üzere diğer sürümlerin sorun çıkardığı biliniyor.

1. Adım: Python 3.11, uv ve MLX Bağımlılıklarını Kurun

SGLang'in Mac kurulumu, Homebrew üzerinden iki paket ve uv ile yönetilen bir Python 3.11 sanal ortamıyla başlıyor.

1. Homebrew bağımlılıklarını yükleyin:

brew install ffmpeg uv

ffmpeg, ses ve multimodal işleme akışlarını yönetir. uv ise SGLang roadmap'inin sanal ortam oluşturmak için önerdiği hızlı Python paket yöneticisidir.

1. SGLang deposunu klonlayın:

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

1. Python 3.11 ortamını oluşturup etkinleştirin:

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

Python 3.12 veya 3.13 kullanmayın. Roadmap issue'a göre Triton stub import'ları Python 3.12+ sürümlerinde bozuluyor (PR #21551 ile düzeltildi, ancak henüz tam doğrulanmadı). MLX'in derleme zinciri de yalnızca 3.11 ile test edildi.

1. MLX çalışma zamanı paketlerini en güncel sürümleriyle yükleyin:

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

Roadmap, eski mlx veya mlx-lm sürümlerinin gürültülü profiling izlerine ve mimari algılama hatalarına yol açtığını özellikle vurguluyor. PR #22162, bunları açık SGLang bağımlılıkları olarak ekledi. mlx-vlm, Muse Glimmer gibi multimodal modeller için gerekli; aksi hâlde başlatma sırasında model type muse_glimmer not supported hatasıyla karşılaşırsınız.

2. Adım: SGLang'i MLX Backend ile Kaynak Koddan Derleyin

SGLang, standart pip install sglang paketiyle MLX desteği sunmuyor. Apple MPS ekstralarını kullanarak kaynak koddan derlemeniz gerekiyor.

1. pyproject.toml dosyasını değiştirin:

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

pyproject_other.toml dosyası, macOS'te derlenemeyen yalnızca CUDA'ya özel bağımlılıkları kaldırır ve bunların yerine MPS uyumlu alternatifleri koyar.

1. SGLang'i MPS ekstralarıyla editable modda yükleyin:

uv pip install -e "python[all_mps]"

Bu işlem Metal kernel stub'larını derler ve Apple Silicon çalışma zamanı yolunu yükler. Süre Mac'inize göre birkaç dakika değişir; en yavaş bölüm sgl-kernel Metal derlemeleridir (PR #23449).

1. Kurulumu doğrulayın:

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

Bu komut Triton hatası vermeden import işlemini tamamlıyorsa MPS yolu doğru yapılandırılmış demektir.

3. Adım: Muse Glimmer MLX Modelini İndirin

MLX Community, Muse Glimmer'ın 4-bit quantized sürümünü Hugging Face üzerinde yayımladı:

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

huggingface-cli kurulu değilse önce şunu yükleyin:

pip install huggingface-hub

İndirme boyutu yaklaşık 16-17 GB. Varsayılan olarak huggingface-cli download, modeli ~/.cache/huggingface/hub/ altında saklar. SGLang, Hugging Face repository ID'sini doğrudan --model-path içinde çözebilir; isterseniz yerel cache dizinini de gösterebilirsiniz.

Hızlı bellek hesabı:

Bu tablo, 32 GB'lık bir Mac'in modeli yükleyebileceğini ancak geniş context window'lar için sınırlı payı olduğunu gösteriyor. Sunucu açılıp ilk uzun prompt'ta çöküyorsa --context-length değerini 8192 veya 16384'e düşürün.

4. Adım: SGLang Sunucusunu Başlatın

Bağımlılıklar kurulu ve model indirilmişse başlatma komutu tek satırdan ibaret. Ancak ortam değişkeni kritik önemde:

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

Parametreler ne işe yarar?

• SGLANG_USE_MLX=1, PyTorch MPS veya CPU'ya düşmek yerine yerel MLX execution backend'ini etkinleştirir. Bu bayrak olmadan sunucu başlar, fakat hızın yalnızca küçük bir bölümünde çalışır.
• --model-path, MLX formatındaki 4-bit modeli işaret eder. SGLang'in PR #25191 değişikliği, MLX formatındaki quantization_config için otomatik algılama ekledi; dolayısıyla ek bayrak gerekmeden formatın tanınması gerekir.
• --context-length, maksimum context window'yu sınırlar. Bellek baskısı yaşıyorsanız bu değeri düşürün. Muse Glimmer, community testing and Meta's release notes verilerine göre teorik olarak 262K token'a kadar destekliyor; fakat unified memory kullanan Mac'lerde pratik sınırlar çok daha düşük.

İleri seviye: SGLang, BF16 ağırlıklarından --quantization mlx_q4 veya mlx_q8 kullanarak anlık quantization işlemini de destekliyor (PR #24907). Hazır 4-bit modeli yüklemeye kıyasla başlangıç süresi uzar; bu yüzden yalnızca quantization sürecini kontrol etmeniz gerekiyorsa tercih edin.

5. Adım: OpenAI Uyumlu API Çağrısıyla Test Edin

Sunucu Server is ready mesajını yazdırdığında, OpenAI uyumlu endpoint'i bir curl isteğiyle test edebilirsiniz:

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
  }'

Başarılı bir istek, completion içeren bir JSON nesnesi döndürür. SGLang roadmap benchmark verilerine göre, M5 Pro üzerinde 4-bit modelle tek kullanıcı decode performansı yaklaşık 17.6 tokens/second olmalı.

Önemli not: max_tokens değerini cömert tutun (200+). Muse Glimmer, chain-of-thought token'larının çıktı bütçesinin önemli bölümünü tüketebildiği reasoning-first bir tasarım kullanıyor. Model boş ya da kesilmiş yanıtlar veriyorsa en yaygın neden max_tokens değerinin düşük olmasıdır: yanıt görünmeden önce tüm bütçe reasoning tarafından harcanır.

MLX Ayar Değişkenleri Ne İşe Yarar?

SGLang, resmî environment variables referansında belgelenen MLX'e özel üç ortam değişkeni sunuyor. Üçü de varsayılan olarak kapalı veya temkinli bir değerde gelir.

Ayarlamaların etkin olduğu örnek:

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

Bunlar roadmap üzerindeki deneysel özelliklerdir. Kernel-fusion bayraklarından herhangi birini etkinleştirmek çökmeye neden olursa bayrağı kapatın ve hata raporu gönderin; MLX backend hâlâ aktif geliştirme aşamasında.

Sık Karşılaşılan Hatalar ve Çözümleri

"Model type muse_glimmer not supported" hatası

İlk gün en sık görülen hata bu. MLX çalışma zamanınızın (mlx-lm veya mlx-vlm) muse_glimmer mimari türünü tanımadığı anlamına gelir. Çözüm:

pip install mlx-lm mlx-vlm --upgrade

Hata devam ederse SGLang checkout'unuzun, yoğun transformer modeller için mimari yeniden yazımlarını ekleyen Qwen3 dense MLX support PR'ını (#25754) içerip içermediğini kontrol edin. Gerekli mimari desteği almak için en güncel main branch'ine git pull yapmanız gerekebilir.

Python 3.12 Triton stub çökmesi

SGLang kurulumu, Python 3.12+ ile uyumsuz Triton stub'larını import eder. Çözüm, sanal ortamı Python 3.11 ile yeniden oluşturmaktır:

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

PR #21551, Triton import yolunu düzeltti; ancak tam olarak doğrulanmış tek sürüm Python 3.11 olmaya devam ediyor.

Sunucu açılıyor ama CPU üzerinde çalışıyor

Token üretimi aşırı yavaşsa (2 tokens/second altında), büyük ihtimalle SGLANG_USE_MLX=1 export edilmediği için SGLang CPU'ya geri düştü. Kontrol edin:

echo $SGLANG_USE_MLX

Komut boş sonuç döndürüyorsa sunucuyu başlatmadan önce değişkeni export edin veya başlatma komutunun başına satır içi olarak ekleyin.

MLX bellek çökmesi veya sistemin yeniden başlaması

Metal'in önerdiği working-set boyutunun aşılması, sunucunun çökmesine veya ağır durumlarda macOS'in tamamen yeniden başlamasına yol açabilir. Roadmap, bunu hafifletmek için PR #21539 ile working-set sınırı ekledi; yine de büyük context window'lar sınırı aşabilir. Çözüm seçenekleri:

• --context-length değerini 8192 veya altına indirin
• Cache'i daha sık temizlemek için SGLANG_MLX_CLEAR_CACHE_STEPS=64 ayarlayın
• BF16 ağırlıklardan anlık quantization yerine 4-bit modeli kullanın
• Başta hardware acceleration kullanan Safari olmak üzere GPU yoğun uygulamaları kapatın

Tool-calling döngüleri veya boş sonuçlar

r/LocalLLaMA topluluğundaki paylaşımlar, Muse Glimmer'ın tool calling davranışının quantization türlerine göre tutarsız olduğunu gösteriyor. Hem MLX hem de GGUF varyantlarını deneyen kullanıcılar tool-calling döngüleri bildirmiş. Sorun MLX'e özgü değil; farklı çalışma zamanlarında da görülüyor. Function calling kullanırken max_tokens değerini 500+ yapın, önce tek çağrılı akışlarla test edin ve güvenilir tool calling temel ihtiyacınızsa Qwen 3.6 27B'yi değerlendirin.

SSS

SGLang'in MLX backend'i Muse Glimmer için speculative decoding destekliyor mu?

Henüz değil. SGLang roadmap'i EAGLE speculative decoding özelliğini planlanan ancak MLX backend için uygulanmamış olarak listeliyor. Mac'te, roadmap discussion içindeki benchmark verilerine göre standart autoregressive decoding ile yaklaşık 17.6 tokens/second (M5 Pro, Q4) ile sınırlısınız.

Mac'te Muse Glimmer için MLX mi, GGUF mi kullanmalıyım?

MLX, Apple Silicon'ın yerel yolu: Metal'i doğrudan kullanır ve açık CPU-to-GPU kopyaları olmadan unified memory'den faydalanır. MLX çalışma zamanınız muse_glimmer mimarisini desteklemiyorsa llama.cpp üzerinden GGUF alternatif yoldur. MLX community'nin 4-bit sürümü ile Unsloth GGUF sürümü (Hugging Face üzerinde bulunuyor) iki ana seçenek. Çalıştığında MLX genellikle daha yüksek decode hızları sunar; GGUF ise daha geniş araç uyumluluğuna sahiptir (LM Studio, Ollama).

Serving için SGLang MLX, mlx-lm ve Ollama ile nasıl karşılaştırılır?

SGLang; OpenAI uyumlu API sunucusu, radix caching ve yukarıda açıklanan ayar değişkenlerini sağlar. mlx-lm daha basittir: daha az yapılandırma seçeneğiyle metin yükler ve üretir, ancak server abstraction sunmaz. r/LocalLLM topluluğundaki bir Reddit kullanıcısı, kendi API katmanına sahip bir Ollama muse-glimmer:30b-mlx tag'i bildirdi. OpenCode CLI gibi coding agent'lar için doğrudan kullanılabilecek bir API istiyorsanız SGLang veya Ollama pratik seçeneklerdir; hızlı ve tek seferlik üretim içinse mlx-lm yeterlidir.