forked from masonhuang/cluster4npu
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>
This commit is contained in:
parent
ccd7cdd6b9
commit
5aa374625f
141
.autoflow/00-onboarding/health-check.md
Normal file
141
.autoflow/00-onboarding/health-check.md
Normal file
@ -0,0 +1,141 @@
|
|||||||
|
# 專案健檢報告
|
||||||
|
|
||||||
|
## 基本資訊
|
||||||
|
|
||||||
|
- **專案名稱**：Cluster4NPU UI — Visual Pipeline Designer
|
||||||
|
- **版本**：v0.0.3
|
||||||
|
- **程式碼來源**：本地路徑 `C:\Users\sungs\Documents\abin\temp\cluster4npu`
|
||||||
|
- **Git 分支**：developer（主分支為 main）
|
||||||
|
- **最後 commit**：feat: Reorganize test scripts and improve YOLOv5 postprocessing
|
||||||
|
- **健檢日期**：2026-04-05
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 技術堆疊
|
||||||
|
|
||||||
|
| 層級 | 技術 | 版本 |
|
||||||
|
|------|------|------|
|
||||||
|
| 語言 | Python | >=3.9, <3.12 |
|
||||||
|
| GUI 框架 | PyQt5 | >=5.15.11 |
|
||||||
|
| 視覺節點編輯器 | NodeGraphQt | >=0.6.40 |
|
||||||
|
| 影像處理 | OpenCV | (runtime dependency) |
|
||||||
|
| 數值運算 | NumPy | (runtime dependency) |
|
||||||
|
| 硬體 SDK | Kneron KP SDK | (runtime, NPU dongle 驅動) |
|
||||||
|
| 套件管理 | uv | — |
|
||||||
|
| 打包 | PyInstaller (main.spec) | — |
|
||||||
|
|
||||||
|
**支援硬體：** Kneron NPU dongles — KL520、KL720、KL1080
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 專案結構概覽
|
||||||
|
|
||||||
|
```
|
||||||
|
cluster4npu/
|
||||||
|
├── main.py # 應用程式入口點
|
||||||
|
├── config/ # 設定與主題 (settings.py, theme.py)
|
||||||
|
├── core/
|
||||||
|
│ ├── pipeline.py # Pipeline 分析、stage 偵測、驗證
|
||||||
|
│ ├── functions/
|
||||||
|
│ │ ├── InferencePipeline.py # 多 stage pipeline 執行引擎（多執行緒）
|
||||||
|
│ │ ├── Multidongle.py # NPU dongle 管理與自動偵測
|
||||||
|
│ │ ├── camera_source.py # 相機輸入來源
|
||||||
|
│ │ ├── video_source.py # 影片輸入來源
|
||||||
|
│ │ ├── result_handler.py # 推論結果處理
|
||||||
|
│ │ ├── workflow_orchestrator.py
|
||||||
|
│ │ ├── mflow_converter.py # .mflow 格式轉換
|
||||||
|
│ │ └── yolo_v5_postprocess_reference.py
|
||||||
|
│ └── nodes/ # 節點定義（5 種類型）
|
||||||
|
│ ├── base_node.py
|
||||||
|
│ ├── input_node.py
|
||||||
|
│ ├── model_node.py
|
||||||
|
│ ├── preprocess_node.py
|
||||||
|
│ ├── postprocess_node.py
|
||||||
|
│ ├── output_node.py
|
||||||
|
│ ├── simple_input_node.py
|
||||||
|
│ └── exact_nodes.py
|
||||||
|
├── ui/
|
||||||
|
│ ├── windows/ # 主視窗（login.py, dashboard.py, pipeline_editor.py）
|
||||||
|
│ ├── components/ # 可重用元件（node_palette, properties_widget, common_widgets）
|
||||||
|
│ └── dialogs/ # 對話框（deployment, performance, stage_config 等）
|
||||||
|
├── utils/ # 工具函式（file_utils, folder_dialog, ui_utils）
|
||||||
|
├── example_utils/ # 範例後處理工具（ByteTrack 等）
|
||||||
|
├── tests/ # 測試腳本（42 個，多為腳本式，非正式 test suite）
|
||||||
|
├── resources/ # 資源檔案
|
||||||
|
└── output/ # 推論輸出結果
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 文件完整度
|
||||||
|
|
||||||
|
| 文件類型 | 狀態 | 位置 | 備註 |
|
||||||
|
|---------|------|------|------|
|
||||||
|
| README | ✅ 有 | `README.md` | 詳細，含安裝、架構說明 |
|
||||||
|
| 產品需求 / PRD | ⚠️ 部分 | `PROJECT_SUMMARY.md` | 有願景與待開發功能，但非正式 PRD 格式 |
|
||||||
|
| 開發路線圖 | ✅ 有 | `DEVELOPMENT_ROADMAP.md` | 四個 Phase，有具體目標 |
|
||||||
|
| 架構設計文件 | ❌ 無 | — | README 內有簡介，但無正式 Design Doc |
|
||||||
|
| API 文件 | ❌ 無 | — | 無正式 API 文件 |
|
||||||
|
| 設計稿 | ❌ 無 | 只有 `Flowchart.jpg` | 無 Wireframe 或 UI 規格 |
|
||||||
|
| 技術設計文件 (TDD) | ❌ 無 | — | 無 |
|
||||||
|
| 測試計畫 | ❌ 無 | — | 有測試腳本但無正式測試計畫 |
|
||||||
|
| 部署文件 | ⚠️ 部分 | README 內 | 有基本步驟，無完整部署文件 |
|
||||||
|
| Release Notes | ✅ 有 | `release_note.md` | 目前到 v0.0.2 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 程式碼健康度
|
||||||
|
|
||||||
|
- **測試覆蓋率**：⚠️ 部分測試 — `tests/` 下有 42 個腳本，但多為情境測試腳本（非 pytest 單元測試），缺乏系統性覆蓋
|
||||||
|
- **程式碼品質**：中等 — 有明確的模組分離；部分根目錄腳本（debug_*.py, force_cleanup.py 等）為開發過程遺留，結構略混亂
|
||||||
|
- **安全性**：低風險（本地桌面應用，無網路 API）
|
||||||
|
- **技術債**：
|
||||||
|
- 根目錄有多個 debug/cleanup 腳本未整理
|
||||||
|
- tests/ 下腳本命名與分類混亂（部分非 test_ 開頭）
|
||||||
|
- 缺乏正式的 pytest 測試架構
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 現有功能清單
|
||||||
|
|
||||||
|
| 功能 | 描述 | 狀態 |
|
||||||
|
|------|------|------|
|
||||||
|
| 視覺化 Pipeline 編輯器 | 拖拽節點建立 Pipeline（NodeGraphQt） | ✅ 完成 |
|
||||||
|
| 5 種節點類型 | Input / Preprocess / Model / Postprocess / Output | ✅ 完成 |
|
||||||
|
| Pipeline 驗證 | 即時 stage 偵測與錯誤標示 | ✅ 完成 |
|
||||||
|
| .mflow 檔案格式 | Pipeline 儲存與載入（JSON） | ✅ 完成 |
|
||||||
|
| 多 NPU Dongle 支援 | KL520 / KL720 / KL1080 自動偵測 | ✅ 完成 |
|
||||||
|
| 多 stage 推論引擎 | 多執行緒 Pipeline 執行 | ✅ 完成 |
|
||||||
|
| 效能監控 | FPS、延遲即時顯示 | ✅ 完成（有 known bugs） |
|
||||||
|
| 相機 / 影片 / 圖片輸入 | 多種輸入來源 | ✅ 完成 |
|
||||||
|
| 專案管理 | 登入畫面、最近專案、新增/載入 Pipeline | ✅ 完成 |
|
||||||
|
| YOLOv5 後處理 | 偵測結果格式化 | ✅ 完成（最近改善） |
|
||||||
|
| ByteTrack 追蹤 | 物件追蹤後處理 | ✅ 完成（example_utils） |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 缺失項目摘要（待開發）
|
||||||
|
|
||||||
|
根據 `PROJECT_SUMMARY.md` 與 `DEVELOPMENT_ROADMAP.md`：
|
||||||
|
|
||||||
|
1. **效能視覺化**：並行 vs 循序執行比較、Speedup 指標顯示（Phase 1）
|
||||||
|
2. **Benchmarking 系統**：自動化效能測試、圖表比較（Phase 1）
|
||||||
|
3. **裝置管理介面**：視覺化裝置分配、負載平衡（Phase 2）
|
||||||
|
4. **即時監控 Dashboard**：FPS/延遲圖表、資源使用率（Phase 2）
|
||||||
|
5. **優化引擎**：自動化建議、效能預測（Phase 3）
|
||||||
|
|
||||||
|
已知 Bug：
|
||||||
|
- 節點屬性顯示問題
|
||||||
|
- 輸出視覺化（含後處理）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## CI/CD 與基礎設施
|
||||||
|
|
||||||
|
| 項目 | 狀態 |
|
||||||
|
|------|------|
|
||||||
|
| Docker | ❌ 無 |
|
||||||
|
| CI/CD | ❌ 無 |
|
||||||
|
| 部署設定 | ❌ 無（本地桌面應用，有 PyInstaller spec） |
|
||||||
|
| 環境變數管理 | ❌ 無 |
|
||||||
|
| 版本控制 | ✅ Git（GitHub 遠端） |
|
||||||
344
.autoflow/02-prd/PRD.md
Normal file
344
.autoflow/02-prd/PRD.md
Normal file
@ -0,0 +1,344 @@
|
|||||||
|
# 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 的相容性需求
|
||||||
1149
.autoflow/04-architecture/TDD.md
Normal file
1149
.autoflow/04-architecture/TDD.md
Normal file
File diff suppressed because it is too large
Load Diff
581
.autoflow/04-architecture/design-doc.md
Normal file
581
.autoflow/04-architecture/design-doc.md
Normal file
@ -0,0 +1,581 @@
|
|||||||
|
# Design Doc — Cluster4NPU UI
|
||||||
|
|
||||||
|
## 作者：Architect Agent
|
||||||
|
## 狀態：Draft
|
||||||
|
## 最後更新：2026-04-05
|
||||||
|
## 版本對應：v0.0.3（developer 分支）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 背景與目標
|
||||||
|
|
||||||
|
### 1.1 背景
|
||||||
|
|
||||||
|
Cluster4NPU UI 是一個桌面應用程式，讓使用者不需要撰寫程式碼，就能透過視覺化拖拽介面設計並執行 AI 推論 Pipeline，並將工作負載分配到多個 Kneron NPU Dongle（KL520、KL720、KL1080）上平行執行。
|
||||||
|
|
||||||
|
現有系統已完成核心 Pipeline 設計器與推論引擎的基礎建設，但缺乏：
|
||||||
|
- 效能視覺化（無法直觀看到平行處理的加速效果）
|
||||||
|
- 進階裝置管理介面
|
||||||
|
- 自動化 Benchmark 系統
|
||||||
|
- 優化建議引擎
|
||||||
|
|
||||||
|
### 1.2 目標
|
||||||
|
|
||||||
|
1. **核心目標**：使任何 AI 應用工程師都能在 5 分鐘內完成 Pipeline 設計並看到推論結果
|
||||||
|
2. **差異化目標**：清楚視覺化呈現多 NPU Dongle 平行處理帶來的效能加速（2x、3x、4x）
|
||||||
|
3. **工程目標**：提供可擴展的架構，支援 Phase 1-4 的功能迭代
|
||||||
|
|
||||||
|
### 1.3 範圍
|
||||||
|
|
||||||
|
**本文件涵蓋：**
|
||||||
|
- 現有（v0.0.3）核心架構的完整說明
|
||||||
|
- Phase 1-3 待開發功能的架構設計方向
|
||||||
|
|
||||||
|
**不涵蓋：**
|
||||||
|
- 雲端功能、非 Kneron 硬體、模型訓練、行動端
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 系統架構總覽
|
||||||
|
|
||||||
|
### 2.1 整體分層架構
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ 使用者介面層（UI Layer） │
|
||||||
|
│ │
|
||||||
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||||
|
│ │ Login Window │ │ Dashboard │ │ Dialogs │ │
|
||||||
|
│ │ (login.py) │ │(dashboard.py)│ │ (deployment, │ │
|
||||||
|
│ └──────────────┘ └──────────────┘ │ performance)│ │
|
||||||
|
│ │ └──────────────┘ │
|
||||||
|
│ ┌──────────────────────────────────────────────────┐ │
|
||||||
|
│ │ 三面板佈局（Three-Panel Layout） │ │
|
||||||
|
│ │ ┌──────────┐ ┌──────────────┐ ┌──────────┐ │ │
|
||||||
|
│ │ │ 左面板 │ │ 中面板 │ │ 右面板 │ │ │
|
||||||
|
│ │ │ 節點面板 │ │ Pipeline 編輯│ │ 設定/監控│ │ │
|
||||||
|
│ │ │(palette) │ │ (NodeGraphQt)│ │(properties│ │ │
|
||||||
|
│ │ └──────────┘ └──────────────┘ └──────────┘ │ │
|
||||||
|
│ └──────────────────────────────────────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ 應用程式核心層（Core Layer） │
|
||||||
|
│ │
|
||||||
|
│ ┌────────────────────┐ ┌──────────────────────────┐ │
|
||||||
|
│ │ Pipeline 分析引擎 │ │ 節點系統（Nodes） │ │
|
||||||
|
│ │ (pipeline.py) │ │ (base/input/model/ │ │
|
||||||
|
│ │ │ │ preprocess/postprocess/ │ │
|
||||||
|
│ │ - Stage 偵測 │ │ output nodes) │ │
|
||||||
|
│ │ - 結構驗證 │ │ │ │
|
||||||
|
│ │ - 路徑分析 │ │ - 業務屬性管理 │ │
|
||||||
|
│ │ - 設定匯出 │ │ - 設定序列化 │ │
|
||||||
|
│ └────────────────────┘ └──────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ ┌──────────────────────────────────────────────────┐ │
|
||||||
|
│ │ 推論執行層（Inference Execution Layer） │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ ┌──────────────────────┐ ┌─────────────────┐ │ │
|
||||||
|
│ │ │ InferencePipeline │ │ MultiDongle │ │ │
|
||||||
|
│ │ │ │ │ │ │ │
|
||||||
|
│ │ │ - 多 Stage 協調 │ │ - NPU 裝置管理 │ │ │
|
||||||
|
│ │ │ - 執行緒管理 │ │ - 非同步推論 │ │ │
|
||||||
|
│ │ │ - 佇列管理 │ │ - 前後處理 │ │ │
|
||||||
|
│ │ │ - FPS 計算 │ │ - 多裝置排程 │ │ │
|
||||||
|
│ │ └──────────────────────┘ └─────────────────┘ │ │
|
||||||
|
│ └──────────────────────────────────────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ 硬體抽象層（Hardware Abstraction Layer） │
|
||||||
|
│ │
|
||||||
|
│ ┌──────────────────────────────────────────────────┐ │
|
||||||
|
│ │ Kneron KP SDK │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ KL520 Dongle │ KL720 Dongle │ KL1080 Dongle │ │
|
||||||
|
│ └──────────────────────────────────────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2 模組間依賴關係
|
||||||
|
|
||||||
|
```
|
||||||
|
main.py
|
||||||
|
└── ui/windows/login.py (DashboardLogin)
|
||||||
|
└── ui/windows/dashboard.py (DashboardWindow)
|
||||||
|
├── ui/windows/pipeline_editor.py
|
||||||
|
│ └── core/pipeline.py (PipelineAnalyzer)
|
||||||
|
│ └── core/nodes/*.py
|
||||||
|
├── ui/components/properties_widget.py
|
||||||
|
│ └── core/nodes/*.py
|
||||||
|
└── core/functions/InferencePipeline.py
|
||||||
|
└── core/functions/Multidongle.py
|
||||||
|
└── kp (Kneron KP SDK)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 核心元件說明
|
||||||
|
|
||||||
|
### 3.1 Pipeline 分析引擎（`core/pipeline.py`）
|
||||||
|
|
||||||
|
**職責：** 分析 NodeGraphQt 視覺圖形，識別 Pipeline 的 Stage 結構、驗證合法性、產生執行設定。
|
||||||
|
|
||||||
|
**關鍵類別：**
|
||||||
|
|
||||||
|
| 類別/函式 | 職責 |
|
||||||
|
|---------|------|
|
||||||
|
| `PipelineStage` | 代表一個推論 Stage，包含 ModelNode 與可選的 Pre/Postprocess Node |
|
||||||
|
| `analyze_pipeline_stages(node_graph)` | 從視覺圖形中識別所有 Stage，依距離排序 |
|
||||||
|
| `get_stage_count(node_graph)` | 計算 Pipeline 中的 Stage 數量（用於 UI 顯示） |
|
||||||
|
| `validate_pipeline_structure(node_graph)` | 驗證 Pipeline 是否包含必要節點（Input、Model、Output） |
|
||||||
|
| `get_pipeline_summary(node_graph)` | 回傳 Pipeline 統計摘要（節點數、Stage 數、驗證結果） |
|
||||||
|
|
||||||
|
**設計決策：**
|
||||||
|
- 採用多重節點識別策略（`__identifier__`、`type_`、`NODE_NAME`、class 名稱、特定方法的存在）以提高相容性
|
||||||
|
- Stage 排序依據：計算各 ModelNode 到輸入節點的最短路徑距離（BFS）
|
||||||
|
- 所有圖遍歷方法都包含 defensive exception handling，避免 NodeGraphQt 物件狀態不一致時崩潰
|
||||||
|
|
||||||
|
**介面：**
|
||||||
|
```python
|
||||||
|
# 主要公開介面
|
||||||
|
get_stage_count(node_graph: NodeGraph) -> int
|
||||||
|
analyze_pipeline_stages(node_graph: NodeGraph) -> List[PipelineStage]
|
||||||
|
validate_pipeline_structure(node_graph: NodeGraph) -> Tuple[bool, str]
|
||||||
|
get_pipeline_summary(node_graph: NodeGraph) -> Dict[str, Any]
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 節點系統（`core/nodes/`）
|
||||||
|
|
||||||
|
**職責：** 定義 Pipeline 中的各類節點，提供業務屬性管理與設定序列化能力。
|
||||||
|
|
||||||
|
**繼承架構：**
|
||||||
|
```
|
||||||
|
NodeGraphQt.BaseNode
|
||||||
|
└── BaseNodeWithProperties（base_node.py）
|
||||||
|
├── InputNode（input_node.py）
|
||||||
|
├── ModelNode（model_node.py）
|
||||||
|
├── PreprocessNode（preprocess_node.py）
|
||||||
|
├── PostprocessNode（postprocess_node.py）
|
||||||
|
└── OutputNode（output_node.py）
|
||||||
|
```
|
||||||
|
|
||||||
|
**`BaseNodeWithProperties` 核心能力：**
|
||||||
|
- `create_business_property(name, default, options)` — 建立帶驗證選項的業務屬性
|
||||||
|
- `validate_property(name, value)` — 數值範圍、選項列表驗證
|
||||||
|
- `get_node_config()` / `load_node_config(config)` — JSON 序列化/還原
|
||||||
|
- `create_node_property_widget(node, prop_name, value, options)` — 根據屬性型別自動生成 Qt Widget
|
||||||
|
|
||||||
|
**ModelNode 屬性（主要節點）：**
|
||||||
|
|
||||||
|
| 屬性 | 型別 | 說明 |
|
||||||
|
|------|------|------|
|
||||||
|
| `model_path` | file_path | .nef 模型檔案路徑 |
|
||||||
|
| `dongle_series` | choice | KL520 / KL720 / KL1080 |
|
||||||
|
| `num_dongles` | int (1-16) | 分配給此 Stage 的 Dongle 數量 |
|
||||||
|
| `port_id` | string | USB Port ID（或 auto） |
|
||||||
|
| `batch_size` | int (1-32) | 推論批次大小 |
|
||||||
|
| `max_queue_size` | int (1-100) | 輸入佇列最大長度 |
|
||||||
|
|
||||||
|
### 3.3 推論執行引擎（`core/functions/InferencePipeline.py`）
|
||||||
|
|
||||||
|
**職責：** 管理多 Stage Pipeline 的生命週期、協調執行緒間資料流、計算效能指標。
|
||||||
|
|
||||||
|
**主要資料結構：**
|
||||||
|
|
||||||
|
```python
|
||||||
|
@dataclass
|
||||||
|
class StageConfig:
|
||||||
|
stage_id: str
|
||||||
|
port_ids: List[int]
|
||||||
|
scpu_fw_path: str # SCPU 韌體路徑
|
||||||
|
ncpu_fw_path: str # NCPU 韌體路徑
|
||||||
|
model_path: str # .nef 模型路徑
|
||||||
|
upload_fw: bool # 是否上傳韌體
|
||||||
|
max_queue_size: int # 佇列大小（預設 50）
|
||||||
|
multi_series_config: Optional[Dict] # 多系列模式設定
|
||||||
|
input_preprocessor: Optional[PreProcessor]
|
||||||
|
output_postprocessor: Optional[PostProcessor]
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class PipelineData:
|
||||||
|
data: Any # 當前資料（影像、中間結果）
|
||||||
|
metadata: Dict[str, Any] # 時間戳、處理資訊
|
||||||
|
stage_results: Dict[str, Any] # 各 Stage 推論結果
|
||||||
|
pipeline_id: str # 唯一識別碼
|
||||||
|
timestamp: float
|
||||||
|
```
|
||||||
|
|
||||||
|
**執行緒模型：**
|
||||||
|
|
||||||
|
```
|
||||||
|
主執行緒（UI）
|
||||||
|
│
|
||||||
|
├── InferencePipeline.coordinator_thread（協調器）
|
||||||
|
│ │ 從 pipeline_input_queue 取資料
|
||||||
|
│ │ 依序分配給各 Stage
|
||||||
|
│ └── 收集結果放入 pipeline_output_queue
|
||||||
|
│
|
||||||
|
├── PipelineStage[0].worker_thread（Stage 0 工作執行緒）
|
||||||
|
│ └── 從 input_queue 取資料 → MultiDongle 推論 → 放入 output_queue
|
||||||
|
│
|
||||||
|
├── PipelineStage[1].worker_thread（Stage 1 工作執行緒）
|
||||||
|
│ └── ...
|
||||||
|
│
|
||||||
|
└── stats_thread（效能統計回報）
|
||||||
|
```
|
||||||
|
|
||||||
|
**FPS 計算方式：** 採用累積式計算（`completed_counter / elapsed_time`），與 Kneron 範例程式的計算邏輯一致，只計算真實推論結果（排除 async/processing 狀態）。
|
||||||
|
|
||||||
|
**佇列管理策略：**
|
||||||
|
- 輸入佇列滿時：捨棄最舊的幀（為了即時串流的實時性）
|
||||||
|
- 輸出佇列上限 50 筆：超出時捨棄最舊的結果，避免記憶體無限增長
|
||||||
|
|
||||||
|
### 3.4 硬體抽象層（`core/functions/Multidongle.py`）
|
||||||
|
|
||||||
|
**職責：** 封裝 Kneron KP SDK，提供統一的 NPU Dongle 管理介面，支援單裝置與多裝置（multi-series）模式。
|
||||||
|
|
||||||
|
**核心抽象類別：**
|
||||||
|
|
||||||
|
```python
|
||||||
|
class DataProcessor(ABC):
|
||||||
|
def process(self, data: Any, *args, **kwargs) -> Any: ...
|
||||||
|
|
||||||
|
class PreProcessor(DataProcessor):
|
||||||
|
# 影像縮放（resize）+ 格式轉換（BGR → BGR565/RGB8888）
|
||||||
|
|
||||||
|
class PostProcessor(DataProcessor):
|
||||||
|
# 支援 4 種後處理類型：
|
||||||
|
# - FIRE_DETECTION（火焰分類）
|
||||||
|
# - CLASSIFICATION（一般分類）
|
||||||
|
# - YOLO_V3（物件偵測）
|
||||||
|
# - YOLO_V5（物件偵測，使用參考實作）
|
||||||
|
# - RAW_OUTPUT（原始輸出）
|
||||||
|
```
|
||||||
|
|
||||||
|
**裝置規格（DongleSeriesSpec）：**
|
||||||
|
|
||||||
|
| 系列 | Product ID | GOPS 算力 |
|
||||||
|
|------|-----------|---------|
|
||||||
|
| KL520 | 0x100 | 2 GOPS |
|
||||||
|
| KL720 | 0x720 | 28 GOPS |
|
||||||
|
| KL630 | 0x630 | 400 GOPS |
|
||||||
|
| KL730 | 0x730 | 1600 GOPS |
|
||||||
|
|
||||||
|
**推論結果資料結構：**
|
||||||
|
|
||||||
|
```python
|
||||||
|
@dataclass
|
||||||
|
class ClassificationResult:
|
||||||
|
probability: float
|
||||||
|
class_name: str
|
||||||
|
class_num: int
|
||||||
|
confidence_threshold: float
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class ObjectDetectionResult:
|
||||||
|
class_count: int
|
||||||
|
box_count: int
|
||||||
|
box_list: List[BoundingBox]
|
||||||
|
# Letterbox 映射資訊（用於還原到原始影像座標）
|
||||||
|
model_input_width, model_input_height: int
|
||||||
|
pad_left, pad_top, pad_right, pad_bottom: int
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.5 使用者介面層（`ui/`）
|
||||||
|
|
||||||
|
**職責：** 呈現視覺化 Pipeline 設計環境，管理節點屬性設定、效能監控顯示。
|
||||||
|
|
||||||
|
**主要視窗：**
|
||||||
|
- `DashboardLogin`（`ui/windows/login.py`）：啟動畫面、最近專案清單、新建/載入 Pipeline
|
||||||
|
- `DashboardWindow`（`ui/windows/dashboard.py`）：主工作介面，三面板佈局
|
||||||
|
- `PipelineEditor`（`ui/windows/pipeline_editor.py`）：內嵌 NodeGraphQt 視覺編輯器
|
||||||
|
|
||||||
|
**三面板配置：**
|
||||||
|
|
||||||
|
| 面板 | 寬度比例 | 主要內容 |
|
||||||
|
|------|---------|---------|
|
||||||
|
| 左面板 | 25% | 節點面板（拖拽來源）、Pipeline 操作按鈕 |
|
||||||
|
| 中面板 | 50% | NodeGraphQt 視覺編輯器、全域狀態列 |
|
||||||
|
| 右面板 | 25% | Properties Tab（節點設定）、Performance Tab（效能監控）、Dongles Tab（裝置管理） |
|
||||||
|
|
||||||
|
### 3.6 應用程式入口（`main.py`）
|
||||||
|
|
||||||
|
**職責：** 應用程式初始化、單一實例保護、Qt 環境設定。
|
||||||
|
|
||||||
|
**單一實例機制：** `SingleInstance` 類別採用雙重保護：
|
||||||
|
1. Qt `QSharedMemory`（跨平台）
|
||||||
|
2. 檔案鎖（Unix: fcntl / Windows: O_CREAT|O_EXCL）
|
||||||
|
3. 自動清理 5 分鐘以上的過期鎖定檔案
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 資料流
|
||||||
|
|
||||||
|
### 4.1 設計階段資料流（Design Time）
|
||||||
|
|
||||||
|
```
|
||||||
|
使用者拖拽節點
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
NodeGraphQt 視覺圖形
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
core/pipeline.py
|
||||||
|
analyze_pipeline_stages()
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
List[PipelineStage]（邏輯 Stage 列表）
|
||||||
|
│
|
||||||
|
├──→ UI 顯示 Stage 數量（狀態列）
|
||||||
|
└──→ 驗證錯誤提示（Validation Errors）
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 執行階段資料流（Runtime）
|
||||||
|
|
||||||
|
```
|
||||||
|
輸入來源（相機 / 影片 / 圖片）
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
camera_source.py / video_source.py
|
||||||
|
│ numpy.ndarray（BGR 影像幀）
|
||||||
|
▼
|
||||||
|
InferencePipeline.put_data()
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
pipeline_input_queue（Queue, maxsize=100）
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
coordinator_thread（協調器執行緒）
|
||||||
|
建立 PipelineData 包裝器
|
||||||
|
│
|
||||||
|
▼（依序通過每個 Stage）
|
||||||
|
PipelineStage[0].input_queue
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
worker_thread[0]
|
||||||
|
1. input_preprocessor（可選的 Stage 間前處理）
|
||||||
|
2. MultiDongle.preprocess_frame()（BGR → BGR565 格式轉換）
|
||||||
|
3. MultiDongle.put_input()（送入推論佇列）
|
||||||
|
4. MultiDongle.get_latest_inference_result()（非阻塞取結果）
|
||||||
|
5. 更新 PipelineData.stage_results
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
PipelineStage[0].output_queue
|
||||||
|
│
|
||||||
|
▼（下一個 Stage...）
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
pipeline_output_queue（Queue, maxsize=50）
|
||||||
|
│
|
||||||
|
├──→ result_callback（UI 更新）
|
||||||
|
└──→ stats_callback（效能統計）
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.3 .mflow 檔案格式
|
||||||
|
|
||||||
|
Pipeline 儲存為 JSON 格式：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"nodes": [
|
||||||
|
{
|
||||||
|
"type": "ModelNode",
|
||||||
|
"name": "Stage 1 Model",
|
||||||
|
"properties": {
|
||||||
|
"model_path": "/path/to/model.nef",
|
||||||
|
"dongle_series": "720",
|
||||||
|
"num_dongles": 2
|
||||||
|
},
|
||||||
|
"position": [100, 200]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"connections": [
|
||||||
|
{"from_node": "input_0", "from_port": "output", "to_node": "model_0", "to_port": "input"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 技術決策紀錄（ADR）
|
||||||
|
|
||||||
|
### ADR-001：選用 PyQt5 作為 GUI 框架
|
||||||
|
|
||||||
|
**決策**：使用 PyQt5（>= 5.15.11）
|
||||||
|
|
||||||
|
**原因：**
|
||||||
|
- NodeGraphQt 依賴 PyQt5，無法使用其他框架
|
||||||
|
- PyQt5 在 Windows 上有成熟的支援
|
||||||
|
- 提供豐富的 Widget 與 Signal/Slot 機制
|
||||||
|
|
||||||
|
**取捨：**
|
||||||
|
- 限制 Python 版本在 3.9–3.11（PyQt5 + Kneron SDK 相容性）
|
||||||
|
- PyQt6 不向下相容，短期不考慮遷移
|
||||||
|
|
||||||
|
### ADR-002：選用 NodeGraphQt 作為視覺節點編輯器
|
||||||
|
|
||||||
|
**決策**：使用 NodeGraphQt（>= 0.6.40）
|
||||||
|
|
||||||
|
**原因：**
|
||||||
|
- 提供完整的拖拽節點圖形編輯能力，開發成本低
|
||||||
|
- 支援節點連接、屬性面板、視覺化輸出
|
||||||
|
|
||||||
|
**取捨：**
|
||||||
|
- NodeGraphQt 的 UI 客製化能力有限（如節點顏色、形狀）
|
||||||
|
- 節點識別採用多重 fallback 機制（透過 `__identifier__`、`NODE_NAME` 等），因 NodeGraphQt 版本差異可能造成 API 不一致
|
||||||
|
|
||||||
|
### ADR-003：多執行緒 Pipeline 架構
|
||||||
|
|
||||||
|
**決策**：每個 Stage 一個 Worker Thread + 一個 Coordinator Thread
|
||||||
|
|
||||||
|
**原因：**
|
||||||
|
- 推論為 CPU/硬體密集操作，多執行緒可避免 UI 阻塞
|
||||||
|
- 各 Stage 獨立執行緒允許流水線（pipelining）並行，提升吞吐量
|
||||||
|
|
||||||
|
**取捨：**
|
||||||
|
- 協調器採用循序（sequential）方式傳遞資料，並非真正平行（真正平行需要 DAG 調度器）
|
||||||
|
- 使用 `queue.Queue` 進行執行緒間通訊，有固定的記憶體上限
|
||||||
|
|
||||||
|
### ADR-004：非阻塞式推論結果取得
|
||||||
|
|
||||||
|
**決策**：`MultiDongle.get_latest_inference_result()` 採用非阻塞模式
|
||||||
|
|
||||||
|
**原因：**
|
||||||
|
- 與 Kneron 範例程式碼（example.py）的設計模式一致
|
||||||
|
- 避免推論延遲阻塞整個 Pipeline 執行緒
|
||||||
|
|
||||||
|
**取捨：**
|
||||||
|
- 結果可能為 None（尚未完成），需要 async/processing 狀態的過濾邏輯
|
||||||
|
|
||||||
|
### ADR-005：FPS 計算採用累積式
|
||||||
|
|
||||||
|
**決策**：`completed_counter / elapsed_time`（從第一個結果開始計算）
|
||||||
|
|
||||||
|
**原因：**
|
||||||
|
- 與 Kneron 官方範例的計算方式一致，確保可比性
|
||||||
|
- 排除熱機（warm-up）期間的異常低 FPS
|
||||||
|
|
||||||
|
**取捨：**
|
||||||
|
- 無法反映即時的 FPS 波動（適合穩定場景，不適合延遲敏感場景）
|
||||||
|
|
||||||
|
### ADR-006：PyInstaller 打包
|
||||||
|
|
||||||
|
**決策**：使用 PyInstaller（`main.spec`）產生獨立可執行檔
|
||||||
|
|
||||||
|
**原因：**
|
||||||
|
- 目標用戶（系統整合商）可能沒有 Python 環境
|
||||||
|
- 簡化部署流程
|
||||||
|
|
||||||
|
**取捨：**
|
||||||
|
- 打包後的執行檔體積較大
|
||||||
|
- Kneron KP SDK 的動態函式庫需要正確包含在打包設定中
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 已知限制與技術債
|
||||||
|
|
||||||
|
### 6.1 已知 Bug
|
||||||
|
|
||||||
|
| Bug | 狀態 | 影響 |
|
||||||
|
|-----|------|------|
|
||||||
|
| 節點屬性顯示問題 | 未修復（v0.0.2 記錄） | 右面板 Properties Tab 可能顯示錯誤 |
|
||||||
|
| 輸出視覺化異常（含後處理結果） | 未修復（v0.0.2 記錄） | 輸出畫面可能不正確 |
|
||||||
|
|
||||||
|
### 6.2 技術債
|
||||||
|
|
||||||
|
| 項目 | 嚴重度 | 說明 |
|
||||||
|
|------|--------|------|
|
||||||
|
| 根目錄 debug 腳本未整理 | 低 | `debug_*.py`、`force_cleanup.py` 等應移至 `tools/` |
|
||||||
|
| tests/ 命名混亂 | 中 | 42 個腳本缺乏系統性分類，部分非 test_ 開頭 |
|
||||||
|
| 缺乏 pytest 測試框架 | 中 | 核心模組（InferencePipeline、MultiDongle）無 pytest 覆蓋 |
|
||||||
|
| Coordinator 為循序設計 | 中 | 真正的 Stage 並行需要重構協調器為 DAG 模式 |
|
||||||
|
| 節點識別多重 fallback | 低 | 可讀性差，應統一為單一識別策略 |
|
||||||
|
| RTSP 串流僅基本支援 | 低 | 完整 RTSP 功能未在當前路線圖中 |
|
||||||
|
|
||||||
|
### 6.3 效能限制
|
||||||
|
|
||||||
|
- **協調器為循序傳遞**：目前 Coordinator 依序將資料傳給 Stage 0 → Stage 1，無真正的平行推論（真正平行需重構為流水線佇列模式）
|
||||||
|
- **FPS 計算不反映即時波動**：累積式 FPS 在長時間執行後準確，但短期波動不可見
|
||||||
|
- **輸出佇列上限 50**：高吞吐量場景下可能成為瓶頸
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 未來架構演進方向
|
||||||
|
|
||||||
|
### Phase 1：效能視覺化（對應 DEVELOPMENT_ROADMAP Phase 1）
|
||||||
|
|
||||||
|
**需要新增的架構元件：**
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 新增模組：core/performance/
|
||||||
|
class PerformanceBenchmarker:
|
||||||
|
"""自動化效能測試器"""
|
||||||
|
def run_sequential_benchmark(self, pipeline_config) -> BenchmarkResult
|
||||||
|
def run_parallel_benchmark(self, pipeline_config) -> BenchmarkResult
|
||||||
|
def calculate_speedup(self, seq: BenchmarkResult, par: BenchmarkResult) -> float
|
||||||
|
|
||||||
|
class PerformanceHistory:
|
||||||
|
"""效能歷史記錄（本地 JSON 儲存）"""
|
||||||
|
def record(self, result: BenchmarkResult)
|
||||||
|
def get_history(self, limit: int) -> List[BenchmarkResult]
|
||||||
|
```
|
||||||
|
|
||||||
|
**UI 層新增：**
|
||||||
|
- `ui/components/performance_dashboard.py`：即時 FPS/延遲折線圖（使用 pyqtgraph 或 matplotlib）
|
||||||
|
- `ui/dialogs/benchmark_dialog.py`：Benchmark 啟動與結果呈現
|
||||||
|
|
||||||
|
**架構考量：**
|
||||||
|
- Benchmark 需要能控制 `InferencePipeline` 以單裝置/多裝置模式執行，需要在 `StageConfig` 層級提供模式切換介面
|
||||||
|
- 效能圖表更新須在獨立執行緒中產生資料，透過 Qt Signal 傳遞到 UI 執行緒
|
||||||
|
|
||||||
|
### Phase 2：裝置管理（對應 DEVELOPMENT_ROADMAP Phase 2）
|
||||||
|
|
||||||
|
**需要新增的架構元件：**
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 強化 core/functions/Multidongle.py
|
||||||
|
class DeviceManager:
|
||||||
|
"""裝置管理器"""
|
||||||
|
def scan_devices() -> List[DeviceInfo]
|
||||||
|
def get_device_health(device_id: str) -> DeviceHealth
|
||||||
|
def assign_device(device_id: str, stage_id: str)
|
||||||
|
def get_load_balance_recommendation() -> Dict[str, str]
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class DeviceInfo:
|
||||||
|
device_id: str
|
||||||
|
series: str # KL520/KL720/KL1080
|
||||||
|
status: str # online/offline/busy
|
||||||
|
gops: int # 算力（來自 DongleSeriesSpec）
|
||||||
|
assigned_stage: Optional[str]
|
||||||
|
```
|
||||||
|
|
||||||
|
**UI 層新增：**
|
||||||
|
- `ui/components/device_management_panel.py`：裝置狀態儀表板
|
||||||
|
|
||||||
|
### Phase 3：優化引擎（對應 DEVELOPMENT_ROADMAP Phase 3）
|
||||||
|
|
||||||
|
**需要新增的架構元件：**
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 新增模組：core/optimization/
|
||||||
|
class OptimizationEngine:
|
||||||
|
def analyze_pipeline(self, stats: PipelineStats) -> List[OptimizationSuggestion]
|
||||||
|
def predict_performance(self, config: PipelineConfig) -> PerformancePrediction
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class OptimizationSuggestion:
|
||||||
|
type: str # "rebalance_devices" | "remove_redundant_node" | ...
|
||||||
|
description: str
|
||||||
|
estimated_improvement: float # 預估效能提升 %
|
||||||
|
action: Callable # 可執行的改善動作
|
||||||
|
```
|
||||||
|
|
||||||
|
### 架構演進的長期考量
|
||||||
|
|
||||||
|
1. **Coordinator 重構**：當前循序協調器在多 Stage Pipeline 中形成瓶頸。長期應重構為流水線（pipeline）模式，讓 Stage N+1 在 Stage N 處理下一幀時就開始處理上一幀的結果。
|
||||||
|
|
||||||
|
2. **測試架構建立**：建立 pytest 測試框架，核心模組需達到 80% 以上覆蓋率（特別是 `InferencePipeline` 的佇列邏輯、`pipeline.py` 的 Stage 分析邏輯）。
|
||||||
|
|
||||||
|
3. **型別標註完善**：目前部分模組缺乏完整型別標註，建議逐步加入 mypy 靜態分析。
|
||||||
39
.autoflow/progress.md
Normal file
39
.autoflow/progress.md
Normal file
@ -0,0 +1,39 @@
|
|||||||
|
# 專案進度 — Cluster4NPU UI
|
||||||
|
|
||||||
|
## 目的：接入既有專案 → 文件補齊 → Phase 1 開發
|
||||||
|
## 當前階段：Phase 1 開發完成，待執行測試
|
||||||
|
## 當前狀態：進行中
|
||||||
|
## 最後更新：2026-04-05
|
||||||
|
|
||||||
|
## 進度表
|
||||||
|
|
||||||
|
| 階段 | 狀態 | 完成時間 | 備註 |
|
||||||
|
|------|------|----------|------|
|
||||||
|
| 專案接入 | ✅ 已完成 | 2026-04-05 | 本地路徑 |
|
||||||
|
| 專案健檢 | ✅ 已完成 | 2026-04-05 | 見 00-onboarding/health-check.md |
|
||||||
|
| PRD 產出 | ✅ 已完成 | 2026-04-05 | 02-prd/PRD.md |
|
||||||
|
| Design Doc 產出 | ✅ 已完成 | 2026-04-05 | 04-architecture/design-doc.md |
|
||||||
|
| TDD 產出 | ✅ 已完成 | 2026-04-05 | 04-architecture/TDD.md |
|
||||||
|
| 交叉審閱 | ✅ 已完成 | 2026-04-05 | PM 審閱 TDD，缺口已補充 |
|
||||||
|
| TDD 補充（Phase 4 功能 11） | ✅ 已完成 | 2026-04-05 | reportlab PDF + csv 標準庫 |
|
||||||
|
| Phase 1 後端實作 | ✅ Review 通過 | 2026-04-05 | PerformanceBenchmarker + PerformanceHistory（31 tests） |
|
||||||
|
| Phase 1 UI 實作 | ✅ Review 通過 | 2026-04-05 | PerformanceDashboard + BenchmarkDialog（58 tests total） |
|
||||||
|
| Phase 1 整合到 dashboard | ✅ Review 通過 | 2026-04-05 | dashboard.py 整合完成 |
|
||||||
|
| Phase 2 後端實作 | ✅ Review 通過 | 2026-04-05 | DeviceManager + BottleneckAlert（94 tests） |
|
||||||
|
| Phase 2 UI 實作 | ✅ Review 通過 | 2026-04-05 | DeviceManagementPanel，已整合到 dashboard |
|
||||||
|
| Phase 3 開發 | ✅ Review 通過 | 2026-04-06 | OptimizationEngine + TemplateManager（154 tests） |
|
||||||
|
| Phase 4 開發 | ✅ Review 通過 | 2026-04-06 | ReportExporter + ExportReportDialog（192 tests） |
|
||||||
|
|
||||||
|
## 當前待辦
|
||||||
|
|
||||||
|
- [ ] 執行 Phase 1 整合測試確認所有元件協同運作
|
||||||
|
- [ ] 決定是否繼續 Phase 2
|
||||||
|
|
||||||
|
## 未解決問題
|
||||||
|
|
||||||
|
- 無
|
||||||
|
|
||||||
|
## 重要決策紀錄
|
||||||
|
|
||||||
|
- 程式碼來源：本地路徑（非 GitHub）
|
||||||
|
- 文件補齊策略：從程式碼反向整理，不補設計稿（無現有 UI 截圖或 Wireframe）
|
||||||
@ -8,3 +8,11 @@ dependencies = [
|
|||||||
"nodegraphqt>=0.6.40",
|
"nodegraphqt>=0.6.40",
|
||||||
"pyqt5>=5.15.11",
|
"pyqt5>=5.15.11",
|
||||||
]
|
]
|
||||||
|
|
||||||
|
[tool.pytest.ini_options]
|
||||||
|
testpaths = ["tests/unit"]
|
||||||
|
pythonpath = ["."]
|
||||||
|
addopts = "--import-mode=importlib"
|
||||||
|
python_files = ["test_*.py"]
|
||||||
|
python_classes = ["Test*"]
|
||||||
|
python_functions = ["test_*", "should_*"]
|
||||||
|
|||||||
46
tests/conftest.py
Normal file
46
tests/conftest.py
Normal file
@ -0,0 +1,46 @@
|
|||||||
|
"""
|
||||||
|
tests/conftest.py — 單元測試環境設定。
|
||||||
|
|
||||||
|
此 conftest.py 位於 tests/ 目錄（非 Python 套件），
|
||||||
|
可在 root __init__.py 被觸發前完成 Mock 注入。
|
||||||
|
|
||||||
|
在沒有 Kneron NPU 硬體、PyQt5、NodeGraphQt 的環境下，
|
||||||
|
仍可測試 core/performance/ 的純 Python 邏輯。
|
||||||
|
"""
|
||||||
|
import sys
|
||||||
|
from unittest.mock import MagicMock
|
||||||
|
|
||||||
|
|
||||||
|
def _install_mock(name: str) -> None:
|
||||||
|
"""若模組尚未存在，安裝空 MagicMock 作為替代。"""
|
||||||
|
if name not in sys.modules:
|
||||||
|
sys.modules[name] = MagicMock()
|
||||||
|
|
||||||
|
|
||||||
|
# Kneron KP SDK（需要硬體驅動程式）
|
||||||
|
_install_mock("kp")
|
||||||
|
|
||||||
|
# NumPy（可能未安裝）
|
||||||
|
try:
|
||||||
|
import numpy # noqa: F401
|
||||||
|
except ImportError:
|
||||||
|
_install_mock("numpy")
|
||||||
|
|
||||||
|
# PyQt5 相關模組（需要 GUI 環境）
|
||||||
|
for _mod in [
|
||||||
|
"PyQt5",
|
||||||
|
"PyQt5.QtWidgets",
|
||||||
|
"PyQt5.QtCore",
|
||||||
|
"PyQt5.QtGui",
|
||||||
|
"PyQt5.QtChart",
|
||||||
|
]:
|
||||||
|
_install_mock(_mod)
|
||||||
|
|
||||||
|
# NodeGraphQt（依賴 PyQt5）
|
||||||
|
_install_mock("NodeGraphQt")
|
||||||
|
_install_mock("NodeGraphQt.constants")
|
||||||
|
_install_mock("NodeGraphQt.base")
|
||||||
|
_install_mock("NodeGraphQt.base.node")
|
||||||
|
|
||||||
|
# OpenCV（可能未安裝）
|
||||||
|
_install_mock("cv2")
|
||||||
Loading…
x
Reference in New Issue
Block a user