---
document_type: "architecture_design"
service: "MOMENTRY_CORE"
title: "技術決策記錄 (Technical Decision Records)"
date: "2026-04-22"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "decision"
  - "技術決策記錄"
ai_query_hints:
  - "查詢 技術決策記錄 (Technical Decision Records) 的內容"
  - "技術決策記錄 (Technical Decision Records) 的主要目的是什麼？"
  - "如何操作或實施 技術決策記錄 (Technical Decision Records)？"
---

# 技術決策記錄 (Technical Decision Records)

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

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 |
|------|------|------|--------|
| V1.0 | 2026-04-22 | 創建技術決策記錄文件 | OpenCode |

---

## 1. 什麼是技術決策記錄 (TDR)

技術決策記錄是一種文檔化方法，用於記錄重要的技術決策、其背景、評估選項、選擇理由以及後果。每條記錄都應包含：

1. **決策標題**：簡要描述決策內容
2. **決策狀態**：已採納、待定、廢棄等
3. **決策日期**：做出決策的日期
4. **決策背景**：為什麼需要這個決策
5. **評估選項**：考慮過的各種方案
6. **選擇理由**：為什麼選擇這個方案
7. **後果**：預期的正面和負面影響
8. **相關鏈接**：相關的文檔、代碼或討論

---

## 2. 架構決策

### TDR-001: 分層分片架構設計

| 項目 | 內容 |
|------|------|
| **決策標題** | 採用四層分片架構設計 |
| **決策狀態** | ✅ 已採納（設計階段） |
| **決策日期** | 2026-04-21 |
| **最後更新** | 2026-04-22 |

#### 2.1 決策背景
Momentry Core 需要將連續視頻轉化為可檢索的知識單元。需要一個架構來支持不同粒度的檢索和分析。

#### 2.2 評估選項

**選項 A: 單層分片架構**
- 所有內容都存儲在同一層級
- 簡單實現，維護成本低
- 但檢索粒度單一，無法支持多層級分析

**選項 B: 兩層分片架構**
- 句子級 + 場景級分片
- 適中的複雜度
- 但缺乏視覺和摘要層級

**選項 C: 四層分片架構（選擇方案）**
- Rule 1: 句子級 (`sentence`)
- Rule 2: 視覺物件級 (`visual`) 
- Rule 3: 場景級 (`scene`)
- Rule 4: 摘要級 (`summary`)

#### 2.3 選擇理由
選擇四層架構的原因：
1. **粒度靈活性**：支持從單詞到故事的各種檢索需求
2. **理解深度**：從細節到整體的多層次理解
3. **未來擴展**：為更複雜的分析提供基礎
4. **用戶體驗**：不同用戶可以選擇合適的檢索粒度

#### 2.4 後果
**正面影響**：
- 豐富的檢索能力
- 支持多層級內容分析
- 更好的用戶體驗

**負面影響**：
- 實現複雜度增加
- 需要更多計算資源
- 數據存儲需求增加

#### 2.5 實現狀態
| 分片層級 | 設計狀態 | 實現狀態 | 備註 |
|----------|----------|----------|------|
| Rule 1 (Sentence) | ✅ 已定義 | ✅ 已實現 | `src/core/chunk/rule1_ingest.rs` |
| Rule 2 (Visual) | ✅ 已定義 | ❌ 未實現 | 需要集成 YOLO 物件檢測 |
| Rule 3 (Scene) | ✅ 已定義 | ⚠️ 部分實現 | 基於 CUT 數據，需要完善 |
| Rule 4 (Summary) | ✅ 已定義 | ❌ 未實現 | 需要集成 LLM 摘要生成 |

#### 2.6 相關鏈接
- [CHUNKING_ARCHITECTURE.md](./chunking/CHUNKING_ARCHITECTURE.md)
- 代碼實現：`src/core/chunk/`

---

### TDR-002: 數據庫技術選型

| 項目 | 內容 |
|------|------|
| **決策標題** | 多數據庫混合架構 |
| **決策狀態** | ✅ 已採納並實現 |
| **決策日期** | 2026-03-15 |
| **最後更新** | 2026-04-22 |

