Настройка Muse Glimmer MLX на Mac: руководство по бэкенду SGLang

После выхода Meta Muse Glimmer 30B 10 августа 2026 года владельцы Mac быстро столкнулись с проблемой: модель с открытыми весами и плотной мультимодальной архитектурой оказалась слишком новой для привычных загрузчиков MLX. Несколько рантаймов отвечали ошибкой model type muse_glimmer not supported.

Рабочий вариант есть — MLX-бэкенд SGLang. Понадобятся сборка из исходников, Python 3.11 и один флаг окружения. Зато затем вы получите OpenAI-совместимый API, к которому можно напрямую подключать кодинговых агентов и чат-интерфейсы. Ниже собраны в единое руководство шаги и решения из дорожной задачи SGLang #19137.

Что потребуется для запуска

Muse Glimmer 30B — плотная мультимодальная модель на 30 миллиардов параметров. При 4-битной MLX-квантизации только веса занимают примерно 16–18 ГБ, а вместе с KV-кэшем для контекстного окна в 32K токенов рабочий набор требует около 18–20 ГБ памяти. При этом дорожная карта SGLang ограничивает потребление памяти рекомендованным Metal размером рабочего набора через PR #21539, поэтому реальный предел ниже общего объёма объединённой памяти Mac.

Как отметил пользователь Reddit в r/opencodeCLI после публикации весов:

«Mac с 32 ГБ объединённой памяти и больше должны подойти для более высоких квантизаций».

Также нужны macOS 13.5 или новее для поддержки Metal, Xcode Command Line Tools и Homebrew. MLX-бэкенд SGLang проверен только с Python 3.11: другие версии, как прямо предупреждает дорожная карта, могут ломаться.

Шаг 1. Устанавливаем Python 3.11, uv и MLX

Установка SGLang на Mac начинается с двух пакетов Homebrew и виртуального окружения Python 3.11 под управлением uv.

1. Установите зависимости через Homebrew:

brew install ffmpeg uv

ffmpeg нужен для конвейеров обработки аудио и других мультимодальных данных, а uv — быстрый менеджер Python-пакетов, который дорожная карта SGLang рекомендует для создания виртуального окружения.

1. Клонируйте репозиторий SGLang:

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

1. Создайте и активируйте окружение Python 3.11:

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

Не используйте Python 3.12 и 3.13. В дорожной задаче указано, что импорты заглушек Triton ломаются на Python 3.12+; это исправляли в PR #21551, но исправление ещё не прошло полную проверку. Цепочка компиляции MLX протестирована только с 3.11.

1. Установите актуальные версии пакетов MLX:

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

Дорожная карта отдельно предупреждает: устаревшие mlx или mlx-lm вызывают шумные профилировочные трассировки и сбои определения архитектуры. PR #22162 добавил их в явные зависимости SGLang. Пакет mlx-vlm необходим мультимодальным моделям, включая Muse Glimmer: без него при запуске появится ошибка model type muse_glimmer not supported.

Шаг 2. Собираем SGLang из исходников с MLX-бэкендом

В обычном пакете pip install sglang поддержки MLX нет. Для macOS нужно собрать проект из исходников с дополнениями Apple MPS.

1. Замените pyproject.toml:

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

Файл pyproject_other.toml убирает CUDA-зависимости, которые не собираются в macOS, и заменяет их MPS-совместимыми вариантами.

1. Установите SGLang в editable-режиме с дополнениями MPS:

uv pip install -e "python[all_mps]"

Команда собирает заглушки Metal-ядер и устанавливает путь выполнения для Apple Silicon. В зависимости от вашего Mac сборка занимает несколько минут; дольше всего компилируются Metal-компоненты sgl-kernel из PR #23449.

1. Проверьте установку:

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

Если импорт проходит без ошибки Triton, путь MPS настроен правильно.

Шаг 3. Скачиваем MLX-версию Muse Glimmer

MLX Community опубликовало на Hugging Face 4-битную квантизованную сборку Muse Glimmer:

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

Если huggingface-cli ещё не установлен, сначала добавьте его:

pip install huggingface-hub

Загрузка занимает приблизительно 16–17 ГБ. По умолчанию huggingface-cli download сохраняет модель в ~/.cache/huggingface/hub/. SGLang умеет напрямую разрешать ID репозитория Hugging Face в параметре --model-path, но можно указать и путь к локальному кэшу.

Быстрый расчёт памяти:

То есть Mac с 32 ГБ способен загрузить модель, но запас для большого контекстного окна будет ограничен. Если сервер успешно стартует, но падает на первом длинном запросе, уменьшите --context-length до 8192 или 16384.

Шаг 4. Запускаем сервер SGLang

Когда зависимости установлены, а модель скачана, запуск сводится к одной команде. Критически важен флаг окружения:

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

За что отвечает каждая часть:

• SGLANG_USE_MLX=1 включает нативный бэкенд MLX вместо отката к PyTorch MPS или CPU. Без этого флага сервер стартует, но работает лишь с малой долей возможной скорости.
• --model-path указывает на 4-битную модель в формате MLX. В PR SGLang #25191 добавлено автоматическое распознавание quantization_config формата MLX, поэтому дополнительные флаги не понадобятся.
• --context-length задаёт предельный размер контекстного окна. При нехватке памяти уменьшите это значение. Согласно тестам сообщества и примечаниям Meta к релизу, теоретически Muse Glimmer поддерживает до 262K токенов, однако на Mac с объединённой памятью практический лимит значительно ниже.

