momentry_core/docs/ARCHITECTURE_EVALUATION.md

架構優化待評估事項

項目	內容
建立者	OpenCode
建立時間	2026-03-21
文件版本	V1.0

---

版本歷史

版本	日期	目的	操作人
V1.0	2026-03-21	創建文件	OpenCode
V1.1	2026-03-22	新增 TigerGraph/GraphRAG 說故事評估	OpenCode

---

架構優化項目

1. PostgreSQL → Redis 故障轉移

說明: 當 PostgreSQL 不可用時，降級到 Redis 作為臨時存儲

複雜度: 中

影響範圍:

• src/core/db/postgres_db.rs
• src/core/db/redis_client.rs

風險:

• 數據一致性問題
• 需要定義轉移策略

優先級: 待評估

---

2. 連接池監控

說明: 添加 PostgreSQL 和 Redis 連接池指標到 Prometheus

複雜度: 低

影響範圍:

• src/core/db/postgres_db.rs
• src/core/db/redis_client.rs
• src/api/ (新增 metrics endpoint)

風險: 低

優先級: 待評估

---

3. Processor 重試機制

說明: 當 processor 失敗時自動重試

複雜度: 中

影響範圍:

• src/core/processor/executor.rs (新增 run_with_retry 方法)
• src/core/processor/mod.rs (導出 RetryConfig)

風險:

• 無限重試風險 → 已通過 max_attempts 控制
• 需要指數退避 → 已實現

優先級: ✅ 已完成 (2026-03-21)

實作內容:

• RetryConfig 結構體 (可配置重試次數、初始延遲、最大延遲、退避倍數)
• run_with_retry() 方法 (自動重試 + 指數退避)
• 單元測試覆蓋

使用範例:

use crate::core::processor::{PythonExecutor, RetryConfig};

let executor = PythonExecutor::new()?;
let config = RetryConfig::new(3).with_delay(1000).with_max_delay(30000);

executor.run_with_retry(
    "asr_processor.py",
    &["--input", "/path/to/video"],
    Some(&uuid),
    "asr",
    Some(Duration::from_secs(3600)),
    Some(config),
).await?;

---

4. PyO3 整合

說明: Python/Rust 直接調用，移除子進程調用

複雜度: 高

影響範圍:

• src/core/processor/executor.rs (重寫)
• Python 模組 (修改為可直接 import)

風險:

• Python GIL 問題
• 依賴版本兼容性
• 需要大量重寫

優先級: 低 (長期目標)

---

5. HTTP 健康端點

說明: 添加 /health API 用於外部監控

複雜度: 低

影響範圍:

• src/api/server.rs (新增路由)

風險: 低

優先級: ✅ 已完成 (2026-03-21)

實作內容:

• GET /health - 基本健康檢查 (status, version, uptime)
• GET /health/detailed - 詳細健康檢查 (PostgreSQL, Redis, Qdrant 狀態和延遲)

---

6. Gitea Actions CI/CD

說明: 配置 Gitea Actions 自動化 CI/CD，在合併前執行檢查

複雜度: 中

影響範圍:

• .gitea/workflows/ (新增 workflow 文件)

優點:

• 強制執行檢查，無法跳過
• 跨設備一致
• PR 審查前自動檢查

風險: 低

優先級: 待評估

---

7. Commit Message Lint

說明: 規範化提交訊息格式 (Conventional Commits)

複雜度: 低

影響範圍:

• .git/hooks/commit-msg (新增 hook)
• ~/dotfiles/hooks/commit-msg

風險: 低

優先級: ✅ 已完成 (2026-03-21)

實作內容:

• 驗證格式: <type>(<scope>): <description>
• 有效類型: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
• 警告: 第一行超過 72 字符

範例:

feat(api): add health check endpoint
fix(db): resolve connection pool issue
docs: update README

---

8. 自動化安裝腳本

說明: 創建腳本一次安裝所有開發工具

複雜度: 低

影響範圍:

• scripts/install-dev-tools.sh (新增)

風險: 低

優先級: 待評估

---

評估標準

