# Feature：推論操作（P0：Camera；P1：Image / Video / Batch）

> 父文件：[PRD.md](../PRD.md) | 對應 User Stories：US-10、US-11、US-15

---

## 概述

使用者選裝置 + 模型 + 來源後，能啟動推論並即時看到結果（bounding box / 分類結果）。

這是**visionA Cloud 最核心的價值體驗**。推論結果要即時、低延遲、UI 和 local-tool 一致。

---

## 使用者行為

### Workspace 進入點（`/workspace` 或 `/workspace/[deviceId]`）

三段式選擇：

1. **選裝置**：從已配對的裝置列表挑一個
2. **選模型**：從模型庫挑一個（需和裝置型號相容）
3. **選來源**：
   - **Camera（Phase 0）**：使用者 agent 端的 USB / IP camera
   - **Image（Phase 1）**：從瀏覽器上傳單張圖片
   - **Video（Phase 1）**：從瀏覽器上傳影片（MP4/AVI/MOV 等）
   - **Batch Images（Phase 1）**：批次上傳多張圖片

選完後進推論工作區。

### 推論工作區

**UI 沿用 local-tool 的設計**：

- 左上：即時 MJPEG 畫面 + overlay（bounding box + label + confidence）
- 右側：控制面板
  - 信心度門檻 slider
  - 推論 FPS / 延遲顯示
  - 開始 / 停止按鈕
- 底下：分類結果 / 偵測框列表
- 右上 header：Tunnel 延遲顯示（visionA Cloud 獨有）

### Camera 推論流程（Phase 0 重點）

```
┌────────────────────────────────────────────────────────────┐
│                    Camera 推論資料流                        │
│                                                            │
│  1. Browser 呼叫 api-server：POST /workspace/start         │
│     { deviceId, modelId, source: "camera", cameraId }      │
│       ▼                                                    │
│  2. api-server 找到對應的 tunnel session                   │
│     透過 remote-proxy 轉發到 local agent                   │
│       ▼                                                    │
│  3. local agent 啟動 KneronPLUS inference pipeline         │
│     Camera → 幀捕捉 → Kneron → 推論結果                    │
│       ▼                                                    │
│  4. local agent 把 MJPEG stream 推給 tunnel                │
│     tunnel ─yamux stream─> remote-proxy ─> api-server      │
│       ▼                                                    │
│  5. Browser 透過 /api/camera/stream 拿到 MJPEG             │
│     （遠端 stream 經過 api-server proxy 到瀏覽器）         │
│       ▼                                                    │
│  6. Browser 透過 WebSocket /ws/inference 拿到推論結果      │
│     Canvas overlay bounding box                            │
└────────────────────────────────────────────────────────────┘
```

### 關鍵技術挑戰（給 Architect 參考）

1. **MJPEG binary stream 要能過 tunnel**：yamux 支援，但需要測試吞吐量
2. **WebSocket（推論結果）也要過 tunnel**：雲端前端的 WebSocket 連到 api-server，api-server 的對應連線再過 tunnel 到 local agent
3. **多 client 存取同一個 stream**：local-tool 支援多 client multipart MJPEG。visionA Cloud 可能一個使用者開多個 tab，要處理並發
4. **Tunnel 斷線處理**：推論中 tunnel 斷線，UI 要明確提示並自動重連

### 延遲預算

| 路徑段 | 延遲 |
|--------|-----|
| Camera → local agent 幀捕捉 | ~10ms |
| local agent → Kneron 推論 | ~30ms（model 而異）|
| local agent → remote-proxy（tunnel，經 WAN）| ~50-200ms RTT |
| remote-proxy → api-server | ~5ms（同機房）|
| api-server → Browser | ~10-50ms |
| **端到端總延遲（P95 目標）** | **< 500ms** |

（local-tool 端到端 ~150-250ms，多的部分主要是 tunnel 的 WAN RTT）

---

## 驗收條件（Phase 0，Camera only）

- [ ] 能從 Workspace 頁選裝置 + 模型 + Camera 來源
- [ ] 點「開始」後，MJPEG 畫面在 2 秒內出現
- [ ] Bounding box / 分類結果 overlay 正確即時更新
- [ ] 信心度門檻調整立即反映在畫面
- [ ] 推論 FPS 顯示正確（大約 10-30 fps）
- [ ] 端到端延遲 P95 < 500ms（內網測試）
- [ ] Tunnel 延遲顯示正確（header）
- [ ] Tunnel 斷線時立即提示使用者並自動嘗試重連
- [ ] 重連成功後推論自動恢復
- [ ] 停止推論後，畫面停在最後一幀 + 有明確「已停止」狀態
- [ ] 同一使用者開兩個 tab 看同一裝置推論 → 都能看（多 client multipart）
- [ ] 不同使用者之間互相隔離（不會看到別人的推論畫面）

---

## Phase 1 擴充（Image / Video / Batch）

Image / Video / Batch 推論**不需要即時 stream**，使用者上傳檔案到 api-server，透過 tunnel 把檔案送到 local agent，agent 做完回傳結果。

技術挑戰：
- 大檔案傳輸的 tunnel 效率
- 檔案臨時儲存策略（api-server 記憶體 or 暫存磁碟）
- 影片 seek 操作的 tunnel 往返

---

## Phase 0 的 TODO

- **TODO 1**：Image / Video / Batch 推論（Phase 1）
- **TODO 2**：推論結果的 history / 回放（Phase 1，需 DB）
- **TODO 3**：多 client 同時看同一推論的效能優化（Phase 1）
- **TODO 4**：推論結果下載 / export（Phase 1）
- **TODO 5**：Camera 來源的使用者選擇 UI — local agent 可能有多個 camera，要讓使用者選
- **TODO 6**：推論 logging / analytics（Phase 2，用於叢集指標追蹤）

---

## 連結

- 回：[PRD 索引](../PRD.md)
- 相關：[叢集推論](feature-cluster-inference.md)、[工作區](feature-workspace.md)、[非功能性需求 — 效能](../nonfunctional.md)