momentry_core/docs/MOMENTRY_RAG_PRESENTATION.md

Momentry Core 影片 RAG 系統說明稿

項目	內容
建立者	Warren
建立時間	2026-03-22
文件版本	V1.1

---

版本歷史

版本	日期	目的	操作人	工具/模型
V1.0	2026-03-22	創建文件	Warren	OpenCode / MiniMax M2.5
V1.1	2026-03-25	更新API回應格式 (media_url→file_path) 與認證標頭	OpenCode	deepseek-reasoner

---

系統架構

┌─────────────────────────────────────────────────────────────┐
│                        使用者                                │
│                    (marcom 團隊)                            │
└─────────────────┬───────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────────┐
│                    WordPress 入口                            │
│              (wp.momentry.ddns.net)                        │
└─────────────────┬───────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────────┐
│                      n8n 自動化                             │
│               (localhost:5678)                             │
│                                                               │
│   [Webhook] → [HTTP Request] → [處理結果] → [回覆用戶]       │
└─────────────────┬───────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────────┐
│                  Momentry Core API                          │
│                (localhost:3002)                             │
│                                                               │
│   POST /api/v1/search     → 語意搜尋                         │
│   POST /api/v1/n8n/search → n8n 專用格式                     │
│   GET  /api/v1/videos    → 影片列表                         │
└─────────────────┬───────────────────────────────────────────┘
                  │
        ┌─────────┴──────────┐
        ▼                    ▼
┌───────────────┐    ┌───────────────┐
│  PostgreSQL   │    │    Qdrant     │
│  (chunks)     │    │  (vectors)    │
└───────────────┘    └───────────────┘

---

資料流程

1. 上傳影片 → SFTPGo
2. 影片註冊 → PostgreSQL
3. ASR 處理 → 產生字幕區塊
4. 儲存 chunks → PostgreSQL
5. 向量化 → Qdrant
6. 搜尋查詢 → API
7. 回傳結果 → n8n → 用戶

---

示範影片

項目	內容
檔案名稱	Old_Time_Movie_Show_-_Charade_1963.HD.mov
UUID	a1b10138a6bbb0cd
時長	6879 秒（約 1.9 小時）
區塊數	3,886 個
向量數	3,688 個

---

API 端點

1. 語意搜尋

POST http://localhost:3002/api/v1/search

請求：

{
  "query": "charade",
  "limit": 5,
  "uuid": "a1b10138a6bbb0cd"
}

注意:

1. API 認證: 所有 /api/v1/* 端點需要 X-API-Key 標頭
2. 檔案路徑轉換: API 現在返回 file_path（檔案系統路徑），需要轉換為可訪問的 URL（例如透過 SFTPGo 分享連結）

---

2. n8n 專用格式

POST http://localhost:3002/api/v1/n8n/search

請求：

{
  "query": "charade",
  "limit": 5
}

回應：

{
  "query": "charade",
  "count": 5,
  "hits": [
    {
      "id": "sentence_0006",
      "vid": "a1b10138a6bbb0cd",
      "start": 48.8,
      "end": 55.44,
      "title": "Chunk sentence_0006",
      "text": "fun plot twists...",
      "score": 0.526,
      "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"
    }
  ]
}

---

實作範例

n8n Workflow 設計

┌─────────────┐
│ Webhook     │  ← 接收用戶搜尋請求
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ HTTP Request│  → POST /api/v1/n8n/search
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Code        │  → 處理回傳結果
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Telegram    │  → 回覆給用戶
│ (或 LINE)   │
└─────────────┘

---

Step-by-Step n8n Workflow

Step 1: 建立 Webhook

1. n8n 開新 Workflow
2. 新增 node: Webhook
3. 設定 path: video-search
4. 複製 Webhook URL

---

Step 2: 設定 HTTP Request

1. 新增 node: HTTP Request

2. 設定：

   Method: POST
   URL: http://localhost:3002/api/v1/n8n/search
   Body Content Type: JSON
   Headers: X-API-Key (需設定)
   

3. Body:

{
  "query": "={{ $json.body }}",
  "limit": 5
}

---

Step 3: 處理結果 (Code)

const hits = $input.first().json.hits;

if (!hits || hits.length === 0) {
  return {
    json: { message: "找不到相關結果" }
  };
}

const results = hits.map((hit, index) => ({
  number: index + 1,
  text: hit.text,
  time: `${hit.start}s - ${hit.end}s`,
  score: Math.round(hit.score * 100) + "%",
  // 注意: API 現在返回 file_path（檔案系統路徑），需要轉換為可訪問的 URL
  url: hit.file_path + "#t=" + hit.start + "," + hit.end // 需實作檔案路徑轉換為 URL
}));

return { json: { results } };

注意:

1. API 認證: 所有 /api/v1/* 端點需要 X-API-Key 標頭
2. 檔案路徑轉換: API 現在返回 file_path（檔案系統路徑），需要轉換為可訪問的 URL（例如透過 SFTPGo 分享連結）

---

Step 4: 格式化輸出

Telegram 格式：

🎬 搜尋結果: "{{ $json.query }}"

1️⃣ "fun plot twists, Woody Dialog and charming performances..."
   ⏱ 48.8s - 55.4s
   📊 相關度: 53%

2️⃣ "Don't you like me to say that a pretty girl..."
   ⏱ 4745.6s - 4748.6s
   📊 相關度: 52%

---

測試指令

curl 測試

# 語意搜尋
curl -X POST http://localhost:3002/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"query": "charade", "limit": 3}'

# n8n 格式
curl -X POST http://localhost:3002/api/v1/n8n/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"query": "charade", "limit": 3}'

# 影片列表
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/videos

# 特定影片區塊
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/videos/a1b10138a6bbb0cd/chunks

---

實際搜尋範例

搜尋詞	結果摘要
charade	"fun plot twists, Woody Dialog and charming performances..."
woody	"Well, you thick skull hair, brain half-witted..."
classic movie	"Hello and welcome to the old-time movie show..."
charming	"fun plot twists, Woody Dialog and charming performances..."

---

資料庫狀態

資料庫	資料筆數	狀態
PostgreSQL (videos)	4	✅
PostgreSQL (chunks)	3,950	✅
PostgreSQL (vectors)	1,870	✅
Qdrant (vectors)	3,688	✅
Redis (job cache)	4 keys	✅

---

下一步

1. 建立 SFTPGo 分享連結

   • 開啟 http://localhost:8080
   • 登入 demo / demopassword123
   • 建立影片分享連結

2. 測試 n8n Workflow

   • 匯入 Postman Collection
   • 建立 Webhook
   • 測試搜尋

3. 整合到 WordPress

   • 建立表單接收用戶輸入
   • 呼叫 n8n Webhook
   • 顯示搜尋結果

---

快速開始

# 1. 測試搜尋 API
curl -X POST http://localhost:3002/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "charade", "limit": 3}'

# 2. 查看影片列表
curl http://localhost:3002/api/v1/videos

# 3. 查看 n8n 是否運行
curl http://localhost:5678