docs: add chunk API usage, playback format, and API examples

2026-03-25 16:06:11 +08:00
parent f8925ab994
commit 17cab667f9
3 changed files with 231 additions and 41 deletions
--- a/docs/API_TRAINING_MARCOM.md
+++ b/docs/API_TRAINING_MARCOM.md
@@ -76,13 +76,21 @@ curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b6
 ### 3.2 搜尋與分段查詢

 #### POST /api/v1/search
-向量搜尋，查詢分段詳情
+向量搜尋，查詢分段（Chunk）詳情
+
+**請求參數**:
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `query` | string | 是 | 搜尋關鍵字 |
+| `limit` | number | 否 | 回傳數量（預設 10） |
+| `uuid` | string | 否 | 只搜尋指定影片 |

 **請求範例**:
 ```json
 {
-  "query": "關鍵字",
-  "limit": 10
+  "query": "天氣",
+  "limit": 10,
+  "uuid": "5dea6618a606e7c7"
 }
 ```

@@ -91,49 +99,77 @@ curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b6
 {
  "results": [
    {
-      "uuid": "5dea6618a606e7c7",
-      "chunk_id": "time_00001",
-      "chunk_type": "time",
-      "start_time": 0.0,
-      "end_time": 10.0,
-      "text": "分段內容文字",
-      "score": 0.95
+      "uuid": "39567a0eb16f39fd",
+      "chunk_id": "sentence_1471",
+      "chunk_type": "sentence",
+      "start_time": 5309.08,
+      "end_time": 5311.08,
+      "text": "influenced by a vital way,",
+      "score": 0.68
    }
-  ]
+  ],
+  "query": "天氣"
 }
 ```

+**Chunk 欄位說明**:
+| 欄位 | 說明 | 範例 |
+|------|------|------|
+| `uuid` | 影片唯一識別碼 | `39567a0eb16f39fd` |
+| `chunk_id` | 分段識別碼 | `sentence_1471` |
+| `chunk_type` | 分段類型 | `sentence` / `cut` / `time` / `trace` / `story` |
+| `start_time` | 開始時間（秒） | `5309.08` |
+| `end_time` | 結束時間（秒） | `5311.08` |
+| `text` | 內容文字 | `influenced by a vital way` |
+| `score` | 相似度分數（0-1） | `0.68` |
+
+**Chunk 類型說明**:
+| 類型 | 說明 | 來源 |
+|------|------|------|
+| `sentence` | 語音轉文字片段 | ASR 處理 |
+| `cut` | 場景變化片段 | CUT 處理 |
+| `time` | 固定時間分段 | 系統自動切割 |
+| `trace` | 軌跡追蹤片段 | YOLO 追蹤 |
+| `story` | 故事線片段（父子關係） | Story 分析 |
+
 #### POST /api/v1/n8n/search
-n8n 專用搜尋（包含縮圖網址）
+n8n 專用搜尋（包含影片網址）

-**請求範例**:
-```json
-{
-  "query": "關鍵字",
-  "limit": 10
-}
-```
+**請求參數**: 與 `/search` 相同

 **回應範例**:
 ```json
 {
+  "query": "天氣",
+  "count": 2,
  "hits": [
    {
-      "uuid": "5dea6618a606e7c7",
-      "chunk_id": "time_00001",
-      "chunk_type": "time",
-      "start_time": 0.0,
-      "end_time": 10.0,
-      "text": "分段內容文字",
-      "score": 0.95,
-      "thumbnail_url": "https://..."
+      "id": "sentence_1471",
+      "vid": "39567a0eb16f39fd",
+      "start": 5309.08,
+      "end": 5311.08,
+      "title": "Chunk sentence_1471",
+      "text": "influenced by a vital way,",
+      "score": 0.68,
+      "media_url": "https://wp.momentry.ddns.net/video.mp4"
    }
  ]
 }
 ```

+**與 /search 的差異**:
+| 欄位 | `/search` | `/n8n/search` |
+|------|-----------|----------------|
+| 影片 UUID | `uuid` | `vid` |
+| Chunk ID | `chunk_id` | `id` |
+| 開始時間 | `start_time` | `start` |
+| 結束時間 | `end_time` | `end` |
+| 影片網址 | ❌ | ✅ `media_url` |
+
 ### 3.3 任務相關

+### 3.4 任務相關
+
 #### GET /api/v1/jobs/:uuid
 查詢處理任務狀態

@@ -164,7 +200,7 @@ curl -s -H "X-API-Key: ..." \
  "https://api.momentry.ddns.net/api/v1/jobs?status=completed&limit=5"
 ```

