在 Mac 上运行本地 LLM

本指南介绍如何在 macOS 上运行一个兼容 OpenAI API 的本地 LLM 服务器。你将获得完整的隐私保护、零 API 费用，以及 Apple Silicon 上出乎意料的出色性能。

我们涵盖两个后端：

后端	安装方式	优势	格式
llama.cpp	brew install llama.cpp	首 token 延迟最低，量化 KV 缓存节省内存	GGUF
omlx	omlx.ai	token 生成速度最快，原生 Metal 优化	MLX (safetensors)

两者均暴露兼容 OpenAI 的 /v1/chat/completions 端点。AigenLabs 支持任意一个——只需将其指向 http://localhost:8080 或 http://localhost:8000。

仅限 Apple Silicon

本指南面向搭载 Apple Silicon（M1 及更新）的 Mac。Intel Mac 可使用 llama.cpp，但无 GPU 加速——性能会明显更慢。

---

选择模型

入门推荐 Qwen3.5-9B——这是一个强推理模型，量化后可在 8GB+ 统一内存上轻松运行。

变体	磁盘占用	所需内存（128K 上下文）	后端
Qwen3.5-9B-Q4_K_M (GGUF)	5.3 GB	~10 GB（含量化 KV 缓存）	llama.cpp
Qwen3.5-9B-mlx-lm-mxfp4 (MLX)	~5 GB	~12 GB	omlx

内存估算规则： 模型大小 + KV 缓存。9B Q4 模型约 5 GB。128K 上下文下 Q4 量化的 KV 缓存额外占用约 4–5 GB。若使用默认（f16）KV 缓存，则会膨胀至约 16 GB。llama.cpp 中的量化 KV 缓存参数是内存受限系统的关键技巧。

对于更大的模型（27B、35B），你需要 32 GB+ 的统一内存。9B 是 8–16 GB 机器的最佳选择。

---

方案 A：llama.cpp

llama.cpp 是移植性最强的本地 LLM 运行时。在 macOS 上，它开箱即用地通过 Metal 进行 GPU 加速。

安装

brew install llama.cpp

安装后即可全局使用 llama-server 命令。

下载模型

你需要 GGUF 格式的模型。最简便的来源是通过 huggingface-cli 从 Hugging Face 下载：

brew install huggingface-cli

然后下载：

huggingface-cli download unsloth/Qwen3.5-9B-GGUF Qwen3.5-9B-Q4_K_M.gguf --local-dir ~/models

受限模型

Hugging Face 上的部分模型需要身份验证。如果遇到 401 或 404 错误，请先运行 huggingface-cli login。

启动服务器

llama-server -m ~/models/Qwen3.5-9B-Q4_K_M.gguf \
  -ngl 99 \
  -c 131072 \
  -np 1 \
  -fa on \
  --cache-type-k q4_0 \
  --cache-type-v q4_0 \
  --host 0.0.0.0

各参数说明：

参数	用途
-ngl 99	将所有层卸载到 GPU（Metal）。设置较大的数值以确保没有层留在 CPU 上。
-c 131072	上下文窗口大小（128K token）。内存不足时可减小此值。
-np 1	并行槽数量。单用户使用时保持为 1——更多槽会分摊内存预算。
-fa on	Flash attention。减少内存占用并加速长上下文推理。
--cache-type-k q4_0	将 key 缓存量化为 4-bit。这是最大的内存节省手段。
--cache-type-v q4_0	将 value 缓存量化为 4-bit。与上一项合用，相比 f16 可将 KV 缓存内存减少约 75%。
--host 0.0.0.0	监听所有网络接口。若不需要网络访问，可改为 127.0.0.1。

当你看到以下输出时，服务器已就绪：

main: server is listening on http://0.0.0.0:8080
srv  update_slots: all slots are idle

内存受限系统的优化

--cache-type-k q4_0 --cache-type-v q4_0 参数是内存有限系统最重要的优化手段。以下是 128K 上下文下的影响对比：

KV 缓存类型	KV 缓存内存（128K 上下文，9B 模型）
f16（默认）	~16 GB
q8_0	~8 GB
q4_0	~4 GB

在 8 GB Mac 上，使用 q4_0 KV 缓存并将上下文缩减为 -c 32768（32K）。在 16 GB 上，可以轻松使用 128K 上下文。在 32 GB+ 上，可以运行更大的模型或多个并行槽。

