如何在 Mac 上搭建 MLX 服务器

本文介绍如何用 mlx_lm.server 在 Mac 上搭建 MLX 服务器：像调用 OpenAI API 一样调用它，用 launchd 让它持续运行，并从外部安全访问。前提是你已按 MLX LM 教程 安装好 mlx-lm。

mlx_lm.server 提供什么

mlx_lm.server 随 mlx-lm 一起安装。它加载一个模型，并提供与 OpenAI chat API 相似的 HTTP 接口。根据撰写本文时的官方文档和源码：

• 默认地址：127.0.0.1，端口 8080。可用 --host 和 --port 修改。
• 接口：POST /v1/chat/completions、POST /v1/completions、GET /v1/models 和 GET /health。
• 请求字段包括 messages、max_tokens（默认 512）、temperature、top_p、stop、stream 和 logprobs，以及 adapters、draft_model 等 MLX 特有字段。

有两点需要提前考虑。文档指出，该服务器只实现了基本的安全检查，不建议用于生产环境。而且它本身没有 API key 设置。因此请把它当作私有后端：只监听 localhost，在前面加访问控制。

启动服务器并用 curl 测试

激活虚拟环境，用 mlx-community 的模型启动服务器。首次运行会把模型下载到 Hugging Face 缓存。

source ~/mlx-env/bin/activate
mlx_lm.server --model mlx-community/Mistral-7B-Instruct-v0.3-4bit

在另一个终端发送对话请求：

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Say this is a test."}],
    "max_tokens": 100,
    "temperature": 0.7
  }'

返回结构和你熟悉的一样：choices[0].message，finish_reason 为 stop 或 length，以及包含 token 数的 usage。流式输出、模型列表和健康检查同样可用：

# stream tokens as server-sent events
curl -N http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Count to five."}], "stream": true}'

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

服务器就绪时，/health 返回 {"status": "ok"}，方便在监控脚本中使用。

用 OpenAI 兼容客户端调用 MLX 服务器

大多数支持自定义 OpenAI base URL 的工具都能对接这个服务器。使用官方 Python SDK（pip install openai）：

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="unused")
resp = client.chat.completions.create(
    model="mlx-community/Mistral-7B-Instruct-v0.3-4bit",
    messages=[{"role": "user", "content": "One tip for faster builds?"}],
)
print(resp.choices[0].message.content)

SDK 要求填写 API key 字符串，但 MLX 服务器会忽略它。如果你按下文加了带 bearer token 的反向代理，这里填真实 token。对 mlx-lm 来说 model 字段是可选的。如果传入另一个仓库 id，服务器会改为加载那个模型，所以除非内存足够切换，否则坚持使用一个模型。

用 launchd 作为服务运行

在为团队提供服务的 Mac mini 或 Mac Studio 上，你希望服务器能自动启动、崩溃后自动重启。在 macOS 上这由 launchd 负责。LaunchAgent 在你的用户会话中运行，可以正常使用 GPU 和你的 Hugging Face 缓存。

先手动运行一次模型，确保下载完成。然后把下面内容保存为 ~/Library/LaunchAgents/com.example.mlx-server.plist，并把 /Users/you 换成你的主目录。launchd 不会展开 ~，所以要写完整路径。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.example.mlx-server</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/you/mlx-env/bin/mlx_lm.server</string>
    <string>--model</string>
    <string>mlx-community/Mistral-7B-Instruct-v0.3-4bit</string>
    <string>--host</string>
    <string>127.0.0.1</string>
    <string>--port</string>
    <string>8080</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/Users/you/mlx</string>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/Users/you/mlx/server.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/you/mlx/server.err.log</string>
</dict>
</plist>

WorkingDirectory 很重要：请求中的本地模型和适配器路径，是相对服务器启动目录解析的。加载并检查服务：

mkdir -p ~/mlx
plutil -lint ~/Library/LaunchAgents/com.example.mlx-server.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.mlx-server.plist
launchctl print gui/$(id -u)/com.example.mlx-server | head -20
tail -f ~/mlx/server.err.log

更换模型后重启，或停止服务：

launchctl kickstart -k gui/$(id -u)/com.example.mlx-server   # restart
launchctl bootout gui/$(id -u)/com.example.mlx-server        # stop and unload

