Przejdź do głównej zawartości

MLX LM na Apple Silicon

Libre WebUI zawiera wtyczkę MLX LM (Apple Silicon) do uruchamiania modeli językowych w formacie MLX bezpośrednio na komputerze Mac z serii M. Wtyczka łączy się z API HTTP zgodnym z OpenAI, wbudowanym w MLX LM.

Ta ścieżka jest przydatna, gdy chcesz korzystać z natywnego wnioskowania Metal bez konwertowania punktu kontrolnego MLX do modelu Ollama lub GGUF.

Architektura​

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

Port 8081 jest celowy. MLX LM domyślnie używa zwykle 8080, co koliduje ze spakowanym serwerem npx libre-webui.

Wymagania​

  • Komputer Mac z Apple Silicon (M1 lub nowszy).
  • macOS z dostępnymi narzędziami wiersza poleceń Xcode.
  • Python 3.10 lub nowszy.
  • Wystarczająco dużo pamięci zunifikowanej dla wybranego modelu, jego pamięci podręcznej KV i macOS.
  • Libre WebUI działające natywnie. Najprostszy jest przepływ deweloperski ze źródeł, ponieważ oba backendy mogą używać interfejsu loopback komputera Mac.

Domyślny model Ternary Bonsai zajmuje około 8,5 GB na dysku i potrzebuje więcej pamięci podczas działania. Mac z 16 GB pamięci zunifikowanej obsłuży krótsze konteksty, ale 24 GB lub więcej zapewnia praktyczny zapas. Jeśli pamięci jest mało, użyj mniejszego punktu kontrolnego MLX i dodaj jego identyfikator repozytorium do kopii definicji wtyczki.

Instalowanie MLX LM​

uv izoluje polecenie od pakietów Python z Homebrew:

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

Jeśli narzędzie już istnieje:

uv tool upgrade mlx-lm
rehash

Modele Qwen 3.5 wymagają mlx-lm 0.30.7 lub nowszego. Przykład z repozytorium wymaga 0.31.3 lub nowszego.

Uruchamianie serwera​

Dla modelu 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"

Pierwsze uruchomienie pobiera model z Hugging Face. Kolejne używają lokalnej pamięci podręcznej. Ternary Bonsai deklaruje maksymalnie 262144 pozycji. Prompt i wygenerowany wynik dzielą okno kontekstu, dlatego długi prompt zmniejsza liczbę tokenów możliwych do wygenerowania, mimo że limit serwera jest ustawiony na maksimum modelu.

Dla mniejszego modelu początkowego:

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

Repozytorium zawiera też program uruchamiający wielokrotnego użytku:

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

Sprawdź rozwiązane polecenie bez ładowania modelu:

uv run server.py --dry-run

Sprawdzanie API zgodnego z OpenAI​

Sprawdź stan i wykrywanie modeli:

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

Wyślij niestrumieniowe żądanie czatu:

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

Serwer obsługuje też strumieniowe Server-Sent Events, gdy "stream": true.

Łączenie Libre WebUI​

Z katalogu głównego repozytorium Libre WebUI:

npm install
npm run dev

Otwórz http://localhost:5173, a następnie:

  1. Otwórz Settings > Plugins.
  2. Znajdź MLX LM (Apple Silicon).
  3. Potwierdź, że punkt końcowy to http://127.0.0.1:8081/v1/chat/completions.
  4. Aktywuj wtyczkę. Lokalny MLX nie wymaga klucza API.
  5. Wróć do Chat i wybierz model MLX.

Wbudowana lista modeli zawiera:

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

Model wybrany w Libre WebUI musi odpowiadać modelowi dostępnemu na serwerze MLX. Aby użyć innego punktu kontrolnego, wyeksportuj lub skopiuj plugins/mlx-lm.json, dodaj identyfikator repozytorium do model_map i zaimportuj zmienioną definicję w Settings > Plugins.

Ustawienia generowania​

Opublikowane zalecenia Ternary Bonsai:

UstawienieWartość
Temperature0.7
Top P0.95
Top K20

Libre WebUI przekazuje temperaturę i Top P przez wtyczkę. Jeśli chcesz użyć zalecenia Top K, uruchom serwer z --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 i wywołania narzędzi​

Wtyczka MLX może pojawić się w Work, ponieważ używa formatu czatu zgodnego z OpenAI. Wybieraj ją dla Work tylko wtedy, gdy model i jego szablon czatu niezawodnie obsługują wywołania narzędzi w stylu OpenAI. Zwykłe generowanie tekstu działające w Chat nie dowodzi, że punkt kontrolny obsługuje narzędzia.

Parsery narzędzi i szablony modeli szybko się zmieniają. Jeśli wykonanie Work zwraca nieprawidłowe wywołania, zaktualizuj mlx-lm, przetestuj to samo żądanie bezpośrednio na serwerze i wypróbuj model, którego karta MLX jawnie dokumentuje użycie narzędzi.

Sieć Docker​

Zalecane jest natywne uruchamianie Libre WebUI do prac deweloperskich. Kontener nie może połączyć się z 127.0.0.1 komputera Mac.

Jeśli Libre WebUI działa w Dockerze:

  1. Uruchom MLX LM z --host 0.0.0.0.
  2. Ustaw jako punkt końcowy wtyczki prywatny adres LAN komputera Mac, na przykład http://192.168.1.20:8081/v1/chat/completions.
  3. Zezwól na port 8081 wyłącznie w zaufanych sieciach lokalnych.

Nie wystawiaj mlx_lm.server bezpośrednio do publicznego internetu. Jego opiekunowie opisują go jako serwer lokalny z jedynie podstawowymi kontrolami bezpieczeństwa. Dla każdego wdrożenia nielokalnego umieść przed nim uwierzytelnione reverse proxy HTTPS.

Rozwiązywanie problemów​

Model type qwen3_5 not supported

Nadal używany jest starszy program uruchamiający:

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

Libre WebUI pokazuje model, ale żądania kończą się błędem

Sprawdź bezpośrednio, czy działa ten sam identyfikator modelu:

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

Następnie potwierdź, że punkt końcowy wtyczki zawiera /v1/chat/completions.

Adres jest już używany

Pozostaw Libre WebUI na zwykłym porcie i przenieś MLX:

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

Zaktualizuj punkt końcowy wtyczki na http://127.0.0.1:8082/v1/chat/completions.

Model jest wolny przy pierwszym żądaniu

Pierwsze ładowanie i wstępne przetwarzanie promptu są kosztowniejsze niż generowanie token po tokenie. Obserwuj presję pamięci w Activity Monitor i wybierz mniejszy model lub krótszą rozmowę, jeśli macOS zaczyna używać pamięci wymiany.

Powiązana dokumentacja​