在 Apple Silicon 上使用 MLX LM

Libre WebUI 内置 MLX LM (Apple Silicon) 插件，可直接在 M 系列 Mac 上运行 MLX 格式的语言模型。该插件连接到 MLX LM 内置的 OpenAI 兼容 HTTP API。

如果希望使用原生 Metal 推理，又不想将 MLX 检查点转换成 Ollama 或 GGUF 模型，这条路径很合适。

架构

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

端口 8081 是有意选择的。MLX LM 通常默认使用 8080，这会与打包的 npx libre-webui 服务器冲突。

要求

Apple Silicon Mac（M1 或更新型号）。
已提供 Xcode 命令行工具的 macOS。
Python 3.10 或更新版本。
足够容纳所选模型、其 KV 缓存和 macOS 的统一内存。
以原生方式运行 Libre WebUI。源代码开发工作流是最简单的设置方式，因为两个后端都能使用 Mac 环回接口。

默认 Ternary Bonsai 模型在磁盘上约占 8.5 GB，运行时需要更多内存。配备 16 GB 统一内存的 Mac 可处理较短上下文，但 24 GB 或更多会留下更实用的余量。如果内存紧张，请使用更小的 MLX 检查点，并将其仓库 ID 添加到复制出的插件定义中。

安装 MLX LM

使用 uv 可将命令与 Homebrew Python 软件包隔离：

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

如果工具已存在：

uv tool upgrade mlx-lm
rehash

Qwen 3.5 模型需要 mlx-lm 0.30.7 或更新版本。仓库示例需要 0.31.3 或更新版本。

启动服务器

对于 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"

首次运行会从 Hugging Face 下载模型，后续运行使用本地缓存。Ternary Bonsai 声明的最大位置数为 262144。提示词和生成输出共享该上下文窗口，因此长提示词会减少可生成的令牌数量，即便服务器限额设置为模型最大值也是如此。

较小的入门模型：

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

仓库还包含可复用的启动器：

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

不加载模型，检查解析后的命令：

uv run server.py --dry-run

验证 OpenAI 兼容 API

检查健康状态和模型发现：

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

发送非流式聊天请求：

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

当 "stream": true 时，服务器也支持流式 Server-Sent Events。

连接 Libre WebUI

从 Libre WebUI 仓库根目录运行：

npm install
npm run dev

打开 http://localhost:5173，然后：

打开设置 > 插件。
找到 MLX LM (Apple Silicon)。
确认端点为 http://127.0.0.1:8081/v1/chat/completions。
激活插件。本地 MLX 不需要 API 密钥。
返回聊天并选择 MLX 模型。

内置模型列表包括：

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

Libre WebUI 中选择的模型必须与 MLX 服务器可用的模型匹配。若要使用其他检查点，请导出或复制 plugins/mlx-lm.json，把仓库 ID 添加到 model_map，再从设置 > 插件导入编辑后的定义。

生成设置

Ternary Bonsai 发布的建议设置为：

设置	值
温度	`0.7`
Top P	`0.95`
Top K	`20`

Libre WebUI 会通过插件发送温度和 Top P。若要采用其 Top K 建议，请用 --top-k 20 启动服务器：

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 与工具调用

MLX 插件采用 OpenAI 兼容聊天格式，因此可出现在 Work 中。只有模型及其聊天模板能可靠支持 OpenAI 风格的工具调用时，才应在 Work 中选择它。普通文本生成能在聊天中工作，并不能证明某个检查点支持工具。

工具解析器和模型模板变化很快。如果 Work 运行返回格式错误的工具调用，请更新 mlx-lm，直接针对服务器测试同一工具请求，并尝试其 MLX 模型卡明确说明支持工具的模型。

Docker 网络

建议以原生方式开发 Libre WebUI。容器无法访问 Mac 的 127.0.0.1。

如果 Libre WebUI 在 Docker 中运行：

使用 --host 0.0.0.0 启动 MLX LM。
使用 Mac 的私有局域网地址作为插件端点，例如 http://192.168.1.20:8081/v1/chat/completions。
只在受信任的本地网络上允许端口 8081。

不要将 mlx_lm.server 直接暴露到公网。其维护者将它描述为仅具备基础安全检查的本地服务器。任何非本地部署都应在它前面放置经过身份验证的 HTTPS 反向代理。

故障排查

Model type qwen3_5 not supported

仍在使用旧启动器：

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

Libre WebUI 显示模型，但请求失败

验证同一模型 ID 能否直接工作：

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

然后确认插件端点包含 /v1/chat/completions。

地址已被占用

Libre WebUI 保持使用常规端口，将 MLX 移到另一端口：

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

将插件端点更新为 http://127.0.0.1:8082/v1/chat/completions。

模型首次请求速度较慢

初始加载和提示词预填充的开销高于逐令牌生成。如果 macOS 开始使用交换空间，请在活动监视器中观察内存压力，并选择更小的模型或更短的对话。

架构​

要求​

安装 MLX LM​

启动服务器​

验证 OpenAI 兼容 API​

连接 Libre WebUI​

生成设置​

Work 与工具调用​

Docker 网络​

故障排查​

相关文档​

架构

要求