abin 5aa374625f docs: add autoflow project docs and test infrastructure

- 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>

2026-04-06 19:31:52 +08:00

14 KiB

Raw Blame History

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 核心價值主張

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

2. 市場背景

2.1 問題陳述

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

設定複雜：在多個 NPU Dongle 上執行平行 AI 推論需要撰寫大量底層程式碼
效能不透明：難以量化平行處理帶來的效能增益，缺乏說服力
Pipeline 設計困難：多模型串接（如偵測 → 追蹤 → 分類）需要手動處理資料流
硬體管理負擔：多個 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 的開發範圍內：

雲端功能：無雲端儲存、遠端執行、或 SaaS 服務
非 Kneron 硬體支援：不支援其他廠商的 NPU（如 Hailo、Coral）
模型訓練：本工具僅處理推論（Inference），不包含模型訓練功能
行動端 App：僅為桌面應用（Windows / Linux）
多人協作：不支援多人同時編輯同一 Pipeline
付費 / 授權系統：目前無商業授權機制
自動語言切換 / 完整多語系：目前以英文 UI 為主，無正式多語系支援
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 的相容性需求

14 KiB Raw Blame History Unescape Escape