feat: add cache toggle, unregister API and chunk training docs
- Add POST /api/v1/config/cache for cache toggle - Add POST /api/v1/unregister for video deletion - Add CHUNK_DATA_STRUCTURE.md for marcom training - Fix processor_results query in delete_video
This commit is contained in:
Warren
281
docs/CHUNK_DATA_STRUCTURE.md
Normal file
281
docs/CHUNK_DATA_STRUCTURE.md
Normal file
@@ -0,0 +1,281 @@
|
||||
# Momentry Chunk 資料結構說明
|
||||
|
||||
> **對象**: marcom 團隊
|
||||
> **版本**: V1.0 | **日期**: 2026-03-25
|
||||
|
||||
---
|
||||
|
||||
## 1. 什麼是 Chunk？
|
||||
|
||||
Chunk（片段）是影片處理後的最小單位。當影片上傳後，系統會自動：
|
||||
|
||||
1. **分析** - 偵測場景、人臉、姿態
|
||||
2. **轉換** - 語音轉文字（ASR）
|
||||
3. **分段** - 將內容切割成可搜尋的片段
|
||||
4. **向量化** - 產生可搜尋的特徵向量
|
||||
|
||||
每個 Chunk 就是一個**可獨立搜尋的內容單位**。
|
||||
|
||||
---
|
||||
|
||||
## 2. Chunk 資料結構
|
||||
|
||||
### 2.1 主要欄位
|
||||
|
||||
| 欄位名 | 類型 | 說明 | 範例 |
|
||||
|--------|------|------|------|
|
||||
| `uuid` | 字串 (32) | 影片唯一識別碼 | `952f5854b9febad1` |
|
||||
| `chunk_id` | 字串 (64) | Chunk 唯一識別碼 | `asr_00001` |
|
||||
| `chunk_index` | 整數 | Chunk 順序號碼 | `1` |
|
||||
| `chunk_type` | 字串 (32) | Chunk 類型 | `sentence` |
|
||||
| `start_time` | 浮點數 | 開始時間（秒） | `12.5` |
|
||||
| `end_time` | 浮點數 | 結束時間（秒） | `18.3` |
|
||||
| `content` | JSONB | 詳細內容 | 見下方 |
|
||||
| `vector_id` | 字串 (64) | 向量 ID | `vec_12345` |
|
||||
| `text_content` | 文字 | 純文字內容 | `這是一段話` |
|
||||
| `fps` | 浮點數 | 影片幀率 | `24.0` |
|
||||
| `start_frame` | 整數 | 開始幀數 | `300` |
|
||||
| `end_frame` | 整數 | 結束幀數 | `439` |
|
||||
| `frame_count` | 整數 | 總幀數 | `139` |
|
||||
|
||||
### 2.2 Chunk 類型說明
|
||||
|
||||
| 類型 | ID | 說明 | 來源處理器 |
|
||||
|------|-----|------|-----------|
|
||||
| `sentence` | `sentence` | 語音轉文字片段 | ASR 處理 |
|
||||
| `time` | `time_based` | 固定時間分段 | 系統自動切割 |
|
||||
| `cut` | `cut` | 場景變化片段 | CUT 處理 |
|
||||
| `trace` | `trace` | 軌跡追蹤片段 | YOLO 追蹤處理 |
|
||||
| `story` | `story` | 故事線片段（父子區塊） | Story 分析處理 |
|
||||
|
||||
**父子區塊關係**：
|
||||
- `story` 是**父區塊**，可包含多個 `sentence`、`cut`、`trace` 子區塊
|
||||
- 透過 `parent_chunk_id` 和 `child_chunk_ids` 建立階層關係
|
||||
|
||||
---
|
||||
|
||||
## 3. Content JSON 結構
|
||||
|
||||
每個 Chunk 的 `content` 欄位包含詳細的處理結果：
|
||||
|
||||
### 3.1 ASR Chunk（語音轉文字）
|
||||
|
||||
```json
|
||||
{
|
||||
"text": "今天天氣非常好，我們去郊外踏青吧",
|
||||
"words": [
|
||||
{
|
||||
"word": "今天",
|
||||
"start": 12.5,
|
||||
"end": 12.8,
|
||||
"confidence": 0.95
|
||||
},
|
||||
{
|
||||
"word": "天氣",
|
||||
"start": 12.8,
|
||||
"end": 13.1,
|
||||
"confidence": 0.92
|
||||
}
|
||||
],
|
||||
"language": "zh-TW",
|
||||
"speaker": null
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 Cut Chunk（場景偵測）
|
||||
|
||||
```json
|
||||
{
|
||||
"scenes": [
|
||||
{
|
||||
"scene_id": "cut_001",
|
||||
"start_time": 12.5,
|
||||
"end_time": 45.2,
|
||||
"transition": "cut",
|
||||
"confidence": 0.98
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 Trace Chunk（軌跡追蹤）
|
||||
|
||||
```json
|
||||
{
|
||||
"track_id": "track_001",
|
||||
"object_class": "person",
|
||||
"frames": [
|
||||
{
|
||||
"frame": 300,
|
||||
"bbox": [120, 80, 200, 300],
|
||||
"confidence": 0.95
|
||||
},
|
||||
{
|
||||
"frame": 301,
|
||||
"bbox": [122, 82, 202, 302],
|
||||
"confidence": 0.94
|
||||
}
|
||||
],
|
||||
"total_frames": 180
|
||||
}
|
||||
```
|
||||
|
||||
### 3.4 Story Chunk（故事線）
|
||||
|
||||
```json
|
||||
{
|
||||
"story_id": "story_001",
|
||||
"title": "開場介紹",
|
||||
"summary": "主持人介紹節目主題",
|
||||
"child_chunk_ids": ["sentence_00001", "sentence_00002", "cut_00001"],
|
||||
"tags": ["intro", "host"]
|
||||
}
|
||||
```
|
||||
|
||||
### 3.5 Metadata（其他偵測資訊）
|
||||
|
||||
人臉（Face）、文字辨識（OCR）、姿態（Pose）等偵測結果會附加在 `metadata` 欄位：
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"faces": [
|
||||
{
|
||||
"bbox": [120, 80, 200, 180],
|
||||
"confidence": 0.87,
|
||||
"emotion": "neutral"
|
||||
}
|
||||
],
|
||||
"ocr": {
|
||||
"text": "MOMENTRY",
|
||||
"confidence": 0.96
|
||||
},
|
||||
"pose": {
|
||||
"keypoints": [
|
||||
{"name": "nose", "x": 192, "y": 85, "confidence": 0.95}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 時間格式說明
|
||||
|
||||
### 4.1 秒數格式（常用）
|
||||
|
||||
```
|
||||
格式: 秒.幀數
|
||||
範例: 1234.60 = 第 1234 秒 + 第 60 幀
|
||||
```
|
||||
|
||||
### 4.2 時間軸格式
|
||||
|
||||
```
|
||||
格式: HH:MM:SS.FF
|
||||
範例: 00:20:34.12 = 20分34秒12幀
|
||||
```
|
||||
|
||||
### 4.3 幀數計算
|
||||
|
||||
```
|
||||
幀數 = 秒數 × fps
|
||||
例如: 12.5秒 × 24fps = 300幀
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 實際資料範例
|
||||
|
||||
假設有一個影片，包含以下處理結果：
|
||||
|
||||
### 5.1 語音片段
|
||||
|
||||
```json
|
||||
{
|
||||
"uuid": "952f5854b9febad1",
|
||||
"chunk_id": "asr_00001",
|
||||
"chunk_type": "sentence",
|
||||
"start_time": 12.5,
|
||||
"end_time": 18.3,
|
||||
"content": {
|
||||
"text": "今天天氣非常好，我們去郊外踏青吧",
|
||||
"language": "zh-TW"
|
||||
},
|
||||
"text_content": "今天天氣非常好，我們去郊外踏青吧",
|
||||
"start_frame": 300,
|
||||
"end_frame": 439,
|
||||
"fps": 24.0
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 場景片段
|
||||
|
||||
```json
|
||||
{
|
||||
"uuid": "952f5854b9febad1",
|
||||
"chunk_id": "cut_00001",
|
||||
"chunk_type": "cut",
|
||||
"start_time": 45.0,
|
||||
"end_time": 120.5,
|
||||
"content": {
|
||||
"scenes": [{
|
||||
"scene_id": "cut_001",
|
||||
"transition": "cut",
|
||||
"confidence": 0.98
|
||||
}]
|
||||
},
|
||||
"start_frame": 1080,
|
||||
"end_frame": 2892,
|
||||
"fps": 24.0
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 如何使用 Chunk
|
||||
|
||||
### 6.1 搜尋相關片段
|
||||
|
||||
當使用者搜尋「天氣」時，系統會：
|
||||
|
||||
1. 將「天氣」轉換為向量
|
||||
2. 在向量資料庫中搜尋相似向量
|
||||
3. 找到相關的 Chunk
|
||||
4. 返回時間軸和內容
|
||||
|
||||
### 6.2 播放指定片段
|
||||
|
||||
取得 Chunk 後可播放：
|
||||
|
||||
```
|
||||
開始時間: 12.5 秒
|
||||
結束時間: 18.3 秒
|
||||
```
|
||||
|
||||
### 6.3 組合多個 Chunk
|
||||
|
||||
多個相關 Chunk 可以組合成一個章節或故事線。
|
||||
|
||||
---
|
||||
|
||||
## 7. 快速參考
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| UUID | 影片唯一識別碼（16位 hex） |
|
||||
| Chunk ID | 片段識別碼（如 `sentence_00001`） |
|
||||
| chunk_type | 片段類型（sentence/time/cut/trace/story） |
|
||||
| start_time | 開始時間（秒） |
|
||||
| end_time | 結束時間（秒） |
|
||||
| text_content | 純文字內容 |
|
||||
| content | 詳細 JSON 結構 |
|
||||
| metadata | 人臉、OCR、姿態等偵測結果 |
|
||||
| parent_chunk_id | 父區塊 ID（用於 story 區塊） |
|
||||
| child_chunk_ids | 子區塊 ID 列表（story 區塊專用） |
|
||||
|
||||
---
|
||||
|
||||
**文件版本**: V1.0
|
||||
**最後更新**: 2026-03-25
|
||||
@@ -148,6 +148,30 @@ struct SearchRequest {
|
||||
uuid: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Deserialize)]
|
||||
struct CacheToggleRequest {
|
||||
enabled: bool,
|
||||
}
|
||||
|
||||
#[derive(Debug, Serialize)]
|
||||
struct CacheToggleResponse {
|
||||
success: bool,
|
||||
cache_enabled: bool,
|
||||
message: String,
|
||||
}
|
||||
|
||||
#[derive(Debug, Deserialize)]
|
||||
struct UnregisterRequest {
|
||||
uuid: String,
|
||||
}
|
||||
|
||||
#[derive(Debug, Serialize)]
|
||||
struct UnregisterResponse {
|
||||
success: bool,
|
||||
uuid: String,
|
||||
message: String,
|
||||
}
|
||||
|
||||
#[derive(Debug, Serialize, Deserialize)]
|
||||
struct SearchResult {
|
||||
uuid: String,
|
||||
@@ -1300,6 +1324,56 @@ async fn get_job(
|
||||
Ok(Json(response))
|
||||
}
|
||||
|
||||
async fn cache_toggle(
|
||||
State(_state): State<AppState>,
|
||||
Json(req): Json<CacheToggleRequest>,
|
||||
) -> Result<Json<CacheToggleResponse>, StatusCode> {
|
||||
tracing::info!("[cache_toggle] Setting cache enabled to: {}", req.enabled);
|
||||
|
||||
crate::core::config::set_cache_enabled(req.enabled);
|
||||
|
||||
let response = CacheToggleResponse {
|
||||
success: true,
|
||||
cache_enabled: req.enabled,
|
||||
message: if req.enabled {
|
||||
"Cache enabled".to_string()
|
||||
} else {
|
||||
"Cache disabled".to_string()
|
||||
},
|
||||
};
|
||||
|
||||
tracing::info!("[cache_toggle] SUCCESS");
|
||||
Ok(Json(response))
|
||||
}
|
||||
|
||||
async fn unregister(
|
||||
State(state): State<AppState>,
|
||||
Json(req): Json<UnregisterRequest>,
|
||||
) -> Result<Json<UnregisterResponse>, StatusCode> {
|
||||
tracing::info!("[unregister] Unregistering video: {}", req.uuid);
|
||||
|
||||
let db = &state.api_state.db;
|
||||
|
||||
match db.delete_video(&req.uuid).await {
|
||||
Ok(_) => {
|
||||
tracing::info!("[unregister] SUCCESS - deleted: {}", req.uuid);
|
||||
Ok(Json(UnregisterResponse {
|
||||
success: true,
|
||||
uuid: req.uuid,
|
||||
message: "Video unregistered successfully".to_string(),
|
||||
}))
|
||||
}
|
||||
Err(e) => {
|
||||
tracing::error!("[unregister] ERROR - {}", e);
|
||||
Ok(Json(UnregisterResponse {
|
||||
success: false,
|
||||
uuid: req.uuid,
|
||||
message: format!("Failed to unregister: {}", e),
|
||||
}))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
pub async fn start_server(host: &str, port: u16) -> anyhow::Result<()> {
|
||||
let _ = SERVER_START.set(Instant::now());
|
||||
|
||||
@@ -1319,6 +1393,7 @@ pub async fn start_server(host: &str, port: u16) -> anyhow::Result<()> {
|
||||
|
||||
let protected_routes = Router::new()
|
||||
.route("/api/v1/register", post(register))
|
||||
.route("/api/v1/unregister", post(unregister))
|
||||
.route("/api/v1/probe", post(probe))
|
||||
.route("/api/v1/search", post(search))
|
||||
.route("/api/v1/n8n/search", post(n8n_search))
|
||||
@@ -1328,6 +1403,7 @@ pub async fn start_server(host: &str, port: u16) -> anyhow::Result<()> {
|
||||
.route("/api/v1/progress/:uuid", get(get_progress))
|
||||
.route("/api/v1/jobs", get(list_jobs))
|
||||
.route("/api/v1/jobs/:uuid", get(get_job))
|
||||
.route("/api/v1/config/cache", post(cache_toggle))
|
||||
.layer(axum::middleware::from_fn_with_state(
|
||||
state.api_state.clone(),
|
||||
api_key_validation,
|
||||
|
||||
@@ -1,5 +1,23 @@
|
||||
use once_cell::sync::Lazy;
|
||||
use std::env;
|
||||
use std::sync::RwLock;
|
||||
|
||||
pub static RUNTIME_CACHE_ENABLED: Lazy<RwLock<bool>> = Lazy::new(|| {
|
||||
let initial = env::var("MONGODB_CACHE_ENABLED")
|
||||
.unwrap_or_else(|_| "true".to_string())
|
||||
.parse()
|
||||
.unwrap_or(true);
|
||||
RwLock::new(initial)
|
||||
});
|
||||
|
||||
pub fn get_cache_enabled() -> bool {
|
||||
*RUNTIME_CACHE_ENABLED.read().unwrap()
|
||||
}
|
||||
|
||||
pub fn set_cache_enabled(enabled: bool) {
|
||||
*RUNTIME_CACHE_ENABLED.write().unwrap() = enabled;
|
||||
tracing::info!("Cache enabled set to: {}", enabled);
|
||||
}
|
||||
|
||||
pub static DATABASE_URL: Lazy<String> = Lazy::new(|| {
|
||||
env::var("DATABASE_URL")
|
||||
|
||||
@@ -584,6 +584,40 @@ impl PostgresDb {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub async fn delete_video(&self, uuid: &str) -> Result<()> {
|
||||
tracing::info!("[PostgresDb] Deleting video: {}", uuid);
|
||||
|
||||
let tx = self.pool.begin().await?;
|
||||
|
||||
sqlx::query("DELETE FROM chunk_vectors WHERE uuid = $1")
|
||||
.bind(uuid)
|
||||
.execute(&self.pool)
|
||||
.await?;
|
||||
|
||||
sqlx::query("DELETE FROM chunks WHERE uuid = $1")
|
||||
.bind(uuid)
|
||||
.execute(&self.pool)
|
||||
.await?;
|
||||
|
||||
sqlx::query("DELETE FROM processor_results WHERE video_id IN (SELECT id FROM videos WHERE uuid = $1)")
|
||||
.bind(uuid)
|
||||
.execute(&self.pool)
|
||||
.await?;
|
||||
|
||||
sqlx::query("DELETE FROM videos WHERE uuid = $1")
|
||||
.bind(uuid)
|
||||
.execute(&self.pool)
|
||||
.await?;
|
||||
|
||||
tx.commit().await?;
|
||||
|
||||
let mut cache = self.cache.write().await;
|
||||
cache.videos.remove(uuid);
|
||||
|
||||
tracing::info!("[PostgresDb] Video deleted: {}", uuid);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub async fn get_storage_status(&self, uuid: &str) -> Result<Option<StorageStatus>> {
|
||||
if let Some(video) = self.get_video_by_uuid(uuid).await? {
|
||||
Ok(Some(video.storage))
|
||||
|
||||
Reference in New Issue
Block a user