# Momentry 搜尋 API 統一與多維度搜尋改善計畫

> **日期**: 2026-04-17  
> **發起原因**:  
> 1. 目前各搜尋 API 回傳的 JSON 結構不一致，缺乏 `start_frame` / `end_frame` 等關鍵定位資訊。  
> 2. 目前的 Vector Search 僅搜尋 ASR Collection，忽略了 YOLO、Face、Pose 等視覺維度的資料。

---

## 1. 問題分析

### A. JSON 回應不一致
| API | 欄位名稱 | 時間精度 | 定位精度 |
|-----|----------|----------|----------|
| `/api/v1/search` | `uuid`, `chunk_id`, `start_time` | `start_time` | ❌ 無 |
| `/api/v1/n8n/search` | `vid`, `id`, `start_time` | `start_time`, `end_time` | ✅ `start_frame`, `end_frame` |
| `/api/v1/search/hybrid` | `uuid`, `chunk_id`, `start_time` | `start_time`, `end_time` | ✅ `start_frame`, `end_frame` |

**改善方向**: 所有 API 應統一回傳 `start_time`, `end_time`, `start_frame`, `end_frame`, `fps`，以確保前端或自動化腳本能精確 Seek。

### B. 向量搜尋僅限 ASR
目前 `/api/v1/search` 使用 `QdrantDb` 進行搜尋，但該 Collection (momentry_rule1) 僅包含語音轉錄 (ASR) 的向量。這導致搜尋「穿紅衣服的人」或「開車的場景」等視覺內容時，結果不理想。

---

## 2. 改善目標

### 目標一：統一搜尋回應結構 (Unified Schema)
建立一個標準的 `SearchHit` 結構，供所有 `/search` 系列 API 使用。

**新標準欄位**:
- **id**: Chunk ID
- **vid**: Video UUID
- **chunk_type**: 類型 (asr, yolo, face, story, etc.)
- **start_time / end_time**: 時間 (秒)
- **start_frame / end_frame**: 幀號 (精確定準則)
- **fps**: 幀率
- **text**: 內容文字
- **score**: 分數
- **file_path**: 影片路徑
- **metadata**: 額外資訊 (如 5W1H)

### 目標二：多維度向量搜尋 (Multi-Modal Vector Search)
在 Qdrant 中區分不同類型的 Collection，搜尋時可同時或分層查詢：
- `asr`: 語音內容 (已有)
- `face`: 臉部特徵 (Face Embedding)
- `object`: 物件偵測 (YOLO Embedding)
- `scene`: 場景描述 (Scene Classification)

**搜尋策略**:
1. **全域搜尋 (Global Search)**: 同時查詢 `asr`, `face`, `object`, `scene` 四個 Collection。
2. **權重融合 (Reranking)**: 將不同 Collection 的結果依據相關性進行合併與重排。

---

## 3. 執行計畫

### Phase 1: 結構統一 (Struct Unification)
| 任務 | 說明 |
|------|------|
| **1.1** | 建立 `UnifiedSearchHit` struct (取代現有的 `SearchResult` 與部分 `N8nSearchHit`) |
| **1.2** | 修改 `/api/v1/search` 實作，補齊 `start_frame`, `end_frame`, `fps` 欄位 |
| **1.3** | 修改 `/api/v1/search/hybrid` 實作，確保欄位與新結構一致 |
| **1.4** | 統一命名規範：`uuid` → `vid`, `chunk_id` → `id` (維持 API 向後相容或明確版本區分) |

### Phase 2: Qdrant 多維度擴充 (Multi-Modal Qdrant)
| 任務 | 說明 |
|------|------|
| **2.1** | 修改 `QdrantDb`，支援動態 Collection 參數或同時搜尋多個 Collection |
| **2.2** | 確認 `face`, `object`, `scene` 等 Collection 的向量維度是否一致 |
| **2.3** | 實作 `/api/v1/search/multimodal` 或擴充現有 `/api/v1/search` 支援多 Collection 搜尋 |
| **2.4** | 在 `search_bm25` 中補強視覺資料搜尋 (如物件標籤的關鍵字匹配) |

### Phase 3: 智慧路由 (Smart Routing)
| 任務 | 說明 |
|------|------|
| **3.1** | 開發 `/api/v1/search/smart`：自動判斷 Query 是屬於語意、視覺或混合意圖 |
| **3.2** | 根據意圖自動選擇最佳的 Collection 組合 (ASR-only 或 ASR+Face+Object) |

---

## 4. 預期效益

1. **開發者體驗提升**: 只需處理一套 JSON 格式，降低串接成本。
2. **影片定位精確化**: `start_frame` / `end_frame` 成為所有搜尋的標準配置，減少前端計算誤差。
3. **搜尋準確度躍升**: 解決「只聽不看」的盲點，真正實現多模態 RAG (Retrieval-Augmented Generation)。

---

## 5. 風險評估

| 風險 | 影響 | 應對策略 |
|------|------|----------|
| Qdrant Collection 維度不一致 | 無法合併搜尋 | 檢查並重新 Embedding 以確保維度統一 (如 768 dim) |
| API 欄位更名導致前端失效 | 前端崩潰 | 保留舊欄位為 Deprecated，於 V2 API 中移除 |
| 多 Collection 搜尋效能下降 | 延遲增加 | 使用非同步平行查詢 (`tokio::join!`) |

---

## 6. 版本歷史

| 版本 | 日期 | 內容 |
|------|------|------|
| V1.0 | 2026-04-17 | 建立初步改善計畫 |
