在 Mac 上运行本地 LLM

> 📖 本文档翻译自 Hermes Agent 官方文档 > 最后更新：2026-04-16

---

在 Mac 上运行本地 LLM

本指南带你了解如何在 macOS 上运行本地 LLM 服务器（提供 OpenAI 兼容 API）。你将获得完全的隐私、零 API 费用，以及在 Apple Silicon 上出人意料的好性能。

我们介绍两种后端：

后端	安装方式	优势	格式
llama.cpp	brew install llama.cpp	首个 token 延迟最低，量化 KV cache 适合低内存环境	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	量化 KV cache 约 10 GB	llama.cpp
Qwen3.5-9B-mlx-lm-mxfp4 (MLX)	~5 GB	~12 GB	omlx

内存经验法则： 模型大小 + KV cache。9B Q4 模型约 5 GB。128K 上下文的 KV cache 使用 Q4 量化增加约 4-5 GB。使用默认 (f16) KV cache 则膨胀到约 16 GB。llama.cpp 中的量化 KV cache 标志是内存受限系统的关键技巧。

对于更大的模型（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 cache 量化为 4 位。这是最大的内存节省利器。
--cache-type-v q4_0	将 value cache 量化为 4 位。与上面的配合，KV cache 内存相比 f16 减少约 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 cache 类型	KV cache 内存（128K 上下文，9B 模型）
f16（默认）	~16 GB
q8_0	~8 GB
q4_0	~4 GB

在 8 GB 的 Mac 上，使用 q4_0 KV cache 并将上下文减少到 -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

获取模型名称

如果你忘了模型名称，查询模型端点：

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

---

方案 B：通过 omlx 使用 MLX

omlx 是一个 macOS 原生应用，用于管理和提供 MLX 模型。MLX 是苹果自己的机器学习框架，专门针对 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 tokens）	7.3s	5.5s	MLX（快 25%）

这意味着什么

• llama.cpp 在提示处理方面表现出色——其 flash attention + 量化 KV cache 流水线让你在大约 66ms 内获得第一个 token。如果你正在构建交互式应用，感知响应速度很重要（聊天机器人、自动补全），这是一个有意义的优势。
• MLX 一旦开始，生成 token 快约 37%。对于批量工作负载、长文本生成，或任何总完成时间比初始延迟更重要的任务，MLX 完成得更快。
• 两个后端都极其稳定——各次运行之间的差异可以忽略不计。你可以信赖这些数据。

你应该选择哪个？

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

---

连接到 Hermes

本地服务器运行后：

hermes model

选择自定义端点并按提示操作。它会询问基础 URL 和模型名称——使用你上面设置的任何后端的值。

---

超时设置

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

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

# In your .env — raise from the 120s default to 30 minutes
HERMES_STREAM_READ_TIMEOUT=1800

超时	默认值	本地自动调整	环境变量覆盖
流式读取（socket 级别）	120s	提高到 1800s	HERMES_STREAM_READ_TIMEOUT
停滞流检测	180s	完全禁用	HERMES_STREAM_STALE_TIMEOUT
API 调用（非流式）	1800s	无需更改	HERMES_API_TIMEOUT

流式读取超时最可能导致问题——它是接收下一个数据块的 socket 级截止时间。在大上下文的预填充阶段，本地模型可能在处理提示时几分钟不产生输出。自动检测会透明地处理这个问题。