# 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](https://github.com/apple/container) releases 的 `container-<ver>-installer-signed.pkg` |

```bash
# 安裝 (需 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) |

## 連線

```bash
ssh mac-mini.internal.lotimmy.com
```

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

### VNC / 螢幕共享

本機開圖形桌面:

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

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

## 常用指令

### Homebrew / llmfit / llama.cpp

非互動 SSH session 載入 PATH:

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

### llmfit

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

```bash
# 互動式對話
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 跑。

## 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 評分前段)