Дополнительно: SGLang умеет квантизовать веса BF16 на лету через --quantization mlx_q4 или mlx_q8 (PR #24907). Такой запуск занимает больше времени, чем загрузка готовой 4-битной модели, поэтому этот вариант стоит выбирать только при необходимости контролировать процесс квантизации.

Шаг 5. Проверяем OpenAI-совместимый API

Когда сервер выведет Server is ready, отправьте тестовый запрос curl в OpenAI-совместимый endpoint:

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

При успешном выполнении в ответ придёт JSON-объект с завершением. По данным бенчмарков из дорожной карты SGLang, на M5 Pro с 4-битной моделью можно ожидать примерно 17.6 токена/с при декодировании для одного пользователя.

Важно: задавайте достаточно большой max_tokens — от 200 и выше. Muse Glimmer построена с приоритетом рассуждений, поэтому токены цепочки рассуждений способны занять значительную часть лимита вывода. Если модель выдаёт пустой или оборванный ответ, наиболее вероятная причина — слишком маленький max_tokens: весь бюджет уходит на рассуждение ещё до появления результата.

Переменные окружения для настройки MLX

В официальном справочнике переменных окружения SGLang описаны три переменные, относящиеся к MLX. По умолчанию все они выключены либо используют консервативные значения.

Пример с включённой настройкой:

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

Это экспериментальные возможности из дорожной карты. Если после включения любого флага слияния ядер возникает сбой, отключите его и отправьте отчёт: MLX-бэкенд всё ещё активно развивается.

Типичные ошибки и способы их устранения

«Model type muse_glimmer not supported»

Это самая распространённая ошибка в первый день. Она означает, что ваш MLX-рантайм — mlx-lm или mlx-vlm — не распознаёт тип архитектуры muse_glimmer. Исправление:

pip install mlx-lm mlx-vlm --upgrade

Если ошибка не исчезла, проверьте, содержит ли ваш checkout SGLang PR с поддержкой плотных MLX-моделей Qwen3 (#25754). В нём добавлены преобразования архитектур для плотных transformer-моделей. Возможно, потребуется выполнить git pull для актуальной ветки main, чтобы получить нужную поддержку архитектуры.

Сбой заглушек Triton на Python 3.12

При настройке SGLang импортируются заглушки Triton, несовместимые с Python 3.12+. Решение — пересоздать виртуальное окружение на 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]"

PR #21551 исправил путь импорта Triton, но Python 3.11 остаётся единственной полностью проверенной версией.

Сервер запустился, но работает на CPU

Если генерация идёт крайне медленно — меньше 2 токенов в секунду, — SGLang, вероятно, переключился на CPU, потому что не была экспортирована переменная SGLANG_USE_MLX=1. Проверьте:

echo $SGLANG_USE_MLX

Если команда ничего не вернула, экспортируйте переменную перед запуском сервера или укажите её в начале команды запуска.

Сбой MLX из-за памяти или перезагрузка системы

Превышение рекомендованного Metal размера рабочего набора приводит к падению сервера, а в тяжёлых случаях — к полной перезагрузке macOS. Ограничение рабочего набора добавлено в дорожную карту PR #21539, чтобы смягчить проблему, однако большое контекстное окно всё равно может выйти за допустимый предел. Что делать:

• Уменьшите --context-length до 8192 или ниже
• Задайте SGLANG_MLX_CLEAR_CACHE_STEPS=64, чтобы очищать кэш чаще
• Используйте 4-битную модель вместо квантизации на лету из весов BF16
• Закройте другие приложения, активно использующие GPU, особенно Safari с аппаратным ускорением

Циклы tool calling или пустые результаты

В обсуждениях сообщества на r/LocalLLaMA сообщают, что вызов инструментов в Muse Glimmer работает нестабильно при разных квантизациях. Пользователи, проверявшие варианты MLX и GGUF, отмечают циклы tool calling. Проблема не привязана к MLX и проявляется в разных рантаймах. Для function calling установите max_tokens в 500+, сначала тестируйте сценарии с одним вызовом и рассмотрите Qwen 3.6 27B, если надёжный вызов инструментов для вас важнее всего.

FAQ

Поддерживает ли MLX-бэкенд SGLang спекулятивное декодирование для Muse Glimmer?

Пока нет. В дорожной карте SGLang EAGLE speculative decoding отмечено как запланированное, но ещё не реализованное для MLX-бэкенда. На Mac доступно только стандартное авторегрессионное декодирование со скоростью примерно 17.6 токена/с на M5 Pro с Q4, согласно бенчмаркам из обсуждения дорожной карты.

Что выбрать для Muse Glimmer на Mac: MLX или GGUF?

MLX — нативный путь для Apple Silicon: он напрямую использует Metal и работает с объединённой памятью без явного копирования данных между CPU и GPU. GGUF через llama.cpp остаётся запасным вариантом, если ваш MLX-рантайм не поддерживает архитектуру muse_glimmer. Основные варианты — 4-битная сборка MLX Community и сборка Unsloth GGUF, доступная на Hugging Face. После успешного запуска MLX обычно даёт более высокую скорость декодирования, а GGUF предлагает более широкую совместимость с инструментами, включая LM Studio и Ollama.

Чем SGLang MLX отличается от mlx-lm и Ollama для сервинга?

SGLang предоставляет OpenAI-совместимый API-сервер с radix-кэшированием и описанными выше переменными настройки. mlx-lm проще: он загружает модель и генерирует текст с меньшим числом параметров, но не предлагает серверную абстракцию. Пользователь Reddit из r/LocalLLM сообщил о теге Ollama muse-glimmer:30b-mlx с собственным API-слоем. Если нужен API, который можно сразу подключить к кодинговым агентам вроде OpenCode CLI, практичнее выбрать SGLang или Ollama; для быстрой разовой генерации достаточно mlx-lm.