如果仍然内存不足，优先减小上下文大小（-c），然后尝试更小的量化级别（Q3_K_M 代替 Q4_K_M）。

测试

curl -s http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3.5-9B-Q4_K_M.gguf",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 50
  }' | jq .choices[0].message.content

获取模型名称

如果忘记了模型名称，可查询 models 端点：

curl -s http://localhost:8080/v1/models | jq '.data[].id'

---

方案 B：通过 omlx 使用 MLX

omlx 是一款 macOS 原生应用，用于管理和提供 MLX 模型服务。MLX 是 Apple 自研的机器学习框架，专为 Apple Silicon 统一内存架构优化。

安装

从 omlx.ai 下载并安装。它提供图形界面用于模型管理，并内置服务器。

下载模型

使用 omlx 应用浏览并下载模型。搜索 Qwen3.5-9B-mlx-lm-mxfp4 并下载。模型存储在本地（通常位于 ~/.omlx/models/）。

启动服务器

omlx 默认在 http://127.0.0.1:8000 上提供服务。通过应用 UI 启动服务，或在可用时使用 CLI。

测试

curl -s http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3.5-9B-mlx-lm-mxfp4",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 50
  }' | jq .choices[0].message.content

列出可用模型

omlx 可同时提供多个模型的服务：

curl -s http://127.0.0.1:8000/v1/models | jq '.data[].id'

---

基准测试：llama.cpp vs MLX

两个后端在同一台机器（Apple M5 Max，128 GB 统一内存）上测试，使用相同模型（Qwen3.5-9B），量化级别相当（GGUF 使用 Q4_K_M，MLX 使用 mxfp4）。五个不同 prompt，每个运行三次，后端顺序测试以避免资源竞争。

结果

指标	llama.cpp (Q4_K_M)	MLX (mxfp4)	胜者
TTFT（首 token 延迟，均值）	67 ms	289 ms	llama.cpp（快 4.3 倍）
TTFT（p50）	66 ms	286 ms	llama.cpp（快 4.3 倍）
生成速度（均值）	70 tok/s	96 tok/s	MLX（快 37%）
生成速度（p50）	70 tok/s	96 tok/s	MLX（快 37%）
总耗时（512 token）	7.3s	5.5s	MLX（快 25%）

含义解读

• llama.cpp 在 prompt 处理上表现突出——其 flash attention + 量化 KV 缓存流水线可在约 66ms 内返回第一个 token。如果你在构建对响应速度敏感的交互式应用（聊天机器人、自动补全），这是显著优势。

• MLX 一旦开始生成，token 速度快约 37%。对于批量任务、长文本生成，或任何更关注总完成时间而非初始延迟的场景，MLX 完成得更快。

• 两个后端都极为稳定——多次运行间的方差可忽略不计。这些数据可作为可靠参考。

如何选择？

使用场景	推荐
交互式聊天、低延迟工具	llama.cpp
长文本生成、批量处理	MLX (omlx)
内存受限（8–16 GB）	llama.cpp（量化 KV 缓存无可匹敌）
同时提供多个模型服务	omlx（内置多模型支持）
最大兼容性（含 Linux）	llama.cpp

---

连接 AigenLabs

本地服务器启动后：

aigenlabs model

选择 Custom endpoint，按提示操作。系统会询问 base URL 和模型名称——使用你所配置的后端对应的值即可。

---

超时设置

AigenLabs 会自动检测本地端点（localhost、局域网 IP）并放宽其流式传输超时限制。大多数情况下无需额外配置。

如果仍然遇到超时错误（例如在慢速硬件上使用超大上下文），可以覆盖流式读取超时：

# 在 .env 中——将默认的 120s 提高到 30 分钟
AIGENLABS_STREAM_READ_TIMEOUT=1800

超时类型	默认值	本地自动调整	环境变量覆盖
流式读取（socket 级别）	120s	提升至 1800s	AIGENLABS_STREAM_READ_TIMEOUT
停滞流检测	180s	完全禁用	AIGENLABS_STREAM_STALE_TIMEOUT
API 调用（非流式）	1800s	无需调整	AIGENLABS_API_TIMEOUT

流式读取超时最容易引发问题——它是接收下一个数据块的 socket 级别截止时间。在大上下文的预填充（prefill）阶段，本地模型可能在处理 prompt 时数分钟内没有任何输出。自动检测机制会透明地处理这一情况。