feat: Initial v0.9 release with API Key authentication
## v0.9.20260325_144654 ### Features - API Key Authentication System - Job Worker System - V2 Backup Versioning ### Bug Fixes - get_processor_results_by_job column mapping Co-authored-by: OpenCode
This commit is contained in:
accusys
271
docs/PROCESSING_PIPELINE.md
Normal file
271
docs/PROCESSING_PIPELINE.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# Video Processing Pipeline - 處理流程
|
||||
|
||||
> 建立時間: 2026-03-22
|
||||
|
||||
---
|
||||
|
||||
## 處理流程架構
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Video Processing Pipeline │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Stage 1: JSON 生成 (Process) │ │
|
||||
│ │ │ │
|
||||
│ │ video.mp4 ──→ [ASR] ──→ asr.json (語音辨識) │ │
|
||||
│ │ ──→ [CUT] ──→ cut.json (場景偵測) │ │
|
||||
│ │ ──→ [ASRX] ──→ asrx.json (說話者分離) │ │
|
||||
│ │ ──→ [YOLO] ──→ yolo.json (物體偵測) │ │
|
||||
│ │ ──→ [OCR] ──→ ocr.json (文字辨識) │ │
|
||||
│ │ ──→ [Face] ──→ face.json (人臉偵測) │ │
|
||||
│ │ ──→ [Pose] ──→ pose.json (姿態估計) │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Stage 2: 入庫 (Import) │ │
|
||||
│ │ │ │
|
||||
│ │ .json files ──→ PostgreSQL (fs_json = true) │ │
|
||||
│ │ ↓ │ │
|
||||
│ │ pre_chunks 表 (from ASR, CUT) │ │
|
||||
│ │ frames 表 (from YOLO, OCR, Face, Pose) │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Stage 3: Chunk 生成 (Chunk) │ │
|
||||
│ │ │ │
|
||||
│ │ pre_chunks ──→ [Chunk Rule] ──→ chunks 表 │ │
|
||||
│ │ ↓ │ │
|
||||
│ │ 清洗 → 純文字 │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Stage 4: 向量化 (Vectorize) │ │
|
||||
│ │ │ │
|
||||
│ │ chunks ──→ [Embedding Model] ──→ vectors │ │
|
||||
│ │ ↓ │ │
|
||||
│ │ Qdrant (主要向量庫) │ │
|
||||
│ │ PGVector (備份向量庫) │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Stage 5: 搜尋 (Search) │ │
|
||||
│ │ │ │
|
||||
│ │ Natural Language Query ──→ [Embedding] ──→ [Qdrant Search] │ │
|
||||
│ │ ↓ │ │
|
||||
│ │ 返回結果含 media_url │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CLI 命令
|
||||
|
||||
### Stage 1: JSON 生成 (Process)
|
||||
|
||||
```bash
|
||||
# 基本用法
|
||||
cargo run --bin momentry -- process <uuid_or_path>
|
||||
|
||||
# 只處理特定模組
|
||||
cargo run --bin momentry -- process <uuid> --modules asr,cut
|
||||
|
||||
# 強制重新處理（忽略完整性檢查）
|
||||
cargo run --bin momentry -- process <uuid> --force
|
||||
|
||||
# 從中斷點續傳
|
||||
cargo run --bin momentry -- process <uuid> --resume
|
||||
|
||||
# 模組使用雲端處理
|
||||
cargo run --bin momentry -- process <uuid> --modules yolo,face --cloud yolo
|
||||
|
||||
# 完整範例
|
||||
cargo run --bin momentry -- process /path/to/video.mp4 \
|
||||
--modules asr,cut,yolo,ocr \
|
||||
--cloud yolo
|
||||
```
|
||||
|
||||
### Stage 2: 入庫 (Import)
|
||||
|
||||
```bash
|
||||
# 目前入庫在 process 完成後自動執行
|
||||
# 計劃新增獨立的 import 命令
|
||||
# cargo run --bin momentry -- import <uuid>
|
||||
```
|
||||
|
||||
### Stage 3: Chunk 生成
|
||||
|
||||
```bash
|
||||
# 生成 chunks
|
||||
cargo run --bin momentry -- chunk <uuid>
|
||||
```
|
||||
|
||||
### Stage 4: 向量化
|
||||
|
||||
```bash
|
||||
# 向量化 chunks
|
||||
cargo run --bin momentry -- vectorize <uuid>
|
||||
|
||||
# 指定模型
|
||||
cargo run --bin momentry -- vectorize <uuid> --model sentence-transformers/all-MiniLM-L6-v2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 處理模式選項
|
||||
|
||||
### --force (強制重新處理)
|
||||
|
||||
- 刪除現有的 JSON 檔案
|
||||
- 從頭開始處理
|
||||
- 適用於：處理失敗、模型更新、需要重新處理
|
||||
|
||||
```bash
|
||||
# 強制重新處理 YOLO
|
||||
cargo run --bin momentry -- process <uuid> --modules yolo --force
|
||||
```
|
||||
|
||||
### --resume (續傳)
|
||||
|
||||
- 檢查現有 JSON 的進度
|
||||
- 從中斷點繼續處理
|
||||
- 適用於：處理中斷、系統崩潰後恢復
|
||||
|
||||
```bash
|
||||
# 從上次中斷點繼續
|
||||
cargo run --bin momentry -- process <uuid> --resume
|
||||
```
|
||||
|
||||
### 預設行為 (Smart Mode)
|
||||
|
||||
- 如果 JSON 完全：跳過
|
||||
- 如果 JSON 不完整：警告 + 跳過（需要 --resume 或 --force）
|
||||
- 如果 JSON 不存在：處理
|
||||
|
||||
```
|
||||
Output:
|
||||
ASR: ✓ Already complete, skipping
|
||||
|
||||
⚠️ Found incomplete JSON file: /path/to/yolo.json
|
||||
Progress: 73800/412343 (17.9%)
|
||||
Use --resume to continue from checkpoint
|
||||
Use --force to reprocess from scratch
|
||||
YOLO: ✓ Already complete, skipping
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 可用模組
|
||||
|
||||
| 模組 | 功能 | 輸出 | 用途 |
|
||||
|------|------|------|------|
|
||||
| asr | 自動語音辨識 | asr.json | 語音轉文字 |
|
||||
| cut | 場景偵測 | cut.json | 影片分段 |
|
||||
| asrx | 說話者分離 | asrx.json | 多人對話分析 |
|
||||
| yolo | 物體偵測 | yolo.json | 物體辨識 |
|
||||
| ocr | 文字辨識 | ocr.json | 畫面文字 |
|
||||
| face | 人臉偵測 | face.json | 人臉辨識 |
|
||||
| pose | 姿態估計 | pose.json | 人體姿態 |
|
||||
|
||||
---
|
||||
|
||||
## 向量化模型選擇
|
||||
|
||||
```bash
|
||||
# 預設模型
|
||||
--model sentence-transformers/all-MiniLM-L6-v2
|
||||
|
||||
# 高精度模型
|
||||
--model sentence-transformers/all-mpnet-base-v2
|
||||
|
||||
# 多語言模型
|
||||
--model sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
|
||||
|
||||
# 中文模型
|
||||
--model sentence-transformers/paraphrase-multilingual-mpnet-base-v2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 資料庫儲存
|
||||
|
||||
### PostgreSQL (主要關聯式資料庫)
|
||||
|
||||
- 影片資訊
|
||||
- Chunks 資料
|
||||
- Pre-chunks 資料
|
||||
- Frames 資料
|
||||
- 使用者資料
|
||||
|
||||
### Qdrant (主要向量資料庫)
|
||||
|
||||
- Chunk 向量
|
||||
- 相似度搜尋
|
||||
|
||||
### PGVector (備份向量資料庫)
|
||||
|
||||
- Chunk 向量副本
|
||||
- 備援機制
|
||||
|
||||
---
|
||||
|
||||
## Pipeline 狀態追蹤
|
||||
|
||||
### PostgreSQL 狀態欄位
|
||||
|
||||
```sql
|
||||
-- 影片處理狀態
|
||||
videos.status: 'pending' | 'processing' | 'completed' | 'failed'
|
||||
|
||||
-- 檔案處理狀態
|
||||
videos.fs_json: true/false
|
||||
videos.fs_chunks: true/false
|
||||
videos.fs_vectors: true/false
|
||||
|
||||
-- pre_chunks 狀態
|
||||
pre_chunks.imported: true/false
|
||||
|
||||
-- frames 狀態
|
||||
frames.imported: true/false
|
||||
|
||||
-- chunks 狀態
|
||||
chunks.cleaned: true/false
|
||||
chunks.vectorized: true/false
|
||||
```
|
||||
|
||||
### 進度查詢 API
|
||||
|
||||
```bash
|
||||
# 查詢處理進度
|
||||
curl http://localhost:3002/api/v1/progress/{uuid}
|
||||
|
||||
# 回應範例
|
||||
{
|
||||
"uuid": "a1b10138a6bbb0cd",
|
||||
"file_name": "video.mp4",
|
||||
"overall_progress": 65,
|
||||
"cpu_percent": 45.2,
|
||||
"gpu_percent": 98.5,
|
||||
"memory_mb": 8500,
|
||||
"processors": [
|
||||
{"name": "asr", "status": "complete", "progress": 100},
|
||||
{"name": "cut", "status": "complete", "progress": 100},
|
||||
{"name": "yolo", "status": "progress", "progress": 45},
|
||||
{"name": "ocr", "status": "pending", "progress": 0}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
1. **API 端點** - 支援 --modules 和 --cloud 參數
|
||||
2. **獨立 Import 命令** - 分離入庫流程
|
||||
3. **獨立 Chunk 命令** - 分離 chunk 生成
|
||||
4. **獨立 Vectorize 命令** - 分離向量化流程
|
||||
5. **模型管理** - 新增、選擇、預覽模型
|
||||
|
||||
Reference in New Issue
Block a user