<!-- Source: https://hermesbible.com/docs/guides/local-llm-on-mac -->

本指南將引導你在 macOS 上設定一個具有 OpenAI 相容 API 的本地 LLM 伺服器。你將獲得完整的隱私、零 API 成本，以及在 Apple Silicon 上令人驚訝的良好效能。

我們涵蓋兩種後端：

兩者都提供 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+ 的統一記憶體中搭配量化可輕鬆運行。

記憶體經驗法則： 模型大小 + 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

以下是每個標誌的作用：

當你看到以下內容時，伺服器已就緒：

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 上下文時的影響：

在 8 GB 的 Mac 上，使用 q4_0 KV 快取並選擇一個仍然能符合 Hermes 64K 最低上下文的較小模型。在 16 GB 上，你可以舒適地使用 128K 上下文。在 32 GB+ 上，你可以運行較大的模型或多個並行槽位。

如果你仍然記憶體不足，請減少上下文但保持在或高於 Hermes 的 64K 最低要求；否則切換到較小的模型或較小的量化（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 下載並安裝。它提供了一個用於模型管理的 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）。使用 5 個不同的提示，每個執行 3 次，後端按順序測試以避免資源競爭。

結果

這意味著什麼

• llama.cpp 在提示處理方面表現出色——其 flash attention + 量化 KV 快取管線讓你在約 64ms 內獲得首個 token。如果你正在建構需要感知回應速度的互動式應用程式（聊天機器人、自動完成），這是一個有意義的優勢。

• MLX 一旦開始產生 token，速度約快 37%。對於批次工作負載、長文本產生或任何更看重總完成時間而非初始延遲的任務，MLX 會更早完成。

• 兩種後端都極為一致——跨執行的方差可以忽略不計。你可以信賴這些數據。

你應該選擇哪一個？

---

連接到 Hermes

一旦你的本地伺服器運行：

hermes model

選擇 Custom endpoint 並按照提示操作。它會要求輸入基礎 URL 和模型名稱——使用你上面設定的後端對應的值。

---

逾時設定

Hermes 會自動偵測本地端點（localhost、區域網路 IP）並放寬其串流逾時。大多數設定不需要配置。

如果你仍然遇到逾時錯誤（例如在較慢的硬體上使用非常大的上下文），你可以覆寫串流讀取逾時：

# 在你的 .env 中 — 從預設的 120 秒提高到 30 分鐘
HERMES_STREAM_READ_TIMEOUT=1800

串流讀取逾時是最可能導致問題的——它是在接收下一個資料區塊時的 socket 層級期限。在大型上下文的預填充期間，本地模型在處理提示時可能長達數分鐘沒有輸出。自動偵測可以透明地處理此情況。

---

---

教學：每日簡報機器人