# 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 四階段進度

**請求參數**:
```json
{
  "file_uuid": "string"
}
```

**回應格式**:
```json
{
  "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`

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

**回應格式**:
```json
{
  "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 處理統計

**回應格式**:
```json
{
  "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