# PRD — Cluster4NPU UI

> 此 PRD 為從既有程式碼與文件反向整理，反映截至 2026-04-05 的實際狀況。  
> 版本：v0.0.3（developer 分支）

---

## 1. 產品概覽

### 1.1 產品願景

Cluster4NPU UI 的目標是讓任何人（不需要寫程式）都能夠透過直覺的視覺化拖拽介面，設計並執行平行 AI 推論 Pipeline，充分發揮 Kneron NPU Dongle 的硬體效能，並清楚看見平行處理帶來的效能提升。

**一句話描述**：「用拖拽的方式設計 AI Pipeline，不需要一行程式碼，就能讓多個 NPU Dongle 平行加速你的 AI 推論工作。」

### 1.2 目標用戶

**主要用戶：AI 應用整合工程師 / 系統整合商**

- 具備 AI 模型使用知識，但未必熟悉底層 NPU 程式設計
- 需要快速驗證多模型串接 Pipeline 的效能
- 希望在不修改程式碼的情況下調整 Pipeline 設定與硬體分配

**次要用戶：AI 研究員 / 技術評估人員**

- 需要比較不同 Pipeline 配置下的效能表現
- 希望有可視化的數據佐證平行處理的效益（用於提案或報告）

**潛在用戶：Kneron 硬體銷售團隊**

- 需要 Demo 工具，向潛在客戶展示 Kneron NPU 的效能優勢

### 1.3 核心價值主張

1. **無程式碼 Pipeline 設計**：拖拽介面即可建立複雜多模型 AI Pipeline
2. **平行效能可視化**：清楚顯示平行 vs 循序處理的效能差異（2x、3x、4x 加速）
3. **硬體自動管理**：自動偵測並最佳化 NPU Dongle 分配，降低使用門檻
4. **專業監控工具**：即時 FPS、延遲、吞吐量監控，滿足工程師級的分析需求

---

## 2. 市場背景

### 2.1 問題陳述

隨著 Edge AI 應用普及，使用者面臨以下問題：

1. **設定複雜**：在多個 NPU Dongle 上執行平行 AI 推論需要撰寫大量底層程式碼
2. **效能不透明**：難以量化平行處理帶來的效能增益，缺乏說服力
3. **Pipeline 設計困難**：多模型串接（如 偵測 → 追蹤 → 分類）需要手動處理資料流
4. **硬體管理負擔**：多個 NPU Dongle 的分配、監控、除錯缺乏統一工具

### 2.2 目標市場

- **主要市場**：使用 Kneron NPU 硬體（KL520、KL720、KL1080）的系統整合商與企業用戶
- **市場範圍**：Edge AI 推論領域，偏向工業視覺、安全監控、智慧零售等應用場景
- **地理範圍**：目前以繁體中文、英文環境為主（台灣、亞太地區）

---

## 3. 用戶故事

以下用戶故事基於現有功能與規劃功能：

**已實現的用戶故事：**

- As a system integrator, I want to design an AI inference pipeline by dragging and dropping nodes, so that I can build complex multi-model workflows without writing code.
- As a developer, I want to see real-time pipeline validation errors, so that I can fix configuration issues before deployment.
- As a user, I want to save my pipeline configuration to a file (.mflow), so that I can reuse and share it with teammates.
- As an engineer, I want to see live FPS and latency metrics during inference, so that I can monitor pipeline performance in real time.
- As a hardware manager, I want the application to automatically detect available NPU dongles, so that I don't need to manually configure device connections.
- As a user, I want to load video files, camera streams, or images as pipeline inputs, so that I can test my pipeline with different data sources.

**待開發的用戶故事：**

- As a user, I want to compare parallel vs sequential inference performance side by side, so that I can clearly see the speedup benefit of using multiple NPU dongles.
- As an engineer, I want to run automated benchmarks with one click, so that I can measure performance without manual testing.
- As a hardware manager, I want to visually assign NPU dongles to specific pipeline stages, so that I have fine-grained control over device allocation.
- As a user, I want to see live performance graphs (FPS, latency over time), so that I can identify bottlenecks during pipeline execution.
- As an engineer, I want to receive automated optimization suggestions, so that I can improve pipeline performance without deep NPU expertise.
- As a sales engineer, I want to generate a performance report showing speedup metrics, so that I can present the ROI of parallel NPU processing to clients.

