diff --git a/docs_v1.0/IMPLEMENTATION/SCENE_API_INTEGRATION.md b/docs_v1.0/IMPLEMENTATION/SCENE_API_INTEGRATION.md new file mode 100644 index 0000000..b4893bb --- /dev/null +++ b/docs_v1.0/IMPLEMENTATION/SCENE_API_INTEGRATION.md @@ -0,0 +1,141 @@ +# 場景識別 API 整合指南 + +## 概述 + +本文檔說明如何在 Playground (port 3003) 中使用場景識別功能。 + +## API Endpoint + +### 場景識別 + +**Endpoint**: `GET /api/v1/scene/:uuid` + +**描述**: 對指定影片執行場景識別 + +**參數**: +- `uuid` (path): 影片 UUID + +**回應格式**: +```json +{ + "video_uuid": "384b0ff44aaaa1f1", + "scenes": [ + { + "start_time": 0.0, + "end_time": 156.0, + "scene_type": "office", + "scene_type_zh": "辦公室", + "confidence": 0.87, + "duration": 156.0 + } + ], + "processing_time": 1.3 +} +``` + +## 使用方式 + +### 1. 啟動 Playground 伺服器 + +```bash +# 使用 port 3003 +cargo run --bin momentry_playground -- server --host 0.0.0.0 --port 3003 +``` + +### 2. 測試場景識別 + +```bash +# 使用測試腳本 +python3 scripts/test_scene_api.py + +# 範例 +python3 scripts/test_scene_api.py 384b0ff44aaaa1f1 +``` + +### 3. 直接使用 curl + +```bash +curl -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \ + "http://localhost:3003/api/v1/scene/384b0ff44aaaa1f1" +``` + +## Python 整合範例 + +```python +import requests + +API_KEY = "muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" +BASE_URL = "http://localhost:3003" + +def classify_scene(video_uuid): + """執行場景識別""" + response = requests.get( + f"{BASE_URL}/api/v1/scene/{video_uuid}", + headers={"X-API-Key": API_KEY} + ) + + if response.status_code == 200: + return response.json() + else: + raise Exception(f"API error: {response.status_code}") + +# 使用範例 +result = classify_scene("384b0ff44aaaa1f1") +print(f"場景數量:{len(result['scenes'])}") +for scene in result['scenes']: + print(f" - {scene['scene_type']} ({scene['confidence']*100:.1f}%)") +``` + +## 目前狀態 + +### 已完成 ✅ +- ✅ 場景識別 Python 腳本 (`scripts/scene_classifier.py`) +- ✅ Places365 380 個場景類別 +- ✅ API 測試腳本 (`scripts/test_scene_api.py`) +- ✅ Rust API handler 設計 + +### 進行中 ⏳ +- ⏳ Rust API endpoint 完整實作 +- ⏳ 與資料庫整合 +- ⏳ 錯誤處理優化 + +### 已知限制 +- Rust API endpoint 需要完整實作以支援資料庫查詢 +- 目前建議使用 Python 腳本直接測試 + +## 故障排除 + +### 問題:API 回應 404 + +**可能原因**: +- 影片 UUID 不存在 +- Playground 伺服器未啟動 + +**解決方案**: +```bash +# 檢查伺服器狀態 +curl http://localhost:3003/health + +# 檢查影片是否存在 +curl -H "X-API-Key: ..." "http://localhost:3003/api/v1/videos" +``` + +### 問題:處理時間過長 + +**建議**: +- 減少取樣頻率 (`--sample-interval`) +- 增加最小場景持續時間 (`--min-scene-duration`) +- 使用 Places365 Core ML 模型(而非 PyTorch) + +## 相關文檔 + +- `docs_v1.0/IMPLEMENTATION/SCENE_CLASSIFICATION_MODULE.md` - 模組使用手冊 +- `docs_v1.0/IMPLEMENTATION/PLACES365_INSTALLATION.md` - 模型安裝指南 +- `docs_v1.0/TESTING/SCENE_CLASSIFICATION_TEST_REPORT_2026_04_01.md` - 測試報告 + +## 下一步 + +1. 完成 Rust API endpoint 實作 +2. 整合資料庫查詢 +3. 添加異步處理支援 +4. 優化效能和記憶體使用 diff --git a/scripts/test_scene_api.py b/scripts/test_scene_api.py new file mode 100755 index 0000000..50d048d --- /dev/null +++ b/scripts/test_scene_api.py @@ -0,0 +1,67 @@ +#!/usr/bin/env python3 +"""測試場景識別 API""" + +import requests +import json +import sys + +API_KEY = "muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" +BASE_URL = "http://localhost:3003" + +def test_scene_classification(video_uuid: str): + """測試場景識別 API""" + print(f"測試場景識別 API: {video_uuid}") + print(f"API URL: {BASE_URL}/api/v1/scene/{video_uuid}") + + headers = { + "X-API-Key": API_KEY + } + + try: + response = requests.get( + f"{BASE_URL}/api/v1/scene/{video_uuid}", + headers=headers, + timeout=300 + ) + + print(f"\nHTTP 狀態碼:{response.status_code}") + + if response.status_code == 200: + result = response.json() + print(f"\n✓ 場景識別成功") + print(f"處理時間:{result.get('processing_time', 0):.2f} 秒") + print(f"場景數量:{len(result.get('scenes', []))}") + + if result.get('scenes'): + print(f"\n場景詳情:") + for i, scene in enumerate(result['scenes'][:3]): + print(f" {i+1}. {scene.get('scene_type')} ({scene.get('confidence', 0)*100:.1f}%)") + print(f" 時間:{scene.get('start_time', 0):.1f}s - {scene.get('end_time', 0):.1f}s") + + return True + else: + print(f"\n✗ API 請求失敗:{response.status_code}") + print(f"回應:{response.text[:200]}") + return False + + except requests.exceptions.RequestException as e: + print(f"\n✗ 請求錯誤:{e}") + print("\n請確認:") + print("1. Playground 伺服器已啟動 (port 3003)") + print("2. API key 正確") + print("3. 影片 UUID 存在") + return False + +def main(): + if len(sys.argv) < 2: + print("使用方式:python3 scripts/test_scene_api.py ") + print("\n範例:") + print(" python3 scripts/test_scene_api.py 384b0ff44aaaa1f1") + sys.exit(1) + + video_uuid = sys.argv[1] + success = test_scene_classification(video_uuid) + sys.exit(0 if success else 1) + +if __name__ == "__main__": + main()