YAML Metadata Warning:empty or missing yaml metadata in repo card

Check out the documentation for more information.

MODNet 与 RVM 模型制品仓库 (Model Artifact Registry)

用途：集中托管 MODNet 与 RVM 的模型制品（ckpt / onnx / rknn 文件本身） 不包含：训练代码与 C++ 推理代码——这些在配套的私有仓库中维护

维护者：PotterWhite 最后更新：2026-07-03 许可证（License）：MIT

1. MODNet 模型

1.1 官方预训练模型

摄影人像抠图（Photographic Portrait Matting）

文件：photographic/modnet_photographic_portrait_matting.ckpt

原始 MODNet 检查点，在人像抠图数据集上训练
- 来源：作者 Google Drive（ZHKKKe/MODNet）
- 格式：PyTorch .ckpt（state_dict）
- 架构：MODNet + IBNorm + InstanceNormalization
- 输入尺寸：512×512
- 用途：微调实验的基线参考
- 状态：✓ 生产基线

摄像头人像抠图（Webcam Portrait Matting）

文件：modnet_webcam_portrait_matting.ckpt

针对摄像头实时抠图优化的 MODNet 检查点
- 来源：作者 Google Drive
- 格式：PyTorch .ckpt（state_dict）
- 架构：MODNet + IBNorm + InstanceNormalization
- 输入尺寸：384×384（更低延迟）
- 用途：实时视频/直播场景
- 状态：✓ 可用，当前管线未使用

MobileNetV2 人体分割（Human Segmentation）

文件：mobilenetv2_human_seg.ckpt

辅助分割模型，用于预处理阶段
- 来源：作者 Google Drive
- 格式：PyTorch .ckpt
- 用途：可选预处理阶段（当前未部署）
- 状态：✓ 可用作参考

1.2 微调模型 — 摄影数据集

纯批归一化变体（Pure Batch Normalization Variant）

训练轮次：Block 1.2 微调（2026-03-19 ~ 2026-03-19）

概要

在 P3M-10k 摄影数据集上微调 MODNet-BN
- 将所有 IBNorm + InstanceNormalization 替换为纯 BatchNorm2d
- 15 个 Epoch 的监督训练，含学习率调度（Learning Rate Schedule）
- 最佳模型：验证集 L1 Loss 0.0062

训练配置

参数	值
数据集（Dataset）	P3M-10k（Photographic 子集）
训练样本数	9,421
验证样本数	500
批大小（Batch Size）	8
轮次（Epochs）	15
初始学习率（Learning Rate）	0.01
学习率调度	StepLR：γ=0.1 @ epoch 5, 10
输入尺寸	512×512
优化器（Optimizer）	Adam (β₁=0.9, β₂=0.999)
损失函数（Loss Function）	L1（MAE），作用于 alpha 遮罩
设备（Device）	NVIDIA A100 (CUDA 11.8)
训练时长	~4 小时
时间戳	2026-03-19 15:40:18

生成的制品（Artifacts）

photographic/finetune/
├── checkpoints/
│   ├── modnet_bn_best.ckpt                    # ★ 最佳模型（Val L1: 0.0062）
│   ├── modnet_bn_epoch_01.ckpt
│   ├── modnet_bn_epoch_02.ckpt
│   ├── ...（epoch 3-14 省略）
│   └── modnet_bn_epoch_15.ckpt
├── logs/
│   └── block1_2_training_20260319_154018.log  # 训练日志（详细）
├── onnx/
│   └── modnet_bn_best_pureBN.onnx             # ★ ONNX 导出（见 §1.3.3）
└── output/
    ├── epoch_01_val.png                       # 验证预览（第 1 轮）
    ├── epoch_02_val.png
    ├── ...（epoch 3-14 省略）
    └── epoch_15_val.png                       # 最终验证可视化

验证损失曲线（Validation Loss Curve）

