docs: 补充完整的 ONNX 调用教程(预处理规范、批量推理、阈值调法与常见问题)
Browse files
README.md
CHANGED
|
@@ -20,16 +20,16 @@ datasets:
|
|
| 20 |
(像素差、dHash、QR 分解、Farnebäck 光流)的判定行为,可在 NVIDIA / AMD / Intel 显卡上
|
| 21 |
通过 DirectML 统一推理。
|
| 22 |
|
| 23 |
-
## 训练数据声明
|
| 24 |
-
|
| 25 |
-
本模型在训练过程中**未分发、未再发布任何原始视频、音频或视频帧**。训练仅使用从公开网络获取的视频中抽取的灰度切片,且全部监督信号由 Easy4K 自研的 SFDP 四阶判重判决器(像素差 / dHash / QR 码 / Farnebäck 光流)自动生成,不含人工标注。
|
| 26 |
-
|
| 27 |
-
视频著作权归原作者所有。所用素材清单见 `training-materials.txt`(含标题、BV 号、UP 主、原始链接),仅用于说明数据来源,不构成对原作品的授权或再分发。
|
| 28 |
-
|
| 29 |
-
若权利人认为其作品不应被用于本研究,请提交 issue,我们将在 72 小时内从清单中移除,并在后续版本训练中排除该来源。
|
| 30 |
-
|
| 31 |
-
模型权重以 **CC BY-NC 4.0** 发布,仅限研究与非商业用途。模型输出为 0~1 的相似度分数,不具备生成、重建或复现原视频内容的能力。
|
| 32 |
-
|
| 33 |
## 模型详情
|
| 34 |
|
| 35 |
| 项目 | 说明 |
|
|
@@ -49,27 +49,105 @@ datasets:
|
|
| 49 |
|
| 50 |
## 快速开始
|
| 51 |
|
|
|
|
|
|
|
| 52 |
```bash
|
| 53 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 54 |
```
|
| 55 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 56 |
```python
|
| 57 |
import numpy as np
|
| 58 |
import onnxruntime as ort
|
| 59 |
|
| 60 |
-
|
| 61 |
-
|
| 62 |
-
|
| 63 |
-
)
|
| 64 |
|
| 65 |
-
|
|
|
|
| 66 |
b = a.copy()
|
| 67 |
|
| 68 |
-
score = sess.run(["score"], {"frame_a": a, "frame_b": b})[0][0, 0]
|
| 69 |
-
print(
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 70 |
```
|
| 71 |
|
| 72 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 73 |
|
| 74 |
## 使用场景
|
| 75 |
|
|
@@ -123,60 +201,60 @@ print(float(score)) # 1.0 表示两帧重复
|
|
| 123 |
| Epoch | 8 |
|
| 124 |
| 硬件 | NVIDIA P106-100(6 GB),CUDA 12.4,PyTorch 2.6.0 |
|
| 125 |
|
| 126 |
-
## 完整实现代码
|
| 127 |
-
|
| 128 |
-
模型训练、导出与数据来源记录的全部实现代码随仓库提供,位于 [`code/`](./code):
|
| 129 |
-
|
| 130 |
-
| 文件 | 作用 |
|
| 131 |
-
|---|---|
|
| 132 |
-
| `code/siai_all.py` | 一体化流水线:视频切片(`tiles`)、教师打标(`teacher`)、软标签生成(`label`)、训练(`train`)、评测(`eval`)、ONNX 导出(`pack`) |
|
| 133 |
-
| `code/append_sources.py` | 训练素材清单的生成与去重追加,产出可溯源的 `training-materials.txt` |
|
| 134 |
-
| `code/algorithm/FrameDedupService.cs` | 四阶判决器教师本体:像素差粗筛 → dHash 细筛 → QR 分解精判 → Farnebäck 光流终判,含全部阈值与标定注释 |
|
| 135 |
-
| `code/algorithm/FarnebackFlow.cs` | 第四阶使用的稠密光流实现(GPU/CPU 混合路径) |
|
| 136 |
-
| `code/algorithm/Easy4K.SFDP.csproj` | 上述两个源文件的编译工程(.NET 10,Windows.Graphics.Imaging) |
|
| 137 |
-
|
| 138 |
-
### 教师算法(四阶判决器)
|
| 139 |
-
|
| 140 |
-
| 阶段 | 方法 | 作用 |
|
| 141 |
-
|---|---|---|
|
| 142 |
-
| 1 | 像素绝对差均值(MAD) | 粗筛,明显不同的帧对直接放过 |
|
| 143 |
-
| 2 | dHash 汉明距离 | 细筛,感知哈希不一致的帧对放过 |
|
| 144 |
-
| 3 | 8×8 分块 QR 分解,取 diag(R) 特征算 Minkowski 距离 | 精判,抑制亮度/压缩噪声造成的误判 |
|
| 145 |
-
| 4 | Farnebäck 稠密光流,统计均值与方差 | 终判,区分“真重复帧”与“相似但不相同”的运动画面 |
|
| 146 |
-
|
| 147 |
-
阈值取论文建议值并对 1080p 动画 MV 重新标定(`τ_flow=0.5`、`τ_var=0.1`、QR 阈值 1.0 灰阶),标定过程与分布数据写在源码注释里。
|
| 148 |
-
|
| 149 |
-
### ONNX 模型
|
| 150 |
-
|
| 151 |
-
| 文件 | 精度 | 体积 | 建议用途 |
|
| 152 |
-
|---|---|---|---|
|
| 153 |
-
| `model.onnx` | FP32 | 9.95 MB | 完美模式(精度优先) |
|
| 154 |
-
| `model_fp16.onnx` | FP16(IO 保持 float32) | 5.01 MB | 性能模式(速度优先,DirectML 下约快 1.5~2 倍) |
|
| 155 |
-
|
| 156 |
-
两份模型输入输出签名完全一致:`frame_a`、`frame_b` → `score`,调用方按模式切换文件名即可。
|
| 157 |
-
|
| 158 |
-
主要命令:
|
| 159 |
-
|
| 160 |
-
```bash
|
| 161 |
-
# 1) 从视频抽取灰度切片
|
| 162 |
-
python code/siai_all.py tiles --raw <视频目录> --segments 4 --out <切片目录>
|
| 163 |
-
|
| 164 |
-
# 2) 用四阶判决器教师生成逐片段标签 CSV
|
| 165 |
-
python code/siai_all.py teacher --tiles <切片目录> --labels <标签目录>
|
| 166 |
-
|
| 167 |
-
# 3) 生成软标签训练集与验证集
|
| 168 |
-
python code/siai_all.py label
|
| 169 |
-
|
| 170 |
-
# 4) 训练(结束后自动导出 FP32 与 FP16 两份 ONNX)
|
| 171 |
-
python code/siai_all.py train --out <输出目录> --epochs 1 --workers 8 --lr 1e-4
|
| 172 |
-
|
| 173 |
-
# 5) 评测 / 打包
|
| 174 |
-
python code/siai_all.py eval --out <输出目录>
|
| 175 |
-
python code/siai_all.py pack --onnx <输出目录>/easy4k_sfdp_siamese_fp32.onnx --out <发布目录>
|
| 176 |
-
```
|
| 177 |
-
|
| 178 |
-
依赖见 `requirements.txt`(PyTorch、OpenCV、onnx、onnxruntime、onnxconverter-common)。教师端二进制 `SfdpTeacher` 属于 Easy4K 应用程序的一部分,不随本仓库分发。
|
| 179 |
-
|
| 180 |
## 评测结果
|
| 181 |
|
| 182 |
### 与教师的一致性(验证集 78147 样本,按视频隔离)
|
|
|
|
| 20 |
(像素差、dHash、QR 分解、Farnebäck 光流)的判定行为,可在 NVIDIA / AMD / Intel 显卡上
|
| 21 |
通过 DirectML 统一推理。
|
| 22 |
|
| 23 |
+
## 训练数据声明
|
| 24 |
+
|
| 25 |
+
本模型在训练过程中**未分发、未再发布任何原始视频、音频或视频帧**。训练仅使用从公开网络获取的视频中抽取的灰度切片,且全部监督信号由 Easy4K 自研的 SFDP 四阶判重判决器(像素差 / dHash / QR 码 / Farnebäck 光流)自动生成,不含人工标注。
|
| 26 |
+
|
| 27 |
+
视频著作权归原作者所有。所用素材清单见 `training-materials.txt`(含标题、BV 号、UP 主、原始链接),仅用于说明数据来源,不构成对原作品的授权或再分发。
|
| 28 |
+
|
| 29 |
+
若权利人认为其作品不应被用于本研究,请提交 issue,我们将在 72 小时内从清单中移除,并在后续版本训练中排除该来源。
|
| 30 |
+
|
| 31 |
+
模型权重以 **CC BY-NC 4.0** 发布,仅限研究与非商业用途。模型输出为 0~1 的相似度分数,不具备生成、重建或复现原视频内容的能力。
|
| 32 |
+
|
| 33 |
## 模型详情
|
| 34 |
|
| 35 |
| 项目 | 说明 |
|
|
|
|
| 49 |
|
| 50 |
## 快速开始
|
| 51 |
|
| 52 |
+
### 1. 安装依赖
|
| 53 |
+
|
| 54 |
```bash
|
| 55 |
+
# Windows(NVIDIA / AMD / Intel 统一走 DirectML)
|
| 56 |
+
pip install onnxruntime-directml numpy opencv-python
|
| 57 |
+
|
| 58 |
+
# Linux / macOS(纯 CPU)
|
| 59 |
+
pip install onnxruntime numpy opencv-python
|
| 60 |
```
|
| 61 |
|
| 62 |
+
### 2. 选择模型文件
|
| 63 |
+
|
| 64 |
+
| 场景 | 文件 | 阈值建议 |
|
| 65 |
+
|---|---|---|
|
| 66 |
+
| 精度优先(对应 Easy4K 完美模式) | `model.onnx`(FP32,9.95 MB) | 0.5 |
|
| 67 |
+
| 速度优先(对应 Easy4K 性能模式) | `model_fp16.onnx`(FP16,5.01 MB) | 0.55~0.6 |
|
| 68 |
+
|
| 69 |
+
两份模型的输入输出签名完全一致,切换只需换文件名。FP16 版本内部半精度、**输入输出仍是 float32**,调用代码不用改。
|
| 70 |
+
|
| 71 |
+
### 3. 最小可运行示例
|
| 72 |
+
|
| 73 |
```python
|
| 74 |
import numpy as np
|
| 75 |
import onnxruntime as ort
|
| 76 |
|
| 77 |
+
providers = [p for p in ("DmlExecutionProvider", "CPUExecutionProvider")
|
| 78 |
+
if p in ort.get_available_providers()]
|
| 79 |
+
sess = ort.InferenceSession("model.onnx", providers=providers)
|
|
|
|
| 80 |
|
| 81 |
+
# 同位置的两块灰度图,[0,1],NCHW
|
| 82 |
+
a = np.random.rand(1, 1, 128, 128).astype(np.float32)
|
| 83 |
b = a.copy()
|
| 84 |
|
| 85 |
+
score = float(sess.run(["score"], {"frame_a": a, "frame_b": b})[0][0, 0])
|
| 86 |
+
print(score) # 越接近 1 越可能是重复帧
|
| 87 |
+
print(score >= 0.5) # 判重结果
|
| 88 |
+
```
|
| 89 |
+
|
| 90 |
+
### 4. 从视频帧取块(预处理规范)
|
| 91 |
+
|
| 92 |
+
预处理必须与训练时一致,否则分数不可信:
|
| 93 |
+
|
| 94 |
+
1. 解码后先转**灰度**
|
| 95 |
+
2. 在**原分辨率**下裁剪出 128×128 的块(不要先缩放整帧再裁)
|
| 96 |
+
3. 归一化到 `[0, 1]`,`float32`
|
| 97 |
+
4. 排列为 `NCHW`,单样本即 `(1, 1, 128, 128)`
|
| 98 |
+
5. 两个输入块必须是**同一坐标位置**
|
| 99 |
+
|
| 100 |
+
```python
|
| 101 |
+
import cv2
|
| 102 |
+
import numpy as np
|
| 103 |
+
|
| 104 |
+
def patch(gray, x, y, size=128):
|
| 105 |
+
p = gray[y:y + size, x:x + size]
|
| 106 |
+
if p.shape[:2] != (size, size):
|
| 107 |
+
return None
|
| 108 |
+
return (p.astype(np.float32) / 255.0)[None, None, :, :]
|
| 109 |
+
|
| 110 |
+
cap = cv2.VideoCapture("input.mp4")
|
| 111 |
+
ok, f1 = cap.read()
|
| 112 |
+
ok2, f2 = cap.read()
|
| 113 |
+
g1 = cv2.cvtColor(f1, cv2.COLOR_BGR2GRAY)
|
| 114 |
+
g2 = cv2.cvtColor(f2, cv2.COLOR_BGR2GRAY)
|
| 115 |
+
|
| 116 |
+
a, b = patch(g1, 320, 180), patch(g2, 320, 180)
|
| 117 |
+
if a is not None and b is not None:
|
| 118 |
+
s = float(sess.run(["score"], {"frame_a": a, "frame_b": b})[0][0, 0])
|
| 119 |
+
print("duplicate" if s >= 0.5 else "different", s)
|
| 120 |
```
|
| 121 |
|
| 122 |
+
### 5. 批量推理
|
| 123 |
+
|
| 124 |
+
`batch` 维度是动态的,一次送入多个帧对可显著提高吞吐(DirectML 下比逐对调用快 2~4 倍):
|
| 125 |
+
|
| 126 |
+
```python
|
| 127 |
+
pairs_a = np.concatenate([a] * 32, axis=0) # (32, 1, 128, 128)
|
| 128 |
+
pairs_b = np.concatenate([b] * 32, axis=0)
|
| 129 |
+
scores = sess.run(["score"], {"frame_a": pairs_a, "frame_b": pairs_b})[0].ravel() # (32,)
|
| 130 |
+
```
|
| 131 |
+
|
| 132 |
+
### 6. 阈值调法
|
| 133 |
+
|
| 134 |
+
| 阈值 | 效果 |
|
| 135 |
+
|---|---|
|
| 136 |
+
| 0.5 | 默认,偏召回,适合“宁可多判不放过” |
|
| 137 |
+
| 0.6~0.7 | 偏精确,适合画面干净、误判代价高的场景 |
|
| 138 |
+
|
| 139 |
+
判断依据:若实际使用中**误删真正不同的帧**(漏检画面),就调高;若**放过重复帧**,就调低。
|
| 140 |
+
|
| 141 |
+
### 7. 常见问题
|
| 142 |
+
|
| 143 |
+
| 现象 | 原因与处理 |
|
| 144 |
+
|---|---|
|
| 145 |
+
| `DmlExecutionProvider` 不可用 | 未装 `onnxruntime-directml`,或系统缺少 DirectX 12;会自动回退 CPU,不影响结果 |
|
| 146 |
+
| 报输入维度错误 | 必须是 `(N, 1, 128, 128)`、`float32`;FP16 模型也接收 float32 输入 |
|
| 147 |
+
| 分数恒为 0 或恒为 1 | 检查是否忘了 `/255`、是否用了彩色三通道、是否两块取自不同位置 |
|
| 148 |
+
| 结果和 Easy4K 不一致 | 预处理路径不同(先缩放 vs 先裁剪)、阈值不同,或用了 FP16 版本 |
|
| 149 |
+
|
| 150 |
+
完整可运行示例见 `example_infer.py`。
|
| 151 |
|
| 152 |
## 使用场景
|
| 153 |
|
|
|
|
| 201 |
| Epoch | 8 |
|
| 202 |
| 硬件 | NVIDIA P106-100(6 GB),CUDA 12.4,PyTorch 2.6.0 |
|
| 203 |
|
| 204 |
+
## 完整实现代码
|
| 205 |
+
|
| 206 |
+
模型训练、导出与数据来源记录的全部实现代码随仓库提供,位于 [`code/`](./code):
|
| 207 |
+
|
| 208 |
+
| 文件 | 作用 |
|
| 209 |
+
|---|---|
|
| 210 |
+
| `code/siai_all.py` | 一体化流水线:视频切片(`tiles`)、教师打标(`teacher`)、软标签生成(`label`)、训练(`train`)、评测(`eval`)、ONNX 导出(`pack`) |
|
| 211 |
+
| `code/append_sources.py` | 训练素材清单的生成与去重追加,产出可溯源的 `training-materials.txt` |
|
| 212 |
+
| `code/algorithm/FrameDedupService.cs` | 四阶判决器教师本体:像素差粗筛 → dHash 细筛 → QR 分解精判 → Farnebäck 光流终判,含全部阈值与标定注释 |
|
| 213 |
+
| `code/algorithm/FarnebackFlow.cs` | 第四阶使用的稠密光流实现(GPU/CPU 混合路径) |
|
| 214 |
+
| `code/algorithm/Easy4K.SFDP.csproj` | 上述两个源文件的编译工程(.NET 10,Windows.Graphics.Imaging) |
|
| 215 |
+
|
| 216 |
+
### 教师算法(四阶判决器)
|
| 217 |
+
|
| 218 |
+
| 阶段 | 方法 | 作用 |
|
| 219 |
+
|---|---|---|
|
| 220 |
+
| 1 | 像素绝对差均值(MAD) | 粗筛,明显不同的帧对直接放过 |
|
| 221 |
+
| 2 | dHash 汉明距离 | 细筛,感知哈希不一致的帧对放过 |
|
| 222 |
+
| 3 | 8×8 分块 QR 分解,取 diag(R) 特征算 Minkowski 距离 | 精判,抑制亮度/压缩噪声造成的误判 |
|
| 223 |
+
| 4 | Farnebäck 稠密光流,统计均值与方差 | 终判,区分“真重复帧”与“相似但不相同”的运动画面 |
|
| 224 |
+
|
| 225 |
+
阈值取论文建议值并对 1080p 动画 MV 重新标定(`τ_flow=0.5`、`τ_var=0.1`、QR 阈值 1.0 灰阶),标定过程与分布数据写在源码注释里。
|
| 226 |
+
|
| 227 |
+
### ONNX 模型
|
| 228 |
+
|
| 229 |
+
| 文件 | 精度 | 体积 | 建议用途 |
|
| 230 |
+
|---|---|---|---|
|
| 231 |
+
| `model.onnx` | FP32 | 9.95 MB | 完美模式(精度优先) |
|
| 232 |
+
| `model_fp16.onnx` | FP16(IO 保持 float32) | 5.01 MB | 性能模式(速度优先,DirectML 下约快 1.5~2 倍) |
|
| 233 |
+
|
| 234 |
+
两份模型输入输出签名完全一致:`frame_a`、`frame_b` → `score`,调用方按模式切换文件名即可。
|
| 235 |
+
|
| 236 |
+
主要命令:
|
| 237 |
+
|
| 238 |
+
```bash
|
| 239 |
+
# 1) 从视频抽取灰度切片
|
| 240 |
+
python code/siai_all.py tiles --raw <视频目录> --segments 4 --out <切片目录>
|
| 241 |
+
|
| 242 |
+
# 2) 用四阶判决器教师生成逐片段标签 CSV
|
| 243 |
+
python code/siai_all.py teacher --tiles <切片目录> --labels <标签目录>
|
| 244 |
+
|
| 245 |
+
# 3) 生成软标签训练集与验证集
|
| 246 |
+
python code/siai_all.py label
|
| 247 |
+
|
| 248 |
+
# 4) 训练(结束后自动导出 FP32 与 FP16 两份 ONNX)
|
| 249 |
+
python code/siai_all.py train --out <输出目录> --epochs 1 --workers 8 --lr 1e-4
|
| 250 |
+
|
| 251 |
+
# 5) 评测 / 打包
|
| 252 |
+
python code/siai_all.py eval --out <输出目录>
|
| 253 |
+
python code/siai_all.py pack --onnx <输出目录>/easy4k_sfdp_siamese_fp32.onnx --out <发布目录>
|
| 254 |
+
```
|
| 255 |
+
|
| 256 |
+
依赖见 `requirements.txt`(PyTorch、OpenCV、onnx、onnxruntime、onnxconverter-common)。教师端二进制 `SfdpTeacher` 属于 Easy4K 应用程序的一部分,不随本仓库分发。
|
| 257 |
+
|
| 258 |
## 评测结果
|
| 259 |
|
| 260 |
### 与教师的一致性(验证集 78147 样本,按视频隔离)
|