Pular para o conteúdo principal

MLX LM no Apple Silicon

O Libre WebUI inclui um plugin MLX LM (Apple Silicon) para executar modelos de linguagem no formato MLX diretamente em um Mac da série M. O plugin se conecta à API HTTP compatível com OpenAI integrada ao MLX LM.

Esse caminho é útil quando você deseja inferência nativa com Metal sem converter um checkpoint MLX em um modelo do Ollama ou GGUF.

Arquitetura​

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

A porta 8081 é intencional. Por padrão, o MLX LM usa 8080, que entra em conflito com o servidor distribuído npx libre-webui.

Requisitos​

  • Um Mac Apple Silicon (M1 ou mais recente).
  • macOS com as ferramentas de linha de comando do Xcode disponíveis.
  • Python 3.10 ou mais recente.
  • Memória unificada suficiente para o modelo selecionado, seu cache KV e o macOS.
  • Libre WebUI em execução nativa. O fluxo de desenvolvimento a partir do código-fonte é a configuração mais simples, pois ambos os backends podem usar a interface de loopback do Mac.

O modelo Ternary Bonsai padrão ocupa cerca de 8,5 GB em disco e precisa de mais memória durante a execução. Um Mac com 16 GB de memória unificada consegue lidar com contextos menores, mas 24 GB ou mais oferecem uma margem prática maior. Use um checkpoint MLX menor e adicione o ID de seu repositório a uma cópia da definição do plugin se houver pouca memória.

Instale o MLX LM​

O uso de uv mantém o comando isolado dos pacotes Python do Homebrew:

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

Se a ferramenta já existir:

uv tool upgrade mlx-lm
rehash

Os modelos Qwen 3.5 exigem mlx-lm 0.30.7 ou mais recente. O exemplo do repositório exige 0.31.3 ou mais recente.

Inicie o servidor​

Para o modelo 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"

A primeira execução baixa o modelo do Hugging Face. As posteriores usam o cache local. O Ternary Bonsai declara 262144 posições máximas. O prompt e a saída gerada compartilham essa janela de contexto; portanto, um prompt longo reduz o número de tokens que podem ser gerados, mesmo que a cota do servidor esteja definida para o máximo do modelo.

Para um modelo inicial menor:

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

O repositório também contém um inicializador reutilizável:

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

Examine o comando resolvido sem carregar um modelo:

uv run server.py --dry-run

Verifique a API compatível com OpenAI​

Verifique a integridade e a descoberta de modelos:

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

Envie uma solicitação de chat sem 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
  }'

O servidor também oferece streaming por Server-Sent Events quando "stream": true.

Conecte o Libre WebUI​

A partir da raiz do repositório do Libre WebUI:

npm install
npm run dev

Abra http://localhost:5173 e, em seguida:

  1. Abra Configurações > Plugins.
  2. Encontre MLX LM (Apple Silicon).
  3. Confirme se o endpoint é http://127.0.0.1:8081/v1/chat/completions.
  4. Ative o plugin. O MLX local não exige uma chave de API.
  5. Volte ao Chat e selecione o modelo MLX.

A lista integrada de modelos inclui:

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

O modelo selecionado no Libre WebUI deve corresponder a um modelo disponível no servidor MLX. Para usar outro checkpoint, exporte ou copie plugins/mlx-lm.json, adicione o ID do repositório a model_map e importe a definição editada em Configurações > Plugins.

Configurações de geração​

As recomendações publicadas do Ternary Bonsai são:

ConfiguraçãoValor
Temperatura0.7
Top P0.95
Top K20

O Libre WebUI envia a temperatura e o Top P pelo plugin. Inicie o servidor com --top-k 20 para usar a recomendação de 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 e chamadas de ferramentas​

O plugin MLX pode aparecer no Work porque usa o formato de chat compatível com OpenAI. Escolha-o para o Work somente quando o modelo e seu template de chat oferecerem suporte confiável a chamadas de ferramentas no estilo da OpenAI. A geração comum de texto funcionar no Chat não comprova que um checkpoint oferece suporte a ferramentas.

Os analisadores de ferramentas e os templates de modelos mudam rapidamente. Se uma execução do Work retornar chamadas de ferramentas malformadas, atualize o mlx-lm, teste a mesma solicitação de ferramenta diretamente no servidor e experimente um modelo cujo cartão MLX documente explicitamente o uso de ferramentas.

Rede no Docker​

Recomenda-se o desenvolvimento nativo do Libre WebUI. Um contêiner não consegue acessar o 127.0.0.1 do Mac.

Se o Libre WebUI for executado no Docker:

  1. Inicie o MLX LM com --host 0.0.0.0.
  2. Use um endereço privado da LAN do Mac, como http://192.168.1.20:8081/v1/chat/completions, como endpoint do plugin.
  3. Permita a porta 8081 somente em redes locais confiáveis.

Não exponha o mlx_lm.server diretamente à Internet pública. Seus mantenedores o descrevem como um servidor local com apenas verificações básicas de segurança. Coloque um proxy reverso HTTPS autenticado à frente dele em qualquer implantação não local.

Solução de problemas​

Model type qwen3_5 not supported

Um inicializador antigo ainda está sendo usado:

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

O Libre WebUI mostra o modelo, mas as solicitações falham

Verifique se o mesmo ID de modelo funciona diretamente:

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

Depois, confirme se o endpoint do plugin inclui /v1/chat/completions.

O endereço já está em uso

Mantenha o Libre WebUI em sua porta normal e altere a porta do MLX:

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

Atualize o endpoint do plugin para http://127.0.0.1:8082/v1/chat/completions.

O modelo fica lento na primeira solicitação

O carregamento inicial e o preenchimento prévio do prompt exigem mais recursos do que a geração token por token. Observe a pressão de memória no Monitor de Atividade e escolha um modelo menor ou uma conversa mais curta se o macOS começar a usar swap.

Documentação relacionada​