---
document_type: "architecture_design"
service: "MOMENTRY_CORE"
title: "Momentry Core 架構總覽"
date: "2026-04-22"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "momentry"
  - "架構總覽"
  - "core"
ai_query_hints:
  - "查詢 Momentry Core 架構總覽 的內容"
  - "Momentry Core 架構總覽 的主要目的是什麼？"
  - "如何操作或實施 Momentry Core 架構總覽？"
---

# Momentry Core 架構總覽

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-22 |
| 文件版本 | V1.2 |
| 最後更新 | 2026-04-22 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.1 | 2026-04-22 | 更新文檔索引，整合新文檔 | OpenCode | OpenCode / deepseek-v3.2 |
| V1.0 | 2026-04-22 | 創建架構總覽文件 | OpenCode | OpenCode / Qwen3.6-Plus |

---

## 1. 系統概覽

Momentry Core 是一個基於 Rust 的數字資產管理系統，專注於視頻分析與多模態檢索能力。系統結合了語音識別（ASR/ASRX）、人臉識別（Face Recognition）、物體檢測（YOLO）、場景分類（Places365）等多種 AI 模型，實現全面的視頻內容理解。

### 核心設計理念
- **邊緣 AI 優先**：在本地設備上運行，減少雲端依賴
- **多模態融合**：結合視覺、聽覺、文本等多種信號
- **層級分片架構**：將連續視頻轉化為結構化知識單元
- **實時處理能力**：支持 on-the-fly 處理，縮短等待時間

---

## 2. 整體架構圖

```
┌─────────────────────────────────────────────────────────────────────────┐
│                         Momentry Core Architecture                        │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                        API Layer (Axum)                         │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                              │                                          │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                      Core Business Logic                        │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐ │   │
│  │  │ Chunking   │  │Processor   │  │Text        │  │Embedding   │ │   │
│  │  │ Engine     │  │Registry    │  │Processing  │  │Engine      │ │   │
│  │  └────────────┘  └────────────┘  └────────────┘  └────────────┘ │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                              │                                          │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                        Data Access Layer                         │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐ │   │
│  │  │PostgreSQL  │  │Redis       │  │MongoDB     │  │Qdrant      │ │   │
│  │  │(Primary)   │  │(Cache)     │  │(Cache)     │  │(Vectors)   │ │   │
│  │  └────────────┘  └────────────┘  └────────────┘  └────────────┘ │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                              │                                          │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                    External Tool Integration                     │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐ │   │
│  │  │Python      │  │FFmpeg/     │  │WhisperX    │  │InsightFace │ │   │
│  │  │Scripts     │  │FFprobe     │  │(ASR)       │  │(Face)      │ │   │
│  │  └────────────┘  └────────────┘  └────────────┘  └────────────┘ │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## 3. 核心模塊

### 3.1 API 層 (`src/api/`)
- **技術棧**: Axum + Tower + Serde
- **功能**: RESTful API 接口，支持同步/異步處理
- **關鍵文件**:
  - `server.rs`: 主 API 服務器
  - `search.rs`: 搜索相關 API
  - `face_recognition.rs`: 人臉識別 API
  - `person_identity.rs`: 人物身份管理 API

### 3.2 核心業務邏輯 (`src/core/`)
- **分片引擎** (`chunk/`): 視頻分片與知識萃取
- **處理器註冊表** (`processor/`): AI 模型執行管理
- **文本處理** (`text/`): 同義詞擴展、分詞
- **嵌入引擎**: 語義向量生成

### 3.3 數據訪問層 (`src/core/db/`)
- **PostgreSQL**: 主數據存儲，關係型數據
- **Redis**: 緩存和隊列管理
- **MongoDB**: 文檔緩存
- **Qdrant**: 向量數據庫，語義搜索

### 3.4 外部工具集成 (`scripts/`)
- **Python 腳本**: ASR、Face、YOLO、OCR、Scene 等處理器
- **FFmpeg/FFprobe**: 視頻處理與元數據提取
- **AI 模型**: WhisperX、InsightFace、YOLOv8 等

---

## 4. 數據流架構

### 4.1 視頻註冊流程
```
1. 用戶上傳視頻 → 2. 生成 UUID → 3. 提取元數據 (FFprobe)
   → 4. 存入 PostgreSQL → 5. 觸發處理任務 → 6. 返回響應
```

### 4.2 分片處理流程
```
1. 原始視頻 → 2. 各處理器執行 (ASR, Face, YOLO, Scene)
   → 3. 生成 Pre-Chunk 數據 → 4. 應用分片規則 (Rule 1-4)
   → 5. 存入對應數據表 → 6. 向量化並存入 Qdrant
```

### 4.3 搜索查詢流程
```
1. 用戶查詢 → 2. 同義詞擴展 → 3. BM25 文本搜索
   → 4. 向量語義搜索 → 5. 結果融合排序 → 6. 返回檢索結果