標準	說明
業務價值	對用戶有何幫助
技術風險	實現難度和潛在問題
維護成本	未來維護負擔
依賴性	對其他系統的影響

---

評估記錄

項目	評估日期	決策	原因
PostgreSQL → Redis 故障轉移	待評估	-	-
連接池監控	待評估	-	-
Processor 重試機制	2026-03-21	已完成	-
PyO3 整合	待評估	-	-
HTTP 健康端點	2026-03-21	已完成	-
Gitea Actions CI/CD	待評估	-	-
Commit Message Lint	2026-03-21	已完成	-
自動化安裝腳本	待評估	-	-

---

9. TigerGraph / Knowledge Graph 圖譜說故事

說明: 使用知識圖譜 (Knowledge Graph) 增強視頻敘事 (Storytelling) 和 RAG 檢索

複雜度: 高

研究來源:

• TigerGraph Agentic GraphRAG (2025-12-15)
• TigerGraph GraphRAG GitHub (v1.2.0, 2026-03-11)
• GraphRAG in 2026: Practitioner's Guide (2026-02-22)
• GraphRAG Complete Guide (2026-02-11)

核心概念

概念	說明
GraphRAG	結合知識圖譜與 RAG，比傳統向量檢索更智能
知識圖譜	實體 (Entity) + 關係 (Relationship) 的結構化表示
多跳推理	Multi-hop traversal，可連接多個相關節點
混合檢索	Graph traversal + Vector similarity 結合

對 Momentry 的潛在應用

視頻場景 → 實體識別 → 關係建立 → 故事圖譜
   ↓            ↓            ↓            ↓
  CUT        [人物, 物品, 動作]  [誰做了什麼, 什麼導致什麼]  [敘事鏈]

1. 敘事圖譜構建 (Narrative Graph)

• 從 Story/Chunks 模組提取實體
• 建立場景之間的因果關係
• 追蹤角色互動和情節發展

2. 故事檢索增強

# 現有: Parent-child chunks
parent_chunk: "場景描述"
child_chunks: [詳細內容]

# 加入圖譜:
場景A --led_to--> 場景B
角色X --interacted_with--> 角色Y
主題Y --related_to--> 主題Z

3. 查詢模式

查詢類型	傳統 RAG	GraphRAG
事實查找	✅ "這個場景在說什麼"	✅
主題推理	❌ "這個視頻的主要情節"	✅ Global search
多跳關係	❌	✅ "A導致B，B導致C"
可解釋性	❌	✅ 關係路徑可追溯

實作方案

方案 A: TigerGraph Cloud (推薦)

• ✅ 原生 Graph + Vector 混合查詢
• ✅ GraphRAG 官方支援
• ✅ 200GB 免費額度
• ❌ 雲端依賴，延遲敏感場景需考慮

方案 B: Neo4j + Qdrant

• ✅ 成熟開源生態
• ✅ LangChain/LlamaIndex 整合
• ❌ 需要維護兩個系統

方案 C: 自建混合架構

• PostgreSQL + Neo4j (或Typesense)
• 利用現有 BM25 + 向量檢索基礎
• ❌ 開發成本高

技術棧整合建議

// 現有架構
Vector Search (Qdrant) ← BM25 (PostgreSQL)

// 加入 GraphRAG
Knowledge Graph (TigerGraph/Neo4j) 
       ↓
  混合檢索 ← Vector + Graph traversal

優先級: 待評估

考慮因素:

• 用戶是否需要複雜的故事情節查詢？
• 實體識別 (NER) 成本是否可以接受？
• 與現有 BM25 + Vector 混合搜索的比較優勢？

---

10. LazyGraphRAG / FastGraphRAG 成本優化

說明: GraphRAG 索引成本高昂，LazyGraphRAG 推遲圖譜構建到查詢時

來源: GraphRAG in 2026

Microsoft GraphRAG 問題: $33K 索引大型數據集

替代方案:

• LazyGraphRAG: 按需構建，查詢時再建立子圖
• FastGraphRAG: 優化索引管道，10-90% 成本節省
• HippoRAG: 使用 Personalised PageRank 優化遍歷

優先級: 待評估 (作為 GraphRAG 的一部分)