kneron-edge-ai-integration

name	kneron-edge-ai-integration
description	把物件偵測模型 (YOLOX) 整合部署到耐能 Kneron NPU (KL730/720/630) 的 SOP 與必踩雷。核心:量化崩潰根因 (raw-logit 須用 mmse range method,非 percentage=1.0)。觸發:「YOLO/模型跑在耐能/Kneron NPU」「KL730/720 部署」「ONNX 轉 NEF」「Kneron toolchain 量化」「NPU 量化後輸出崩潰/全0」「kneron-mmdetection 環境」「edge AI 晶片整合物件偵測」。完整 SOP 與觸發見內文。

Kneron Edge AI 整合部署 SOP

把現成物件偵測算法 (YOLOX) 整合到現成 Kneron NPU 晶片,讓它在 edge (如無人機) 即時跑。 這是系統整合 (systems integration),不是算法研發 — 不發明新網路,而是讓「算法 + AI 晶片 + 資料 + 部署」協同運作。

本 skill 階層式:先讀本檔 (總覽 + 致命雷),需要某階段細節再讀 references/ 對應檔。 來源:UAV2UAV 熱影像辨識專案實戰 (2026-06, KL730 + YOLOX-s),repo: github.com/wicanr2/uav-yolox-kl730

何時用此 Skill

• 要把 YOLO / 物件偵測模型部署到 Kneron KL730 / KL720 / KL630
• ONNX → NEF 轉換、Kneron toolchain 量化
• NPU 量化後輸出崩潰 / 全 0 / 精度暴跌 ← 本 skill 最高價值,直接跳 §3
• kneron-mmdetection 訓練/匯出環境建不起來
• 規劃「邊緣 AI 影像辨識」系統整合專案 (晶片選型、軟體鏈、成本重量)

0. 心智模型:兩個世界 + 一座橋

【訓練世界 PC/GPU, PyTorch】          橋        【部署世界 晶片, C/SDK】
資料 → 訓練 → checkpoint → ONNX ──[Kneron toolchain]──→ NEF → NPU 即時跑
                          (opset11)  優化→量化→編譯

• NEF = Kneron NPU 的可執行檔 (等於「編譯好的程式」)。
• NPU 只算 raw 張量;decode + NMS 跑在晶片的 CPU 核 (如 KL730 的 A55),不是 NPU。
• 七站完整流程見 references/03-pipeline-playbook.md。

1. 致命雷 #1 — 量化崩潰 (最該先知道的)

症狀:NEF 模擬推論輸出退化成「每個 channel 一個常數值」,float 範圍 −15~+7 被壓成 ±0.01。

根因:--skip-postprocess 匯出的是 raw logits (無 sigmoid,範圍 −15~+1)。 量化用 detection 官方建議的 percentage=1.0 會把範圍張到含 −15 離群值 → INT8 的 256 格攤在 ~16 寬範圍 → 多數值擠進同一格 → 崩潰。

解法 (一個參數):datapath_range_method="mmse" (SNR-based,對離群值穩健)。 改這一個就好,不必動位寬、不必重 export、不必 mix 模式 (mix 模式吃爆記憶體)。

詳細 7 輪排查、per-channel 驗收法、其他量化參數 → references/02-quantization-gotchas.md

2. 致命雷 #2 — 把開發機記憶體用爆

Kneron toolchain 的 mix-mode 量化做 int16 模擬,記憶體爆量;曾把 30GB RAM 機器拖進 swap thrash 假死 (需重開機,kernel OOM killer 不會觸發)。

對策 (一律照做):

docker run --rm --cpus=8 --memory=20g --memory-swap=20g ...   # 硬上限,爆了只 kill 容器不拖垮主機

量化降載:threads=4、校正集 100 張、優先 int8 (非 mix)。

3. 致命雷 #3 — kneron-mmdetection 環境 (舊生態 + 新工具)

kneron-mmdetection 是 mmdetection 2.25.0 fork (2022),配新版套件會炸。版本鎖死:

套件	鎖定	不鎖會怎樣
PyTorch	1.12.1	—
mmcv-full	1.6.0	mmdet assert 失敗
ONNX opset	11	export 腳本內 assert
yapf	0.40.1	新版移除 FormatCode(verify=) → TypeError
onnx-simplifier	0.4.36	0.5.x 的 onnxsim 在舊 py 無 wheel

用 uv venv 還有額外 3 個坑 (no-build-isolation / setuptools / UV_PYTHON_INSTALL_DIR)。 完整 Dockerfile + 6 個 build 坑 → references/01-docker-toolchain-env.md

4. 關鍵決策原則 (選型,非研發)

• YOLOX 優於新版 YOLO:授權乾淨 (Apache-2.0 vs Ultralytics AGPL);Kneron 官方驗證; 新版 NMS-free (YOLOv10/26) 的 TopK 子圖在各家 NPU 量化都踩雷。「越新越好」是迷思 — 正確標準是「能在目標 NPU 正確量化的最新版」。
• platform id 是字串 "730";toolchain conda env 用 onnx1.13 (base 不支援 730)。
• 驗收要有鑑別力:① 量化後逐 channel corr (非攤平,>0.9 合格) ② cpu_node: N/A (零 fallback) ③ mAP 掉幅 <3%。「非全 0」這種檢查太弱,抓不到退化。
• 詳細模型/資料/輸入尺寸 fps 權衡 → references/04-model-data-choices.md

5. 標準工作流 (七站)

1.資料蒐集 → 2.轉COCO → 3.訓練(YOLOX) → 4.匯出ONNX(opset11,skip-postprocess)
→ 5.量化編譯(toolchain: 優化→evaluate→mmse量化→compile→NEF) → 6.後處理(decode+NMS,跑CPU核)
→ 7.部署(Kneron PLUS 載 NEF 上板)

每站都要有可驗證的 pass/fail 訊號 (smoke / corr / fps / mAP / 端到端出框)。 逐站指令與 make target → references/03-pipeline-playbook.md

6. 無 GPU 也能做到的事 (CPU-only 開發策略)

本機只有 CPU 時:資料管線、smoke 訓練、整條 ONNX→NEF 量化鏈 (toolchain 本就 CPU)、端到端模擬推論 全部可在本機驗證;只有「正式訓練」需要 GPU → 丟雲端 (Kaggle 免費 30h/週)。 用官方 Model Zoo 預訓練權重,甚至不訓練就能先把量化鏈與最大風險驗完。

方法論備註 (digital twin)

• 棘手問題先建「快速、決定性的 pass/fail 訊號」,再用對照組逐一排除假設 (一次只變一個變因)。
• silent failure 最危險 (knerex 忽略參數不報錯、報告與實際設定脫鉤) → 主動驗證「設定真的生效了嗎」。
• 知識交付分層 (問題→概念→技術鏈→深入→實戰),讓非專家也能漸進理解。
• 大記憶體 docker 工作一律設 --memory/--cpus 上限,出事前就要設。