momentry_studio/docs/PIPELINE_PROGRESS_UPDATE_FOR_CORE.md

Pipeline 四階段進度更新說明 - Core Team 參考

文件: Pipeline Progress Update for Core Team
日期: 2026-10-15
版本: v0.1.0
作者: Momentry Studio Team

---

📌 目的

說明 Momentry Studio 前端對 Pipeline 進度顯示的實現和需求，供 Core Team 參考實現後端 API。

---

🎯 四階段架構

階段總覽

Momentry Studio 將 Pipeline 分為四個主要階段：

階段	名稱	權重	功能
1	處理器 (Processors)	30%	原始媒體分析
2	知識圖譜 (Knowledge Graph)	35%	關係網路建構
3	片段提取 (Moment Extraction)	6%	AI 內容理解
4	資料整合 (Integration)	29%	資料入庫儲存

---

階段 1: 處理器 (Processors)

權重: 30%

包含的處理器:

• ASR: 語音識別 - 轉換語音為文字
• ASRX: 說話人向量化 (VOD) - 建立說話人身分
• FACE: 人臉檢測 - 檢測人臉位置和特徵
• Face Tracing: 人臉追蹤 - 追蹤人臉在視訊中的軌跡
• OCR: 文字識別 - 識別畫面文字
• CUT: 鏡頭切換 - 識別場景切換點

說明:

• ASRX 使用 VOD 技術將說話人語音特徵向量化
• Face Tracing 已從階段 4 移至階段 1，作為處理器執行
• 所有處理器並行執行

---

階段 2: 知識圖譜 (Knowledge Graph)

權重: 35%

包含的步驟:

• TKG Nodes: 人物/物品/對話節點建構
• TKG Edges: 人物關係/共現關係建構

---

階段 3: 片段提取 (Moment Extraction)

權重: 6%

包含的步驟:

• VLM Summary: 視訊總結
• Scene VLM: 場景理解
• Moment Chunks: 片段分割

---

階段 4: 資料整合 (Integration)

權重: 29%

包含的步驟:

Rule1 Ingestion (PostgreSQL 入庫)

• 句子區塊 (sentence_chunks)
• 關係資料 (relationship_chunks)
• 追蹤區塊 (trace_chunks)

Rule2 Ingestion (向量入庫 - Qdrant)

• 文字向量入庫: 句子嵌入向量，支援語意搜尋
• 說話人語音向量入庫: 由 ASRX 處理器生成，VOD 實現
• 人臉向量入庫: 人臉嵌入向量，支援人臉識別

Face Dedup (人臉去重)

• 去除重複的人臉檢測結果
• 合併同一人的多次檢測

---

🔍 關鍵更新說明

1. ASRX 處理器 (說話人向量化)

名稱: ASRX (非 VSRX)

功能:

• 使用 VOD 技術
• 將說話人語音特徵轉換為向量
• 建立說話人身分

位置: 階段 1 (處理器)

輸出:

• 說話人嵌入向量
• 用於後續的說話人向量入庫 (階段 4)

---

2. Face Tracing 處理器

位置變更: 階段 4 → 階段 1

原因:

• Face Tracing 是基於人臉檢測結果的追蹤
• 屬於原始媒體分析的一部分
• 應該在處理器階段完成

功能:

• 追蹤人臉在視訊中的軌跡
• 建立人臉出現序列
• 關聯同一人的多次出現

---

3. 向量入庫說明

文字向量入庫:

• 句子嵌入向量
• 支援語意搜尋和相似度匹配

說話人語音向量入庫 (VOD):

• 由 ASRX 處理器生成
• 說話人嵌入向量
• 支援說話人識別和跨視訊追蹤

人臉向量入庫:

• 人臉嵌入向量
• 支援人臉相似度搜尋和身分識別

---

📊 進度計算方式

總體進度公式

總體進度 = (階段1進度 × 30%) + (階段2進度 × 35%) + (階段3進度 × 6%) + (階段4進度 × 29%)

計算範例

範例 1: 處理器階段完成

Processors: 100% × 30% = 30%
Knowledge Graph: 0% × 35% = 0%
Moment Extraction: 0% × 6% = 0%
Integration: 0% × 29% = 0%

總體進度 = 30%

範例 2: 知識圖譜階段完成

Processors: 100% × 30% = 30%
Knowledge Graph: 100% × 35% = 35%
Moment Extraction: 0% × 6% = 0%
Integration: 0% × 29% = 0%

總體進度 = 65%

範例 3: 全部完成

Processors: 100% × 30% = 30%
Knowledge Graph: 100% × 35% = 35%
Moment Extraction: 100% × 6% = 6%
Integration: 100% × 29% = 29%

總體進度 = 100%

---

🔌 需要的 API 端點

1. Pipeline Phases API

端點: GET /api/v1/pipeline/phases

用途: 獲取檔案的 Pipeline 四階段進度

請求參數:

{
  "file_uuid": "string"
}

回應格式:

{
  "file_uuid": "abc-123",
  "phases": [
    {
      "name": "processors",
      "weight": 30,
      "progress": 0.75,
      "status": "processing",
      "processors": [
        {
          "name": "asr",
          "progress": 1.0,
          "status": "completed"
        },
        {
          "name": "asrx",
          "progress": 0.8,
          "status": "processing"
        },
        {
          "name": "face",
          "progress": 1.0,
          "status": "completed"
        },
        {
          "name": "face_tracing",
          "progress": 0.5,
          "status": "processing"
        },
        {
          "name": "ocr",
          "progress": 0.0,
          "status": "pending"
        },
        {
          "name": "cut",
          "progress": 0.0,
          "status": "pending"
        }
      ]
    },
    {
      "name": "knowledge_graph",
      "weight": 35,
      "progress": 0.0,
      "status": "pending",
      "steps": [
        {
          "name": "tkg_nodes",
          "progress": 0.0,
          "status": "pending"
        },
        {
          "name": "tkg_edges",
          "progress": 0.0,
          "status": "pending"
        }
      ]
    },
    {
      "name": "moment_extraction",
      "weight": 6,
      "progress": 0.0,
      "status": "pending",
      "steps": [
        {
          "name": "vlm_summary",
          "progress": 0.0,
          "status": "pending"
        },
        {
          "name": "scene_vlm",
          "progress": 0.0,
          "status": "pending"
        },
        {
          "name": "moment_chunks",
          "progress": 0.0,
          "status": "pending"
        }
      ]
    },
    {
      "name": "integration",
      "weight": 29,
      "progress": 0.0,
      "status": "pending",
      "steps": [
        {
          "name": "rule1_ingestion",
          "progress": 0.0,
          "status": "pending"
        },
        {
          "name": "rule2_ingestion",
          "progress": 0.0,
          "status": "pending"
        },
        {
          "name": "face_dedup",
          "progress": 0.0,
          "status": "pending"
        }
      ]
    }
  ],
  "overall_progress": 0.225
}

狀態值:

• pending: 等待中
• processing: 處理中
• completed: 已完成
• failed: 失敗

---

2. File Progress API (可選，用於快速輪詢)

端點: GET /api/v1/file/{uuid}/progress

用途: 快速獲取檔案的總體進度（不包含詳細階段資訊）

回應格式:

{
  "file_uuid": "abc-123",
  "overall_progress": 0.65,
  "status": "processing",
  "phases": {
    "processors": 100,
    "knowledge_graph": 100,
    "moment_extraction": 50,
    "integration": 0
  }
}

---

3. Scene VLM Stats API (已實現)

端點: GET /api/v1/file/{uuid}/scene-vlm-stats

用途: 獲取 Scene VLM 處理統計

回應格式:

{
  "file_uuid": "abc-123",
  "total_scenes": 10,
  "processed_scenes": 8,
  "progress": 0.8,
  "status": "processing"
}

---

🎨 前端實現說明

顯示位置

Library 頁面 → 右鍵選單 → Pipeline Progress

顯示內容

1. 四階段進度條

   • 各階段進度百分比
   • 狀態圖標 (✓ ○ ✗)
   • 階段權重標示

2. 處理器/步驟詳情

   • 階段 1: 6 個處理器進度
   • 階段 2: TKG Nodes + TKG Edges
   • 階段 3: VLM Summary + Scene VLM + Moment Chunks
   • 階段 4: Rule1 + Rule2 + Face Dedup

3. 總體進度

   • 四階段加權平均
   • 整體處理狀態

更新機制

• 輪詢間隔: 2 秒
• 更新條件: 檔案狀態為 scanning
• 停止條件: 檔案狀態為 agent_ready 或失敗

---

📋 處理器完整列表

階段 1: 處理器 (Processors)

處理器名稱	功能	輸出
ASR	語音識別	文字稿
ASRX	說話人向量化 (VOD)	說話人嵌入向量
FACE	人臉檢測	人臉位置、特徵
Face Tracing	人臉追蹤	人臉軌跡、出現序列
OCR	文字識別	畫面文字內容
CUT	鏡頭切換	場景切換點

---

🚀 建議實現順序

Phase 1: 基礎進度 API

1. 實現 GET /api/v1/pipeline/phases 端點
2. 在 Redis 中儲存進度資訊
3. Worker 更新進度

Phase 2: 階段劃分

1. 將處理器分為四個階段
2. ASRX 作為處理器 (階段 1)
3. Face Tracing 作為處理器 (階段 1)

Phase 3: 進度計算

1. 實現加權進度計算
2. 計算各階段進度
3. 計算總體進度

Phase 4: 前端整合

1. 前端調用 API
2. 顯示四階段進度
3. 即時更新

---

🔗 相關文件

1. 前端實現: src/store.ts - loadPipelinePhases(), loadFileProgress()
2. UI 顯示: src/views/LibraryView.vue - Pipeline Progress 對話框
3. 用戶說明: docs/PIPELINE_STAGES_EXPLANATION.md
4. 快速參考: docs/PIPELINE_STAGES_QUICK_REF.md

---

✅ 驗收標準

API 驗收

• GET /api/v1/pipeline/phases 返回正確的四階段資料
• 各階段進度準確
• 處理器列表包含 ASRX 和 Face Tracing
• 總體進度計算正確

進度更新驗收

• Worker 在各階段完成時更新進度
• 進度儲存在 Redis
• 前端可正確獲取進度

前端顯示驗收

• Library 頁面顯示四階段進度
• 各階段權重正確顯示
• 總體進度計算正確
• 狀態圖標正確顯示

---

📞 聯絡資訊

如有問題或需要討論，請聯繫：

Momentry Studio Team

---

最後更新: 2026-10-15
版本: v0.1.0