小黃老師嘿技術

1. 為什麼選擇「oMLX + Hermes Agent」雙機分離架構？

在本地運行大型語言模型（LLM）時，我們往往面臨兩難：高效能的運算硬體通常體積龐大且功耗較高，而輕便的日常工作筆電在跑高負載模型時，容易出現記憶體不足與發熱降頻的問題。透過雙機分離的拓撲架構，我們可以把兩項開源工具的優勢發揮到極致：

將 oMLX 作為「運算大腦（Host）」，專注處理矩陣運算與 Token 生成；而把 Hermes Agent 放在「操作工作機（Client）」，負責處理日常程式編寫與工具執行，不僅徹底解放筆電效能，更讓開發流程變得優雅而安定。

2. 行前準備：硬體角色分配與區域網路拓撲

在動手修改設定檔之前，請先確認兩台設備在實體網路與環境上的就緒狀態：

⚠️ 關鍵網路條件：兩台設備必須處於同一個區域網路（LAN）網段（例如皆連線至相同的家用 Wi-Fi 或實體路由器，IP 屬於 192.168.1.X 或 10.0.0.X），且路由器切勿開啟「訪客隔離 (AP Isolation)」功能，否則設備間將無法互相通訊。

3. 伺服端設定：讓 oMLX 開放全域網路監聽 (0.0.0.0)

基於本機安全性考量，oMLX 預設通常僅綁定在環回位址（127.0.0.1），這會導致外部設備的連線請求直接遭到系統拒絕。我們需要將其調整為全介面監聽（0.0.0.0）。

步驟 A：查詢伺服端內網 IP

在 Mac 伺服端開啟「終端機」，輸入下列指令查詢當前分配到的區域網路 IP：

ipconfig getifaddr en0
# 若使用有線乙太網路，可改為查詢 en1，或執行以下指令查看：
ifconfig | grep "inet " | grep -v 127.0.0.1

此處請先記下終端機顯示的數值（本文教學以 192.168.1.100 為範例）。

步驟 B：設定 oMLX 監聽 0.0.0.0

根據你的 oMLX 啟動模式，挑選對應的方式調整監聽位址：

• 圖形介面 (GUI App)：開啟 oMLX 視窗，進入「Settings」設定頁籤，將 Host 欄位由 127.0.0.1 更改為 0.0.0.0，連接埠（Port）保持預設的 8000。
• 命令列模式 (CLI)：若習慣透過終端機啟動服務，請加上 --host 參數：
  omlx serve --host 0.0.0.0 --port 8000
• 設定檔持久化：亦可直接在系統環境變數中加入 export OMLX_HOST=0.0.0.0，確保未來開機或重啟服務時皆能維持對外監聽。

步驟 C：放行 macOS 系統防火牆與確認模型

前往 Mac 的「系統設定」>「網路」>「防火牆」，確認防火牆允許 oMLX 接收傳入連線。接著打開伺服端瀏覽器進入 https://127.0.0.1:8000/admin，確認模型已經載入完成，並記錄下模型代號（如 mlx-community/Hermes-3-Llama-3.1-8B-4bit，或你在管理後台設定的模型別名 Alias）。

4. 連通性驗證：使用 curl 快速排查通訊管道

在著手設定工作機上的 Hermes Agent 之前，務必先確認兩台電腦之間的網路握手是否順暢。請走到客戶端電腦（你的工作筆電）前，開啟終端機執行：

curl https://192.168.1.100:8000/v1/models

若網路配置正確，終端機將會立即回傳一段結構嚴謹的 JSON 資料，列出伺服端目前掛載的模型清單：

{
  "object": "list",
  "data": [
    {
      "id": "hermes-3-8b",
      "object": "model",
      "owned_by": "omlx"
    }
  ]
}

只要能順利取得上述 JSON，就代表網路通道與防火牆已全數開通！若此時出現 Connection refused 或指令卡住超時，請停下腳步回到步驟三重新檢查 Host 是否確實為 0.0.0.0。

5. 客戶端配置：為 Hermes Agent 設定遠端 API 端點

確認底層網路相通後，接下來就是告訴 Hermes Agent：「請將所有對話與工具呼叫請求，指派到遠端的 oMLX 伺服器處理」。

方式一：手動編輯核心設定檔 (推薦，穩定可靠)

找到 Hermes Agent 的使用者家目錄設定檔 ~/.hermes/config.yaml（若不存在請手動建立），編輯為以下內容：

model:
  provider: custom
  default: "hermes-3-8b"                    # 填入步驟三查詢到的模型 ID 或別名
  base_url: "https://192.168.1.100:8000/v1"  # 伺服端內網 IP 與埠號，末端務必包含 /v1
  api_mode: chat_completions
  temperature: 0.7
  max_tokens: 4096

此外，由於許多基於 OpenAI SDK 建構的 Agent 客戶端會強制檢查環境變數中的金鑰，即便本地 oMLX 預設無須驗證，也請在 ~/.hermes/.env 檔案中補上一行虛擬金鑰以避免程式拋出缺少 Key 的警告：

OPENAI_API_KEY="omlx-local"

方式二：透過 CLI 命令列互動引導設定

如果你偏好在終端機中透過選單操作，也可以直接在工作機執行：

hermes model

在互動式提示中，Provider 選擇 Custom Endpoint，並依序填入 Base URL（https://192.168.1.100:8000/v1）以及對應的模型名稱即可。

6. 實戰演練：從 Ping 測試到自主工具調用

設定完成後，我們可以在客戶端進行兩階段測試，確保各項協同模組運作正常。

階段一：非互動式極速連線探測

在客戶端終端機執行單次探測指令，確認端點能正常回傳字串：

hermes chat -q "請簡短說明什麼是分散式推論架構？" -Q

若數秒內終端機順暢輸出繁體中文解答，恭喜你！這代表訊息已經順利往返兩台裝置。

階段二：進入完整交互式 Agent 模式

鍵入以下指令，進入全功能自主智慧工作台：

hermes chat

在對話介面中，你可以嘗試輸入稍微複雜的任務，例如：
「請幫我在目前目錄建立一個名為 network_test 的資料夾，並寫入一個能定期檢查內網連線狀態的 Python 腳本。」

此時你可以觀察到：工作機上的 Hermes Agent 會解析意圖、規劃工具調用、並在本地安全環境下執行檔案與終端機指令；而所有繁重的神經網絡推論與自然語言組織，全都在遠端的 Mac 伺服端無聲高速運轉。工作機依然冰涼省電，工作體驗極度流暢！

7. 專家級避坑指南：常見連線報錯與除錯 SOP

在建置跨裝置 API 串接的過程中，如果遇到突發狀況，可以依循下表進行快速定位：