Перейти к основному содержимому

MLX LM на Apple Silicon

Libre WebUI включает плагин MLX LM (Apple Silicon) для запуска языковых моделей в формате MLX непосредственно на Mac серии M. Он подключается к совместимому с OpenAI HTTP API, встроенному в MLX LM.

Этот путь полезен для нативного инференса Metal без преобразования контрольной точки MLX в Ollama или GGUF.

Архитектура​

Libre WebUI in native development mode
  frontend http://localhost:5173
  backend  http://localhost:3001
                  |
                  | OpenAI-compatible chat request
                  v
mlx_lm.server http://127.0.0.1:8081
                  |
                  v
MLX model on Apple Silicon unified memory

Порт 8081 выбран намеренно. MLX LM обычно использует 8080, что конфликтует с пакетным сервером npx libre-webui.

Требования​

  • Mac с Apple Silicon (M1 или новее).
  • macOS с инструментами командной строки Xcode.
  • Python 3.10 или новее.
  • Достаточно unified memory для модели, KV-кэша и macOS.
  • Нативно работающий Libre WebUI. Разработка из исходников проще всего, поскольку оба бэкенда используют loopback Mac.

Модель Ternary Bonsai по умолчанию занимает около 8,5 ГБ на диске и больше при работе. Mac с 16 ГБ unified memory справится с коротким контекстом, но 24 ГБ и больше дают практический запас. При нехватке памяти используйте меньшую контрольную точку MLX и добавьте ID репозитория в копию плагина.

Установка MLX LM​

uv изолирует команду от пакетов Homebrew Python:

brew install uv
uv tool install --upgrade mlx-lm
rehash
mlx_lm.server --help

Если инструмент уже установлен:

uv tool upgrade mlx-lm
rehash

Модели Qwen 3.5 требуют mlx-lm 0.30.7 или новее. Пример репозитория требует 0.31.3 или новее.

Запуск сервера​

Для Ternary Bonsai:

mlx_lm.server \
  --model "prism-ml/Ternary-Bonsai-27B-mlx-2bit" \
  --host 127.0.0.1 \
  --port 8081 \
  --max-tokens 262144 \
  --allowed-origins "http://localhost:5173,http://127.0.0.1:5173"

Первый запуск загружает модель с Hugging Face, последующие используют кэш. Ternary Bonsai объявляет максимум 262144 позиций. Промпт и результат делят окно, поэтому длинный промпт сокращает доступную генерацию, хотя лимит сервера равен максимуму модели.

Для меньшей стартовой модели:

mlx_lm.server \
  --model "mlx-community/Llama-3.2-3B-Instruct-4bit" \
  --host 127.0.0.1 \
  --port 8081 \
  --max-tokens 2048

В репозитории есть повторно используемый запуск:

cd examples/mlx-lm-server
uv run server.py

Просмотрите разрешённую команду без загрузки модели:

uv run server.py --dry-run

Проверка совместимого с OpenAI API​

Проверьте состояние и обнаружение моделей:

curl http://127.0.0.1:8081/health
curl http://127.0.0.1:8081/v1/models

Отправьте нестриминговый запрос чата:

curl http://127.0.0.1:8081/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "prism-ml/Ternary-Bonsai-27B-mlx-2bit",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Reply with: MLX is ready."}
    ],
    "temperature": 0.7,
    "top_p": 0.95,
    "max_tokens": 64,
    "stream": false
  }'

Сервер также поддерживает Server-Sent Events при "stream": true.

Подключение Libre WebUI​

Из корня репозитория Libre WebUI:

npm install
npm run dev

Откройте http://localhost:5173, затем:

  1. Откройте Settings > Plugins.
  2. Найдите MLX LM (Apple Silicon).
  3. Убедитесь, что эндпоинт — http://127.0.0.1:8081/v1/chat/completions.
  4. Активируйте плагин. Локальному MLX не нужен ключ API.
  5. Вернитесь в Chat и выберите MLX-модель.

Встроенный список содержит:

  • prism-ml/Ternary-Bonsai-27B-mlx-2bit

Выбранная в Libre WebUI модель должна быть доступна серверу MLX. Для другой контрольной точки экспортируйте или скопируйте plugins/mlx-lm.json, добавьте ID в model_map и импортируйте определение через Settings > Plugins.

Параметры генерации​

Рекомендации Ternary Bonsai:

ПараметрЗначение
Temperature0.7
Top P0.95
Top K20

Libre WebUI передаёт Temperature и Top P через плагин. Для рекомендуемого Top K запускайте с --top-k 20:

mlx_lm.server \
  --model "prism-ml/Ternary-Bonsai-27B-mlx-2bit" \
  --host 127.0.0.1 \
  --port 8081 \
  --top-k 20 \
  --max-tokens 262144

Work и вызовы инструментов​

Плагин MLX может появиться в Work благодаря формату OpenAI. Выбирайте его лишь тогда, когда модель и шаблон надёжно поддерживают вызовы инструментов. Обычная генерация текста в Chat не доказывает поддержку инструментов.

Парсеры и шаблоны быстро меняются. При некорректных вызовах Work обновите mlx-lm, проверьте запрос напрямую и выберите модель, карточка MLX которой явно документирует инструменты.

Сеть Docker​

Рекомендуется нативная разработка Libre WebUI. Контейнер не может достичь 127.0.0.1 Mac.

Если Libre WebUI работает в Docker:

  1. Запустите MLX LM с --host 0.0.0.0.
  2. Используйте приватный LAN-адрес Mac, например http://192.168.1.20:8081/v1/chat/completions.
  3. Разрешите порт 8081 только доверенным локальным сетям.

Не открывайте mlx_lm.server публичному интернету. Сопровождающие описывают его как локальный сервер с базовыми проверками. Для нелокального развёртывания поставьте аутентифицированный HTTPS reverse proxy.

Устранение неполадок​

Model type qwen3_5 not supported

Используется старый запуск:

rehash
which -a mlx_lm.server
uv tool upgrade mlx-lm

Libre WebUI показывает модель, но запросы не работают

Проверьте тот же ID напрямую:

curl http://127.0.0.1:8081/v1/models

Затем убедитесь, что URL содержит /v1/chat/completions.

Адрес занят

Оставьте Libre WebUI на обычном порту, а MLX перенесите:

mlx_lm.server --model "owner/model" --port 8082

Обновите URL до http://127.0.0.1:8082/v1/chat/completions.

Первый запрос медленный

Начальная загрузка и prefill дороже генерации по токенам. Следите за памятью в Activity Monitor и выбирайте меньшую модель или диалог, если macOS начинает swap.

Связанная документация​