---
document_type: "architecture_design"
service: "MOMENTRY_CORE"
title: "Momentry Core 全域資源與處理管線架構 (v1.0)"
date: "2026-04-21"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "momentry"
  - "core"
  - "全域資源與處理管線架構"
ai_query_hints:
  - "查詢 Momentry Core 全域資源與處理管線架構 (v1.0) 的內容"
  - "Momentry Core 全域資源與處理管線架構 (v1.0) 的主要目的是什麼？"
  - "如何操作或實施 Momentry Core 全域資源與處理管線架構 (v1.0)？"
---

# Momentry Core 全域資源與處理管線架構 (v1.0)

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

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-21 | 創建從檔案到知識的端到端處理管線架構 | OpenCode | OpenCode / Qwen3.6-Plus |

---

## 0. 設計目標

建立一套**標準化、可追溯、可擴展**的媒體處理管線，將原始媒體檔案自動轉化為結構化知識與可檢索內容。

核心原則：
1. **一切皆資源**: 檔案、處理器、服務、產出文件皆受資料庫納管。
2. **異步與容錯**: 註冊、處理、索引全階段解耦，支援斷點續傳與失敗重試。
3. **版本精確追溯**: 從模型 GGUF Hash 到處理器 Build Time，確保結果可重現。
4. **第一階段即時可用**: ASR/文本處理完成後立即提供 BM25/向量搜尋。

---

## 1. 大框架總覽：從檔案到知識

```
[原始檔案] (SFTP/API)
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│ 階段一：檔案註冊納管作業 (Onboarding Pipeline)           │
│ • Hash 計算 & UUID 分配                                 │
│ • ffprobe 探針分析 & 分類                               │
│ • Smart Thumbnail (跳過黑屏截圖)                        │
│ • 狀態更新: CREATED → PENDING                           │
└─────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│ 階段二：處理器調度與執行作業 (Orchestration)             │
│ • 排程器取出 PENDING 任務                               │
│ • 查詢 Services Registry (確認 Ollama/GPU/Qdrant 在線)  │
│ • 分配 Processors (Python/Shell/CLI/Docker)             │
│ • 執行 ASR / OCR / Face / Yolo / 向量嵌入                │
│ • 狀態更新: PENDING → PROCESSING → COMPLETED/FAILED     │
└─────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│ 階段三：產出解析與索引建立 (Output & Indexing)           │
│ • 解析標準化 JSON 產出 (Pre-Chunks, Frames)             │
│   - Pre-Chunk: 以 frame 為基準的區間 (start_frame, end_frame) │
│   - Frame: 單幀偵測數據 (frame_number)                  │
│ • 參考時間換算: timestamp_sec = frame / probe_fps       │
│ • 存入 Raw Data Tables (segments, detections)           │
│ • Chunk 聚合: 依據 Rule 1/2/3 將 Pre-Chunk 組裝為 Chunk │
│ • 向量嵌入: 呼叫 Embedding Service (nomic-v2-moe)        │
│ • 寫入 Qdrant 建立索引                                  │
│ • 狀態更新: INDEXING → READY (可搜尋)                   │
└─────────────────────────────────────────────────────────┘
    │
    ▼
[搜尋 API / Portal / N8N Webhooks]
```

---

## 2. 階段一：檔案註冊納管作業 (Onboarding)

將陌生媒體轉化為系統可識別的標準資產。

### 2.1 `assets` 表設計

```sql
CREATE TABLE assets (
    id UUID PRIMARY KEY,
    file_path TEXT NOT NULL,
    file_hash VARCHAR(64) UNIQUE NOT NULL,      -- SHA-256 防重複
    asset_type VARCHAR(20),                     -- video, audio, image
    media_info JSONB,                           -- ffprobe 原始輸出
    status VARCHAR(20) DEFAULT 'CREATED',       -- 狀態機核心欄位
    metadata JSONB,                             -- 標題、語言、來源標籤
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);
```

### 2.2 核心流程
1. **上傳/偵測**: SFTPGo 觸發 Webhook 或用戶透過 API 上傳。
2. **探針分析**: `ffprobe` 提取解析度、幀率、音軌、編碼、時長。
3. **智能預處理**: 呼叫 `Smart Thumbnail` 處理器，跳過片頭黑屏，提取正片首幀。
4. **分類標記**: 根據探針結果自動標記類型（如 `duration > 300s` 標記為 `long_form`）。
5. **入隊**: 狀態轉為 `PENDING`，寫入 Redis 任務隊列 `queue:processing`。

---

## 3. 階段二：處理器調度與執行作業 (Orchestration)

排程器根據資源可用性與任務優先級，動態分配處理器。

### 3.1 排程邏輯 (Scheduler)
```sql
-- 取出可執行的任務
SELECT * FROM tasks 
WHERE status = 'queued' 
  AND required_services <@ (SELECT id FROM services WHERE status = 'online')
ORDER BY priority DESC, created_at ASC
LIMIT 1;
```

### 3.2 執行標準化介面
所有處理器接收統一參數，確保多態兼容：
| 參數 | 說明 | 範例 |
|:---|:---|:---|
| `--uuid` | 任務唯一標識 | `--uuid 384b0ff4...` |
| `--input` | 輸入媒體路徑 | `--input /data/raw/charade.mov` |
| `--output` | 產出目錄 | `--output /data/output/384b...` |
| `--config` | (選填) 執行配置 | `--config model_config.json` |