Epoch | Val L1 Loss | 改进幅度
------|-------------|-------------------
  1   | 0.0264      | Δ = -0.0202（新最佳）
  2   | 0.0175      | Δ = -0.0089（新最佳）
  3   | 0.0121      | Δ = -0.0054（新最佳）
  4   | 0.0098      | Δ = -0.0023（新最佳）
  5   | 0.0089      | Δ = -0.0009（新最佳）
  6   | 0.0081      | Δ = -0.0008（新最佳）
  7   | 0.0076      | Δ = -0.0005（新最佳）
  8   | 0.0074      | Δ = -0.0002（新最佳）
  9   | 0.0072      | Δ = -0.0002（新最佳）
  10  | 0.0070      | Δ = -0.0002（新最佳）
  11  | 0.0068      | Δ = -0.0002（新最佳）
  12  | 0.0066      | Δ = -0.0002（新最佳）
  13  | 0.0065      | Δ = -0.0001（新最佳）
  14  | 0.0063      | Δ = -0.0002（新最佳）
  15  | 0.0062      | Δ = -0.0001（最终）

→ 第 5 轮后收敛（学习率调度生效），持续稳步改进

使用方法

# PyTorch 推理
import torch
from modnet import MODNet

checkpoint = torch.load('photographic/finetune/checkpoints/modnet_bn_best.ckpt')
model = MODNet()
model.load_state_dict(checkpoint)
model.eval()

# 或使用 ONNX 推理（推荐用于部署）
import onnxruntime
sess = onnxruntime.InferenceSession('photographic/finetune/onnx/modnet_bn_best_pureBN.onnx')

1.3 ONNX 模型变体

官方原始版本（Photographic）

文件：photographic/modnet_photographic_portrait_matting.onnx

从官方检查点直接导出的 ONNX
- 来源：作者 Google Drive
- 格式：ONNX opset 11
- 包含：InstanceNormalization 算子
- 输入：[1, 3, 512, 512]（float32，[-1, 1] 归一化）
- 输出：[1, 1, 512, 512]（float32，[0, 1] 范围）
- 状态：✓ 对比参考
- 注意：InstanceNormalization 在 NPU 上会回退到 CPU，**不推荐用于边缘部署**

折叠变体（Folded Variant，Anti-fusion）

文件：photographic/modnet_photographic_portrait_matting_in_folded.onnx

通过 anti-fusion 方法展开 InstanceNormalization
- 优化者：PotterWhite (potter_white@outlook.com)
- 日期：2026-03-11 16:11
- 方法：将 InstanceNorm 展开为算术原语
  - Var(x) = E[x²] − (E[x])²
  - 防止 RKNN 编译器重新识别 InstanceNormalization
  - 强制在 CPU 上执行（负面效果）
- 状态：⚠️ 实验性，不推荐
- 分析：违背了优化初衷

纯批归一化版本（ONNX 导出）

文件：photographic/finetune/onnx/modnet_bn_best_pureBN.onnx

从 modnet_bn_best.ckpt（微调模型）导出的 ONNX
- 来源：PyTorch 微调训练（第 15 轮）
- 导出日期：2026-03-31 16:15
- 格式：ONNX opset 11
- 架构：纯 BatchNormalization（无 InstanceNorm）
- 输入：[1, 3, 512, 512]（float32，[-1, 1] 归一化）
- 输出：[1, 1, 512, 512]（float32，[0, 1] 范围）
- 文件大小：25 MB
- 状态：⚠️ 参考用。纯 BN 变体在当前量化/部署路径上仍有数值问题，
        **生产部署请用 §1.3.1 官方原版（带 InstanceNorm）**。

技术说明（仅供对比研究）：
  - 无 InstanceNormalization → 理论上是 NPU 友好
  - 全部算子：Conv2d, BatchNorm2d, ReLU 等（硬件友好）
  - 但实测在某些量化路径上数值偏移较大，需进一步调试