-### 3.3 系統管理
+### 3.5 系統管理

 #### POST /api/v1/config/cache
 切換快取功能（管理員專用）
@@ -205,7 +241,7 @@ curl -s -H "X-API-Key: ..." \

 **注意**: 此操作會刪除影片及其所有分段、處理結果、縮圖等關聯資料，**無法復原**。

-### 3.5 健康檢查
+### 3.6 健康檢查

 #### GET /health
 服務健康狀態（**無需認證**）
@@ -330,3 +366,4 @@ GET /api/v1/jobs/{uuid}
 |------|------|------|--------|
 | V1.0 | 2026-03-25 | 初版建立 | OpenCode |
 | V1.1 | 2026-03-25 | 新增快取/刪除 API、搜尋端點文件 | OpenCode |
+| V1.2 | 2026-03-25 | 新增 Chunk 欄位說明、類型、播放方式 | OpenCode |
--- a/docs/API_WORKFLOW_WORDPRESS_N8N.md
+++ b/docs/API_WORKFLOW_WORDPRESS_N8N.md
@@ -154,10 +154,54 @@ curl -s -X POST "https://api.momentry.ddns.net/api/v1/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "測試關鍵字",
-    "top_k": 5
+    "limit": 5
  }'
 ```

+### 取得分段（Chunk）內容
+
+搜尋結果會返回影片分段（Chunk），包含可播放的時間軸資訊：
+
+```json
+{
+  "results": [
+    {
+      "uuid": "39567a0eb16f39fd",
+      "chunk_id": "sentence_1471",
+      "chunk_type": "sentence",
+      "start_time": 5309.08,
+      "end_time": 5311.08,
+      "text": "influenced by a vital way,",
+      "score": 0.68
+    }
+  ]
+}
+```
+
+**Chunk 欄位說明**:
+| 欄位 | 說明 |
+|------|------|
+| `uuid` | 影片 UUID（用於取得影片網址） |
+| `chunk_id` | 分段 ID |
+| `chunk_type` | 分段類型（sentence/cut/time/trace/story） |
+| `start_time` | 開始時間（秒） |
+| `end_time` | 結束時間（秒） |
+| `text` | 語音內容文字 |
+| `score` | 相似度分數（0-1） |
+
+### 播放分段
+
+取得 Chunk 後可組合成播放網址：
+
+```
+影片網址?start={start_time}&end={end_time}
+```
+
+範例：
+```
+https://wp.momentry.ddns.net/video.mp4?start=5309.08&end=5311.08
+```
+
 ---

 ## 完整 n8n Workflow 範例
@@ -295,7 +339,7 @@ switch ($job['status']) {
 }
 ```

-### Step 5: 搜尋內容
+### Step 5: 搜尋內容並取得 Chunk

 ```php
 <?php
@@ -303,14 +347,18 @@ switch ($job['status']) {
 $results = Momentry_API::search('測試關鍵字', 5);

 foreach ($results['results'] as $result) {
-    echo "UUID: " . $result['chunk_id'] . "\n";
-    echo "分數: " . $result['score'] . "\n";
+    echo "影片 UUID: " . $result['uuid'] . "\n";
+    echo "Chunk ID: " . $result['chunk_id'] . "\n";
+    echo "類型: " . $result['chunk_type'] . "\n";
+    echo "開始: " . $result['start_time'] . "s\n";
+    echo "結束: " . $result['end_time'] . "s\n";
    echo "內容: " . ($result['text'] ?? '') . "\n";
+    echo "相似度: " . $result['score'] . "\n";
    echo "---\n";
 }
 ```