---

## 4. 功能需求

### 4.1 已完成功能（現有）

以下功能已在 v0.0.3 中實作完成（資料來源：健檢報告）：

| 功能 | 描述 | 狀態 |
|------|------|------|
| 視覺化 Pipeline 編輯器 | 基於 NodeGraphQt 的拖拽節點介面 | 完成 |
| 5 種節點類型 | Input / Preprocess / Model / Postprocess / Output | 完成 |
| Pipeline 即時驗證 | 即時 Stage 偵測與錯誤標示 | 完成 |
| .mflow 檔案格式 | Pipeline 儲存與載入（JSON 格式） | 完成 |
| 三面板 UI 佈局 | 左：節點面板、中：編輯器、右：設定與監控 | 完成 |
| 多 NPU Dongle 支援 | KL520 / KL720 / KL1080 自動偵測 | 完成 |
| 多 Stage 推論引擎 | 基於多執行緒的平行 Pipeline 執行 | 完成 |
| 效能基礎監控 | FPS、延遲即時顯示（有已知 Bug） | 完成（有瑕疵） |
| 多種輸入來源 | 相機（USB）、影片（MP4/AVI/MOV）、圖片（JPG/PNG/BMP）、RTSP 串流（基本） | 完成 |
| 專案管理 | 登入畫面、最近專案清單、新增 / 載入 Pipeline | 完成 |
| YOLOv5 後處理 | 偵測結果格式化與邊界框處理 | 完成 |
| ByteTrack 追蹤 | 物件追蹤後處理（example_utils） | 完成 |
| 固件上傳支援 | upload_fw 選項與推論流程整合 | 完成（v0.0.2） |
| PyInstaller 打包 | 獨立執行檔打包支援（main.spec） | 完成 |

**已知 Bug（v0.0.2 記錄）：**

- 節點屬性顯示問題
- 輸出視覺化（含後處理結果）異常

### 4.2 待開發功能（依優先級）

#### Phase 1：效能視覺化（第 1-2 週，優先級：P0）

**功能 1：平行 vs 循序效能比較**

- **描述**：提供並行處理與循序處理的效能對照，視覺化顯示加速倍數（如 "3.2x FASTER"）
- **驗收標準**：
  - 可選擇「單裝置 / 多裝置」模式執行同一 Pipeline
  - 顯示兩種模式的 FPS 與延遲數值
  - 以視覺指標（進度條、倍數文字）呈現加速結果
  - 比較結果可在 UI 中保留供查閱
- **優先級**：P0
- **所屬 Phase**：Phase 1

**功能 2：自動化效能 Benchmark 系統（PerformanceBenchmarker）**

- **描述**：一鍵啟動效能測試，自動執行單裝置與多裝置比較並記錄結果
- **驗收標準**：
  - 提供「執行 Benchmark」按鈕
  - 自動完成測試並呈現結果圖表
  - 結果可歷史保存（追蹤效能變化）
  - 支援回歸測試（比較不同版本的效能）
- **優先級**：P0
- **所屬 Phase**：Phase 1

**功能 3：即時效能儀表板（PerformanceDashboard）**

- **描述**：在推論執行期間顯示即時 FPS、延遲、吞吐量折線圖
- **驗收標準**：
  - 以圖表形式顯示 FPS 隨時間變化
  - 以圖表形式顯示延遲分佈
  - 更新頻率 >= 1 Hz
  - 不影響推論效能（CPU 使用率增加 < 5%）
- **優先級**：P0
- **所屬 Phase**：Phase 1

#### Phase 2：裝置管理（第 3-4 週，優先級：P1）

**功能 4：視覺化裝置管理面板（DeviceManagementPanel）**