已测试环境：
  - ONNX Runtime 1.16.3（CPU, x86_64）
  - ONNX Runtime 1.16.3（aarch64, 模拟环境）
  - RKNN 工具链 v2.3.2（编译阶段验证）

验证结果（对比参考）

黄金测试向量（Golden Test Vector）：green-fall-girl-point-to.png (1803×1019)
- Python 推理输出：py_08_inference-Output.bin ✓
- C++ 推理输出：cpp_08_inference-Output.bin（待 C++ 构建）
- 预期匹配：像素级 L∞ 误差 < 1e-5（float32 精度）

1.4 目录结构

MODNet/
│
├── README.md                                    ← 当前文件
│
├── [官方模型 - 根目录]
│   ├── mobilenetv2_human_seg.ckpt               （备份，非活跃）
│   └── modnet_webcam_portrait_matting.ckpt      （参考用，384×384）
│
└── photographic/                                ← ★ 活跃部署变体
    │
    ├── README.md                                （历史文件，已被取代）
    │
    ├── [官方基线]
    │   ├── modnet_photographic_portrait_matting.ckpt      (1.8 GB)
    │   ├── modnet_photographic_portrait_matting.onnx      (26 MB, InstanceNorm)
    │   └── modnet_photographic_portrait_matting_in_folded.onnx  (26 MB, folded)
    │
    └── finetune/                                ← ★ 活跃训练输出
        │
        ├── checkpoints/                         （PyTorch 制品）
        │   ├── modnet_bn_best.ckpt              ★ (1.8 GB, 最佳模型)
        │   ├── modnet_bn_epoch_01.ckpt
        │   ├── modnet_bn_epoch_02.ckpt
        │   ├── ... (epoch 3-14)
        │   └── modnet_bn_epoch_15.ckpt
        │
        ├── onnx/                                （部署用）
        │   └── modnet_bn_best_pureBN.onnx       ★ (25 MB, 推荐)
        │
        ├── logs/                                （元数据）
        │   └── block1_2_training_20260319_154018.log
        │
        └── output/                              （验证可视化）
            ├── epoch_01_val.png
            ├── epoch_02_val.png
            ├── ... (epoch 3-14)
            └── epoch_15_val.png

1.5 速查表

模型	文件	大小	用途	状态
官方摄影模型	`photographic/modnet_photographic_portrait_matting.ckpt`	1.8 GB	基线参考	✓ 参考
官方 ONNX	`photographic/modnet_photographic_portrait_matting.onnx`	26 MB	InstanceNorm 变体	⚠️ 不推荐
微调最佳模型	`photographic/finetune/checkpoints/modnet_bn_best.ckpt`	1.8 GB	PyTorch 部署	✓ 生产
微调 ONNX	`photographic/finetune/onnx/modnet_bn_best_pureBN.onnx`	25 MB	C++/RKNN 部署	★ 推荐
摄像头模型	`modnet_webcam_portrait_matting.ckpt`	1.8 GB	实时流媒体	✓ 可用

2. RVM 模型

2.1 ONNX 模型

位于 RobustVideoMatting/onnx/。

模型	文件	大小	骨干网络（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 友好）
6 个输入：src [1,3,H,W]、r1i~r4i（ConvGRU 状态）、downsample_ratio [1]
经 ArcFoundry fold_constant_inputs 处理后：5 个输入（downsample_ratio 烘焙为常量）

2.2 RKNN 模型

位于 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 v0.15.0

配置目录：ArcFoundry.git/configs/rvm/
目标平台：RK3588 / RK3588S
归一化：mean=[0,0,0], std=[255,255,255]（RKNN 运行时执行 /255.0）

2.3 质量总结

当前批次（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）—— 当前批次未提供该组合

详细 benchmark 数据待补。

2.4 推荐模型选择

待补。当前批次（rk3588s_20260603）的 benchmark 数据收集中。一般规则：质量优先选 dsr=0.5 中最大处理分辨率（候选：544×960 / 736×1280），速度优先选 1080×1920 / dsr=0.25，低内存选 256×256 / dsr=0.25。选定后填入下表。

