本地 LLM 搭建步骤｜在 Mac 上启动并验证 mlx-serve

我们在 Mac 上安装了 mlx-serve 和 Qwen3-4B-4bit，在本机启动模型，并确认了 API 的响应。下文的耗时和速度，是 2026 年 11 月 5 日和 6 日在 Apple M1 Max、64 GB 内存、macOS 26.6 上测得的。换一台 Mac，不保证得到相同的数值。

使用条件与许可证

我们用的是 GitHub Releases 上 v26.11.1 的 mlx-serve-bin-macos-arm64.tar.gz。mlx-serve 本身采用 MIT 许可证，随附的第三方部分标有 Apache-2.0 和 BSD 许可声明，可以在发行包的 NOTICE 文件中查看。模型是 mlx-community/Qwen3-4B-4bit，基于原版 Qwen/Qwen3-4B，以 Apache-2.0 许可证发布。使用前，请核对你手上发行包里的 LICENSE、NOTICE，以及模型的许可证说明。官方还介绍了 DMG 和 Homebrew 两种安装方式，本文没有试过。

校验压缩包，找到可执行文件

压缩包下载自官方 GitHub Releases 的 v26.11.1。请把 ARCHIVE 和 UNPACK_DIR 改成你实际的保存位置。我们设好这两个路径后，分别在 zsh 和 bash 中执行过这段命令。SHA-256 不一致就不解压；确认不了可执行文件或版本，就不进入下一步。命令与实测时一字不差，所以其中的提示信息是日语。

ARCHIVE="$HOME/Downloads/mlx-serve-bin-macos-arm64.tar.gz"
UNPACK_DIR="$HOME/Downloads/mlx-serve-v26.11.1"
if ! printf '%s  %s\n' '9acaa7a21b294536c3db9f2683d85079727b4e8db725d34260020499523dc267' "$ARCHIVE" | shasum -a 256 -c -; then
  printf '%s\n' 'SHA-256が一致しません。ここで中止してください。' >&2
elif ! mkdir -p "$UNPACK_DIR" || ! tar -xzf "$ARCHIVE" -C "$UNPACK_DIR"; then
  printf '%s\n' '解凍できませんでした。ここで中止してください。' >&2
else
  BIN="$(find "$UNPACK_DIR" -type f -name mlx-serve -print -quit)"
  if [ -z "$BIN" ] || [ ! -x "$BIN" ]; then
    unset BIN
    printf '%s\n' '実行可能な mlx-serve が見つかりません。' >&2
  elif ! "$BIN" --version; then
    unset BIN
    printf '%s\n' 'バージョンを確認できませんでした。' >&2
  fi
fi

SHA-256 一致，--version 输出的第一行是 mlx-serve 26.11.1 (fast)。发行包的签名团队 ID 是 S77TW432YG（David Dalcu 的 Developer ID）。上面的命令不包含签名校验。BIN 中保存的是在解压目录里找到的可执行文件路径。下一步也要在同一个终端里执行。

下载模型并启动

下载模型需要联网。11 月 5 日首次下载共 9 个文件、2,173 MB，用时约 54 秒。模型保存在 ~/.mlx-serve/models/ 下。11 月 6 日模型已经在本机，pull 没有重新下载，直接继续执行。

if [ -n "${BIN:-}" ] && [ -x "$BIN" ]; then
  "$BIN" pull mlx-community/Qwen3-4B-4bit &&
  "$BIN" --model "$HOME/.mlx-serve/models/mlx-community/Qwen3-4B-4bit" --serve --host 127.0.0.1 --port 11234
else
  printf '%s\n' '先にアーカイブとバージョンを確認してください。' >&2
fi

启动后几秒内，终端显示 Server listening on http://127.0.0.1:11234。上下文长度根据可用内存自动决定，同一台 Mac 上有时是 12,288 token，有时只有 870 token。

不要省略 --host 127.0.0.1。官方的 cli.md 写的默认值是 0.0.0.0，SECURITY.md 写的却是 127.0.0.1，两份文档说法不一致。本文不把服务开放到局域网。

验证 API 响应

让服务器保持运行，在另一个终端里按下面的顺序执行，检查 HTTP 状态码和保存下来的响应。x-api-key: local-test 是本地请求时用的值。提示词按实测时的原样用日语发送，每个结果后附有译文。

OpenAI 兼容：非流式响应

OUT_DIR="$(mktemp -d)"
curl -sS -o "$OUT_DIR/chat.json" -w 'HTTP %{http_code}\n' \
  -H 'Content-Type: application/json' \
  --data-binary @- http://127.0.0.1:11234/v1/chat/completions <<'JSON'
{"model":"mlx-community/Qwen3-4B-4bit","max_tokens":128,"messages":[{"role":"user","content":"ローカルLLMとは何か、3文で説明してください。"}]}
JSON
python3 -m json.tool --no-ensure-ascii "$OUT_DIR/chat.json"

11 月 6 日的响应是 HTTP 200，生成了 65 个 token，速度为 81.0 tokens/秒。提示词要求用三句话解释什么是本地 LLM，回答的开头是“ローカルLLMとは、自社や組織のサーバー内に置かれる人工知能モデルのことです。”（本地 LLM 是指放在自家公司或组织服务器内的人工智能模型。）

OpenAI 兼容：流式响应

curl -sSN -o "$OUT_DIR/stream.sse" -w 'HTTP %{http_code}\n' \
  -H 'Content-Type: application/json' \
  --data-binary @- http://127.0.0.1:11234/v1/chat/completions <<'JSON'
{"model":"mlx-community/Qwen3-4B-4bit","max_tokens":64,"stream":true,"messages":[{"role":"user","content":"日本の首都はどこですか。短く答えてください。"}]}
JSON
grep '^data:' "$OUT_DIR/stream.sse"

HTTP 200。data: 行依次返回，最后一行是 data: [DONE]。提示词问日本的首都在哪里，要求简短回答，回答是“東京”（东京）。

Anthropic 兼容：Messages API

curl -sS -o "$OUT_DIR/messages.json" -w 'HTTP %{http_code}\n' \
  -H 'Content-Type: application/json' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'x-api-key: local-test' \
  --data-binary @- http://127.0.0.1:11234/v1/messages <<'JSON'
{"model":"mlx-community/Qwen3-4B-4bit","max_tokens":64,"messages":[{"role":"user","content":"推論を英語で一語で説明してください。"}]}
JSON
python3 -m json.tool --no-ensure-ascii "$OUT_DIR/messages.json"

HTTP 200。提示词要求用一个英文单词解释日语的“推論”（推理），回答是“Inference.”，stop_reason 为 end_turn。在这台 Mac 上观测到的生成速度为 34～90 tokens/秒，会随同时运行的其他任务而变化。这些数值不代表其他机型的速度。

错误与未验证事项

SHA-256 不一致时，不要运行那个发行包。11 月 6 日，在另一个程序占用 GPU 内存的情况下，同样的三个请求全部返回 HTTP 400，错误信息是“Prompt (29 tokens) requires ~661MB GPU memory but only ~53MB is available …”。遇到这个错误，先关掉占用内存的程序，再重试。遇到其他 HTTP 错误，请查看保存下来的响应和服务器日志。

断网运行、App、Homebrew 和 GGUF 都没有验证。“没有分析和遥测”是官方 FAQ 的说法，不是我们实测网络通信得出的结果。想深入了解评估方法，请参阅微调适配器上线前如何检查。

在 Mac 上搭建本地 LLM：mlx-serve 的安装与 API 验证