- **描述**：提供 NPU Dongle 狀態總覽，包含裝置健康度、型號、當前分配狀態
- **驗收標準**：
  - 列出所有已偵測的 NPU Dongle 及其狀態（線上/離線/繁忙）
  - 顯示每個裝置的型號（KL520/KL720/KL1080）
  - 顯示每個裝置當前分配至哪個 Pipeline Stage
- **優先級**：P1
- **所屬 Phase**：Phase 2

**功能 5：手動裝置分配介面**

- **描述**：允許用戶手動將特定 NPU Dongle 指定給特定 Pipeline Stage
- **驗收標準**：
  - 可透過下拉選單或拖拽方式指定裝置
  - 指定後立即反映在 Pipeline 執行設定中
  - 無效的分配（如指定離線裝置）會有錯誤提示
- **優先級**：P1
- **所屬 Phase**：Phase 2

**功能 6：裝置效能分析（DeviceManager 強化）**

- **描述**：追蹤個別 NPU Dongle 的效能指標與歷史記錄
- **驗收標準**：
  - 顯示每個裝置的推論吞吐量（Inference/sec）
  - 顯示裝置使用率百分比
  - 提供自動負載平衡建議
- **優先級**：P1
- **所屬 Phase**：Phase 2

**功能 7：瓶頸偵測與警告系統**

- **描述**：自動識別 Pipeline 中的效能瓶頸並發出警告
- **驗收標準**：
  - 當某 Stage 的佇列持續積壓時觸發警告
  - 在 UI 中以視覺提示標示瓶頸 Stage
  - 提供基本的改善建議（如增加裝置數量）
- **優先級**：P1
- **所屬 Phase**：Phase 2

#### Phase 3：進階功能（第 5-6 週，優先級：P2）

**功能 8：自動化優化引擎（OptimizationEngine）**

- **描述**：分析當前 Pipeline 配置，自動產生效能優化建議
- **驗收標準**：
  - 分析 Stage 效能差異，建議最佳裝置分配方式
  - 識別不必要的前後處理步驟並提出建議
  - 建議以卡片形式呈現，用戶可選擇採納或忽略
- **優先級**：P2
- **所屬 Phase**：Phase 3

**功能 9：Pipeline 設定範本**

- **描述**：提供常見使用情境的預設 Pipeline 範本（如 YOLOv5 偵測、物件追蹤）
- **驗收標準**：
  - 提供至少 3 種常見範本
  - 範本可直接載入並修改
  - 現有 Pipeline 可儲存為自訂範本
- **優先級**：P2
- **所屬 Phase**：Phase 3

**功能 10：效能預測（執行前估算）**

- **描述**：在執行 Pipeline 之前，根據硬體設定預估效能表現
- **驗收標準**：
  - 顯示預估 FPS 與延遲範圍
  - 預估值與實際值誤差 <= 20%（基於歷史資料）
- **優先級**：P2
- **所屬 Phase**：Phase 3

#### Phase 4：專業潤色（第 7-8 週，優先級：P2）

**功能 11：效能報告匯出**

- **描述**：將 Benchmark 結果匯出為可分享的報告格式
- **驗收標準**：
  - 支援匯出為 PDF 或 CSV
  - 報告包含：Pipeline 設定、裝置配置、效能指標、加速倍數
- **優先級**：P2
- **所屬 Phase**：Phase 4

**功能 12：進階分析與趨勢圖**

- **描述**：追蹤效能指標的歷史趨勢，識別長期的效能退化
- **驗收標準**：
  - 顯示多次執行的效能趨勢圖
  - 支援篩選特定時間範圍
- **優先級**：P2
- **所屬 Phase**：Phase 4

---

## 5. 非功能需求

### 5.1 效能需求

- UI 互動回應時間 < 200ms（節點拖拽、屬性切換）
- Pipeline 即時驗證延遲 < 100ms
- 效能儀表板更新不得對推論 FPS 造成超過 5% 的影響
- 應用程式啟動時間（含硬體偵測）< 10 秒

### 5.2 相容性需求

- **作業系統**：Windows 10/11（主要）；Linux（次要）
- **Python 版本**：3.9 以上、3.12 以下
- **硬體**：Kneron NPU Dongle（KL520、KL720、KL1080），USB 3.0 連接
- **PyQt5 版本**：>= 5.15.11

