Helmsman：端侧（SOC）AI 人像抠图 — 从模型到部署的全栈工程 on Potter的个人笔记

Chapter 1: 黄金参考系统 — 在 x86 上搭建像素级对齐的 C++ 推理管线

Tue, 09 Jun 2026 00:00:00 +0000

Chapter 1: Building a Golden Reference System

Project Attribute	Details
Project Name	Helmsman — Golden Reference System
Phase	Foundation F1
Date	2026-01 ~ 2026-02
Key Personnel	Potter White

1. Core Question

2. Goal Review

3. Implementation

|导出 reference_tensor.txt| B[对比]

C[C++ preprocess] -->|导出 cpp_tensor.txt| B
B -->|diff 无差异| D[✅ 对齐成功]


步骤：
1. 预处理对齐：OpenCV resize + normalize [0,255]→[-1,1] + HWC→CHW
2. 推理引擎封装：InferenceEngineONNX 类（Load + Infer）
3. 后处理：pha tensor → alpha matte → alpha blend
4. 验证：md5 逐字节对比
-->

### **4. Key Challenge: 归一化精度 Bug**

<!-- 填入：
- 现象：bitwise 对比失败，Python 和 C++ 的 tensor 数据有微小差异
- 根因：float 精度差异（浮点运算顺序不同导致的舍入误差）
- 解决：统一 normalize 实现，确保逐元素操作顺序一致
- 参考 PKB：bug-F1-normalization-bitwise.md
-->

### **5. Outcome**

<!-- 填入：
- C++ 输出与 Python baseline md5 一致 ✅
- Golden Reference 作为后续所有板端测试的 baseline
- 封装了可复用的模块：TensorData、InferenceEngineONNX、Preprocessor
-->

### **6. Reusable Assets**

<!-- 填入：表格，列出这一阶段产出的可复用代码/工具：

| 资产 | 路径 | 说明 |
|------|------|------|
| TensorData | include/.../tensor-data.h | 统一的 tensor 数据结构 |
| InferenceEngineONNX | src/.../inference/onnx/ | ONNX Runtime 封装 |
| Preprocessor | src/.../frontend/preprocessor.cpp | 预处理模块 |

-->

Chapter 2: 网络手术 — IBNorm→BatchNorm 与 ONNX 导出

Tue, 09 Jun 2026 00:00:00 +0000

Chapter 2: Network Surgery — IBNorm to BatchNorm

Project Attribute	Details
Project Name	Helmsman — Round 1 Model Surgery
Phase	MR1 Phase-1
Date	2026-03-12 ~ 2026-03-19
Key Personnel	Potter White

1. Core Question

2. Problem Discovery

3. Root Cause Analysis

4. Solution: BN Surgery

5. ONNX Export — 踩坑记录

6. Validation

7. Key Insight

Chapter 3: RKNN 移植与 ONNX Graph Surgery

Tue, 09 Jun 2026 00:00:00 +0000

Chapter 3: RKNN Porting and ONNX Graph Surgery

Project Attribute	Details
Project Name	Helmsman — RKNN Porting + Graph Surgery
Phase	DR1 RKNN + MR2 Phase-1~2
Date	2026-04-02 ~ 2026-04-11
Key Personnel	Potter White

1. Core Question

2. ArcFoundry: YAML-Driven RKNN Conversion

3. MODNet RKNN FP16 Benchmark

4. Graph Surgery — 移除 DeepGuidedFilterRefiner

5. RVM Round 2: Gate-0 → RKNN FP16

6. Guided Filter Experiments

7. Reusable Assets

Chapter 4: C++ 推理流水线工程

Tue, 09 Jun 2026 00:00:00 +0000

Chapter 4: Engineering a Production-Grade C++ Inference Pipeline

Project Attribute	Details
Project Name	Helmsman — C++ Inference Pipeline
Phase	MR2 Phase-3 + Phase-5
Date	2026-04-11 ~ 2026-04-18
Key Personnel	Potter White

1. Core Question

2. Architecture: NVI Pattern

|TensorData| B[InferenceEngine]

B -->|vector<TensorData>| C[Backend]

