在 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 tokens）。內存不足時可減小此值。
-np 1	並行槽位數量。單用戶使用時保持為 1——更多槽位會分割您的內存預算。
-fa on	啟用 Flash Attention。可減少內存佔用並加快長上下文推理速度。
--cache-type-k q4_0	將鍵緩存量化為 4 位。這是節省內存的關鍵。
--cache-type-v q4_0	將值緩存量化為 4 位。與上一項結合使用，相比 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

獲取模型名稱

若忘記模型名稱，可通過查詢模型端點獲取：

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 提供模型服務。可通過應用界面啟動服務，或使用可用的 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 與 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 緩存流水線可在約 66ms 內輸出第一個 token。如果你正在構建對感知響應速度敏感的交互式應用（如聊天機器人、自動補全），這將帶來顯著優勢。

• MLX 在開始生成後，token 生成速度比 llama.cpp 快約 37%。對於批量任務、長文本生成，或任何更關注總完成時間而非初始延遲的場景，MLX 能更快完成任務。

• 兩個後端均表現出極高的穩定性——各次運行間的差異可忽略不計。你可以完全信賴這些數據。

你應該選擇哪一個？

使用場景	推薦方案
交互式聊天、低延遲工具	llama.cpp
長文本生成、批量處理	MLX（omlx）
內存受限（8-16 GB）	llama.cpp（量化 KV 緩存表現無與倫比）
同時服務多個模型	omlx（內置多模型支持）
最大兼容性（支持 Linux）	llama.cpp

---

連接到 Hermes

本地服務器啟動後：

hermes model

選擇 自定義端點 並按提示操作。系統將要求輸入基礎 URL 和模型名稱——請使用你在上文設置的後端對應的值。

---

超時設置

Hermes 會自動檢測本地端點（localhost、局域網 IP），並自動放寬流式傳輸超時時間。大多數情況下無需任何配置。

如果你仍然遇到超時錯誤（例如在慢速硬件上處理非常大的上下文），可以手動覆蓋流式讀取超時時間：

# 在您的 `.env` 中 — 從默認值 120 秒提高到 30 分鐘
HERMES_STREAM_READ_TIMEOUT=1800

超時類型	默認值	本地自動調整	環境變量覆蓋
流式讀取（socket 層）	120s	提升至 1800s	HERMES_STREAM_READ_TIMEOUT
舊流檢測	180s	完全禁用	HERMES_STREAM_STALE_TIMEOUT
API 調用（非流式）	1800s	無需更改	HERMES_API_TIMEOUT

最可能引發問題的是流式讀取超時——這是接收下一數據塊的 socket 層截止時間。在大上下文預填充階段，本地模型可能在處理提示時數分鐘內無輸出。自動檢測機制會透明地處理這一情況。