-### WordPress Shortcode 範例
+### WordPress Shortcode 範例（可點擊播放）

 ```php
 <?php
@@ -337,10 +385,21 @@ add_shortcode('momentry_search', function($atts) {
        $html .= '<ul>';

        foreach ($results['results'] as $result) {
+            $video_uuid = $result['uuid'];
+            $start = $result['start_time'] ?? 0;
+            $end = $result['end_time'] ?? 0;
+            $text = $result['text'] ?? '無文字描述';
+            
            $html .= '<li>';
-            $html .= '<strong>時間: ' . ($result['start_time'] ?? 'N/A') . 's</strong>';
+            $html .= '<a href="/player?uuid=' . esc_attr($video_uuid) . 
+                     '&start=' . esc_attr($start) . 
+                     '&end=' . esc_attr($end) . '">';
+            $html .= '播放 ' . $start . 's - ' . $end . 's';
+            $html .= '</a>';
            $html .= '<br>';
-            $html .= esc_html($result['text'] ?? '無文字描述');
+            $html .= '<small>相似度: ' . round($result['score'] * 100) . '%</small>';
+            $html .= '<br>';
+            $html .= esc_html($text);
            $html .= '</li>';
        }

@@ -398,3 +457,4 @@ add_shortcode('momentry_search', function($atts) {
 | 版本 | 日期 | 內容 | 操作人 |
 |------|------|------|--------|
 | V1.0 | 2026-03-25 | 初版建立 | OpenCode |
+| V1.1 | 2026-03-25 | 新增 Chunk 取得與播放說明、Shortcode 範例 | OpenCode |
--- a/docs/CHUNK_DATA_STRUCTURE.md
+++ b/docs/CHUNK_DATA_STRUCTURE.md
@@ -236,7 +236,33 @@ Chunk（片段）是影片處理後的最小單位。當影片上傳後，系統

 ## 6. 如何使用 Chunk

-### 6.1 搜尋相關片段
+### 6.1 API 取得 Chunk
+
+使用搜尋 API 取得 Chunk：
+
+```bash
+curl -X POST "https://api.momentry.ddns.net/api/v1/search" \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "關鍵字",
+    "limit": 10
+  }'
+```
+
+**指定影片搜尋**：
+```bash
+curl -X POST "https://api.momentry.ddns.net/api/v1/search" \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "關鍵字",
+    "uuid": "39567a0eb16f39fd",
+    "limit": 5
+  }'
+```
+
+### 6.2 搜尋相關片段

 當使用者搜尋「天氣」時，系統會：

@@ -245,22 +271,88 @@ Chunk（片段）是影片處理後的最小單位。當影片上傳後，系統
 3. 找到相關的 Chunk
 4. 返回時間軸和內容

-### 6.2 播放指定片段
+### 6.3 播放指定片段

 取得 Chunk 後可播放：

 ```
 開始時間: 12.5 秒
 結束時間: 18.3 秒
+影片 UUID: 39567a0eb16f39fd
 ```

-### 6.3 組合多個 Chunk
+**播放器連結格式**：
+```
+/player?uuid={uuid}&start={start_time}&end={end_time}
+```
+
+### 6.4 組合多個 Chunk

 多個相關 Chunk 可以組合成一個章節或故事線。

+### 6.5 Story Chunk（父子關係）
+
+Story Chunk 可包含多個子 Chunk：
+
+```json
+{
+  "chunk_id": "story_001",
+  "chunk_type": "story",
+  "content": {
+    "story_id": "story_001",
+    "title": "開場介紹",
+    "child_chunk_ids": ["sentence_00001", "sentence_00002", "cut_00001"]
+  }
+}
+```
+
 ---

-## 7. 快速參考
+## 7. API 回應格式
+
+### /search 回應
+
+```json
+{
+  "results": [
+    {
+      "uuid": "39567a0eb16f39fd",
+      "chunk_id": "sentence_1471",
+      "chunk_type": "sentence",
+      "start_time": 5309.08,
+      "end_time": 5311.08,
+      "text": "influenced by a vital way,",
+      "score": 0.68
+    }
+  ],
+  "query": "關鍵字"
+}
+```
+
+### /n8n/search 回應
+
+```json
+{
+  "query": "關鍵字",
+  "count": 1,
+  "hits": [
+    {
+      "id": "sentence_1471",
+      "vid": "39567a0eb16f39fd",
+      "start": 5309.08,
+      "end": 5311.08,
+      "title": "Chunk sentence_1471",
+      "text": "influenced by a vital way,",
+      "score": 0.68,
+      "media_url": "https://wp.momentry.ddns.net/video.mp4"
+    }
+  ]
+}
+```
+
+---
+
+## 8. 快速參考

 | 項目 | 說明 |
 |------|------|
@@ -273,7 +365,7 @@ Chunk（片段）是影片處理後的最小單位。當影片上傳後，系統
 | content | 詳細 JSON 結構 |
 | metadata | 人臉、OCR、姿態等偵測結果 |
 | parent_chunk_id | 父區塊 ID（用於 story 區塊） |
-| child_chunk_ids | 子區塊 ID 列表（story 區塊專用） |
+| child_chunk_ids | 子區塊 ID 列表（story 區塊專用） | |

 ---

@@ -282,3 +374,4 @@ Chunk（片段）是影片處理後的最小單位。當影片上傳後，系統
 | 版本 | 日期 | 內容 | 操作人 |
 |------|------|------|--------|
 | V1.0 | 2026-03-25 | 初版建立 | OpenCode |
+| V1.1 | 2026-03-25 | 新增 API 取得 Chunk 方式、播放連結格式 | OpenCode |