subgraph Frontend
 A1[Input Source] --> A2[Decoder]
 A2 --> A3[Color Convert]
 A3 --> A4[Preprocess]
end

subgraph InferenceEngine
 B1[Inject States] --> B2[Quantize]
 B2 --> B3[NPU Execute]
 B3 --> B4[Dequantize]
end

subgraph Backend
 C1[Postprocess] --> C2[Composite]
end


设计原则：
- Preprocessor 只负责空间变换（resize, letterbox）
- Engine 负责精度变换（normalize, quantize, dequantize）
- Backend 负责数据提取 + 合成输出
- 三者正交，互不依赖
-->

### **3. Frontend: 4 Sub-Stages**

<!-- 填入：4 个子阶段的说明（参考 PKB _DASHBOARD.md 附录 B §2）：
1. Stage 01 Input Source：FFmpegInputSource，读取视频 packet
2. Stage 02 Decoder：MppFrameDecoder，硬件解码 H.264/H.265
3. Stage 03 Color Convert：RgaNv12ToBgr，RGA 硬件 NV12→BGR
4. Stage 04 Preprocess：resize + letterbox → TensorData(float32 [0,255])
-->

### **4. InferenceEngine: NVI + Factory Pattern**

<!-- 填入：
- NVI（Non-Virtual Interface）模式：Infer() 公开入口 → 注入状态 → DoInfer() 纯虚钩子 → 捕获状态
- 工厂模式：make_engine() 根据 INFERENCE_BACKEND 配置创建不同引擎
- 三路引擎：onnx | rknn-zerocopy | rknn-non-zerocopy

关键设计决策：为什么 Normalize + Quantize 放在 Engine 里？

| 引擎 | 输入量化方式 | 输出反量化方式 |
|------|------------|--------------|
| RKNN Zero-Copy | 手动：(pixel-127.5)/127.5/scale+zp 写入 DMA | 手动：(val-zp)*scale 从 DMA 读出 |
| RKNN Non-Zero-Copy | rknn_inputs_set(pass_through=0) | rknn_outputs_get(want_float=1) |
| ONNX Runtime | 模型内嵌 QDQ 节点 | 模型内嵌 QDQ 节点 |

如果把 normalize 放到 Preprocessor 里，换引擎就要改 Preprocessor → 违反"换引擎只需重新编译"的设计目标。
-->

### **5. Multi-Model Support: MODNet + RVM**

<!-- 填入：
- MODNet：1-in/1-out，无状态
- RVM：5-in/6-out，有递归状态（r1i~r4i 注入/捕获）
- 设计：在旁边加新路，不改旧路（RecurrentStateManager）
- 参考 PKB summarize-MR2-G0 Q4
-->

### **6. Pipeline Modes: Sync → Double Buffer → Worker Thread**

<!-- 填入：三种模式的演进：
1. 同步模式：read → preprocess → infer → backend（串行）
2. 双 buffer 流水线：std::async 预取第 N+1 帧 decode+preprocess 与第 N 帧推理并行
3. 持久 Worker Thread：SingleSlotChannel<T> + 持久 worker thread 替换 std::async-per-frame，零线程创建开销

参考 PKB log-MR2-P5-video-pipeline.md Block 5.2 + 5.4
-->

### **7. Reusable Assets**

<!-- 填入：表格

| 资产 | 说明 |
|------|------|
| NVI InferenceEngine 基类 | 可扩展到任意模型 |
| 工厂模式 + 三路引擎 | 换引擎只需重新编译 |
| RecurrentStateManager | RVM 递归状态管理 |
| SingleSlotChannel<T> | 生产者-消费者通道，零锁开销 |
| ScopedTimer + StageAccumulator | 层级计时系统 |

-->

Chapter 5: 打破速度极限 — DMA Zero-Copy、MPP 硬解与 NEON SIMD

Tue, 09 Jun 2026 00:00:00 +0000

Chapter 5: Breaking the Speed Limit

Project Attribute	Details
Project Name	Helmsman — Speed Optimization
Phase	MR2 Phase-5
Date	2026-04-15 ~ 2026-06-08
Key Personnel	Potter White

1. Core Question

