在 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 端点。Hermes 与两者均可配合使用——只需将其指向 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 位。这是最大的内存节省手段。
--cache-type-v q4_0	将 value 缓存量化为 4 位。与上一项结合，相比 f16 可减少约 75% 的 KV 缓存内存。
--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 是一个用于管理和提供 MLX 模型的 macOS 原生应用。MLX 是 Apple 自研的机器学习框架，专为 Apple Silicon 统一内存架构进行了优化。

安装

从 omlx.ai 下载并安装。它提供模型管理 GUI 和内置服务器。

下载模型

使用 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）进行测试。五个不同类型的提示词，每个运行三次，后端依次测试以避免资源竞争。

结果

指标	llama.cpp (Q4_K_M)	MLX (mxfp4)	胜者
TTFT（平均）	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 在提示词处理方面表现出色——其 flash attention + 量化 KV 缓存流水线能在约 66ms 内给出第一个 token。如果你正在构建感知响应速度至关重要的交互式应用（聊天机器人、自动补全），这是一个显著优势。

• MLX 一旦开始生成 token，速度快约 37%。对于批量工作负载、长文本生成，或任何完成时间比初始延迟更重要的任务，MLX 完成得更快。

• 两种后端都极其稳定——多次运行间的差异可以忽略不计。这些数据具有参考价值。

如何选择？

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

---

连接到 Hermes

本地服务器启动后：

hermes model

选择自定义端点并按提示操作。系统会询问 base URL 和模型名称——使用上面对应后端的配置值即可。

---

超时设置

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

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

# 在 .env 中设置——将默认的 120 秒提升到 30 分钟
HERMES_STREAM_READ_TIMEOUT=1800

超时类型	默认值	本地自动调整	环境变量覆盖
流式读取（套接字级别）	120s	提升到 1800s	HERMES_STREAM_READ_TIMEOUT
陈旧流检测	180s	完全禁用	HERMES_STREAM_STALE_TIMEOUT
API 调用（非流式）	1800s	无需调整	HERMES_API_TIMEOUT

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