### 3.3 資源依賴檢查
執行前，排程器驗證 `services` 表：
- ASR 需要 `llm_engine` 或本地 GPU。
- 向量嵌入需要 `embedding_engine` (Ollama nomic-v2-moe) 在線。
- 若依賴服務離線，任務自動降級或進入 `retry_queue`。

*(詳細處理器註冊與多態設計請見 `PROCESSOR_REGISTRY_ARCHITECTURE.md`)*

---

## 4. 階段三：產出管理與第一階段搜尋

處理完成後，系統自動將非結構化 JSON 轉化為可檢索的結構化數據。

### 4.1 產出文件規範：Pre-Chunk 與 Frame
所有處理器產出之 JSON 皆基於 **Frame (幀)** 為時間權威單位。
- **時間計算**: `timestamp = frame_number / fps` (fps 來自 ffprobe)。
- **Pre-Chunk**: 具持續時間的片段 (如 ASR 語句)，記錄 `start_frame`, `end_frame`。
- **Frame**: 單幀偵測數據 (如 Face, OCR)，記錄 `frame_number`。
- **命名**: `{asset_uuid}_{processor_type}_{timestamp}.json`

### 4.2 數據解析與落庫
| 處理器產出 | 數據類型 | 對應 DB 表 | 搜尋能力 |
|------------|----------|------------|----------|
| `asr.json` | Pre-Chunk | `segments` | 語音關鍵字 BM25、說話者過濾 |
| `ocr.json` | Frame | `visual_texts` | 畫面文字搜尋、浮水印過濾 |
| `face.json` | Frame | `face_detections` | 人物出現時間軸、身份匹配 |
| `chunks.json` | Pre-Chunk | `chunks` + `parent_chunks` | 語意搜尋、父子關聯檢索 |

### 4.3 向量索引建立
1. 提取文本內容 (ASR + OCR + Chunk Summary)。
2. 呼叫 `embedding_engine` 服務 (`nomic-embed-text-v2-moe`) 生成 768-dim 向量。
3. 寫入 Qdrant Collection (`momentry_rule1`, `rule2`, `rule3`)。
4. 狀態更新至 `READY`，觸發 Webhook 通知使用者。

---

## 5. 底層支撐：服務與處理器註冊中心

管線的高效運行依賴於兩個註冊中心的動態協調：

### 5.1 服務註冊中心 (`services`)
管理底層基礎設施 (Ollama, Qdrant, Redis, SFTPGo)。
- **健康監控**: 定期探活 `/health`，自動標記 `offline`。
- **配置動態注入**: 處理器不需寫死 IP/Key，啟動時從註冊中心讀取。
- **備份與路徑**: 統一管理 `storage_paths` 與 `backup_policy`。

*(詳細服務註冊設計請見 `SERVICE_REGISTRY_ARCHITECTURE.md`)*

### 5.2 處理器註冊中心 (`processors`)
管理執行邏輯與腳本 (ASR, OCR, Face, Thumbnail)。
- **多態執行**: 支援 Python, Shell, CLI, Docker, HTTP。
- **產出驗證**: 定義 `output_spec` JSON Schema，確保下游解析不崩潰。
- **版本追溯**: 記錄 `version` 與 `build_time`，支持結果重現與比對。

---

## 6. 狀態機與異常處理 (State Machine)

```mermaid
stateDiagram-v2
    [*] --> CREATED: 檔案上傳
    CREATED --> PREPARING: 開始探針分析
    PREPARING --> PENDING: 預處理完成
    PENDING --> PROCESSING: 排程器分配處理器
    PROCESSING --> INDEXING: 處理器產出 JSON
    INDEXING --> READY: 向量/全文索引完成
    PROCESSING --> FAILED: 超時/依賴服務離線
    FAILED --> PENDING: 自動重試 (Max 3次)
    READY --> [*]: 可對外提供 API
```

### 容錯機制
- **心跳超時**: 處理器每 30s 寫入 Redis `progress:{uuid}`，超時則判定為假死並 Kill。
- **依賴降級**: 若 Ollama 離線，可跳過 Vector 索引，僅保留 BM25 搜尋 (功能降級但不中斷)。
- **產出校驗**: JSON 寫入前驗證 `output_spec`，損壞檔案觸發重新處理。

---

## 7. 總結

本架構確立了 Momentry Core 的端到端資料流：

| 階段 | 核心動作 | 產出物 | 關鍵技術 |
|------|----------|--------|----------|
| **納管** | Hash / Probe / Thumbnail | `assets` 記錄 | `ffprobe`, `blackdetect` |
| **調度** | 依賴檢查 / 多態分發 | 執行進程 | Redis Queue, Service Registry |
| **處理** | AI 推論 / 特徵提取 | 標準化 JSON | WhisperX, EasyOCR, InsightFace |
| **索引** | 解析 / Embedding / 寫入 | BM25 + Vector | `nomic-v2-moe`, Qdrant, PGVector |
| **服務** | 健康檢查 / 配置注入 | 高可用叢集 | Health Check Worker, Backup Policy |

此設計將「檔案」、「處理器」、「服務」三大維度統一納管，實現了從原始媒體到智能搜尋的完全自動化與可追溯性。