2. Baseline Profiling

3. FPS 演进历程

4. DMA Zero-Copy — 单次最大 FPS 提升

5. MPP 硬解调试 — 五层 Bug 剥洋葱

6. NEON SIMD — 精确到 0.01ms 的 Profiling

7. librknnrt.so 白盒分析

8. Reusable Assets

Chapter 6: INT8 量化探索 — 发现 ConvGRU 的架构性死局

Tue, 09 Jun 2026 00:00:00 +0000

Chapter 6: INT8 Quantization Exploration

Project Attribute	Details
Project Name	Helmsman — INT8 Quantization Exploration
Phase	DR1 INT8 + MR2 Phase-4
Date	2026-04-06 ~ 2026-06-05
Key Personnel	Potter White

1. Core Question

2. MODNet INT8 — 纯 CNN 路线

3. RVM INT8 — 纯 INT8 崩溃

|r-state| B[Frame 2]

B -->|r-state + 量化误差| C[Frame 3]
C -->|r-state + 更大误差| D[Frame N]
D -->|误差指数发散| E[pha = 0.000000]


核心洞察：**RNN 的误差累积是架构性问题，不是校准问题。**
-->

### **4. RVM INT8 — 混合量化尝试**

<!-- 填入：
- 方案：INT8 编解码 + FP16 r-state（保留递归状态精度）
- 阻断：被 SDK v2.3.2 bug 阻断（SE Block KeyError '593'）
- 根因：rknn-toolkit2 v2.3.2 的 quant_optimizer.py._p_adjust_tanh_sigmoid() 对 SE Block 的 MatMul→Sigmoid tensor key 处理有缺陷
- 进展：v2.4.0 修复了 quant_optimizer，但 hybrid_step2 完整验证未完成
- 参考 PKB summarize-MR2-ending.md §2.2
-->

### **5. ConvGRU INT8 vs MODNet INT8 对比**

<!-- 填入：对比表（参考 PKB summarize-MR2-ending.md §2.3）：

| 维度 | RVM (ConvGRU) | MODNet (纯 CNN) |
|------|---------------|-----------------|
| INT8 精度 | ❌ cosine=0.000 | ✅ cosine=0.999 |
| 误差累积 | 有（帧间 r-state）| 无（每帧独立）|
| 混合量化可行性 | ❌ SDK bug 阻断 | ✅ 不需要 |
| FPS 上限 | ~16.7 | ~30-40 |
-->

### **6. Value of This Exploration**

<!-- 填入：这一章的核心价值：

"用实验证明了一条路走不通"本身就是工程判断力。

具体价值：
1. 避免了在错误方向上继续投入（RVM INT8）
2. 定量证明了 RNN 在 NPU 上的架构性限制
3. 为项目方向决策提供了数据支撑（回到 MODNet）
4. 发现了 SDK bug，对社区有参考价值

这个发现不是"失败"，而是"用最小代价获得了最关键的判断"。
-->

### **7. Decision: Back to MODNet**

<!-- 填入：基于以上实验，做出的决策：

1. RVM 架构性 FPS 天花板 16.7，无法突破 30 FPS
2. ConvGRU INT8 精度崩溃，混合量化被 SDK bug 阻断
3. MODNet 纯 CNN 无帧间依赖，INT8 可行，理论 30+ FPS
4. 决定回到 MODNet 路线，继续 INT8 + 流水线并行
-->

Chapter 7: 复盘与反思

Tue, 09 Jun 2026 00:00:00 +0000

Chapter 7: Retrospective — Lessons from an Edge AI Deployment Journey

Project Attribute	Details
Project Name	Helmsman — Retrospective
Date	2026-01 ~ 2026-06（5 个月）
Key Personnel	Potter White

1. Project Timeline

2. Key Decisions

3. What Went Right

4. What I’d Do Differently

5. Skills Gained

6. Reusable Assets

7. What’s Next

8. Closing Thoughts

Section 8.1: Orin NX 上给 RVM 测 FPS 基线

Fri, 28 Aug 2026 00:00:00 +0000

Orin NX 上给 RVM 测 FPS 基线

