mac-mini/README.md

mac-mini

家中 LLM 主機 mac-mini.internal.lotimmy.com 的設定與操作筆記。

硬體

• 機器: Apple Mac mini, M4 (10 cores)
• 記憶體: 24 GB unified memory (Metal/MLX backend)
• 架構: arm64
• 使用者: timmy
• 位址: mac-mini.internal.lotimmy.com (192.168.88.15)

已安裝工具 (Homebrew, /opt/homebrew)

工具	版本	用途
llmfit	0.9.5	分析硬體適配的 LLM 模型、下載 GGUF
llama.cpp	b8680	LLM 推論引擎 (Metal backend 已驗證)
ggml	0.9.11	llama.cpp 依賴

容器 (Apple container)

Apple 原生容器 runtime,取代已移除的 OrbStack/Docker。非 Homebrew — 由官方簽章 .pkg 安裝,裝在 /usr/local/bin。

項目	值
版本	1.1.0
需求	Apple Silicon + macOS 26
安裝來源	github.com/apple/container releases 的 container-<ver>-installer-signed.pkg

# 安裝 (需 sudo,要在真正的 Terminal 跑)
sudo installer -pkg container-1.1.0-installer-signed.pkg -target /

# 首次啟動 + 非互動裝 kata kernel
container system start --enable-kernel-install

# 常用
container run --rm docker.io/library/alpine echo hi   # 跑容器
container images ls        # 列 image
container ls               # 列執行中容器
container system status    # 服務狀態

⚠️ container system start 若不加 --enable-kernel-install,會互動詢問是否下載預設 kernel;非互動 SSH 沒 stdin 會 Error: failed to read user input,固定用該 flag。

已下載模型

模型	路徑	大小	速度
Gemma 4 E4B-it (Q8_0)	~/.cache/llmfit/models/gemma-4-E4B-it-Q8_0.gguf	7.6 GB	~18.7 tok/s (Metal)

連線

ssh mac-mini.internal.lotimmy.com

⚠️ 用 IP (192.168.88.15) 連線會 host-key verification failed,固定用 hostname。

VNC / 螢幕共享

本機開圖形桌面:

open -n vnc://timmy@mac-mini.internal.lotimmy.com

前提是遠端已在「系統設定 → 一般 → 共享 → 螢幕共享」把開關打開。這個授權主開關只能用 GUI(或 MDM)開,SSH 完全翻不動 — 詳見踩雷紀錄第 6 條。

常用指令

Homebrew / llmfit / llama.cpp

非互動 SSH session 載入 PATH:

ssh mac-mini.internal.lotimmy.com 'eval "$(/opt/homebrew/bin/brew shellenv)" && <command>'

llmfit

llmfit system                              # 顯示硬體規格
llmfit fit --no-dashboard --limit 15       # 列出適配模型
llmfit search <keyword> --no-dashboard     # 搜尋模型
llmfit info <model> --no-dashboard         # 看單一模型詳情
llmfit download <repo> --quant <quant>     # 下載 GGUF

跑 Gemma 4 E4B

# 互動式對話
llama-cli -m ~/.cache/llmfit/models/gemma-4-E4B-it-Q8_0.gguf -ngl 999 --jinja

# 單次推論 (非互動)
llama-completion -m ~/.cache/llmfit/models/gemma-4-E4B-it-Q8_0.gguf \
    -p "你的提示" -n 200 -ngl 999 --jinja

# OpenAI 相容 API server (port 8080)
llama-server -m ~/.cache/llmfit/models/gemma-4-E4B-it-Q8_0.gguf -ngl 999 --jinja

踩雷紀錄

1. brew 不在預設 SSH PATH — 必須先跑 eval "$(/opt/homebrew/bin/brew shellenv)",否則 brew/llmfit/llama-* 都會 command not found。

2. llama-cli -no-cnv 在 b8680 不支援 — 會印一行錯誤訊息然後依然進入 chat 模式空轉。

   • 單次推論 → 用 llama-completion
   • 互動聊天 → 用 llama-cli (不加 -no-cnv)

3. Gemma 4 必須加 --jinja — 否則 llama-completion 會丟 std::runtime_error: this custom template is not supported, try using --jinja。

4. -ngl 999 強制全部層丟 GPU — 沒指定時 auto-detection 可能掉到 CPU,慢約 5 倍。

5. 驗證輸出時不要 pipe tail — llama-cli 互動模式會持續印 > prompt,pipe tail 看不到生成內容,還會把 stdout 撐到 GB 級。要嘛用 llama-completion,要嘛 redirect 到檔案再讀。

6. macOS 26 開螢幕共享:只能 GUI/MDM,別浪費時間在 CLI — 「連線失敗 / 不允許螢幕共享,請在系統設定停用並重新啟用」這個錯誤,不是 launchctl / kickstart / SRP / 存取群組能修的。實測全部無效:

   • launchctl enable/bootstrap system/com.apple.screensharing → daemon 有跑、port 5900 有 LISTEN,但握手仍被拒
   • kickstart -activate(啟用 Remote Management)→ 印警告 Screen recording/control might be disabled ... must be enabled from System Settings or via MDM,本身就是官方在說 CLI 開不動
   • AllowSRPForNetworkNodes -bool true、加 com.apple.access_screensharing 群組 → 都沒用
   • 唯一解:實體到那台「系統設定 → 一般 → 共享 → 螢幕共享」把開關打開(已開就關掉再開,對應錯誤訊息的「停用並重新啟用」)。這個授權主開關受保護,SSH 摸不到。→ headless 機器至少要接一次螢幕鍵鼠開好它。
   • sudo ssh 要密碼但 ! 前綴管道無 tty → sudo 會 a terminal is required;這類指令要在真正的 Terminal.app 跑。

7. VNC 連線選「標準」,別選「高效能」 — 「高效能」會建立一個虛擬顯示器,VNC 看到的是虛擬螢幕、不是電視畫面;那個多出來的隱形顯示器還會讓電視卡在「鏡像輸出或延伸顯示」引導畫面出不來。「標準」= 共享實際螢幕,跟電視完全同步。

   • 電視卡引導畫面時,killall WindowServer、killall AirPlayUIAgent、displayplacer 重套設定都清不掉;鍵鼠能點就點掉,不能點就設好自動登入後重開機。

8. 重開機後 screensharing 不會自動起來 — 5900 關著時用 sudo launchctl enable system/com.apple.screensharing && sudo launchctl bootstrap system /System/Library/LaunchDaemons/com.apple.screensharing.plist 拉起來(這跟第 6 條不衝突:主開關已在 GUI 開過、只是服務沒被 launchd 載入時,CLI 拉得動)。

9. headless 主機必設自動登入 — 沒設的話重開機停在登入視窗,藍牙鍵鼠不聽話就卡死。GUI 設定在「使用者與群組 → 自動登入」;純 CLI 要把密碼 XOR 加密寫 /etc/kcpassword + defaults write /Library/Preferences/com.apple.loginwindow autoLoginUser timmy。

24 GB 記憶體下的模型選擇

• 旗艦 (吃緊): gemma-4-26B-A4B-it MoE → 16.8 GB at 4-bit (70% 記憶體)
• 平衡: gemma-4-E4B-it Q8 → 9 GB (37% 記憶體) ← 目前使用
• 同類選擇: Qwen3-Coder-30B-A3B-Instruct MoE 系列 (llmfit 評分前段)