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

# Momentry Core 分片架構總綱 (Master Chunking Architecture) (v1.1)

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-22 |
| 最後更新 | 2026-04-22 |
| 文件版本 | V1.1 |
| **狀態** | **設計文檔（與實際實現有差異）** |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.1 | 2026-04-22 | 術語標準化整合，添加參考文件連結 | OpenCode | OpenCode / deepseek-v3.2 |
| V1.0 | 2026-04-22 | 整合分片規則、標記設計與實現差異 | OpenCode | OpenCode / Qwen3.6-Plus |

---

## ⚠️ 重要說明：設計與實現差異

本文檔描述的是**設計目標**，與**實際實現**存在差異。以下是主要差異點：

### 差異點 1: `chunk_type` 值
| 設計文檔 | 實際實現 | 狀態 |
|----------|----------|------|
| `sentence` | `ChunkType::Sentence` | ✅ 一致 |
| `visual` | 未實現 (設計值: visual) | ❌ 缺失 |
| `scene` | `ChunkType::Cut` (設計值: scene) | ⚠️ 部分實現 |
| `summary` | `ChunkType::Story` (設計值: summary) | ⚠️ 概念調整 |
| - | `"time"` | 🔄 額外 |
| - | `"cut"` | 🔄 額外 |
| - | `"trace"` | 🔄 額外 |
| - | `"story"` | 🔄 額外 |

### 差異點 2: 規則實現
| 規則 | 設計描述 | 實際實現 |
|------|----------|----------|
| Rule 1 | 句子級檢索 | ✅ 已實現 (`rule1_ingest.rs`) |
| Rule 2 | 視覺物件級檢索 | ❌ 未實現 |
| Rule 3 | 場景級檢索 | ⚠️ 部分實現 (`rule3_ingest.rs`) |
| Rule 4 | 摘要級檢索 | ❌ 未實現 |

---

## 0. 設計目標

**分片 (Chunking)** 是 Momentry Core 將連續影音轉化為**可檢索知識**的核心樞紐。本架構定義了如何將處理器產出的原始數據 (Pre-Chunk/Frame)，依據標準規則組裝為多層級 Chunk，並透過關聯分析產出高價值摘要。

- **時間權威 (Frame-Based)**：所有時間計算以 `frame_number` 為唯一權威，秒數僅供參考 (`time = frame / fps`)。
- **多模態融合 (Multimodal Fusion)**：每個 Chunk 聚合 ASR (聽覺)、Face (人物)、YOLO (物件) 特徵。
- **分層檢索 (Hierarchical Retrieval)**：從微觀台詞 (Rule 1) 到宏觀劇情問答 (Rule 4)。
- **自動知識萃取 (Auto-Enrichment)**：利用 LLM 聚合父子內容，自動生成 Summary 與 5W1H。

---

## 1. 通用分片結構 (Universal Chunk Schema)

無論是哪一種 Rule，所有 Chunk 皆遵循以下核心定義：

| 欄位 | 類型 | 說明 |
|:---|:---|:---|
| `chunk_id` | UUID | 分片唯一標識符 (PK) |
| `asset_uuid` | UUID | 所屬影片資產 UUID |
| `chunk_type` | ENUM | **設計值**：`sentence`, `visual`, `scene`, `summary`<br>**實際值**：`"time"` (`ChunkType::TimeBased`), `"sentence"` (`ChunkType::Sentence`), `"cut"` (`ChunkType::Cut`), `"trace"` (`ChunkType::Trace`), `"story"` (`ChunkType::Story`) |
| `start_frame` | INT | **起始幀** (時間權威來源) |
| `end_frame` | INT | **結束幀** (時間權威來源) |
| `content` | TEXT | 主要檢索內容 (ASR 文本 / 物件描述 / 劇情摘要) |
| `metadata` | JSONB | 關聯內容 (Speaker, Face IDs, Frame Objects) |

---

## 2. 分片規則路由 (Rule Routing Table)

系統依據規則將原始數據轉化為不同粒度的檢索單元，並寫入對應資料表。

