Перейти до основного вмісту

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 або новіший.
  • Достатньо спільної пам’яті для моделі, кешу KV і macOS.
  • Libre WebUI, що працює безпосередньо. Розробка з вихідного коду найпростіша, оскільки обидві серверні частини використовують loopback Mac.

Модель Ternary Bonsai типово займає близько 8,5 ГБ на диску й більше під час роботи. Mac із 16 ГБ спільної пам’яті впорається з коротким контекстом, але 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.

Усунення неполадок​

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

Потім переконайтеся, що адреса містить /v1/chat/completions.

Адреса зайнята

Залиште Libre WebUI на звичайному порту, а MLX перенесіть:

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

Оновіть адресу до http://127.0.0.1:8082/v1/chat/completions.

Перший запит повільний

Початкове завантаження й попереднє опрацювання підказки дорожчі за генерування токенів. Стежте за пам’яттю в Activity Monitor і вибирайте меншу модель або діалог, якщо macOS починає використовувати файл підкачки.

Пов’язана документація​