```

---

## 5. 技術棧

### 5.1 後端 (Rust)
- **Web 框架**: Axum + Tower
- **異步運行時**: Tokio (full features)
- **序列化**: Serde + Serde JSON
- **數據庫驅動**: SQLx, Redis 1.0.x, MongoDB, Qdrant-client
- **錯誤處理**: Anyhow + Thiserror
- **日誌**: Tracing + Tracing-subscriber

### 5.2 數據存儲
- **主數據庫**: PostgreSQL (SQLx)
- **緩存**: Redis 1.0.x + MongoDB
- **向量數據庫**: Qdrant
- **文件存儲**: SFTPGo

### 5.3 AI 模型
- **語音識別**: WhisperX (Python)
- **人臉識別**: InsightFace (Python)
- **物體檢測**: YOLOv8 (Python)
- **場景分類**: Places365 (Python)
- **語義嵌入**: Nomic-embed-text-v2-moe (Ollama)
- **文本生成**: Gemma4 (llama.cpp)

### 5.4 基礎設施
- **反向代理**: Caddy
- **CI/CD**: GitHub Actions
- **監控**: 自定義指標 + 日誌聚合
- **配置管理**: 環境變量 + 配置文件

---

## 6. 實現狀態

### 6.1 分片規則實現狀態
基於詳細的設計與實現差異分析（參見 [DESIGN_IMPLEMENTATION_GAP.md](./DESIGN_IMPLEMENTATION_GAP.md)）：

| 分片規則 | 設計概念 | 實現狀態 | 實現對應 | 完成度 |
|----------|----------|----------|----------|--------|
| **Rule 1** | 句子級分片 (`sentence`) | ✅ 完整實現 | `ChunkType::Sentence` | 95% |
| **Rule 2** | 視覺物件級分片 (`visual`) | ❌ 未實現 | 無對應實現 | 0% |
| **Rule 3** | 場景級分片 (`scene`) | ⚠️ 部分實現 | `ChunkType::Cut` | 60% |
| **Rule 4** | 摘要級分片 (`summary`) | ⚠️ 概念調整 | `ChunkType::Story` | 40% |
| **附加規則** | 時間基準分片 (`time`) | ✅ 完整實現 | `ChunkType::TimeBased` | 100% |
| **附加規則** | 軌跡追蹤分片 (`trace`) | ✅ 完整實現 | `ChunkType::Trace` | 100% |

### 6.2 核心功能實現狀態
| 功能模塊 | 實現狀態 | 備註 |
|----------|----------|------|
| **視頻註冊** | ✅ 完整實現 | 支持多種視頻格式 |
| **ASR 處理** | ✅ 完整實現 | WhisperX 集成 |
| **OCR 處理** | ✅ 完整實現 | GPU 加速支持 |
| **人臉識別** | ✅ 完整實現 | InsightFace 集成 |
| **YOLO 檢測** | ✅ 完整實現 | 物件檢測與分類 |
| **場景分類** | ✅ 完整實現 | Places365 模型 |
| **向量搜索** | ✅ 完整實現 | Qdrant 集成 |
| **同義詞擴展** | ✅ 完整實現 | 在線+離線模式 |

### 6.3 近期開發重點
1. **設計與實現一致性**：統一術語，更新文檔
2. **視覺分片框架**：實現 Rule 2 基礎功能
3. **場景語義增強**：改進 Rule 3 質量
4. **LLM 集成**：為 Rule 4 添加摘要生成

---

## 7. 部署架構

### 6.1 本地部署 (當前)
```
┌─────────────────────────────────────────┐
│          macOS (M4 Mac Mini)            │
│                                         │
│  ┌────────────┐  ┌────────────┐        │
│  │  Momentry  │  │   Redis    │        │
│  │   Core     │  │            │        │
│  │  (Rust)    │  │            │        │
│  └────────────┘  └────────────┘        │
│                                         │
│  ┌────────────┐  ┌────────────┐        │
│  │ PostgreSQL │  │   Python   │        │
│  │            │  │  Scripts   │        │
│  │            │  │            │        │
│  └────────────┘  └────────────┘        │
└─────────────────────────────────────────┘
```

### 6.2 未來擴展架構
```
┌─────────────────────────────────────────────────────┐
│                  Momentry Platform                   │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │             Core API Server                 │   │
│  │  (Load Balancer + Service Discovery)        │   │
│  └─────────────────────────────────────────────┘   │
│                   │                                  │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐   │
│  │ Worker Node │ │ Worker Node │ │ Worker Node │   │
│  │  (ASR)      │ │  (Face)     │ │  (YOLO)     │   │
│  └─────────────┘ └─────────────┘ └─────────────┘   │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │          Data Storage Cluster               │   │
│  │  PostgreSQL | Redis | Qdrant | Object Store │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
```

---

## 8. 擴展性設計

### 8.1 水平擴展
- **無狀態 API 服務器**: 可通過負載均衡器擴展
- **處理器工作節點**: 可動態添加/移除 AI 處理節點
- **數據庫分片**: PostgreSQL 可配置讀寫分離

### 8.2 垂直擴展
- **GPU 加速**: 支持多種 AI 模型的 GPU 加速
- **內存優化**: 支持大內存配置的視頻處理
- **存儲擴展**: 支持 TB 級視頻文件存儲

### 8.3 模塊化設計
- **插件化處理器**: 可熱插拔 AI 模型
- **可替換組件**: 數據庫、緩存、向量存儲可替換
- **API 擴展**: 可添加新的 API 端點而不影響現有功能

---

## 9. 相關文件索引

### 8.1 核心架構文檔
| 文件 | 描述 | 位置 | 狀態 |
|------|------|------|------|
| ARCHITECTURE_OVERVIEW.md | 架構總覽 | `ARCHITECTURE/` | ✅ 最新版 |
| ARCHITECTURE_ROADMAP.md | 架構發展路線圖 | `ARCHITECTURE/` | ✅ 最新版 |
| TECHNICAL_DECISION_RECORDS.md | 技術決策記錄 | `ARCHITECTURE/` | ✅ 最新版 |
| DESIGN_IMPLEMENTATION_GAP.md | 設計與實現差異分析 | `ARCHITECTURE/` | ✅ 最新版 |
| ARCHITECTURE_DOCUMENTATION_MAP.md | 文檔關係圖與導航 | `ARCHITECTURE/` | ✅ 最新版 |

### 8.2 功能專題文檔
| 文件 | 描述 | 位置 | 狀態 |
|------|------|------|------|
| CHUNKING_ARCHITECTURE.md | 分片架構總綱 | `ARCHITECTURE/chunking/` | 🔄 部分更新 |
| CHUNK_RULE_1_SENTENCE.md | Rule 1: 句子級檢索 | `ARCHITECTURE/chunking/` | ✅ 最新版 |
| CHUNK_RULE_2_VISUAL.md | Rule 2: 視覺物件級檢索 | `ARCHITECTURE/chunking/` | 📋 設計階段 |
| CHUNK_RULE_3_SCENE.md | Rule 3: 場景級檢索 | `ARCHITECTURE/chunking/` | 🔄 部分實現 |
| CHUNK_RULE_4_SUMMARY.md | Rule 4: 摘要級檢索 | `ARCHITECTURE/chunking/` | 🔄 概念調整 |

### 8.3 質量與安全文檔
| 文件 | 描述 | 位置 | 狀態 |
|------|------|------|------|
| PERFORMANCE_AND_SCALABILITY.md | 效能與可擴展性架構 | `ARCHITECTURE/` | ✅ 最新版 |
| SECURITY_ARCHITECTURE.md | 安全架構設計 | `ARCHITECTURE/` | ✅ 最新版 |
| MONITORING_ARCHITECTURE.md | 監控架構設計 | `ARCHITECTURE/` | ✅ 最新版 |
| API_KEY_ARCHITECTURE.md | API Key 管理系統 | `ARCHITECTURE/` | ✅ 最新版 |

### 8.4 服務與處理器文檔
| 文件 | 描述 | 位置 | 狀態 |
|------|------|------|------|
| SERVICE_REGISTRY_ARCHITECTURE.md | 服務資源管理架構 | `ARCHITECTURE/` | ✅ 最新版 |
| PROCESSOR_REGISTRY_ARCHITECTURE.md | 處理器資源管理架構 | `ARCHITECTURE/` | ✅ 最新版 |
| PROCESSOR_LIFECYCLE.md | 處理器生命週期管理 | `ARCHITECTURE/` | ✅ 最新版 |
| PROCESSING_PIPELINE.md | 處理流程文檔 | `ARCHITECTURE/` | ✅ 最新版 |
| MODULE_STANDARDIZATION_IMPLEMENTATION_PLAN.md | 模塊標準化計劃 | `ARCHITECTURE/` | ✅ 最新版 |
| **新增文件** | | | |
| TERMINOLOGY_MAPPING.md | 術語對照表 | `ARCHITECTURE/` | ✅ 最新版 |
| DESIGN_IMPLEMENTATION_GAP.md | 設計與實現差異分析 | `ARCHITECTURE/` | ✅ 最新版 |
| ARCHITECTURE_DECISION_EXECUTION_PLAN.md | 架構決策執行計劃 | `ARCHITECTURE/` | ✅ 最新版 |
| PERFORMANCE_AND_SCALABILITY.md | 效能與可擴展性架構 | `ARCHITECTURE/` | ✅ 最新版 |
| SECURITY_ARCHITECTURE.md | 安全架構設計 | `ARCHITECTURE/` | ✅ 最新版 |
| MONITORING_ARCHITECTURE.md | 監控架構設計 | `ARCHITECTURE/` | ✅ 最新版 |

---

## 10. 更新記錄

| 日期 | 版本 | 變更內容 | 操作人 |
|------|------|----------|--------|
| 2026-04-22 | V1.2 | 術語標準化：添加術語對照表索引 | OpenCode |
| 2026-04-22 | V1.1 | 更新文檔索引，添加新創建的架構文檔 | OpenCode |
| 2026-04-22 | V1.0 | 創建架構總覽文件 | OpenCode |

**最後更新**: 2026-04-22 (V1.2)