deploy: Gemma 4 31B llama-server running on M5 Max (192.168.110.201:8081)

docs_v1.0/API_V1.0.0/DEPLOY/GEM4_LLM_DEPLOY_PLAN_V1.0.0.md

@@ -0,0 +1,159 @@
+---
+document_type: "deployment_plan"
+service: "MOMENTRY_CORE"
+title: "Gemma 4 LLM 部署計劃 — M5 Max MacBook Pro"
+date: "2026-05-06"
+version: "V1.0"
+status: "draft"
+owner: "Warren"
+created_by: "OpenCode"
+---
+
+# Gemma 4 LLM 部署計劃 — M5 Max
+
+## 1. 環境
+
+| 項目 | 規格 |
+|------|------|
+| 機型 | MacBook Pro M5 Max |
+| 統一記憶體 | 48 GB |
+| 架構 | arm64 (Apple Silicon) |
+| SSH | `accusys@10.10.10.10` |
+| 外網 | ❌ 無（需透過本機 scp） |
+| 本機 | M4 Mac，有外網，已有 llama.cpp |
+
+## 2. 模型選擇
+
+| 版本 | 參數 | Q5_K_M 大小 | 預估速度 | 備註 |
+|------|------|------------|---------|------|
+| **Gemma 4 31B-it** | 33B | ~20 GB | 15-25 tok/s | 多模態，可處理圖像 |
+| Gemma 4 26B-A4B-it | 27B MoE | ~15 GB | 25-40 tok/s | MoE，更快 |
+| Gemma 4 E4B-it | 8B | ~5 GB | 60+ tok/s | 最快，品質較低 |
+
+**推薦**: Gemma 4 31B-it (Q5_K_M)。48GB 記憶體綽綽有餘。
+
+## 3. 部署步驟
+
+### Step 1: 本機下載模型
+
+```bash
+# 登入 HuggingFace（需 access token）
+huggingface-cli login
+
+# 下載 Gemma 4 31B GGUF
+huggingface-cli download bartowski/gemma-4-31B-it-GGUF \
+  gemma-4-31b-it-Q5_K_M.gguf \
+  --local-dir ~/llama.cpp/models/
+```
+
+### Step 2: 準備 llama.cpp binary
+
+```bash
+# llama.cpp 已安裝於本機 /opt/homebrew/bin/llama-server
+# 收集依賴的 dylib
+mkdir -p /tmp/llama_bundle/bin /tmp/llama_bundle/lib
+cp /opt/homebrew/bin/llama-server /tmp/llama_bundle/bin/
+cp /opt/homebrew/lib/libggml*.dylib /tmp/llama_bundle/lib/
+cp /opt/homebrew/lib/libllama*.dylib /tmp/llama_bundle/lib/
+```
+
+### Step 3: scp 到 M5 Max
+
+```bash
+# 傳送 binary
+scp -r /tmp/llama_bundle/* accusys@10.10.10.10:~/bin/
+
+# 傳送模型
+scp ~/llama.cpp/models/gemma-4-31b-it-Q5_K_M.gguf \
+  accusys@10.10.10.10:~/models/
+
+# 傳送模型（若檔案太大可分批或用 rsync）
+rsync -avz --progress ~/llama.cpp/models/ accusys@10.10.10.10:~/models/
+```
+
+### Step 4: M5 Max 上啟動
+
+```bash
+ssh accusys@10.10.10.10
+
+# 設定 library path
+export DYLD_LIBRARY_PATH=~/bin/lib:$DYLD_LIBRARY_PATH
+
+# 啟動 llama-server
+~/bin/bin/llama-server \
+  -m ~/models/gemma-4-31b-it-Q5_K_M.gguf \
+  --host 0.0.0.0 \
+  --port 8081 \
+  --n-gpu-layers 999 \
+  --ctx-size 8192 \
+  --threads 10 \
+  --parallel 2 \
+  --mlock
+```
+
+## 4. 記憶體分配
+
+```
+48 GB total
+  ├─ 20 GB  Gemma 4 31B Q5_K_M
+  ├─  4 GB  PostgreSQL
+  ├─  1 GB  Redis
+  ├─  1 GB  MongoDB + Qdrant
+  ├─  2 GB  swift_face / face_processor (burst)
+  ├─  3 GB  llama-server overhead
+  └─ 17 GB  剩餘 (OS + buffer)
+```
+
+## 5. Momentry 整合
+
+更新 `.env` 或 config：
+
+```bash
+MOMENTRY_LLM_ENDPOINT=http://10.10.10.10:8081/v1
+MOMENTRY_LLM_MODEL=gemma-4-31b-it
+```
+
+Agent 端點改用 LLM：
+- `POST /api/v1/agents/translate` → llama.cpp server
+- `POST /api/v1/agents/identity/suggest` → llama.cpp server
+- `POST /api/v1/agents/5w1h/analyze` → llama.cpp server
+- `POST /api/v1/agents/suggest/merge` → llama.cpp server
+
+## 6. 測試驗證
+
+```bash
+# Health check
+curl http://10.10.10.10:8081/health
+
+# Inference test
+curl http://10.10.10.10:8081/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gemma-4-31b-it",
+    "messages": [{"role": "user", "content": "Hello"}],
+    "max_tokens": 100
+  }'
+```
+
+## 7. 啟動腳本（M5 Max 上）
+
+```bash
+#!/bin/bash
+# ~/start_llm.sh
+export DYLD_LIBRARY_PATH=~/bin/lib:$DYLD_LIBRARY_PATH
+exec ~/bin/bin/llama-server \
+  -m ~/models/gemma-4-31b-it-Q5_K_M.gguf \
+  --host 0.0.0.0 --port 8081 \
+  --n-gpu-layers 999 --ctx-size 8192 \
+  --threads 10 --parallel 2 --mlock \
+  >> ~/llama.log 2>&1
+```
+
+## 8. 風險與備案
+
+| 風險 | 備案 |
+|------|------|
+| GGUF 下載失敗（HF gated） | 用 ollama pull + ollama export to GGUF |
+| M5 Max Metal 不相容 | 改用 CPU only (`--n-gpu-layers 0`) |
+| 31B 太大速度太慢 | 改用 26B-A4B (MoE, 更快) |
+| scp 傳輸中斷 | 用 rsync --partial 續傳 |