LaunchAgent 在该用户登录时启动。如果 Mac 重启，服务会在用户会话重新开始后恢复，因此在无人值守的服务器上，可以考虑为服务账户开启自动登录（启用 FileVault 时无法自动登录）。修改 plist 后，需要先 bootout 再重新 bootstrap。

只监听 localhost，通过 SSH 隧道访问

最简单的安全方案是让 --host 保持 127.0.0.1，通过 SSH 访问服务器。在你的笔记本上执行：

ssh -N -L 8080:127.0.0.1:8080 you@your-mac-address

这样笔记本上的 http://127.0.0.1:8080 就能经加密通道访问 Mac 上的服务器，并且只有拥有 SSH 权限的人能用。请使用基于密钥的 SSH 登录。我们的 远程访问 Mac 指南 介绍了 SSH 及其他方式。

或者加一层带认证的反向代理

如果其他服务或同事需要不经 SSH 直接调用 API，可以在前面放一个反向代理，负责 TLS 并校验 token。下面的 nginx 示例要求请求带 Authorization: Bearer 头，这正是 OpenAI 客户端发送的格式。使用 Homebrew 版 nginx 时，保存为 /opt/homebrew/etc/nginx/servers/mlx.conf：

map $http_authorization $mlx_ok {
    default 0;
    "Bearer REPLACE_WITH_LONG_RANDOM_TOKEN" 1;
}

server {
    listen 8443 ssl;
    server_name mlx.example.com;
    ssl_certificate     /opt/homebrew/etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /opt/homebrew/etc/nginx/certs/privkey.pem;

    location / {
        if ($mlx_ok = 0) { return 401; }
        proxy_pass http://127.0.0.1:8080;
        proxy_buffering off;
        proxy_read_timeout 600s;
    }
}

brew install nginx
openssl rand -hex 32
nginx -t && brew services start nginx

用 openssl rand -hex 32 的输出作为 token，配置你自己的 TLS 证书，并让 MLX 服务器继续绑定 127.0.0.1，使代理成为唯一入口。proxy_buffering off 让流式 token 实时透传。从外部测试：

curl https://mlx.example.com:8443/v1/models \
  -H "Authorization: Bearer $MLX_TOKEN"

把 token 存放在环境变量或密钥管理工具中，不要写进代码。防火墙只开放代理端口，token 泄露时及时更换。

值得了解的调优参数

• --max-tokens：请求未指定时的默认输出上限。
• --kv-bits 4 或 8：为长上下文量化 KV cache。文档指出这会关闭批处理，请求将逐个处理。建议同时调小 --prefill-step-size。
• --prompt-cache-size 和 --prompt-cache-bytes：控制服务器保留多少可复用的提示缓存。
• --decode-concurrency 和 --prompt-concurrency：控制可批处理请求的并行度。
• --allowed-origins：默认为 *。如果浏览器直接调用 API，请设置为你的 Web 应用来源。
• --adapter-path：在基础模型上加载 LoRA 适配器提供服务。

mlx_lm.server --model mlx-community/Mistral-7B-Instruct-v0.3-4bit \
  --max-tokens 1024 --kv-bits 8 --prefill-step-size 512 \
  --allowed-origins https://app.example.com

参数会随版本变化，请运行 mlx_lm.server --help 查看最新列表。

按模型大小选择套餐

共享接口要按模型本身加上并发请求的上下文来估算内存。4-bit 模型每十亿参数大约需要 0.5–0.7 GB，默认情况下 macOS 允许 GPU 使用约三分之二到四分之三的统一内存。

模型规模（4-bit）	建议机型
3B–8B 助手、内部工具	Mac mini M4 或 M6，16GB
约 14B 以内，或长上下文的 8B	Mac mini M6 24GB 或 Mac mini M5 Pro 24GB
约 30B 级	Mac Studio M5 Max，36GB
70B 级	Mac Studio M5 Ultra，96GB

以上只是粗略参考，取决于上下文长度和并发量。更大内存可按需提供。背景知识可阅读 在 Mac Studio 上运行本地 LLM，或查看 Apple 芯片 AI 服务器 页面。

价格为每台机器起始配置的美元月费。需要更多内存、存储或多台机器？联系我们。

每台 Hatmac 机器都是分配给单一客户的独享实体 Mac。付款后我们会完成配置并发邮件通知你，访问信息会显示在账户的“My Macs”中。Hatmac 是独立公司，与 Apple 无关联。