diff --git a/docs/PIPELINE_PROGRESS_UPDATE_FOR_CORE.md b/docs/PIPELINE_PROGRESS_UPDATE_FOR_CORE.md new file mode 100644 index 0000000..c218b04 --- /dev/null +++ b/docs/PIPELINE_PROGRESS_UPDATE_FOR_CORE.md @@ -0,0 +1,473 @@ +# 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 \ No newline at end of file