#### 2.1 決策背景
需要選擇合適的數據存儲方案來支持不同類型的數據和查詢需求。

#### 2.2 評估選項

**選項 A: 單一關係型數據庫**
- 使用 PostgreSQL 存儲所有數據
- 簡單統一，但可能不適合所有數據類型

**選項 B: 單一 NoSQL 數據庫**
- 使用 MongoDB 存儲所有數據
- 靈活的 schema，但關係查詢能力有限

**選項 C: 多數據庫混合架構（選擇方案）**
- **PostgreSQL**: 主數據存儲，關係型數據
- **Redis**: 緩存和隊列管理
- **MongoDB**: 文檔緩存
- **Qdrant**: 向量數據庫，語義搜索

#### 2.3 選擇理由
選擇混合架構的原因：
1. **專業化存儲**：每個數據庫處理最適合的數據類型
2. **性能優化**：向量搜索用 Qdrant，緩存用 Redis
3. **靈活性**：不同類型的數據有不同的存儲需求
4. **可擴展性**：可以獨立擴展各個組件

#### 2.4 後果
**正面影響**：
- 各組件性能最優化
- 支持複雜的查詢需求
- 良好的可擴展性

**負面影響**：
- 系統複雜度增加
- 需要管理多個數據庫
- 數據一致性挑戰

#### 2.5 實現狀態
| 數據庫 | 用途 | 實現狀態 |
|--------|------|----------|
| PostgreSQL | 主數據存儲，關係型數據 | ✅ 已實現 |
| Redis | 緩存和隊列管理 | ✅ 已實現 |
| MongoDB | 文檔緩存 | ✅ 已實現 |
| Qdrant | 向量數據庫，語義搜索 | ✅ 已實現 |

#### 2.6 相關鏈接
- 代碼實現：`src/core/db/`

---

### TDR-003: 編程語言選擇

| 項目 | 內容 |
|------|------|
| **決策標題** | 使用 Rust 作為核心開發語言 |
| **決策狀態** | ✅ 已採納並實現 |
| **決策日期** | 2026-03-10 |
| **最後更新** | 2026-04-22 |

#### 3.1 決策背景
需要選擇一個高性能、安全、可維護的語言來構建視頻處理系統。

#### 3.2 評估選項

**選項 A: Python**
- 生態豐富，AI 庫完善
- 開發速度快
- 但性能較低，不適合高並發

**選項 B: Go**
- 性能好，並發支持好
- 簡單易學
- 但生態不如 Rust 豐富

**選項 C: Rust（選擇方案）**
- 高性能，接近 C++ 的性能
- 內存安全，無 GC
- 強大的類型系統和錯誤處理

**選項 D: Java/Kotlin**
- 企業級生態
- 性能良好
- 但內存佔用大，啟動慢

#### 3.3 選擇理由
選擇 Rust 的原因：
1. **性能需求**：視頻處理需要高性能
2. **安全性**：內存安全避免潛在的崩潰和安全問題
3. **並發處理**：強大的並發支持適合高並發 API
4. **生態系統**：豐富的網絡和數據庫庫
5. **長期維護**：嚴格的編譯器檢查減少 bug

#### 3.4 後果
**正面影響**：
- 高性能和低延遲
- 高可靠性和安全性
- 良好的可維護性

**負面影響**：
- 學習曲線陡峭
- 開發速度相對較慢
- 某些 AI 庫需要通過 Python 橋接

#### 3.5 實現狀態

- ✅ 核心系統使用 Rust 實現
- ✅ Python 用於 AI 模型處理
- ✅ 通過子進程調用橋接 Rust 和 Python

#### 3.6 相關鏈接
- 代碼庫：`src/` 目錄
- [RUST_DEVELOPMENT.md](../REFERENCE/RUST_DEVELOPMENT.md)

---

### TDR-004: 分片規則分析與未來規劃

| 項目 | 內容 |
|------|------|
| **決策標題** | 視覺/場景/摘要分片的設計意義與實現規劃 |
| **決策狀態** | 📝 設計階段（未實現） |
| **提出日期** | 2026-04-22 |
| **最後更新** | 2026-04-22 |

