docs(readme): strip private-repo references, sync RKNN list to 2026-06-03 batch

- Drop §1.5 (references helmsman private repo)
- §1.3.3 pureBN: remove 'recommended for deployment' (production uses §1.3.1)
- §2.1: rename 'Refiner' column to '深度导向滤波 (Deep Guided Filter)'
- §2.2: replace RKNN table with current 11-file 2026-06-03 batch
(all no-resize); fix ArcFoundry version to v0.15.0
- §2.3/§2.4: mark old s14/s20/s21 data stale; new benchmarks pending
- §2.5: reword '全部 RKNN 已应用 graph surgery' (no special variant)
- §3: strip helmsman private paths; keep only public-facing pointers
- Add scope note to top (this repo = artifacts only)
- Bump version 1.3 → 1.4

README.md

@@ -1,6 +1,7 @@
 # MODNet 与 RVM 模型制品仓库 (Model Artifact Registry)
 
-> **用途**：集中管理 MODNet 与 RVM 的检查点（Checkpoint）、ONNX/RKNN 模型及训练制品（Training Artifacts）
+> **用途**：集中托管 MODNet 与 RVM 的模型制品（ckpt / onnx / rknn 文件本身）
+> **不包含**：训练代码与 C++ 推理代码——这些在配套的私有仓库中维护
 >
 > **维护者**：PotterWhite
 > **最后更新**：2026-07-03