### 5.3 可用性需求

- 首次使用者應能在 5 分鐘內完成基本 Pipeline 設計（拖拽 5 個節點並連接）
- 節點設定面板需防止水平滾動條出現（已在 v0.0.2 修正）
- 所有錯誤訊息應具有可讀性，避免技術術語

### 5.4 可靠性需求

- 重複執行推論不得出現錯誤（已在 v0.0.2 修正）
- Pipeline 儲存（.mflow）需能完整還原節點設定與連接關係
- 應用程式異常關閉後，下次啟動應能顯示最近專案清單

### 5.5 可維護性需求

- 新增節點類型需有對應的單元測試
- 核心模組（InferencePipeline、Multidongle）需有 pytest 格式的測試覆蓋
- 根目錄的 debug/cleanup 腳本應整理並移至 `tools/` 或 `tests/` 目錄

---

## 6. 成功指標

### 6.1 核心使用目標（依產品階段）

**Phase 1 完成標準（效能視覺化）：**
- 用戶可在 3 步以內啟動 Benchmark 並看到加速倍數比較結果
- 儀表板更新流暢（無明顯卡頓）

**Phase 2 完成標準（裝置管理）：**
- 用戶可在不修改程式碼的情況下手動調整裝置分配
- 瓶頸偵測正確識別率 > 80%（在測試情境下）

**Phase 3 完成標準（進階功能）：**
- OptimizationEngine 建議的裝置分配方案，實際效能提升 > 10%
- 提供至少 3 種可直接使用的 Pipeline 範本

**整體產品品質標準：**
- 已知 Bug（節點屬性顯示、輸出視覺化）全數修復
- 完整的 pytest 測試覆蓋核心模組

### 6.2 使用者體驗指標

- Pipeline 設計完成時間（目標：首次使用 < 5 分鐘，熟悉後 < 2 分鐘）
- Benchmark 一鍵啟動到結果呈現（目標：< 30 秒完成）

---

## 7. 超出範圍

以下事項明確不在 v0.0.3 至 Phase 4 的開發範圍內：

1. **雲端功能**：無雲端儲存、遠端執行、或 SaaS 服務
2. **非 Kneron 硬體支援**：不支援其他廠商的 NPU（如 Hailo、Coral）
3. **模型訓練**：本工具僅處理推論（Inference），不包含模型訓練功能
4. **行動端 App**：僅為桌面應用（Windows / Linux）
5. **多人協作**：不支援多人同時編輯同一 Pipeline
6. **付費 / 授權系統**：目前無商業授權機制
7. **自動語言切換 / 完整多語系**：目前以英文 UI 為主，無正式多語系支援
8. **RTSP 串流完整支援**：RTSP 目前僅為基本支援，完整串流管理不在當前範圍

---

## 附錄

### A. 版本歷史摘要

| 版本 | 日期 | 主要變更 |
|------|------|---------|
| v0.0.1 | — | 初始版本（確切日期不明） |
| v0.0.2 | 2025-07-31 | 自動資料清理、固件上傳支援、修復多次推論錯誤、FPS 修正 |
| v0.0.3 | 進行中 | YOLOv5 後處理改善、測試腳本整理（developer 分支） |

### B. 相關文件

- 健檢報告：`C:\Users\sungs\Documents\abin\temp\cluster4npu\.autoflow\00-onboarding\health-check.md`
- 開發路線圖：`C:\Users\sungs\Documents\abin\temp\cluster4npu\DEVELOPMENT_ROADMAP.md`
- 專案摘要：`C:\Users\sungs\Documents\abin\temp\cluster4npu\PROJECT_SUMMARY.md`
- README：`C:\Users\sungs\Documents\abin\temp\cluster4npu\README.md`

### C. 技術限制說明

- 本工具強依賴 Kneron KP SDK，SDK 版本更新可能影響硬體相容性
- NodeGraphQt 的視覺編輯器版本（>= 0.6.40）限制了某些 UI 客製化能力
- Python 版本限制（3.9–3.11）源自 PyQt5 與 Kneron SDK 的相容性需求