Aller au contenu principal

MLX LM sur Apple Silicon

Libre WebUI comprend une extension MLX LM (Apple Silicon) permettant d'exécuter des modèles de langage au format MLX directement sur un Mac de série M. L'extension se connecte à l'API HTTP compatible OpenAI intégrée à MLX LM.

Cette méthode est utile pour bénéficier d'une inférence Metal native sans convertir un point de contrôle MLX en modèle Ollama ou GGUF.

Architecture​

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

Le port 8081 est choisi délibérément. MLX LM utilise normalement 8080 par défaut, ce qui entre en conflit avec le serveur fourni par npx libre-webui.

Prérequis​

  • Un Mac Apple Silicon (M1 ou plus récent).
  • macOS avec les outils en ligne de commande Xcode disponibles.
  • Python 3.10 ou version ultérieure.
  • Une mémoire unifiée suffisante pour le modèle choisi, son cache KV et macOS.
  • Libre WebUI exécuté nativement. La méthode de développement depuis les sources est la configuration la plus simple, car les deux serveurs peuvent utiliser l'interface de bouclage du Mac.

Le modèle Ternary Bonsai par défaut occupe environ 8.5 GB sur le disque et demande davantage de mémoire à l'exécution. Un Mac doté de 16 GB de mémoire unifiée peut gérer des contextes plus courts, mais 24 GB ou plus offrent une marge plus confortable. Utilisez un point de contrôle MLX plus petit et ajoutez l'identifiant de son dépôt à une copie de la définition de l'extension si la mémoire est limitée.

Installer MLX LM​

L'utilisation d'uv maintient la commande isolée des paquets Python de Homebrew :

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

Si l'outil existe déjà :

uv tool upgrade mlx-lm
rehash

Les modèles Qwen 3.5 nécessitent mlx-lm 0.30.7 ou version ultérieure. L'exemple du dépôt nécessite la version 0.31.3 ou ultérieure.

Démarrer le serveur​

Pour le modèle 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 première exécution télécharge le modèle depuis Hugging Face. Les suivantes utilisent le cache local. Ternary Bonsai déclare 262144 positions maximales. La requête et la sortie générée se partagent cette fenêtre de contexte ; une longue requête réduit donc le nombre de jetons pouvant être générés, même si la limite du serveur est fixée au maximum du modèle.

Pour un modèle de démarrage plus petit :

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

Le dépôt contient aussi un lanceur réutilisable :

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

Inspectez la commande résolue sans charger de modèle :

uv run server.py --dry-run

Vérifier l'API compatible OpenAI​

Vérifiez l'état et la découverte des modèles :

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

Envoyez une requête de chat sans diffusion progressive :

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

Le serveur prend également en charge les Server-Sent Events diffusés lorsque "stream": true.

Connecter Libre WebUI​

Depuis la racine du dépôt Libre WebUI :

npm install
npm run dev

Ouvrez http://localhost:5173, puis :

  1. Ouvrez Paramètres > Extensions.
  2. Recherchez MLX LM (Apple Silicon).
  3. Vérifiez que le point de terminaison est http://127.0.0.1:8081/v1/chat/completions.
  4. Activez l'extension. Une instance MLX locale ne nécessite pas de clé API.
  5. Revenez au chat et sélectionnez le modèle MLX.

La liste de modèles intégrée comprend :

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

Le modèle sélectionné dans Libre WebUI doit correspondre à un modèle disponible sur le serveur MLX. Pour utiliser un autre point de contrôle, exportez ou copiez plugins/mlx-lm.json, ajoutez l'identifiant du dépôt à model_map, puis importez la définition modifiée depuis Paramètres > Extensions.

Paramètres de génération​

Les recommandations publiées pour Ternary Bonsai sont :

ParamètreValeur
Température0.7
Top P0.95
Top K20

Libre WebUI transmet la température et Top P au moyen de l'extension. Démarrez le serveur avec --top-k 20 pour appliquer la recommandation Top K :

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 et appel d'outils​

L'extension MLX peut apparaître dans Work, car elle utilise le format de chat compatible OpenAI. Ne la choisissez pour Work que si le modèle et son modèle de conversation prennent correctement en charge les appels d'outils de type OpenAI. Une génération de texte ordinaire qui fonctionne dans le chat ne prouve pas qu'un point de contrôle prend en charge les outils.

Les analyseurs d'outils et les modèles de conversation évoluent rapidement. Si une exécution Work renvoie des appels d'outils mal formés, mettez mlx-lm à jour, testez la même requête d'outil directement auprès du serveur et essayez un modèle dont la fiche MLX documente explicitement l'utilisation d'outils.

Réseau Docker​

Le développement natif de Libre WebUI est recommandé. Un conteneur ne peut pas accéder à l'adresse 127.0.0.1 du Mac.

Si Libre WebUI s'exécute dans Docker :

  1. Démarrez MLX LM avec --host 0.0.0.0.
  2. Utilisez comme point de terminaison de l'extension une adresse privée du Mac sur le réseau local, par exemple http://192.168.1.20:8081/v1/chat/completions.
  3. N'autorisez le port 8081 que sur les réseaux locaux de confiance.

N'exposez pas directement mlx_lm.server à l'Internet public. Ses responsables le décrivent comme un serveur local qui ne possède que des contrôles de sécurité élémentaires. Placez un proxy inverse HTTPS authentifié devant lui pour tout déploiement non local.

Dépannage​

Model type qwen3_5 not supported

Un ancien lanceur est encore utilisé :

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

Libre WebUI affiche le modèle, mais les requêtes échouent

Vérifiez directement que le même identifiant de modèle fonctionne :

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

Puis confirmez que le point de terminaison de l'extension comprend /v1/chat/completions.

Adresse déjà utilisée

Conservez Libre WebUI sur son port habituel et déplacez MLX :

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

Remplacez le point de terminaison de l'extension par http://127.0.0.1:8082/v1/chat/completions.

Le modèle est lent lors de sa première requête

Le chargement initial et le préremplissage de la requête coûtent davantage que la génération jeton par jeton. Surveillez la pression sur la mémoire dans Moniteur d'activité et choisissez un modèle plus petit ou une conversation plus courte si macOS commence à utiliser l'espace d'échange.

Documentation connexe​