Passa al contenuto principale

MLX LM su Apple Silicon

Libre WebUI include un plugin MLX LM (Apple Silicon) per eseguire modelli linguistici in formato MLX direttamente su un Mac serie M. Il plugin si collega all'API HTTP compatibile con OpenAI integrata in MLX LM.

Questo percorso è utile per ottenere un'inferenza Metal nativa senza convertire un checkpoint MLX in un modello Ollama o GGUF.

Architettura​

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

La porta 8081 è intenzionale. MLX LM usa normalmente 8080 per impostazione predefinita, ma questa porta è in conflitto con il server incluso npx libre-webui.

Requisiti​

  • Un Mac Apple Silicon (M1 o successivo).
  • macOS con gli strumenti da riga di comando di Xcode disponibili.
  • Python 3.10 o successivo.
  • Memoria unificata sufficiente per il modello selezionato, la relativa cache KV e macOS.
  • Libre WebUI in esecuzione nativa. Il flusso di sviluppo dal codice sorgente è la configurazione più semplice, perché entrambi i backend possono usare l'interfaccia di loopback del Mac.

Il modello Ternary Bonsai predefinito occupa circa 8,5 GB su disco e richiede più memoria durante l'esecuzione. Un Mac con 16 GB di memoria unificata può gestire contesti più brevi, ma 24 GB o più offrono un margine pratico maggiore. Se la memoria è scarsa, usa un checkpoint MLX più piccolo e aggiungi il relativo ID repository a una copia della definizione del plugin.

Installare MLX LM​

L'uso di uv mantiene il comando isolato dai pacchetti Python di Homebrew:

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

Se lo strumento esiste già:

uv tool upgrade mlx-lm
rehash

I modelli Qwen 3.5 richiedono mlx-lm 0.30.7 o successivo. L'esempio del repository richiede la versione 0.31.3 o successiva.

Avviare il server​

Per il modello 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"

La prima esecuzione scarica il modello da Hugging Face. Le successive usano la cache locale. Ternary Bonsai dichiara 262144 posizioni massime. Il prompt e l'output generato condividono la stessa finestra di contesto, quindi un prompt lungo riduce il numero di token generabili, anche se il limite del server è impostato sul massimo del modello.

Per un modello iniziale più piccolo:

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

Il repository contiene anche un programma di avvio riutilizzabile:

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

Esamina il comando risolto senza caricare un modello:

uv run server.py --dry-run

Verificare l'API compatibile con OpenAI​

Controlla lo stato e il rilevamento dei modelli:

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

Invia una richiesta di chat senza streaming:

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

Il server supporta anche lo streaming con Server-Sent Events quando "stream": true.

Collegare Libre WebUI​

Dalla radice del repository Libre WebUI:

npm install
npm run dev

Apri http://localhost:5173, quindi:

  1. Apri Impostazioni > Plugin.
  2. Trova MLX LM (Apple Silicon).
  3. Verifica che l'endpoint sia http://127.0.0.1:8081/v1/chat/completions.
  4. Attiva il plugin. MLX locale non richiede una chiave API.
  5. Torna alla Chat e seleziona il modello MLX.

L'elenco di modelli integrato include:

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

Il modello selezionato in Libre WebUI deve corrispondere a un modello disponibile nel server MLX. Per usare un altro checkpoint, esporta o copia plugins/mlx-lm.json, aggiungi l'ID repository a model_map e importa la definizione modificata da Impostazioni > Plugin.

Impostazioni di generazione​

Le raccomandazioni pubblicate per Ternary Bonsai sono:

ImpostazioneValore
Temperatura0.7
Top P0.95
Top K20

Libre WebUI invia temperatura e Top P attraverso il plugin. Avvia il server con --top-k 20 per applicare il valore Top K consigliato:

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 e chiamate agli strumenti​

Il plugin MLX può comparire in Work perché usa il formato di chat compatibile con OpenAI. Sceglilo per Work solo quando il modello e il relativo modello di chat supportano in modo affidabile le chiamate agli strumenti in stile OpenAI. Il corretto funzionamento della normale generazione di testo in Chat non dimostra che un checkpoint supporti gli strumenti.

I parser degli strumenti e i modelli cambiano rapidamente. Se un'esecuzione Work restituisce chiamate agli strumenti non corrette, aggiorna mlx-lm, prova la stessa richiesta di strumenti direttamente sul server e scegli un modello la cui scheda MLX documenti esplicitamente l'uso degli strumenti.

Rete Docker​

È consigliato lo sviluppo nativo di Libre WebUI. Un container non può raggiungere 127.0.0.1 del Mac.

Se Libre WebUI viene eseguito in Docker:

  1. Avvia MLX LM con --host 0.0.0.0.
  2. Usa un indirizzo LAN privato del Mac, ad esempio http://192.168.1.20:8081/v1/chat/completions, come endpoint del plugin.
  3. Consenti la porta 8081 solo sulle reti locali attendibili.

Non esporre mlx_lm.server direttamente alla rete Internet pubblica. I suoi manutentori lo descrivono come un server locale con soli controlli di sicurezza di base. Per qualsiasi distribuzione non locale, colloca davanti al server un proxy inverso HTTPS con autenticazione.

Risoluzione dei problemi​

Model type qwen3_5 not supported

È ancora in uso un programma di avvio precedente:

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

Libre WebUI mostra il modello, ma le richieste non riescono

Verifica direttamente che lo stesso ID modello funzioni:

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

Quindi verifica che l'endpoint del plugin includa /v1/chat/completions.

Indirizzo già in uso

Mantieni Libre WebUI sulla sua porta normale e sposta MLX:

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

Aggiorna l'endpoint del plugin in http://127.0.0.1:8082/v1/chat/completions.

Il modello è lento alla prima richiesta

Il caricamento iniziale e il riempimento preliminare del prompt richiedono più risorse della generazione token per token. Controlla la pressione sulla memoria in Monitoraggio Attività e scegli un modello più piccolo o una conversazione più breve se macOS inizia a usare lo spazio di swap.

Documenti correlati​