warren/momentry_core
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

feat: backup architecture docs, source code, and scripts

Browse Source
This commit is contained in:
Warren
2026-04-25 17:15:45 +08:00
parent 59809dae1f
commit 1f84e5469f
368 changed files with 146329 additions and 261 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs_v1.0/ARCHITECTURE/ARCHITECTURE_OVERVIEW.md
+329
View File
@@ -0,0 +1,329 @@
---
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)