状态：骨架，待填肉。数字已核对，散文全部待写。归属：Helmsman / CUDA 平台线（与现有 7 章 Rockchip 线并列，勿插入编号） 数据来源：deploy/cuda/day3-docker-pytorch-and-rvm-fp32.md（2026-08-26/27 实测）

〇 · 流水账

镜像选型 → 容器起来 → CUDA 可用性验证 → RVM 仓库 + 权重就位
出图成功：363 帧 1080p，vlc 确认抠图正常、发丝边缘干净
端到端 1.83 it/s

ClaudeCode用来建立课程，尤其是自己不太熟悉的领域，效果不错。

虽然RVM的模型部署对我来说并不陌生了，但是毕竟Jetson是陌生的，所以最初的基础还是CC给我建立的。

拿到硬件的检查，打印外壳，模组压力测试，温度曲线，GPU使用率曲线等都属于BSP的内容，我在此就以BSP环节都完成为起点，直接展开RVM的部署记载。

第一件事，选择什么容器镜像

虽然我觉得在arm板上再部署docker,对于最终性能的损耗总会有担心，但AI给的回答是：

现在以快速上线为第一，而英伟达给的容器镜像就把这部分依赖环境都给建立好，所以用容器的学习成本是小于投入时间研究环境的代价的。
容器不会留到最终生产阶段，所以性能的微弱影响可以在此忽略不计。
Jetson上部署容器，以及nvidia-container-toolkit关系是什么，能用docker官网给出的安装命令吗？（反正都是apt去做）为什么？

带着这些问题，我决定跟着课程走。第一件事，就是选择什么镜像呢？

1. 打开 https://catalog.ngc.nvidia.com/
 ↓
2. 左侧筛选栏先勾 【Containers】 ← ⭐ 第一下就勾这个
 ↓ （NGC 上还有 Models / Resources / Helm Charts / Collections，
 ↓ 跟找镜像无关，勾掉之后页面立刻清爽）
 ↓
3. 搜索框输 "pytorch" ← ⭐ 只输容器名，永远不要输版本号
 ↓
4. 点进 【PyTorch】 那张卡片（因为rvm的模型用的就是pytorch）
 ↓
5. 点页面上的 【Tags】 标签页 ← ⭐ 关键就是这一下，tag 只在这里
 ↓
6. 在 tag 列表里找名字带 -igpu 的
 ↓
7. 有N个带-igpu的镜像，选择哪一个得看pytorch对应的cuda版本
 a. ssh到jetson,输入'ls -lhat /usr/local/cuda-*'，此处我显示出是cuda-12.6。因此接下来就是要找到对应cuda12.6的pytorch-xx-igpu镜像
 b. 打开 https://docs.nvidia.com/deeplearning/frameworks/pytorch-release-notes/
 c. 左侧目录点 "PyTorch Release 24.12"
 （或直接改 URL：.../rel-24-12.html ← 把年月换成我要查的那个版本）
 d. 页面开头 "This container image contains..." 那段，看两行：
 NVIDIA CUDA xxxx ← ⭐ 这个跟宿主比
 PyTorch 2.6.yyyy
 e. 如果不匹配，就继续回到b,寻找其他pytorch的版本，直到找到为止；
 如果已找到匹配，那就记下这个版本号，例如24.12

8. 回到5的tags标签页，找到你要的标签，例如上面举例的24.12，然后用每行右边的 【Copy】 按钮取完整 pull 路径（别手打，容易出错）

第二件事. 初始化开发环境

cd /workspace/rvm
git clone https://github.com/PeterL1n/RobustVideoMatting.git
cd RobustVideoMatting.git

# 下预训练权重
wget https://github.com/PeterL1n/RobustVideoMatting/releases/download/v1.0.0/rvm_mobilenetv3.pth \
 -O /workspace/rvm/weights/rvm_mobilenetv3.pth

# 依赖
pip3 install numpy==1.26.4 av==12.3.0 pims==0.7 slicerator==1.1.0 imageio==2.34.2 tqdm==4.67.1 tifffile==2024.8.30 --proxy="http://192.168.3.164:7890"

这些依赖都在我的docker of jetson里跑通了。