Como rodar Muse Glimmer MLX no Mac com o backend SGLang

A Meta lançou o Muse Glimmer 30B em 10 de agosto de 2026 como um modelo multimodal denso, de pesos abertos. Para quem tentou executá-lo no Mac logo de início, porém, o cenário não foi tão simples: diversos runtimes MLX exibiam o erro model type muse_glimmer not supported, já que a arquitetura era recente demais para os carregadores existentes.

O backend MLX do SGLang é uma alternativa que funciona. Ele exige uma compilação a partir do código-fonte, Python 3.11 fixado no ambiente e uma variável de ambiente específica. Em troca, entrega uma API compatível com OpenAI, pronta para ser usada por agentes de código e interfaces de chat. Este guia reúne os procedimentos e as correções da issue #19137 do roadmap do SGLang em um só passo a passo.

Pré-requisitos: Mac, memória e ferramentas

O Muse Glimmer 30B é um modelo multimodal denso com 30 bilhões de parâmetros. Na quantização MLX de 4 bits, apenas os pesos ocupam aproximadamente 16-18 GB. Ao incluir o cache KV para uma janela de contexto de 32K tokens, o consumo de memória de trabalho chega a cerca de 18-20 GB. O roadmap do SGLang também limita a memória pelo tamanho máximo recomendado do working set do Metal (PR #21539), portanto o limite prático fica abaixo da memória unificada total do Mac.

Como observou um usuário do Reddit em r/opencodeCLI quando os pesos foram liberados:

"Macs com 32 GB ou mais de memória unificada devem ser viáveis para quantizações mais altas."

Também são necessários macOS 13.5 ou posterior, para o suporte ao Metal, Xcode Command Line Tools e Homebrew. O backend MLX do SGLang foi validado apenas com Python 3.11. Outras versões têm problemas conhecidos, como o próprio roadmap alerta de forma explícita.

Passo 1: instale Python 3.11, uv e MLX

A instalação do SGLang no Mac começa com dois pacotes do Homebrew e um ambiente virtual Python 3.11 administrado pelo uv.

1. Instale as dependências do Homebrew:

brew install ffmpeg uv

O ffmpeg cuida dos pipelines de processamento de áudio e multimídia. Já o uv é o gerenciador rápido de pacotes Python recomendado pelo roadmap do SGLang para criar o ambiente virtual.

1. Clone o repositório do SGLang:

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

1. Crie e ative um ambiente com Python 3.11:

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

Não use Python 3.12 nem 3.13. A issue do roadmap documenta que as importações de stubs do Triton falham no Python 3.12+ — problema corrigido na PR #21551, mas ainda sem validação completa. Além disso, a cadeia de compilação do MLX só foi testada com a versão 3.11.

1. Instale as versões mais recentes dos pacotes de runtime MLX:

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

O roadmap alerta especificamente que versões antigas de mlx ou mlx-lm podem causar traces de profiling excessivos e falhas na detecção da arquitetura. A PR #22162 tornou esses pacotes dependências explícitas do SGLang. O mlx-vlm é necessário para modelos multimodais como o Muse Glimmer; sem ele, o servidor pode falhar na inicialização com model type muse_glimmer not supported.

Passo 2: compile o SGLang com o backend MLX

O pacote padrão instalado por pip install sglang não inclui o suporte a MLX. No macOS, é necessário compilar a partir do código-fonte usando os extras Apple MPS.

1. Substitua o pyproject.toml:

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

O arquivo pyproject_other.toml remove dependências exclusivas de CUDA, que não compilam no macOS, e as troca por alternativas compatíveis com MPS.

1. Instale o SGLang em modo editável com os extras MPS:

uv pip install -e "python[all_mps]"

Esse comando compila os stubs de kernels Metal e instala o caminho de runtime para Apple Silicon. A compilação leva alguns minutos, dependendo do Mac; os builds Metal de sgl-kernel (PR #23449) são a parte mais demorada.

1. Confira se a instalação funcionou:

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

Se a importação terminar sem um erro do Triton, o caminho MPS está configurado corretamente.

Passo 3: baixe o modelo Muse Glimmer em MLX

A MLX Community publicou uma versão quantizada em 4 bits do Muse Glimmer no Hugging Face:

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

Caso o huggingface-cli não esteja instalado, adicione-o antes:

pip install huggingface-hub

O download tem aproximadamente 16-17 GB. Por padrão, o comando huggingface-cli download armazena o modelo em ~/.cache/huggingface/hub/. O SGLang consegue resolver diretamente o ID do repositório no Hugging Face em --model-path, mas você também pode apontar para o diretório local do cache.

Resumo do consumo de memória:

Na prática, um Mac com 32 GB consegue carregar o modelo, mas sobra pouca margem para janelas de contexto grandes. Se o servidor inicia, mas fecha ao receber o primeiro prompt longo, reduza --context-length para 8192 ou 16384.

Passo 4: inicie o servidor SGLang

Com as dependências instaladas e o modelo baixado, o comando de inicialização é curto. A variável de ambiente, contudo, é indispensável:

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

Entenda os parâmetros:

• SGLANG_USE_MLX=1 ativa o backend de execução MLX nativo, evitando o fallback para PyTorch MPS ou CPU. Sem essa variável, o servidor inicia, mas roda a uma fração da velocidade.
• --model-path aponta para o modelo de 4 bits no formato MLX. A PR #25191 do SGLang adicionou a detecção automática de quantization_config no formato MLX, então o reconhecimento deve ocorrer sem flags extras.
• --context-length define o limite da janela máxima de contexto. Reduza esse valor se houver pressão de memória. Segundo testes da comunidade e as notas de lançamento da Meta, o Muse Glimmer suporta teoricamente até 262K tokens, mas os limites práticos em um Mac com memória unificada são muito menores.

Avançado: o SGLang também aceita quantização em tempo de execução a partir de pesos BF16 com --quantization mlx_q4 ou mlx_q8 (PR #24907). O processo demora mais para iniciar do que carregar um modelo de 4 bits já preparado, portanto use-o apenas se precisar controlar a quantização.

Passo 5: teste pela API compatível com OpenAI

Quando o servidor exibir Server is ready, faça um teste no endpoint compatível com OpenAI usando 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
  }'

Se tudo der certo, a resposta será um objeto JSON com a conclusão gerada. Em um M5 Pro com o modelo de 4 bits, espere aproximadamente 17.6 tokens/second na geração para um único usuário, de acordo com os benchmarks do roadmap do SGLang.

Importante: deixe max_tokens com uma margem generosa, de 200 ou mais. O Muse Glimmer adota um design que prioriza raciocínio, e os tokens de chain-of-thought podem consumir uma parcela grande do orçamento de saída. Se o modelo parecer devolver respostas vazias ou cortadas, a causa mais comum é um max_tokens baixo demais: o raciocínio esgota o limite antes que a resposta apareça.

Variáveis para ajustar o MLX

O SGLang expõe três variáveis de ambiente específicas para MLX, documentadas na referência oficial de variáveis de ambiente. Todas começam desativadas ou com valores conservadores.

Exemplo com os ajustes ativados:

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

Esses recursos ainda são experimentais no roadmap. Se alguma das flags de fusão de kernels provocar uma falha, desative-a e envie um relatório: o backend MLX segue em desenvolvimento ativo.

Erros frequentes e como resolver

"Model type muse_glimmer not supported"

Este foi o erro mais comum no primeiro dia. Ele indica que o runtime MLX — mlx-lm ou mlx-vlm — não reconhece o tipo de arquitetura muse_glimmer. A correção é:

pip install mlx-lm mlx-vlm --upgrade

Se o erro continuar, verifique se seu checkout do SGLang inclui a PR de suporte MLX para Qwen3 dense (#25754), que adicionou reescritas de arquitetura para modelos transformer densos. Pode ser necessário executar git pull no branch main mais recente para obter o suporte de arquitetura exigido.

Falha nos stubs do Triton com Python 3.12

O setup do SGLang importa stubs do Triton incompatíveis com Python 3.12+. A solução é recriar o ambiente virtual 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]"

A PR #21551 corrigiu o caminho de importação do Triton, mas Python 3.11 continua sendo a única versão totalmente validada.

O servidor inicia, mas usa a CPU

Se a geração estiver extremamente lenta, abaixo de 2 tokens por segundo, o SGLang provavelmente caiu no modo CPU porque SGLANG_USE_MLX=1 não foi exportada. Confira:

echo $SGLANG_USE_MLX

Se o resultado estiver vazio, exporte a variável antes de iniciar o servidor ou inclua-a no começo do comando de inicialização.

Falha de memória no MLX ou reinicialização do sistema

Exceder o tamanho de working set recomendado pelo Metal pode encerrar o servidor ou, em casos graves, reiniciar todo o macOS. O roadmap adicionou uma limitação do working set na PR #21539 para amenizar esse problema, mas janelas de contexto grandes ainda podem ultrapassar o limite. Faça o seguinte:

• Reduza --context-length para 8192 ou menos
• Defina SGLANG_MLX_CLEAR_CACHE_STEPS=64 para limpar o cache com maior frequência
• Use o modelo de 4 bits em vez da quantização em tempo de execução a partir de pesos BF16
• Feche outros aplicativos que usam muito a GPU, especialmente o Safari com aceleração de hardware

Loops em tool calling ou resultados vazios

Discussões da comunidade no r/LocalLLaMA relatam inconsistência no tool calling do Muse Glimmer entre diferentes quantizações. Usuários testando variantes MLX e GGUF apontaram loops de chamadas de ferramentas. Não é um problema exclusivo do MLX: ele aparece em vários runtimes. Ao usar function calling, defina max_tokens como 500 ou mais, comece testando fluxos com uma única chamada e considere Qwen 3.6 27B se tool calling confiável for sua prioridade.

Perguntas frequentes

O backend MLX do SGLang oferece speculative decoding para Muse Glimmer?

Ainda não. O roadmap do SGLang lista o speculative decoding EAGLE como planejado, mas não implementado no backend MLX. No Mac, você fica limitado ao decode autorregressivo padrão, em torno de 17.6 tokens por segundo no M5 Pro com Q4, segundo os benchmarks da discussão do roadmap.

Para Muse Glimmer no Mac, devo usar MLX ou GGUF?

MLX é o caminho nativo do Apple Silicon: usa Metal diretamente e aproveita a memória unificada sem cópias explícitas entre CPU e GPU. GGUF via llama.cpp é a alternativa quando seu runtime MLX não oferece suporte à arquitetura muse_glimmer. A versão de 4 bits da MLX Community e a versão GGUF da Unsloth, disponível no Hugging Face, são as duas opções principais. Em geral, MLX entrega decode mais rápido quando funciona; GGUF tem compatibilidade mais ampla com ferramentas, como LM Studio e Ollama.

Como o SGLang MLX se compara a mlx-lm e Ollama para servir o modelo?

O SGLang fornece um servidor de API compatível com OpenAI, com radix caching e as variáveis de ajuste descritas acima. O mlx-lm é mais simples: carrega o modelo e gera texto com menos opções de configuração, mas sem a abstração de servidor. Um usuário do Reddit em r/LocalLLM relatou uma tag muse-glimmer:30b-mlx no Ollama, com sua própria camada de API. Se você precisa de uma API pronta para agentes de código como OpenCode CLI, SGLang e Ollama são as escolhas práticas; para uma geração rápida e pontual, mlx-lm basta.