feat: add source prefix to search results

- Add [OCR], [ASRX], [ASRX+OCR] prefix to text_content - Add content field to SemanticSearchResult struct - Update SQL queries to include content field - Helps users distinguish the source of search results
2026-07-19 14:06:06 +08:00
parent 5e83ee7dac
commit 87aa7e0c40
10 changed files with 3947 additions and 6 deletions
@@ -0,0 +1,274 @@
+---
+document_type: "reference_doc"
+service: "MOMENTRY_CORE"
+title: "LLM 模型服務管理與配置指南"
+date: "2026-07-16"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+  - "momentry"
+  - "llm"
+  - "model"
+  - "configuration"
+ai_query_hints:
+  - "查詢 LLM 模型服務管理與配置指南 的內容"
+  - "如何切換 momentry 使用的 LLM 模型？"
+  - "有哪些 LLM 模型可以選擇？"
+  - "如何啟動或關閉 LLM 模型服務？"
+---
+
+# LLM 模型服務管理與配置指南
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | Warren |
+| 建立時間 | 2026-07-16 |
+| 文件版本 | V1.0 |
+
+---
+
+## 概述
+
+Momentry Core 支援多種 LLM 後端服務。本文說明如何：
+- 啟動 / 停止各模型服務
+- 配置 momentry_core 使用不同模型
+- 管理模型記憶體用量（M5 Max 128GB）
+
+---
+
+## 服務總覽
+
+| 端口 | 服務類型 | 模型 | 記憶體 | 文字 | Vision | 速度 |
+|------|----------|------|--------|------|--------|------|
+| `:11434` | **Ollama** (常駐) | Qwen2.5-VL:7b | 8.5GB | ✅ 中文 | ✅ 正確 | 快 |
+| `:11434` | **Ollama** (常駐) | LLaVA | 合併 | ⚠️ 英文 | ⚠️ 部分正確 | 快 |
+| `:11434` | **Ollama** (常駐) | Qwen2.5:7b | 合併 | ✅ 最佳中文 | — | 快 |
+| `:8090` | **llama.cpp** (按需) | Qwen2.5-VL-7B | 12.4GB | ✅ 中文 | ❌ 亂碼(bug) | 109 t/s |
+| `:8091` | **llama.cpp** (按需) | LLaVA 1.6 Vicuna 13B | 11.2GB | ✅ 中文 | ✅ 顏色正確 | 62 t/s |
+| `:8092` | **llama.cpp** (按需) | Gemma 3 12B | 16.0GB | ⚠️ 英文 | ✅ **中英雙語** | 60 t/s |
+| `:8081-8083` | **MarkBaseEngine** (既有) | Gemma-4 系列 | 各 0.1-2.9GB | ⚠️ 已棄用 | ❌ | — |
+
+**結論**：日常使用 **Ollama** 即可滿足多數需求。需要更強 Vision 時才啟動 `llama.cpp` 的 Gemma 3 12B 或 LLaVA 13B。
+
+---
+
+## 服務管理
+
+### Ollama（預設常駐）
+
+Ollama 已配置為 launchd 服務，開機自動啟動。
+
+```bash
+# 啟動
+sudo launchctl load /Library/LaunchDaemons/com.momentry.ollama.plist
+
+# 停止
+sudo launchctl unload /Library/LaunchDaemons/com.momentry.ollama.plist
+
+# 狀態
+launchctl list | grep ollama
+
+# 可用模型
+ollama ls
+
+# 手動執行
+ollama run qwen2.5vl:7b        # 多語言 + Vision
+ollama run llava               # Vision（英文）
+ollama run qwen2.5:7b          # 純文字（最佳中文）
+ollama run llama3.1            # 純文字（英文）
+ollama run gemma2:9b           # 純文字（多語言）
+```
+
+### llama.cpp（按需啟動）
+
+llama.cpp 模型預設**不開機啟動**（節省記憶體）。使用時手動啟動，用完關閉。
+
+**一鍵管理腳本**：
+
+```bash
+# 啟動模型（第一次會自動從 HuggingFace 下載）
+~/models/llama-cpp/run_model.sh qwen2.5-vl    # Qwen2.5-VL-7B on :8090
+~/models/llama-cpp/run_model.sh llava-13b      # LLaVA 1.6 13B on :8091
+~/models/llama-cpp/run_model.sh gemma3-12b     # Gemma 3 12B on :8092
+
+# 關閉全部
+~/models/llama-cpp/run_model.sh stop
+
+# 指定端口
+~/models/llama-cpp/run_model.sh gemma3-12b 8085
+```
+
+**手動啟動**：
+
+```bash
+llama-server -hf ggml-org/Qwen2.5-VL-7B-Instruct-GGUF --port 8090 -ngl 99
+llama-server -hf cjpais/llava-v1.6-vicuna-13b-gguf --port 8091 -ngl 99
+llama-server -hf ggml-org/gemma-3-12b-it-GGUF --port 8092 -ngl 99
+```
+
+**模型快取位置**（已下載後不需重複下載）：
+```
+~/.cache/huggingface/hub/models--ggml-org--Qwen2.5-VL-7B-Instruct-GGUF/
+~/.cache/huggingface/hub/models--cjpais--llava-v1.6-vicuna-13b-gguf/
+~/.cache/huggingface/hub/models--ggml-org--gemma-3-12b-it-GGUF/
+```
+
+### MLX-VLM（可選）
+
+```bash
+# 安裝
+pip install mlx-vlm
+
+# 啟動
+nohup python3 /tmp/mlx_server.py \
+  --model mlx-community/LLaVA-1.5-7B-4bit --port 8093 \
+  > ~/models/llama-cpp/mlx-vlm.log 2>&1 &
+```
+
+> **注意**：MLX-VLM 目前 vision API 不完整，僅支援純文字。建議優先使用 Ollama 或 llama.cpp。
+
+---
+
+## Momentry Core 配置
+
+### 環境變數（`.env` / `.env.development`）
+
+momentry_core 透過以下環境變數決定使用的 LLM 後端：
+
+| 變數 | 預設值 | 說明 |
+|------|--------|------|
+| `MOMENTRY_LLM_CHAT_URL` | `http://127.0.0.1:8082/v1/chat/completions` | 聊天/工具呼叫端點 |
+| `MOMENTRY_LLM_CHAT_MODEL` | `google_gemma-4-26B-A4B-it-Q5_K_M.gguf` | 聊天模型名稱 |
+| `MOMENTRY_LLM_VISION_URL` | 同 `CHAT_URL` | Vision 端點 |
+| `MOMENTRY_LLM_VISION_MODEL` | 同 `CHAT_MODEL` | Vision 模型名稱 |
+| `MOMENTRY_LLM_SUMMARY_URL` | 同 `CHAT_URL` | 摘要端點 |
+| `MOMENTRY_LLM_SUMMARY_MODEL` | 同 `CHAT_MODEL` | 摘要模型名稱 |
+| `MOMENTRY_LLM_SUMMARY_TIMEOUT` | 120 | 摘要超時(秒) |
+| `MOMENTRY_LLM_SUMMARY_ENABLED` | true | 啟用摘要 |
+
+### 配置範例
+
+**情境一：使用 Ollama Qwen2.5:7b（推薦日常）**
+```bash
+# .env.development 加入
+MOMENTRY_LLM_CHAT_URL=http://localhost:11434/v1/chat/completions
+MOMENTRY_LLM_CHAT_MODEL=qwen2.5:7b
+MOMENTRY_LLM_VISION_URL=http://localhost:11434/v1/chat/completions
+MOMENTRY_LLM_VISION_MODEL=qwen2.5vl:7b
+```
+
+**情境二：使用 llama.cpp Gemma 3 12B（最佳 vision）**
+```bash
+# 先啟動模型
+~/models/llama-cpp/run_model.sh gemma3-12b
+
+# .env.development 加入
+MOMENTRY_LLM_CHAT_URL=http://localhost:8092/v1/chat/completions
+MOMENTRY_LLM_CHAT_MODEL=ggml-org/gemma-3-12b-it-GGUF
+MOMENTRY_LLM_VISION_URL=http://localhost:8092/v1/chat/completions
+MOMENTRY_LLM_VISION_MODEL=ggml-org/gemma-3-12b-it-GGUF
+```
+
+**情境三：混合使用（聊天用 Ollama，Vision 用 llama.cpp）**
+```bash
+MOMENTRY_LLM_CHAT_URL=http://localhost:11434/v1/chat/completions
+MOMENTRY_LLM_CHAT_MODEL=qwen2.5:7b
+MOMENTRY_LLM_VISION_URL=http://localhost:8092/v1/chat/completions
+MOMENTRY_LLM_VISION_MODEL=ggml-org/gemma-3-12b-it-GGUF
+MOMENTRY_LLM_SUMMARY_URL=http://localhost:11434/v1/chat/completions
+MOMENTRY_LLM_SUMMARY_MODEL=qwen2.5:7b
+```
+
+---
+
+## 記憶體管理
+
+M5 Max 配備 128GB RAM，所有服務同時運行約使用 66GB：
+
+| 服務 | 記憶體 | 建議 |
+|------|--------|------|
+| Ollama (常駐) | ~8.5GB | ✅ 保持開啟 |
+| MarkBaseEngine x4 | ~4.5GB | ✅ 保持開啟（既有服務） |
+| llama.cpp Qwen2.5-VL | 12.4GB | ❌ 按需啟動 |
+| llama.cpp LLaVA 13B | 11.2GB | ❌ 按需啟動 |
+| llama.cpp Gemma 3 12B | 16.0GB | ❌ 按需啟動 |
+| MLX-VLM | 4.2GB | ❌ 按需啟動 |
+
+**建議只保留 Ollama 常駐**，llama.cpp 模型在用完後立即關閉：
+```bash
+~/models/llama-cpp/run_model.sh stop
+```
+
+---
+
+## API 相容性
+
+所有服務皆支援 OpenAI-compatible API：
+
+### 純文字請求
+```bash
+curl http://localhost:{PORT}/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [{"role": "user", "content": "你好"}],
+    "max_tokens": 100
+  }'
+```
+
+### Vision 請求
+```bash
+B64=$(base64 -i image.png)
+curl http://localhost:{PORT}/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"messages\": [{\"role\": \"user\", \"content\": [
+      {\"type\": \"image_url\", \"image_url\": {\"url\": \"data:image/png;base64,${B64}\"}},
+      {\"type\": \"text\", \"text\": \"請描述這張圖片\"}
+    ]}],
+    \"max_tokens\": 500
+  }"
+```
+
+---
+
+## 健康檢查
+
+```bash
+# 檢查 Ollama
+curl -s http://localhost:11434/api/tags | python3 -c "import sys,json; [print(m['name']) for m in json.load(sys.stdin)['models']]"
+
+# 檢查 llama.cpp
+for port in 8090 8091 8092; do
+  result=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:$port/v1/chat/completions \
+    -H "Content-Type: application/json" \
+    -d '{"messages":[{"role":"user","content":"hi"}],"max_tokens":1,"stream":false}' 2>/dev/null)
+  echo "Port $port: HTTP $result"
+done
+```
+
+---
+
+## 常見問題
+
+### Q: 啟動 llama.cpp 時 port 已被佔用？
+現有服務佔用 port 對照：
+| Port | 服務 |
+|------|------|
+| 8080-8083 | MarkBaseEngine (Gemma-4) |
+| 8084 | Embedding Server |
+| 11434 | Ollama |
+
+使用其他 port：`~/models/llama-cpp/run_model.sh gemma3-12b 8095`
+
+### Q: 模型下載很慢？
+第一次下載後會快取在 `~/.cache/huggingface/hub/`，之後不需重複下載。可預先下載：
+```bash
+ls ~/.cache/huggingface/hub/ | grep models--
+```
+
+### Q: 哪個模型最適合中文 + Vision？
+1. **Ollama Qwen2.5-VL:7b** — 中文 vision 最準確，已常駐
+2. **Gemma 3 12B (llama.cpp)** — 能以中文描述 vision 結果（含注音）
+3. **LLaVA 1.6 13B (llama.cpp)** — vision 正確但僅英文輸出