#### 4.1 視覺分片 (Visual Chunk) 的意義

**核心價值**：
1. **物件級搜索**：支持「看到了什麼」的搜索
2. **跨模態橋接**：連接視覺與語音/文本內容
3. **場景理解基礎**：通過物件組合理解場景

**好處**：
- 實現「視覺第一」的搜索體驗
- 支持基於物件出現的視頻分析
- 為場景分析提供基礎數據

#### 4.2 場景分片 (Scene Chunk) 的意義

**核心價值**：
1. **語義聚合**：將相關句子/物件組成有意義場景
2. **上下文保留**：保持對話和行為的連貫性
3. **高效檢索**：直接定位到場景而非單句

**好處**：
- 支持語義級搜索（如「會議對話」、「爭吵場景」）
- 保留完整上下文
- 為故事摘要提供基礎

#### 4.3 摘要分片 (Summary Chunk) 的意義

**核心價值**：
1. **高層級理解**：提供視頻整體概括
2. **5W1H 結構化**：提取關鍵信息
3. **敘事壓縮**：將長視頻精簡為可快速理解的摘要

**好處**：
- 用戶無需觀看整個視頻即可了解內容
- 提供清晰的結構化信息
- 支持視頻內容快速評估和比較

#### 4.4 實現優先級與挑戰

**實現優先級**：
1. ✅ **Rule 1 (句子級)** - 已實現
2. ⚠️ **Rule 3 (場景級)** - 部分實現（基於 CUT 數據）
3. ❌ **Rule 2 (視覺級)** - 待實現
4. ❌ **Rule 4 (摘要級)** - 待實現

**技術挑戰**：
1. **視覺分片**：物件檢測準確性與性能平衡
2. **場景分片**：場景邊界智能識別
3. **摘要分片**：LLM 摘要質量與一致性
4. **數據融合**：多模態信息有效整合

#### 4.5 遷移計劃

**短期 (1-2個月)**：
- 完善 Rule 3 (場景級分片)
- 集成 Places365 場景分類
- 完善基於視覺和語音的場景識別

**中期 (3-6個月)**：
- 實現 Rule 2 (視覺分片)
- 集成 YOLO 物件檢測
- 創建物件標籤索引

**長期 (6-12個月)**：
- 實現 Rule 4 (摘要分片)
- 集成 LLM 摘要生成
- 實現5W1H結構化提取

#### 4.6 相關鏈接

- [CHUNKING_ARCHITECTURE.md](./chunking/CHUNKING_ARCHITECTURE.md))
- Rule 1 實現：`src/core/chunk/rule1_ingest.rs`
- Rule 3 實現：`src/core/chunk/rule3_ingest.rs`

---

## 3. 設計與實現差異分析

### 設計目標 vs 實際實現

#### 差異點1: chunk_type 定義

| 設計文件 | 實際代碼 | 狀態分析 |
|----------|----------|----------|
| `sentence` | `"sentence"` | ✅ 一致 |
| `visual` | 未實現 | ❌ 缺失設計功能 |
| `scene` | `"cut"` + 部分實現 | ⚠️ 部分實現（名稱差異） |
| `summary` | 未實現 | ❌ 缺失設計功能 |
| - | `"time"`, `"trace"`, `"story"` | 🔄 代碼中的額外類型 |

#### 差異點2: 分片規則實現

| 規則 | 設計描述 | 實現狀態 | 問題分析 |
|------|----------|----------|----------|
| Rule 1 | 句子級檢索 | ✅ 已實現 | 完整功能 |
| Rule 2 | 視覺物件級檢索 | ❌ 未實現 | 缺乏物件檢測集成 |
| Rule 3 | 場景級檢索 | ⚠️ 部分實現 | 僅基於CUT數據，缺少場景分類 |
| Rule 4 | 摘要級檢索 | ❌ 未實現 | 缺少LLM集成和結構化摘要 |

#### 差異點3: 數據庫結構