@@ -15,8 +16,7 @@
    - [1.2 微调模型 — 摄影数据集](#12-微调模型--摄影数据集)
    - [1.3 ONNX 模型变体](#13-onnx-模型变体)
    - [1.4 目录结构](#14-目录结构)
-   - [1.5 生成与部署指南](#15-生成与部署指南)
-   - [1.6 速查表](#16-速查表)
+   - [1.5 速查表](#15-速查表)
 2. [RVM 模型](#2-rvm-模型)
    - [2.1 ONNX 模型](#21-onnx-模型)
    - [2.2 RKNN 模型](#22-rknn-模型)
@@ -209,8 +209,6 @@ sess = onnxruntime.InferenceSession('photographic/finetune/onnx/modnet_bn_best_p
 **文件**：`photographic/finetune/onnx/modnet_bn_best_pureBN.onnx`
 
 ```
-★ 推荐用于部署
-
 从 modnet_bn_best.ckpt（微调模型）导出的 ONNX
 - 来源：PyTorch 微调训练（第 15 轮）
 - 导出日期：2026-03-31 16:15
@@ -219,14 +217,13 @@ sess = onnxruntime.InferenceSession('photographic/finetune/onnx/modnet_bn_best_p
 - 输入：[1, 3, 512, 512]（float32，[-1, 1] 归一化）
 - 输出：[1, 1, 512, 512]（float32，[0, 1] 范围）
 - 文件大小：25 MB
-- 状态：✓ 可用于 C++ 推理的生产版本
+- 状态：⚠️ 参考用。纯 BN 变体在当前量化/部署路径上仍有数值问题，
+        **生产部署请用 §1.3.1 官方原版（带 InstanceNorm）**。
 
-推荐理由：
-  ✓ 无 InstanceNormalization → 更好的 NPU 调度
-  ✓ 全部算子：Conv2d, BatchNorm2d, ReLU 等（硬件友好）
-  ✓ 定点推理下数值精度更优
-  ✓ RKNN 工具链编译更快
-  ✓ 比 IBNorm 变体收敛更好
+技术说明（仅供对比研究）：
+  - 无 InstanceNormalization → 理论上是 NPU 友好
+  - 全部算子：Conv2d, BatchNorm2d, ReLU 等（硬件友好）
+  - 但实测在某些量化路径上数值偏移较大，需进一步调试
 
 已测试环境：
   - ONNX Runtime 1.16.3（CPU, x86_64）
@@ -289,79 +286,7 @@ MODNet/
 
 ---
 
-### 1.5 生成与部署指南
-
-#### ONNX 生成方法
-
-```python
-# 第 1 步：训练微调检查点
-# $ cd helmsman.git/
-# $ python3 third-party/scripts/modnet/train_modnet_block1_2.py
-# → 输出：photographic/finetune/checkpoints/modnet_bn_best.ckpt
-
-# 第 2 步：导出为 ONNX（Pure-BN 架构）
-import torch
-import onnx
-from modnet import MODNet  # Pure-BN 版本
-
-checkpoint = torch.load('checkpoints/modnet_bn_best.ckpt')
-model = MODNet()
-model.load_state_dict(checkpoint)
-model.eval()
-
-# 虚拟输入（Dummy Input）
-dummy_input = torch.randn(1, 3, 512, 512)
-
-# 导出，支持动态轴（Dynamic Axes）
-torch.onnx.export(
-    model, dummy_input,
-    'onnx/modnet_bn_best_pureBN.onnx',
-    export_params=True,
-    opset_version=11,
-    do_constant_folding=False,  # 保留 BN 参数可见
-    input_names=['input'],
-    output_names=['output'],
-    dynamic_axes={
-        'input': {0: 'batch_size', 2: 'height', 3: 'width'},
-        'output': {0: 'batch_size', 2: 'height', 3: 'width'}
-    }
-)
-
-# 第 3 步：验证 ONNX 模型
-onnx_model = onnx.load('onnx/modnet_bn_best_pureBN.onnx')
-onnx.checker.check_model(onnx_model)
-print("✓ ONNX 模型验证通过")
-```
-
-#### C++ 推理部署
-
-```bash
-# 构建 C++ 推理引擎
-cd helmsman.git/
-./helmsman prepare                    # 安装 Python 依赖、MODNet 子模块
-./helmsman build cpp cb native        # 清理构建（x86_64 原生）
-
-# 运行推理
-./install/native/release/bin/Helmsman_Matting_Client \
-    <input_image> \
-    photographic/finetune/onnx/modnet_bn_best_pureBN.onnx \
-    <output_dir>
-
-# 对比 Python 黄金参考
-python3 tools/MODNet/verify_golden_tensor.py
-```
-
-#### 部署清单
-
-- [ ] ONNX 模型通过 `onnx.checker.check_model()` 验证
-- [ ] C++ 构建通过黄金张量验证（Golden Tensor Verification）
-- [ ] Python 与 C++ 推理输出匹配（L∞ 误差 < 1e-5）
-- [ ] 边缘设备（RK3588S）交叉编译测试通过
-- [ ] 延迟基准测试：每次推理 < 100ms（512×512 输入）
-
----
-
-### 1.6 速查表
+### 1.5 速查表
 
 | 模型 | 文件 | 大小 | 用途 | 状态 |
 |------|------|------|------|------|
@@ -379,72 +304,80 @@ python3 tools/MODNet/verify_golden_tensor.py
 
 位于 `RobustVideoMatting/onnx/`。
 
-| 模型 | 文件 | 大小 | 骨干网络（Backbone） | 精炼器（Refiner） | 来源 |
-|------|------|------|----------|---------|------|
-| **MobileNetV3 FP32** | `rvm_mobilenetv3_fp32.onnx` | 14.3MB | MobileNetV3 | 无 | PeterL1n/RobustVideoMatting v1.0.0 |
-| **MobileNetV3 FP16** | `rvm_mobilenetv3_fp16.onnx` | 7.2MB | MobileNetV3 | 无 | FP16 导出 |
-| **MobileNetV3 FP32（无精炼器）** | `rvm_mobilenetv3_fp32_no_refiner.onnx` | 14.3MB | MobileNetV3 | 无 | 移除 refiner 算子 |
-| **ResNet50 FP32** | `rvm_resnet50_fp32.onnx` | ~90MB | ResNet50 | 无 | PeterL1n v1.0.0 |
-| **ResNet50 FP16** | `rvm_resnet50_fp16.onnx` | ~45MB | ResNet50 | 无 | FP16 导出 |
+| 模型 | 文件 | 大小 | 骨干网络（Backbone） | 深度导向滤波（Deep Guided Filter） | 来源 |
+|------|------|------|----------|-----------------|------|
+| **MobileNetV3 FP32** | `rvm_mobilenetv3_fp32.onnx` | 14.3MB | MobileNetV3 | ✓ | PeterL1n/RobustVideoMatting v1.0.0 |
+| **MobileNetV3 FP16** | `rvm_mobilenetv3_fp16.onnx` | 7.2MB | MobileNetV3 | ✓ | FP16 导出 |
+| **MobileNetV3 FP32** | `rvm_mobilenetv3_fp32_no_refiner.onnx` | 14.3MB | MobileNetV3 | — | 移除 Deep Guided Filter |
+| **ResNet50 FP32** | `rvm_resnet50_fp32.onnx` | ~90MB | ResNet50 | ✓ | PeterL1n v1.0.0 |
+| **ResNet50 FP16** | `rvm_resnet50_fp16.onnx` | ~45MB | ResNet50 | ✓ | FP16 导出 |
 
 **关键模型属性**（MobileNetV3）：
 - Opset 12，IR version 6，353 个节点
 - 零个 InstanceNorm 节点（NPU 友好）
-- 无精炼器算子（DeepGuidedFilterRefiner 未包含）
 - 6 个输入：`src [1,3,H,W]`、`r1i~r4i`（ConvGRU 状态）、`downsample_ratio [1]`
 - 经 ArcFoundry `fold_constant_inputs` 处理后：5 个输入（downsample_ratio 烘焙为常量）
 
 ### 2.2 RKNN 模型
 
-位于 `RobustVideoMatting/rknn/`。
-
-| 模型 | 文件 | 大小 | 分辨率 | 精度 | dsr | 状态 | PKB 参考 |
-|------|------|------|--------|------|-----|------|----------|
-| **256×256 FP16** | `rvm_mobilenetv3_fp16_256x256_rk3588_fp16_v20260416.rknn` | 9.0MB | 256×256 | FP16 | 0.25 | Phase-1 验证用 | §3 |
-| **288×512 FP16** | `rvm_mobilenetv3_fp16_288x512_rk3588_fp16_v20260416.rknn` | 9.3MB | 288×512 | FP16 | 0.25 | 早期板端实验 | §3 |
-| **1080p FP16 (dsr=0.25)** | `rvm_mobilenetv3_fp16_1080x1920_rk3588_fp16.rknn` | 12MB | 1080×1920 | FP16 | 0.25 | **当前默认模型** | §12-§13, §20 |
-| **1080p FP16 (dsr=0.5)** | `rvm_mobilenetv3_fp16_1080x1920_0.5-dsr_rk3588_fp16.rknn` | 16MB | 1080×1920 | FP16 | 0.5 | **最佳质量模型** | §21 |
-| **256×256 INT8** | `rvm_mobilenetv3_int8_256x256_rk3588_int8_v20260416.rknn` | 5.5MB | 256×256 | INT8 | 0.25 | Phase-4 量化实验 | §4 |
-| **288×512 INT8** | `rvm_mobilenetv3_int8_288x512_rk3588_int8_v20260416.rknn` | 5.7MB | 288×512 | INT8 | 0.25 | Phase-4 量化实验 | §4 |
-| **416×736 FP16 (oplv3)** | `rvm_mobilenetv3_fp16_416x736_0.5-dsr-oplv3_rk3588_fp16.rknn` | 10.0MB | 416×736 | FP16 | 0.5 | oplv3 中等分辨率（2026-06-01 加入） | — |
-| **544×960 FP16 (oplv3)** | `rvm_mobilenetv3_fp16_544x960_0.5-dsr-oplv3_rk3588_fp16.rknn` | 10.6MB | 544×960 | FP16 | 0.5 | oplv3 中等分辨率（2026-06-01 加入） | — |
-| **544×960 FP16 (oplv3, no-resize)** | `rvm_mobilenetv3_fp16_544x960_0.5-dsr-oplv3-no-resize_rk3588_fp16.rknn` | 10.3MB | 544×960 | FP16 | 0.5 | oplv3 + no-resize 变体（2026-07-03 加入） | — |
-
-**转换工具**：[ArcFoundry](https://github.com/PotterWhite/ArcFoundry.git) v0.14.0
+位于 `RobustVideoMatting/rknn/`，目标平台 RK3588 / RK3588S。
+
+> **全部 RKNN 都已应用 no-resize graph surgery**（详见 §2.5）：refiner 末尾的
+> 2× Resize + Mul/Add/Split/Clip 链已从 NPU 图中移除，由 C++ 后处理端实现
+> guided-filter 组合 + 上采样。下表不再单独标注 no-resize 变体。
+
+| 模型 | 文件 | 大小 | 分辨率 | 精度 | dsr | 状态 |
+|------|------|------|--------|------|-----|------|
+| **1080×1920 FP16** | `rvm_mobilenetv3_fp16_1080x1920_0.25-dsr_rk3588s_20260603_rk3588_fp16.rknn` | 10.9MB | 1080×1920 | FP16 | 0.25 | 默认 |
+| **736×1280 FP16** | `rvm_mobilenetv3_fp16_736x1280_0.5-dsr_rk3588s_20260603_rk3588_fp16.rknn` | 11.3MB | 736×1280 | FP16 | 0.5 | 较高质量 |
+| **736×1280 FP16** | `rvm_mobilenetv3_fp16_736x1280_0.25-dsr_rk3588s_20260603_rk3588_fp16.rknn` | 9.9MB | 736×1280 | FP16 | 0.25 | — |
+| **544×960 FP16** | `rvm_mobilenetv3_fp16_544x960_0.5-dsr_rk3588s_20260603_rk3588_fp16.rknn` | 10.3MB | 544×960 | FP16 | 0.5 | 中等质量 |
+| **544×960 FP16** | `rvm_mobilenetv3_fp16_544x960_0.25-dsr_rk3588s_20260603_rk3588_fp16.rknn` | 9.5MB | 544×960 | FP16 | 0.25 | — |
+| **416×736 FP16** | `rvm_mobilenetv3_fp16_416x736_0.5-dsr_rk3588s_20260603_rk3588_fp16.rknn` | 9.8MB | 416×736 | FP16 | 0.5 | — |
+| **416×736 FP16** | `rvm_mobilenetv3_fp16_416x736_0.25-dsr_rk3588s_20260603_rk3588_fp16.rknn` | 9.3MB | 416×736 | FP16 | 0.25 | — |
+| **320×576 FP16** | `rvm_mobilenetv3_fp16_320x576_0.5-dsr_rk3588s_20260603_rk3588_fp16.rknn` | 9.5MB | 320×576 | FP16 | 0.5 | — |
+| **320×576 FP16** | `rvm_mobilenetv3_fp16_320x576_0.25-dsr_rk3588s_20260603_rk3588_fp16.rknn` | 9.1MB | 320×576 | FP16 | 0.25 | — |
+| **288×512 FP16** | `rvm_mobilenetv3_fp16_288x512_0.25-dsr_rk3588s_20260603_rk3588_fp16.rknn` | 9.1MB | 288×512 | FP16 | 0.25 | 早期验证 |
+| **256×256 FP16** | `rvm_mobilenetv3_fp16_256x256_0.25-dsr_rk3588s_20260603_rk3588_fp16.rknn` | 8.8MB | 256×256 | FP16 | 0.25 | 早期验证 |
+
+**转换工具**：[ArcFoundry](https://github.com/PotterWhite/ArcFoundry.git) v0.15.0
 - 配置目录：`ArcFoundry.git/configs/rvm/`
-- 目标平台：RK3588
+- 目标平台：RK3588 / RK3588S
 - 归一化：`mean=[0,0,0], std=[255,255,255]`（RKNN 运行时执行 `/255.0`）
 
 ### 2.3 质量总结
 
-| 模型 | dsr | 与 PyTorch 的 mean_diff | bg_ratio | 速度（推理+合成） | 备注 |
-|------|-----|------------------------|----------|------------------|------|
-| 1080p FP16 (s14) | 0.25 | 2.30 | 86.6% | ~485ms | NCHW→NHWC 转置修复 |
-| 1080p FP16 (s20) | 0.25 | 2.30 | 86.6% | ~485ms | r2o stride padding: OK |
-| 1080p FP16 (s21) | 0.5 | **2.18** | **86.5%** | ~691ms | **最佳质量** |
+> 当前批次（`rk3588s_20260603`）的板端 benchmark 正在收集中。
+> 旧的 s14/s20/s21 数据对应的是已下线的 `rk3588` 批次，不再适用。
+
+通用预期（基于已知的 RVM 行为规律）：
+
+- **dsr 越大，质量越好、速度越慢**（decoder 工作在 `H×dsr × W×dsr` 分辨率上）
+- **处理分辨率越大，alpha 边缘越锐利**，但 NPU 推理时间近似线性增长
+- 1080p 输入 + `dsr=0.25` 是速度最优档（decoder 工作在 270×480）
+- 1080p 输入 + `dsr=0.5` 是质量最优档（decoder 工作在 540×960）—— 当前批次未提供该组合
 
-- PyTorch 基线 bg_ratio：86.6%（dsr=0.25）、86.5%（dsr=0.5）
-- 所有模型在 `dance.mp4` 上测试（363 帧，1920×1080）
-- 板端：RK3588S，NPU0=40%，NPU1&2=10%
+> 详细 benchmark 数据待补。
 
 ### 2.4 推荐模型选择
 
+> 待补。当前批次（`rk3588s_20260603`）的 benchmark 数据收集中。
+> 一般规则：质量优先选 `dsr=0.5` 中最大处理分辨率（候选：544×960 / 736×1280），
+> 速度优先选 `1080×1920 / dsr=0.25`，低内存选 `256×256 / dsr=0.25`。
+> 选定后填入下表。
+
 | 使用场景 | 推荐模型 | 理由 |
 |----------|---------|------|
-| **质量优先** | `rvm_mobilenetv3_fp16_1080x1920_0.5-dsr_rk3588_fp16.rknn` | mean_diff=2.18，最佳 alpha 边缘 |
-| **速度优先** | `rvm_mobilenetv3_fp16_1080x1920_rk3588_fp16.rknn` | 比 dsr=0.5 快 1.43 倍 |
-| **低内存** | `rvm_mobilenetv3_fp16_288x512_rk3588_fp16_v20260416.rknn` | 最小 r-state 占用 |
+| **质量优先** | _（待补）_ | _（待补）_ |
+| **速度优先** | _（待补）_ | _（待补）_ |
+| **低内存** | _（待补）_ | _（待补）_ |
 
 ### 2.5 Graph Surgery：移除最终的 Resize 及以后的算子
 
-> 最终调试版 RKNN 模型（文件名包含 `no-resize`）通过 ArcFoundry `graph_surgery`
-> 把原始 RVM ONNX 中 refiner 末尾的 2 个 Resize + 后续 element-wise 链裁掉，
-> 由 C++ 后处理端自行完成 guided-filter 组合 + 上采样。
->
-> 详情见 `primary-folder/log/log-MR2-P5-s5_8_22-bottleneck-investigation.md`
-> 的 §s5_8_22_12（独立脚本版）和 §s5_8_22_14（ArcFoundry 集成版）；
-> 算子实测对比结果（脚本 + 输出）已嵌入该 PKB 的 §s5_8_22_12 / `### After - 执行` /
-> `2026-07-03 算子数对比验证` 章节。
+> **本仓库全部 RKNN 模型都已应用此 graph surgery**（见 §2.2 表前的说明）。
+> 原始 RVM ONNX 的 refiner 末尾含 2 个 `Resize` + 后续 element-wise 链（Mul、Add、
+> Split、Clip 等），通过 ArcFoundry 的 `graph_surgery` 步骤把这些节点从 NPU 图中
+> 移除，由 C++ 后处理端自行完成 guided-filter 组合 + 上采样。
 
 #### 裁剪点
 
@@ -456,7 +389,7 @@ python3 tools/MODNet/verify_golden_tensor.py
 | **图清理后净减少的节点（实测）** | **36 个**（353 → 317） |
 | 裁剪版图输出 tensor | `777`（Conv_316 输出，refiner A，4ch，272×480）、`779`（Sub_318 输出，refiner b，4ch，272×480），外加 `r1o~r4o` |
 
-#### 实测算子分类对比（脚本与实测：见 PKB §s5_8_22_12 / `2026-07-03 算子数对比验证` 章节）
+#### 实测算子分类对比
 
 | op_type | 原版 | 裁剪版 | Δ（原版 − 裁剪版） |
 |---------|----:|-----:|------------------:|
@@ -472,8 +405,7 @@ python3 tools/MODNet/verify_golden_tensor.py
 | Split    | 10  |  9   |  +1 |
 | **合计** |    |     | **+36** |
 
-> 上表只列出发生变化的 `op_type`（未变的不列出）。所有数值由 PKB §s5_8_22_12
-> `2026-07-03 算子数对比验证` 章节中嵌入的脚本在 2026-07-03 实测得出，无估算。
+> 上表只列出发生变化的 `op_type`（未变的不列出）。
 
 **为什么 `Constant` 减少了 16 个？** 因为 `graph.cleanup()` 会同时清理那些原本只为
 被删节点提供常量输入的 Constant 节点；而 `Shape`/`Slice`/`Concat` 的减少则来自
@@ -487,13 +419,13 @@ A(4ch,272×480) + b(4ch,272×480) 是 C++ 后处理 guided-filter 组合的输
 
 ## 3. 相关文档
 
-- **训练脚本**：`helmsman.git/third-party/scripts/modnet/train_modnet_block1_2.py`
-- **ONNX 导出脚本**：`helmsman.git/third-party/scripts/modnet/onnx/export_onnx_pureBN.py`
-- **C++ 推理**：`helmsman.git/runtime/cpp/apps/matting/client/`
-- **Python 黄金参考**：`helmsman.git/third-party/scripts/modnet/onnx/generate_golden_files.py`
-- **验证工具**：`helmsman.git/tools/MODNet/verify_golden_tensor.py`
-- **RVM 瓶颈 PKB（含算子对比脚本 + 实测结果）**：`primary-folder/log/log-MR2-P5-s5_8_22-bottleneck-investigation.md`
-- **RVM ArcFoundry 配置**：`ArcFoundry.git/configs/rvm/`
+本仓库**仅托管模型制品**（ckpt / onnx / rknn 文件），不包含训练代码和 C++ 推理代码。
+
+- 训练流程、ONNX 导出、C++ 推理、RKNN 转换等代码均在配套的私有仓库中维护
+- 公开可见的模型来源：
+  - MODNet：作者 Google Drive（ZHKKKe/MODNet）
+  - RVM：[PeterL1n/RobustVideoMatting](https://github.com/PeterL1n/RobustVideoMatting) v1.0.0
+- RKNN 转换 pipeline：[ArcFoundry](https://github.com/PotterWhite/ArcFoundry.git)（配置文件位于其 `configs/rvm/`）
 
 ---
 
@@ -519,6 +451,6 @@ Overfitting: ✓ No significant degradation, clean convergence
 
 ---
 
-**文档版本**：1.3
+**文档版本**：1.4
 **最后更新**：2026-07-03 by PotterWhite
 **提交历史**：通过 Git commit message 追踪