使用场景	推荐模型	理由
质量优先	（待补）	（待补）
速度优先	（待补）	（待补）
低内存	（待补）	（待补）

2.5 Graph Surgery：移除最终的 Resize 及以后的算子

本仓库全部 RKNN 模型都已应用此 graph surgery（见 §2.2 表前的说明）。原始 RVM ONNX 的 refiner 末尾含 2 个 Resize + 后续 element-wise 链（Mul、Add、 Split、Clip 等），通过 ArcFoundry 的 graph_surgery 步骤把这些节点从 NPU 图中移除，由 C++ 后处理端自行完成 guided-filter 组合 + 上采样。

裁剪点

项目	数值
原始 ONNX 总节点数	353
被删除的"尾部"命名算子	2× Resize + Mul + Add + Split + Add + 2× Clip（共 8 个）
`graph.cleanup()` 级联删除的死节点	28 个
图清理后净减少的节点（实测）	36 个（353 → 317）
裁剪版图输出 tensor	`777`（Conv_316 输出，refiner A，4ch，272×480）、`779`（Sub_318 输出，refiner b，4ch，272×480），外加 `r1o~r4o`

实测算子分类对比

op_type	原版	裁剪版	Δ（原版 − 裁剪版）
Constant	48	32	+16
Shape	12	8	+4
Slice	12	8	+4
Concat	23	20	+3
Add	16	14	+2
Clip	2	0	+2
Resize	7	5	+2
Mul	47	46	+1
ReduceMean	2	1	+1
Split	10	9	+1
合计			+36

上表只列出发生变化的 op_type（未变的不列出）。

为什么 Constant 减少了 16 个？ 因为 graph.cleanup() 会同时清理那些原本只为被删节点提供常量输入的 Constant 节点；而 Shape/Slice/Concat 的减少则来自 refiner 内 Concat_311 上游、只为已删除 Resize 准备 shape/slice 信息的辅助节点。

为什么 Conv 一颗没少？ 裁剪只动 refiner 尾巴（ID 195-202 对应的算子）， refiner 内部产生 A/b 的 Conv 网络（Conv_312/314/316）被保留——它输出的 A(4ch,272×480) + b(4ch,272×480) 是 C++ 后处理 guided-filter 组合的输入。

3. 相关文档

本仓库仅托管模型制品（ckpt / onnx / rknn 文件），不包含训练代码和 C++ 推理代码。

训练流程、ONNX 导出、C++ 推理、RKNN 转换等代码均在配套的私有仓库中维护
公开可见的模型来源：
- MODNet：作者 Google Drive（ZHKKKe/MODNet）
- RVM：PeterL1n/RobustVideoMatting v1.0.0
RKNN 转换 pipeline：ArcFoundry（配置文件位于其 configs/rvm/）

附录：训练日志摘要

[Config] Device: cuda
[Config] Epochs: 15, BS: 8, LR: 0.01, Input: 512×512
[Dataset] Loaded 9421 samples (P3M-10k train)
[Model] Total parameters: 6,487,795
[Model] Trainable parameters: 6,487,795

Training Results (15 epochs):
  - Epoch  1: Avg Loss 0.5410 → Val L1 0.0264 (new best)
  - Epoch  2: Avg Loss 0.3054 → Val L1 0.0175 (new best)
  - Epoch  3: Avg Loss 0.2634 → Val L1 0.0121 (new best)
  - ...
  - Epoch 15: Avg Loss 0.1820 → Val L1 0.0062 (final)

Convergence: ✓ Steady improvement through all 15 epochs
Overfitting: ✓ No significant degradation, clean convergence

文档版本：1.4 最后更新：2026-07-03 by PotterWhite 提交历史：通过 Git commit message 追踪

Downloads last month: -; Downloads are not tracked for this model. How to track

Inference Providers NEW

This model isn't deployed by any Inference Provider. 🙋 Ask for provider support