| name | llm-benchmark |
| description | Use when the user wants to test, compare, or choose local Ollama models for their machine. Checks Ollama/GPU state, recommends model sizes from available VRAM, preserves existing benchmark records, pulls only approved models, runs repeatable benchmarks, restores stopped services, and writes a markdown comparison report. NOT for hosted API model evaluation or subjective chat-quality judging without local benchmark commands. |
| version | 1.0.1 |
| status | stable |
| triggers | ["/llm-benchmark","測本地模型","模型 benchmark","比較 ollama 模型"] |
LLM Benchmark Skill
You are a local LLM benchmarking specialist. 你負責用可重現的命令測 Ollama 模型效能，保護使用者現有服務狀態，並把推薦和限制講清楚。
不適用
- 不評測雲端 API 模型。
- 不用單次主觀聊天感覺取代 benchmark。
- 不在未確認硬體與服務狀態前直接 pull 大模型或重啟服務。
執行以下完整流程：
Step 0：環境檢查
curl -s http://localhost:11434/api/version 2>/dev/null || echo "NOT_RUNNING"
which ollama 2>/dev/null || echo "NOT_INSTALLED"
- 若 未安裝：執行
curl -fsSL https://ollama.com/install.sh | sh，再啟動服務
- 若 未運行：執行
ollama serve & 或 systemctl start ollama
- 確認成功後繼續
Step 0.5：VRAM 清空（benchmark 前必做）
1. 停止其他吃 GPU / RAM 的本地 LLM 服務（若有且正在運行）
LLM_GATEWAY="your-llm-gateway"
docker ps --format '{{.Names}}' | grep -i "$LLM_GATEWAY"
記錄該服務是否原本是啟動的，benchmark 完成後需還原狀態。
2. 重啟 Ollama 清除 VRAM（必做）
sudo systemctl restart ollama
sleep 5
3. 確認 VRAM 已釋放
nvidia-smi --query-gpu=memory.used,memory.free --format=csv,noheader,nounits
確認 memory.used 降到 ~1500 MB 以下再繼續。若仍偏高，再等 5 秒重確認。
4. Benchmark 完成後還原服務
若步驟 1 有停止服務，benchmark 全部完成後執行：
cd "$LLM_STACK_DIR" && docker compose start "$GATEWAY_SERVICE"
Step 1：取得 GPU/VRAM 資訊
nvidia-smi --query-gpu=name,memory.total,memory.free --format=csv,noheader,nounits 2>/dev/null \
|| rocm-smi --showmeminfo vram 2>/dev/null \
|| echo "NO_GPU"
依據 可用 VRAM 推薦模型最大參數量（以 Q4 量化為基準）：
| 可用 VRAM | 推薦最大 B |
|---|
| < 4 GB | 3B |
| 4–6 GB | 7B |
| 6–8 GB | 8B |
| 8–10 GB | 12–14B |
| 10–14 GB | 14B |
| 14–16 GB | 14–20B |
| > 16 GB | 30B+ |
向使用者說明推薦理由，列出推薦模型清單（附 Ollama model tag）。
Step 2：確認要測試的模型
詢問使用者確認測試清單（若使用者已在指令中指定則略過）。
同時列出機器上 現有模型：
curl -s http://localhost:11434/api/tags | python3 -c "
import sys,json
data=json.load(sys.stdin)
for m in data.get('models',[]):
print(m['name'], round(m['size']/1024/1024), 'MB')
"
Step 3：檢查既有 Benchmark 記錄
檢查 ~/benchmark_results.json 是否存在：
python3 -c "
import json, os
path = os.path.expanduser('~/benchmark_results.json')
if not os.path.exists(path):
print('NO_BENCHMARK_FILE')
else:
data = json.load(open(path))
benchmarked = [e['model'] for e in data]
print('BENCHMARKED:', benchmarked)
"
- 若某模型已有 benchmark 記錄 → 直接沿用，不重跑
- 若機器上有模型但無 benchmark 記錄 → 詢問使用者是否要補跑
- 若是新模型（需先 pull）→ 自動 pull 後跑 benchmark
Step 4：Pull 新模型
ollama pull <model_tag>
pull 完成後確認：ollama list | grep <model_name>
Step 5：執行 Benchmark
將 skills/llm-benchmark/scripts/benchmark.py 複製到目標機器並執行：
scp scripts/benchmark.py USER@PC_IP:/tmp/benchmark.py
python3 /tmp/benchmark.py <model1> <model2> ...
benchmark.py 的完整原始碼在 scripts/benchmark.py。
Step 6：生成 Markdown 報告
benchmark 完成後，讀取 ~/benchmark_results.json，生成 ~/model_benchmark.md。
報告結構（參考 ~/model_benchmark.md）：
- 執行環境（CPU / GPU / RAM / OS）
- 測試模型列表（參數量、最大 ctx、檔案大小）
- Token/s 速度總覽表格（模型 × context size）
- 若某個 ctx size 的
cpu_offload_detected 為 true，在表格該格標示「⚠️ 中止」，並加註說明：
此 context size 的 KV cache 超過 GPU VRAM 容量，Ollama 自動將計算 offload 至 CPU，導致 GPU 使用率驟降、CPU 全速運轉，推理速度大幅劣化。測試已提前終止，此 ctx 不列入甜蜜點評估。
- GPU 資源使用（VRAM、GPU 利用率）
- 回答品質評估（每題正確性分析 + 摘要）
- Context Window 甜蜜點分析（僅含未觸發 cpu_offload 的 ctx）
- 瓶頸分析（Compute Bound vs Memory Bandwidth Bound）
- 排名（邏輯推理 / 程式設計 / Token/s）
- 結論與建議（依使用情境推薦）
Step 7：結論說明
向使用者口頭總結：
- 各模型 token/s 排名
- 回答品質排名（重點標注邏輯題正確性）
- VRAM 使用量
- 最終推薦：哪個模型適合什麼情境
注意事項
- 全程使用繁體中文
- 每個推理超時設 120 秒，避免卡住
- 若模型 pull 失敗，記錄原因後繼續測其他模型
- 生成報告前先確認
~/benchmark_results.json 完整性
- 報告最後更新時間戳記
