Saltar al contenido principal

MLX LM en Apple Silicon

Libre WebUI incluye un plugin MLX LM (Apple Silicon) para ejecutar modelos de lenguaje con formato MLX directamente en un Mac de la serie M. Se conecta a la API HTTP compatible con OpenAI integrada en MLX LM.

Este camino resulta útil para obtener inferencia Metal nativa sin convertir un checkpoint MLX a Ollama o GGUF.

Arquitectura​

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

El puerto 8081 es intencionado. MLX LM usa normalmente 8080, que entra en conflicto con npx libre-webui.

Requisitos​

  • Mac con Apple Silicon (M1 o posterior).
  • macOS con herramientas de línea de comandos de Xcode.
  • Python 3.10 o posterior.
  • Memoria unificada suficiente para el modelo, su caché KV y macOS.
  • Libre WebUI ejecutándose de forma nativa; el flujo desde código es el más sencillo porque ambos backends usan loopback.

El modelo Ternary Bonsai predeterminado ocupa unos 8.5 GB en disco y necesita más al ejecutarse. Un Mac de 16 GB puede manejar contextos cortos, pero 24 GB o más ofrecen margen. Si falta memoria, usa un checkpoint MLX menor y añade su ID a una copia de la definición del plugin.

Instalar MLX LM​

uv mantiene el comando aislado de los paquetes Python de Homebrew:

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

Si ya existe:

uv tool upgrade mlx-lm
rehash

Los modelos Qwen 3.5 requieren mlx-lm 0.30.7 o posterior; el ejemplo del repositorio requiere 0.31.3 o posterior.

Iniciar el servidor​

Para 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 primera ejecución descarga el modelo de Hugging Face; las posteriores usan la caché. Ternary Bonsai declara 262144 posiciones máximas. El prompt y la salida comparten la ventana, por lo que un prompt largo reduce los tokens generables aunque el servidor use el máximo del modelo.

Para empezar con algo menor:

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

El repositorio incluye un lanzador reutilizable:

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

Inspecciona el comando sin cargar un modelo:

uv run server.py --dry-run

Verificar la API compatible con OpenAI​

Comprueba salud y modelos:

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

Envía un chat sin 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
  }'

También admite Server-Sent Events cuando "stream": true.

Conectar Libre WebUI​

Desde la raíz:

npm install
npm run dev

Abre http://localhost:5173 y:

  1. Ve a Ajustes > Plugins.
  2. Busca MLX LM (Apple Silicon).
  3. Confirma http://127.0.0.1:8081/v1/chat/completions.
  4. Activa el plugin; no necesita clave API.
  5. Vuelve al chat y selecciona el modelo MLX.

La lista integrada incluye:

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

El modelo seleccionado debe estar disponible en el servidor. Para otro checkpoint, exporta o copia plugins/mlx-lm.json, añade el ID a model_map e importa la definición desde Ajustes > Plugins.

Ajustes de generación​

Recomendaciones publicadas:

AjusteValor
Temperatura0.7
Top P0.95
Top K20

Libre WebUI envía temperatura y Top P. Inicia el servidor con --top-k 20 para aplicar 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 y llamadas a herramientas​

El plugin puede aparecer en Work por usar el formato de chat de OpenAI. Elígelo solo si el modelo y su plantilla admiten llamadas a herramientas de forma fiable. Que el texto funcione en Chat no demuestra compatibilidad.

Los analizadores cambian rápidamente. Si una ejecución devuelve llamadas malformadas, actualiza mlx-lm, prueba la solicitud directamente y usa un modelo cuya ficha documente herramientas.

Redes con Docker​

Se recomienda ejecutar Libre WebUI nativamente: un contenedor no alcanza 127.0.0.1 del Mac.

Si se ejecuta en Docker:

  1. Inicia MLX LM con --host 0.0.0.0.
  2. Usa una IP LAN privada como http://192.168.1.20:8081/v1/chat/completions.
  3. Permite 8081 solo en redes fiables.

No expongas mlx_lm.server a Internet. Sus responsables lo describen como servidor local con controles básicos; usa un proxy HTTPS autenticado para cualquier despliegue no local.

Solución de problemas​

Model type qwen3_5 not supported

Se sigue usando un lanzador antiguo:

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

Libre WebUI muestra el modelo, pero fallan las solicitudes

Verifica el ID directamente:

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

Confirma también que el endpoint incluya /v1/chat/completions.

Dirección en uso

Mueve MLX a otro puerto:

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

Actualiza a http://127.0.0.1:8082/v1/chat/completions.

El primer pedido es lento

La carga y el prefill inicial cuestan más que la generación. Vigila la presión de memoria y usa un modelo o chat menor si macOS empieza a intercambiar.

Documentación relacionada​