docs: update docs_v1.0/ documentation
- Fix markdown lint issues (MD030, MD047, MD051, MD028, MD005) - Update AI agents, architecture, implementation docs - Add new identity, face recognition, and API documentation - Remove deprecated face/person API guides
This commit is contained in:
Warren
@@ -112,9 +112,9 @@ ai_query_hints:
|
||||
### 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")。
|
||||
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)
|
||||
|
||||
@@ -270,4 +270,4 @@ src/core/db/postgres_db.rs
|
||||
2. **[DESIGN_IMPLEMENTATION_GAP.md](../../DESIGN_IMPLEMENTATION_GAP.md)** - 設計與實現差異分析
|
||||
3. **[ARCHITECTURE_OVERVIEW.md](../../ARCHITECTURE_OVERVIEW.md)** - 架構總覽
|
||||
|
||||
**最後更新**: 2026-04-22
|
||||
**最後更新**: 2026-04-22
|
||||
|
||||
@@ -61,9 +61,9 @@ ai_query_hints:
|
||||
|
||||
本規範確保所有資料庫表嚴格遵循 **Chunking Architecture** 定義的通用結構：
|
||||
|
||||
1. **時間權威 (Frame-Based)**：所有時間相關欄位以 `frame` 為核心，`timestamp` 為計算參考。
|
||||
2. **內容與元數據分離 (Content vs Metadata)**：`content` 用於全文檢索與向量嵌入，`metadata` (JSONB) 儲存關聯物件、Speaker、Faces 等結構化數據。
|
||||
3. **路由清晰 (Rule Routing)**：每個 Rule 對應獨立的資料表，透過 `chunk_type` 欄位輔助識別。
|
||||
1. **時間權威 (Frame-Based)**：所有時間相關欄位以 `frame` 為核心，`timestamp` 為計算參考。
|
||||
2. **內容與元數據分離 (Content vs Metadata)**：`content` 用於全文檢索與向量嵌入，`metadata` (JSONB) 儲存關聯物件、Speaker、Faces 等結構化數據。
|
||||
3. **路由清晰 (Rule Routing)**：每個 Rule 對應獨立的資料表，透過 `chunk_type` 欄位輔助識別。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -42,8 +42,8 @@ ai_query_hints:
|
||||
|
||||
- **核心原則**: 一個鏡頭/場景 (Cut) = 一個 Parent Chunk。
|
||||
- **結構**: 採用 **Parent-Child (父子)** 架構。
|
||||
- **Parent (Rule 3)**: 代表整個場景，包含摘要 (Summary) 與聚合向量。
|
||||
- **Children (Rule 1/2)**: 場景內包含的具體句子與視覺幀。
|
||||
- **Parent (Rule 3)**: 代表整個場景，包含摘要 (Summary) 與聚合向量。
|
||||
- **Children (Rule 1/2)**: 場景內包含的具體句子與視覺幀。
|
||||
- **優勢**: 支援跨句子的長語境搜尋 (例如搜尋整個情節的摘要，而非單一單詞)。
|
||||
|
||||
---
|
||||
@@ -52,11 +52,11 @@ ai_query_hints:
|
||||
|
||||
Rule 3 不直接從原始影片產生，而是依賴 **Rule 1** 與 **Rule 2** 的產出。
|
||||
|
||||
1. **Cut Processor (Primary)**: 提供場景的邊界。
|
||||
1. **Cut Processor (Primary)**: 提供場景的邊界。
|
||||
- *定義*: `start_frame`, `end_frame` 為一個完整鏡頭。
|
||||
2. **Rule 1 Chunks (Children)**: 收集該場景內所有的 ASR 語句 (Sentences)。
|
||||
3. **Rule 2 Chunks (Children)**: 收集該場景內所有的視覺幀數據 (Visual Frames)。
|
||||
4. **Summary Generation**:
|
||||
2. **Rule 1 Chunks (Children)**: 收集該場景內所有的 ASR 語句 (Sentences)。
|
||||
3. **Rule 2 Chunks (Children)**: 收集該場景內所有的視覺幀數據 (Visual Frames)。
|
||||
4. **Summary Generation**:
|
||||
- 為了讓 Parent Chunk 具備搜尋能力，系統會將所有子 Chunk 的內容 (ASR 文本 + 物件標籤) 組合成一段「場景描述」，並由 LLM (選用) 或規則生成一段 **Summary**。
|
||||
|
||||
---
|
||||
@@ -138,15 +138,15 @@ Rule 3 的 API 返回應包含聚合後的子項目。
|
||||
Rule 3 專為**宏觀理解**與**摘要檢索**設計。
|
||||
|
||||
### 3.1 場景摘要搜尋 (Summary Search)
|
||||
* **場景**: "尋找他們討論分贓的場景" (可能包含多句對話)。
|
||||
* **邏輯**:
|
||||
- **場景**: "尋找他們討論分贓的場景" (可能包含多句對話)。
|
||||
- **邏輯**:
|
||||
1. Query: "Discussion about splitting the money".
|
||||
2. Match: 搜尋 `parent_chunks.summary` 的向量。
|
||||
3. 結果：直接返回整個場景 (Parent)，而非零碎的句子。
|
||||
|
||||
### 3.2 混合檢索 (Hybrid Retrieval)
|
||||
* **場景**: 使用者搜尋 "槍戰"。
|
||||
* **策略**:
|
||||
- **場景**: 使用者搜尋 "槍戰"。
|
||||
- **策略**:
|
||||
1. **Hit**: Rule 2 (Visual) 命中 (偵測到 "gun")。
|
||||
2. **Expand**: 系統自動向上查找該 Rule 2 所屬的 Rule 3 Parent。
|
||||
3. **Return**: 返回該場面的完整上下文 (包含槍戰前後的對話)。
|
||||
|
||||
@@ -50,10 +50,10 @@ ai_query_hints:
|
||||
|
||||
Rule 1 的生成依賴三個上游處理器的產出：
|
||||
|
||||
1. **ASR (Primary)**: 提供文本內容 (`text`)、起始時間 (`start_time`)、結束時間 (`end_time`)。
|
||||
2. **ASRX (Speaker)**: 提供說話者 ID (`speaker_id`)。
|
||||
1. **ASR (Primary)**: 提供文本內容 (`text`)、起始時間 (`start_time`)、結束時間 (`end_time`)。
|
||||
2. **ASRX (Speaker)**: 提供說話者 ID (`speaker_id`)。
|
||||
- *聚合策略*: 使用 ASR 的時間區間去對齊 ASRX，取該區間內**佔比最高**的 `speaker_id`。
|
||||
3. **Face (Visual)**: 提供幀級別的人物 ID (`face_id`)。
|
||||
3. **Face (Visual)**: 提供幀級別的人物 ID (`face_id`)。
|
||||
- *聚合策略*: 在 ASR 的 `[start_frame, end_frame]` 區間內，收集所有出現的 `face_id`。若同一 ID 出現多次，去重後形成 `face_ids` 陣列。
|
||||
|
||||
---
|
||||
@@ -120,21 +120,21 @@ CREATE TABLE chunks_rule1 (
|
||||
Rule 1 支援三種主要搜尋模式：
|
||||
|
||||
### 3.1 語意搜尋 (Vector Search)
|
||||
* **場景**: "有人提到錢嗎？" (即使影片沒說 "錢"，而是說 "鈔票" 也能搜到)。
|
||||
* **邏輯**:
|
||||
- **場景**: "有人提到錢嗎？" (即使影片沒說 "錢"，而是說 "鈔票" 也能搜到)。
|
||||
- **邏輯**:
|
||||
1. 將 Query 透過 Ollama (`nomic-v2-moe`) 轉為 768-dim 向量。
|
||||
2. 在 Qdrant (`collection: momentry_rule1`) 中進行 Cosine 相似度比對。
|
||||
3. **Filter**: 可加入 `metadata.speaker == "SPEAKER_00"`。
|
||||
|
||||
### 3.2 關鍵字搜尋 (BM25 Search)
|
||||
* **場景**: "搜尋確切字串 'Charade 1963'"。
|
||||
* **邏輯**:
|
||||
- **場景**: "搜尋確切字串 'Charade 1963'"。
|
||||
- **邏輯**:
|
||||
1. 使用 PostgreSQL `tsvector` 進行全文檢索。
|
||||
2. 適合精確匹配專有名詞。
|
||||
|
||||
### 3.3 過濾搜尋 (Faceted Search)
|
||||
* **場景**: "找出 **Audrey Hepburn (Face)** 說話的所有片段"。
|
||||
* **邏輯**:
|
||||
- **場景**: "找出 **Audrey Hepburn (Face)** 說話的所有片段"。
|
||||
- **邏輯**:
|
||||
1. `face_ids` 包含 "Audrey Hepburn" 的 ID。
|
||||
2. `speaker_id` 不為空 (代表她在說話)。
|
||||
3. 檢索符合條件的 Chunks。
|
||||
@@ -181,9 +181,9 @@ for seg in asr_segments:
|
||||
|
||||
## 5. 向量嵌入策略
|
||||
|
||||
* **嵌入模型**: `nomic-embed-text-v2-moe` (768-dim)。
|
||||
* **嵌入內容**: 僅使用 `content` (句子文字)。
|
||||
* *原因*: 避免 speaker 或 face 的 metadata 干擾語意向量空間，確保語意純淨。Metadata 僅用於過濾 (Filter)。
|
||||
- **嵌入模型**: `nomic-embed-text-v2-moe` (768-dim)。
|
||||
- **嵌入內容**: 僅使用 `content` (句子文字)。
|
||||
- *原因*: 避免 speaker 或 face 的 metadata 干擾語意向量空間，確保語意純淨。Metadata 僅用於過濾 (Filter)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -50,12 +50,12 @@ ai_query_hints:
|
||||
|
||||
Rule 2 的生成主要依賴視覺處理器產出，並輔助以音訊元數據。
|
||||
|
||||
1. **YOLO (Primary)**: 提供幀級別的物件檢測。
|
||||
1. **YOLO (Primary)**: 提供幀級別的物件檢測。
|
||||
- *過濾*: 僅保留 `confidence > 0.8` 的物件。
|
||||
- *格式*: 轉換為描述性字串，如 "a person", "a car", "a cup"。
|
||||
2. **Face (Secondary)**: 提供幀級別的人物 ID。
|
||||
2. **Face (Secondary)**: 提供幀級別的人物 ID。
|
||||
- *策略*: 記錄當前幀所有可見的 `face_id`。
|
||||
3. **ASRX (Audio Overlay)**: 提供當前時間點的說話者。
|
||||
3. **ASRX (Audio Overlay)**: 提供當前時間點的說話者。
|
||||
- *策略*: 取時間重疊的 `speaker_id`，若無則為空。
|
||||
|
||||
### 聚合策略 (Time-Windowing)
|
||||
@@ -130,23 +130,23 @@ CREATE TABLE chunks_rule2 (
|
||||
Rule 2 專為**視覺語意 (Visual Semantics)** 設計。
|
||||
|
||||
### 3.1 視覺關鍵字搜尋 (Visual Keyword Search)
|
||||
* **場景**: "找出有車子的畫面"、"搜尋開車場景"。
|
||||
* **邏輯**:
|
||||
- **場景**: "找出有車子的畫面"、"搜尋開車場景"。
|
||||
- **邏輯**:
|
||||
1. Query: "driving a car"。
|
||||
2. Embedding: 將 "driving a car" 轉為向量。
|
||||
3. Match: 與 `content` ("car, person...") 的向量進行比對。
|
||||
- *注意*: 雖然使用者搜尋是自然語言，但 Rule 2 的底層索引是物件標籤。由於 `nomic-v2-moe` 具有強大的語意對齊能力，"driving a car" 會高度匹配 "car" 標籤。
|
||||
- *注意*: 雖然使用者搜尋是自然語言，但 Rule 2 的底層索引是物件標籤。由於 `nomic-v2-moe` 具有強大的語意對齊能力，"driving a car" 會高度匹配 "car" 標籤。
|
||||
|
||||
### 3.2 高信心值過濾 (Confidence Filtering)
|
||||
* **場景**: "找出 100% 確定有槍的畫面"。
|
||||
* **邏輯**:
|
||||
- 直接查詢 `frame_objects` JSONB 欄位，要求 `confidence > 0.95`。
|
||||
- **場景**: "找出 100% 確定有槍的畫面"。
|
||||
- **邏輯**:
|
||||
- 直接查詢 `frame_objects` JSONB 欄位，要求 `confidence > 0.95`。
|
||||
|
||||
### 3.3 跨模態搜尋
|
||||
* **場景**: "找出 Cary Grant 說話且背景有車的畫面"。
|
||||
* **邏輯**:
|
||||
- `face_ids` 包含 "Cary Grant" **AND**
|
||||
- `frame_objects` 包含 "car"。
|
||||
- **場景**: "找出 Cary Grant 說話且背景有車的畫面"。
|
||||
- **邏輯**:
|
||||
- `face_ids` 包含 "Cary Grant" **AND**
|
||||
- `frame_objects` 包含 "car"。
|
||||
|
||||
---
|
||||
|
||||
@@ -196,8 +196,8 @@ for i in range(0, total_frames, WINDOW):
|
||||
|
||||
### 4.2 嵌入策略 (Embedding Strategy)
|
||||
|
||||
* **輸入文本**: 僅使用 `content` (物件標籤字串)。
|
||||
* **原因**: 確保向量空間專注於**視覺語意**。若混入 Audio (ASR) 文本，會導致搜尋 "車" 時意外匹配到只提到車但未出現車的畫面。
|
||||
- **輸入文本**: 僅使用 `content` (物件標籤字串)。
|
||||
- **原因**: 確保向量空間專注於**視覺語意**。若混入 Audio (ASR) 文本，會導致搜尋 "車" 時意外匹配到只提到車但未出現車的畫面。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user