forked from masonhuang/cluster4npu
abin
5aa374625f
- Add .autoflow/ with health check, PRD, Design Doc, TDD, progress tracking - Add tests/conftest.py with PyQt5/KP SDK stubs for unit testing - Add pytest config to pyproject.toml (pythonpath, import-mode, test naming) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
345 lines
14 KiB
Markdown
345 lines
14 KiB
Markdown
# 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 的相容性需求
|