| Rule | 粒度 | `chunk_type` | 內容來源 (Content) | 關聯內容 (Metadata) | 寫入資料表 | 實現狀態 |
|:---|:---|:---|:---|:---|:---|:---|
| **Rule 1** | 語句 | `ChunkType::Sentence` (設計值: `sentence`) | **ASR 文本** (單句文字) | Speaker ID, Face IDs (區間聚合) | `chunks_rule1` | ✅ 已實現 |
| **Rule 2** | 畫面 | 未實現 (設計值: `visual`) | **物件標籤串** (e.g., "car, person") | YOLO Objects (>0.8), Faces, Speaker | `chunks_rule2` | ❌ 未實現 |
| **Rule 3** | 場景 | `ChunkType::Cut` (設計值: `scene`) | **場景摘要** (聚合多個 Rule 1/2) | Aggregated Faces, Objects, Speakers | `chunks_rule3` | ⚠️ 部分實現 |
| **Rule 4** | 摘要 | `ChunkType::Story` (設計值: `summary`) | **劇情描述 & 5W1H 分析** (LLM 生成) | 5W1H 結構化數據, 關聯 Rule 3 IDs | `chunks_rule4` | ⚠️ 概念調整 |

---

## 3. 關聯與知識萃取流程 (Associative Enrichment Pipeline)

這是系統將「原始數據」轉化為「結構化知識」的核心機制。針對 **父 Chunk (Rule 3 Scene)**，系統會匯聚其下屬的所有子 Chunk、視覺物件與人物特徵，並透過 LLM 產出全新的敘事內容。

### 3.1 數據關聯架構 (Input Aggregation)

針對每一個 Parent Chunk `[start_frame, end_frame]`，系統提取：
1. **子 Chunk (Rule 1)**: 提取對話 (`content`) 與說話者 (`speaker_id`)。
2. **子 Chunk (Rule 2)**: 提取物件標籤 (`frame_objects`)。
3. **身份解析**: 將 `face_id` 解析為真實人名 (e.g., `face_01` -> "Cary Grant")。

### 3.2 LLM 上下文構造 (Context Construction)

系統組裝 Prompt 提供給 Gemma4：
```text
### 場景數據
**人物**: Cary Grant, Audrey Hepburn
**物件**: car, street, gun
**對話**: [Cary] "Look at that car!"

### 任務
1. **New Content**: 融合所有資訊，生成一段詳細的繁體中文敘述。
2. **Summary**: 一句話精簡摘要。
3. **5W1H**: 結構化提取 (Who, What, Where, Why, How)。
```

### 3.3 輸出與寫入 (Output & Ingestion)

LLM 返回的 JSON 將直接更新資料庫：
```sql
UPDATE chunks_rule3
SET 
    content = $new_content,       -- 覆蓋為詳細敘述
    summary = $new_summary,       -- 儲存精簡摘要
    analysis_5w1h = $json_5w1h    -- 儲存結構化分析
WHERE id = $chunk_id;
```

---

## 4. 實際實現狀態

### 4.1 已實現功能
- **Rule 1 (Sentence Chunk)**: 完整實現，位於 `src/core/chunk/rule1_ingest.rs`
- **Rule 3 (Scene Chunk)**: 部分實現，位於 `src/core/chunk/rule3_ingest.rs`
  - 目前基於 CUT 數據識別場景
  - 聚合 Rule 1 句子
  - 調用 LLM 生成 5W1H 摘要

### 4.2 未實現功能
- **Rule 2 (Visual Chunk)**: 未實現
- **Rule 4 (Summary Chunk)**: 未實現
- **完整的場景分類**: 目前僅基於 CUT 數據，未集成 Places365 場景分類

### 4.3 實際數據庫結構
```sql
-- 實際的 chunks 表結構
CREATE TABLE chunks (
    id SERIAL PRIMARY KEY,
    uuid VARCHAR(32) NOT NULL,
    chunk_id VARCHAR(64) NOT NULL,
    chunk_index INTEGER NOT NULL,
    chunk_type VARCHAR(32) NOT NULL,  -- "time", "sentence", "cut", "trace", "story"
    start_time DOUBLE PRECISION NOT NULL,
    end_time DOUBLE PRECISION NOT NULL,
    fps DOUBLE PRECISION DEFAULT 24.0,
    start_frame BIGINT DEFAULT 0,
    end_frame BIGINT DEFAULT 0,
    content JSONB NOT NULL,
    metadata JSONB,
    vector_id VARCHAR(64),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(uuid, chunk_id)
);
```

---

## 5. 遷移計劃建議

### 5.1 短期目標 (1-2個月)
1. **實現 Rule 2 (Visual Chunk)**
   - 集成 YOLO 物件檢測結果
   - 創建 `chunks_rule2` 表
   - 實現 `rule2_ingest.rs`

2. **完善 Rule 3 (Scene Chunk)**
   - 集成 Places365 場景分類
   - 完善 LLM 摘要生成
   - 創建 `chunks_rule3` 表

### 5.2 中期目標 (3-6個月)
1. **實現 Rule 4 (Summary Chunk)**
   - 跨場景劇情摘要
   - 創建 `chunks_rule4` 表

2. **統一 `chunk_type` 枚舉**
   - 更新 Rust 代碼中的 `ChunkType` 枚舉
   - 遷移現有數據

### 5.3 長期目標 (6-12個月)
1. **動態分片規則**
   - 支持用戶自定義分片規則
   - 可配置的聚合策略

2. **實時分片處理**
   - On-the-fly 分片生成
   - 增量更新機制

---

## 6. 相關文件

| 文件 | 描述 | 狀態 |
|------|------|------|
| [CHUNK_RULE_1_SENTENCE.md](./CHUNK_RULE_1_SENTENCE.md) | Rule 1: 句子級檢索 | ✅ 與實現一致 |
| [CHUNK_RULE_2_VISUAL.md](./CHUNK_RULE_2_VISUAL.md) | Rule 2: 視覺物件級檢索 | ⚠️ 設計文檔 |
| [CHUNK_RULE_3_SCENE.md](./CHUNK_RULE_3_SCENE.md) | Rule 3: 場景級檢索 | ⚠️ 部分實現 |
| [CHUNK_RULE_4_SUMMARY.md](./CHUNK_RULE_4_SUMMARY.md) | Rule 4: 摘要級檢索 | ⚠️ 設計文檔 |
| [CHUNKING_SCHEMA_SPEC.md](./CHUNKING_SCHEMA_SPEC.md) | 數據庫結構規範 | ⚠️ 設計文檔 |
| [CHUNKING_ENRICHMENT_PIPELINE.md](./CHUNKING_ENRICHMENT_PIPELINE.md) | 知識萃取流程 | ⚠️ 設計文檔 |

---

## 7. 代碼引用

### 7.1 主要實現文件
```rust
// Rule 1 實現
src/core/chunk/rule1_ingest.rs

// Rule 3 實現  
src/core/chunk/rule3_ingest.rs

// Chunk 類型定義
src/core/chunk/types.rs

// Chunk 分割器
src/core/chunk/splitter.rs
```

### 7.2 數據庫操作
```rust
// 數據庫層的 chunk 處理
src/core/db/postgres_db.rs
```

---

## 8. 更新記錄

| 日期 | 版本 | 變更內容 | 操作人 |
|------|------|----------|--------|
| 2026-04-22 | V1.1 | 術語標準化整合，添加參考文件連結 | OpenCode |
| 2026-04-22 | V1.0 | 創建整合文檔，標記設計與實現差異 | OpenCode |

---

## 參考文件

1. **[TERMINOLOGY_MAPPING.md](../../TERMINOLOGY_MAPPING.md)** - 完整術語對照表
2. **[DESIGN_IMPLEMENTATION_GAP.md](../../DESIGN_IMPLEMENTATION_GAP.md)** - 設計與實現差異分析
3. **[ARCHITECTURE_OVERVIEW.md](../../ARCHITECTURE_OVERVIEW.md)** - 架構總覽

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