ByteNoteByteNote
字

字节笔记本

2026年6月21日

hermes教程-在 Mac 上运行本地 LLM

#AI 前沿
API中转
¥120
每日科技简报 · 每天一篇,快速了解科技圈大事

在 Mac 上运行本地 LLM

本指南将带你通过兼容 OpenAI API 的方式在 macOS 上运行本地 LLM 服务器。你将获得完全的隐私保护、零 API 成本，以及在 Apple Silicon 上令人惊喜的性能表现。

我们介绍两种后端：

后端安装方式最佳场景格式
llama.cppbrew install llama.cpp最快的首 token 生成时间，量化 KV 缓存节省内存GGUF
omlxomlx.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 以上的统一内存。

变体磁盘占用所需 RAM（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 GBomlx

内存经验法则： 模型大小 + 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 加速。

安装

bash
brew install llama.cpp

这会将 llama-server 命令安装到全局。

下载模型

你需要一个 GGUF 格式的模型。最简单的来源是通过 huggingface-cli 从 Hugging Face 获取：

bash
brew install huggingface-cli

然后下载：

bash
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。

启动服务器

bash
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闪存注意力。减少内存使用并加速长上下文推理。
--cache-type-k q4_0将键缓存量化为 4 位。这是节省内存的关键。
--cache-type-v q4_0将值缓存量化为 4 位。与上述结合，KV 缓存内存相比 f16 减少约 75%。
--host 0.0.0.0监听所有接口。如果不需要网络访问，使用 127.0.0.1。

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

text
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 缓存，并选择一个仍能满足 Hermes 64K 最小上下文的较小模型。在 16 GB 上，你可以轻松处理 128K 上下文。在 32 GB 以上，你可以运行更大的模型或多个并行槽位。

如果仍然内存不足，请仅在保持不低于 Hermes 64K 最小上下文的前提下减少上下文；否则切换到更小的模型或更小的量化（例如 Q3_K_M 代替 Q4_K_M）。

测试

bash
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

获取模型名称

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

bash
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。

测试

bash
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 可以同时提供多个模型：

bash
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 ms289 msllama.cpp（快 4.3 倍）
TTFT（p50）66 ms286 msllama.cpp（快 4.3 倍）
生成速度（平均）70 tok/s96 tok/sMLX（快 37%）
生成速度（p50）70 tok/s96 tok/sMLX（快 37%）
总时间（512 tokens）7.3s5.5sMLX（快 25%）

这意味着什么

  • llama.cpp 在提示处理方面表现出色——其闪存注意力 + 量化 KV 缓存流水线可在约 66ms 内获得第一个 token。如果你正在构建对感知响应速度有要求的交互式应用（聊天机器人、自动补全），这是一个有意义的优势。

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

  • 两个后端都极其稳定——运行之间的差异可以忽略不计。你可以信赖这些数字。

你应该选择哪一个？

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

连接到 Hermes

本地服务器运行后：

bash
hermes model

选择 Custom endpoint 并按照提示操作。它会询问基础 URL 和模型名称——使用你上面设置的后端对应的值。

超时设置

Hermes 会自动检测本地端点（localhost、LAN IP）并放宽其流式超时。大多数情况下无需配置。

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

bash
## 在 .env 中——从默认的 120 秒提高到 30 分钟
HERMES_STREAM_READ_TIMEOUT=1800
超时默认值本地自动调整环境变量覆盖
流式读取（套接字级别）120s提高到 1800sHERMES_STREAM_READ_TIMEOUT
流式过期检测180s完全禁用HERMES_STREAM_STALE_TIMEOUT
API 调用（非流式）1800s无需更改HERMES_API_TIMEOUT

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

AI 前沿
上一篇

hermes教程-提示与最佳实践

下一篇

hermes教程-在 Mac 上运行本地 LLM

分享: