jim800121chen
fb7da5d180
依 autoflow-agent workspace v2 設計把 PRD / 設計 / 架構 / 交付類 共享文件從個人層 .autoflow/（ignored）搬到 docs/autoflow/（進 git）， 讓團隊可共享產品與架構文件，個人層只留 progress / review / testing 等 per-branch 筆記。 - 02-prd/ 21 個檔（PRD、features、market-analysis 等） - 03-design/ 18 個檔（design-spec、wireframes、flows 等） - 04-architecture/ 31 個檔（TDD、design-doc、ADR×14、API 規格等） - 07-delivery/ 3 個檔（project-summary、phase-0.6-handover、stage-deployment-setup） 合計 73 檔。原檔已從 .autoflow/ 移除（migration 工具執行 git mv， 但因 .autoflow/ 在 .gitignore 中、git 將此操作視為新增、無 rename history）。
134 lines
5.8 KiB
Markdown
134 lines
5.8 KiB
Markdown
# 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)
|