docs: pipeline services checklist for M4

docs_v1.0/M4_workspace/2026-05-14_pipeline_services_checklist.md

@@ -0,0 +1,60 @@
+# Pipeline 服務檢查清單
+
+**Date**: 2026-05-14
+**From**: M5
+**To**: M4
+**Ref**: `health/detailed` → `pipeline` 區塊
+
+---
+
+## 必要服務
+
+| 服務 | Port | 用途 | 啟動方式 |
+|------|------|------|----------|
+| PostgreSQL | 5432 | 主資料庫 | 系統服務 |
+| Redis | 6379 | Cache / job queue | 系統服務 |
+| Qdrant | 6333 | 向量資料庫 | `services/qdrant/` |
+| **EmbeddingGemma** | **11436** | Text embedding (768D) | `scripts/embeddinggemma_server.py --port 11436` |
+| **llama.cpp (Gemma4)** | **8082** | LLM summary / QA | `llama-server -m models/gemma4.gguf --port 8082` |
+| MongoDB | 27017 | Cache / session | 系統服務 |
+| ffmpeg-full | — | 影片處理、drawtext overlay | Homebrew: `ffmpeg-full` |
+
+## 可選服務
+
+| 服務 | Port | 用途 | 備註 |
+|------|------|------|------|
+| GDINO | 8080 | 物件偵測 (QA agent) | 未啟用時不影響 pipeline |
+| Ollama | 11434 | 替代 LLM backend | 目前 embedding 專用 (bge-m3) |
+
+## Pipeline 必要條件
+
+執行 `register`（新影片 pipeline）前需確認：
+
+```
+GET /health/detailed
+{
+  "pipeline": {
+    "scripts": true,        ← 有 scripts/ 目錄
+    "models": true,         ← 有 models/ 目錄
+    "ffmpeg": true,         ← ffmpeg-full 可執行
+    "embedding_server": ok, ← port 11436
+    "llm": ok               ← port 8082 (Gemma4)
+  }
+}
+```
+
+vector search 仰賴 `embedding_server`（11436）在 register 階段產生 chunk embeddings。若未啟動，pipeline 會跳過 vectorization，搜尋功能無向量可比對。
+
+## 啟動順序
+
+```bash
+# 1. Embedding server（text → 768D 向量）
+python3 scripts/embeddinggemma_server.py --port 11436 &
+
+# 2. LLM（Gemma4 via llama.cpp）
+llama-server -m models/google_gemma-4-26B-A4B-it-Q5_K_M.gguf \
+  --host 0.0.0.0 --port 8082 -ngl 99 -c 16384 --temp 0.1 &
+
+# 3. momentry API server
+DATABASE_SCHEMA=public ./momentry server --port 3002
+```