| 設計目標 | 實現現狀 | 分析 |
|----------|----------|------|
| 通用分片結構 | 已實現基本結構 | ✅ |
| 視覺物件索引 | 未實現 | ❌ |
| 場景聚合表 | 部分實現 | ⚠️ |
| 摘要生成表 | 未實現 | ❌ |

---

## 4. 建議實現路徑與計劃

### 優先級1: 完善現有實現

**短期目標 (1-2週)**：

1. **統一 `chunk_type` 枚舉**：
   - 更新 `src/core/chunk/types.rs` 中的 `ChunkType` 枚舉
   - 確保與數據庫中存儲的字符串值一致

2. **擴展Rule 3實現**：
   - 集成Places365模型進行場景分類
   - 結合視覺和語音數據的場景邊界識別
   - 創建 `chunks_rule3` 表的完整結構

### 優先級2: 實現視覺分片

**中期目標 (1-2個月)**：

1. **YOLO集成**：
   - 創建 `yolo_processor.py` 腳本
   - 實現基於關鍵幀的物件檢測
   - 物件標籤標準化和索引建立

2. **視覺分片生成**：
   - 創建 `visual_ingest.rs` 處理器
   - 實現物件聚合和標籤生成
   - 創建 `chunks_rule2` 表結構

### 優先級3: 實現摘要分片

**長期目標 (3-6個月)**：

1. **LLM集成**：
   - 集成Gemma4或類似LLM
   - 實現視頻內容摘要生成
   - 5W1H結構化信息提取

2. **摘要分片生成**：
   - 創建 `summary_ingest.rs` 處理器
   - 實現跨場景的敘事壓縮
   - 創建 `chunks_rule4` 表結構

---

## 5. 關鍵決策點總結

### 決策1: 分層架構設計

**設計目標**：
- 四層分片架構：句子 → 視覺 → 場景 → 摘要
- 多粒度檢索：從細節到整體的不同層次理解

**實現現狀**：
- 句子級分片（Rule 1）完整實現
- 場景級分片（Rule 3）部分實現
- 視覺和摘要分片未實現

### 決策2: 數據庫混合架構

**設計目標**：
- PostgreSQL: 主數據存儲
- Redis: 緩存和隊列
- MongoDB: 文檔緩存
- Qdrant: 向量搜索

**實現現狀**：
- ✅ 所有數據庫均已集成
- ✅ 多數據庫協同工作
- ⚠️ 數據一致性管理需要完善

### 決策3: 技術棧選擇

**設計目標**：
- Rust: 核心系統語言
- Python: AI模型處理
- Axum: Web框架
- Tokio: 異步運行時

**實現現狀**：
- ✅ Rust核心系統完整實現
- ✅ Python AI模型集成
- ✅ Axum + Tokio 穩定運行
- ⚠️ Python-Rust 橋接效率需優化

---

## 6. 未來改進方向

### 短期改進 (1-2個月)

1. **統一API設計**：
   - 標準化所有列表API的分頁參數
   - 統一回應結構格式
   - 完善錯誤處理和文檔

2. **優化性能**：
   - 改進數據庫查詢效率
   - 優化Python子進程調用
   - 改善並發處理能力

### 中期改進 (3-6個月)

1. **完善分片規則**：
   - 實現視覺分片（Rule 2）
   - 實現摘要分片（Rule 4）
   - 完善場景分片（Rule 3）

2. **擴展功能**：
   - 支持更多視頻格式
   - 集成更多AI模型
   - 提供更多分析維度

### 長期改進 (6-12個月)

1. **系統架構升級**：
   - 微服務化架構
   - 雲原生部署支持
   - 大規模視頻處理能力

2. **平台化發展**：
   - 多租戶支持
   - 可擴展插件架構
- 雲端協同工作流

---

## 7. 最後更新記錄

| 版本 | 日期 | 主要變更 | 操作人 |
|------|------|----------|--------|
| V1.0 | 2026-04-22 | 創建技術決策記錄文件 | OpenCode |
| V1.1 | 2026-04-22 | 添加設計與實現差異分析 | OpenCode |
| V1.2 | 2026-04-22 | 完善實現計劃和改進方向 | OpenCode |

**最後更新日期**: 2026-04-22
