Ga naar hoofdinhoud

MLX LM op Apple Silicon

Libre WebUI bevat een plug-in MLX LM (Apple Silicon) waarmee taalmodellen in MLX-indeling rechtstreeks op een Mac uit de M-serie kunnen worden uitgevoerd. De plug-in maakt verbinding met de OpenAI-compatibele HTTP-API die in MLX LM is ingebouwd.

Dit pad is nuttig wanneer u rechtstreekse Metal-inferentie wilt zonder een MLX-controlepunt naar een Ollama- of GGUF-model te converteren.

Architectuur​

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

Poort 8081 is bewust gekozen. MLX LM gebruikt normaal standaard 8080, wat conflicteert met de verpakte server npx libre-webui.

Vereisten​

  • Een Mac met Apple Silicon (M1 of nieuwer).
  • macOS waarop de Xcode-opdrachtregeltools beschikbaar zijn.
  • Python 3.10 of nieuwer.
  • Voldoende uniform geheugen voor het gekozen model, de KV-cache en macOS.
  • Libre WebUI dat rechtstreeks op de host draait. De ontwikkelworkflow vanuit de broncode is het eenvoudigst, omdat beide backends de loopbackinterface van de Mac kunnen gebruiken.

Het standaardmodel Ternary Bonsai neemt ongeveer 8,5 GB schijfruimte in en heeft tijdens het uitvoeren meer geheugen nodig. Een Mac met 16 GB uniform geheugen kan kortere contexten aan, maar 24 GB of meer biedt in de praktijk extra speelruimte. Gebruik een kleiner MLX-controlepunt en voeg de repository-ID toe aan een gekopieerde plug-indefinitie als het geheugen krap is.

MLX LM installeren​

Met uv blijft de opdracht geïsoleerd van Homebrew Python-pakketten:

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

Als de tool al bestaat:

uv tool upgrade mlx-lm
rehash

Qwen 3.5-modellen vereisen mlx-lm 0.30.7 of nieuwer. Het voorbeeld in de repository vereist 0.31.3 of nieuwer.

De server starten​

Voor het Ternary Bonsai-model:

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"

Bij de eerste uitvoering wordt het model van Hugging Face gedownload. Latere uitvoeringen gebruiken de lokale cache. Ternary Bonsai declareert maximaal 262144 posities. De prompt en gegenereerde uitvoer delen dat contextvenster. Een lange prompt vermindert dus het aantal tokens dat kan worden gegenereerd, ook al is de serverlimiet ingesteld op het maximum van het model.

Voor een kleiner instapmodel:

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

De repository bevat ook een herbruikbaar startprogramma:

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

Bekijk de herleide opdracht zonder een model te laden:

uv run server.py --dry-run

De OpenAI-compatibele API controleren​

Controleer de status en modeldetectie:

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

Verstuur een niet-streamende chataanvraag:

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

De server ondersteunt ook streamende Server-Sent Events wanneer "stream": true.

Libre WebUI verbinden​

Vanuit de hoofdmap van de Libre WebUI-repository:

npm install
npm run dev

Open http://localhost:5173 en doe vervolgens het volgende:

  1. Open Settings > Plugins.
  2. Zoek MLX LM (Apple Silicon).
  3. Controleer of het eindpunt http://127.0.0.1:8081/v1/chat/completions is.
  4. Activeer de plug-in. Lokale MLX vereist geen API-sleutel.
  5. Ga terug naar Chat en selecteer het MLX-model.

De ingebouwde modellenlijst bevat:

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

Het in Libre WebUI geselecteerde model moet overeenkomen met een model dat beschikbaar is op de MLX-server. Als u een ander controlepunt wilt gebruiken, exporteert of kopieert u plugins/mlx-lm.json, voegt u de repository-ID toe aan model_map en importeert u de bewerkte definitie via Settings > Plugins.

Generatie-instellingen​

De gepubliceerde aanbevelingen voor Ternary Bonsai zijn:

InstellingWaarde
Temperature0.7
Top P0.95
Top K20

Libre WebUI stuurt de temperatuur en Top P via de plug-in door. Start de server met --top-k 20 als u de aanbeveling voor Top K wilt gebruiken:

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 en tooloproepen​

De MLX-plug-in kan in Work verschijnen omdat hij de OpenAI-compatibele chatindeling gebruikt. Kies hem alleen voor Work wanneer het model en de chatsjabloon betrouwbare OpenAI-achtige tooloproepen ondersteunen. Gewone tekstgeneratie die in Chat werkt, bewijst niet dat een controlepunt tools ondersteunt.

Toolparsers en modelsjablonen veranderen snel. Als een Work-uitvoering misvormde tooloproepen retourneert, werkt u mlx-lm bij, test u dezelfde toolaanvraag rechtstreeks tegen de server en probeert u een model waarvan de MLX-kaart het gebruik van tools expliciet documenteert.

Docker-netwerken​

Het wordt aanbevolen om Libre WebUI rechtstreeks op de host te ontwikkelen. Een container kan 127.0.0.1 van de Mac niet bereiken.

Als Libre WebUI in Docker draait:

  1. Start MLX LM met --host 0.0.0.0.
  2. Gebruik een privé-LAN-adres van de Mac, zoals http://192.168.1.20:8081/v1/chat/completions, als plug-ineindpunt.
  3. Sta poort 8081 alleen toe op vertrouwde lokale netwerken.

Stel mlx_lm.server niet rechtstreeks bloot aan het openbare internet. De beheerders beschrijven hem als een lokale server met alleen eenvoudige beveiligingscontroles. Plaats voor elke niet-lokale implementatie een geauthenticeerde HTTPS-reverse-proxy vóór de server.

Problemen oplossen​

Model type qwen3_5 not supported

Er wordt nog een ouder startprogramma gebruikt:

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

Libre WebUI toont het model, maar aanvragen mislukken

Controleer rechtstreeks of dezelfde model-ID werkt:

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

Controleer daarna of het plug-ineindpunt /v1/chat/completions bevat.

Adres is al in gebruik

Houd Libre WebUI op de normale poort en verplaats MLX:

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

Werk het plug-ineindpunt bij naar http://127.0.0.1:8082/v1/chat/completions.

Het model is traag bij de eerste aanvraag

Het eerste laden en vooraf verwerken van de prompt zijn duurder dan het token voor token genereren. Houd de geheugendruk in Activity Monitor in de gaten en kies een kleiner model of korter gesprek als macOS begint te swappen.

Gerelateerde documentatie​