Sudabaka commited on
Commit
5303c9b
·
verified ·
1 Parent(s): 16100c3

docs: 补充完整的 ONNX 调用教程(预处理规范、批量推理、阈值调法与常见问题)

Browse files
Files changed (1) hide show
  1. README.md +151 -73
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
- pip install onnxruntime-directml numpy
 
 
 
 
54
  ```
55
 
 
 
 
 
 
 
 
 
 
 
 
56
  ```python
57
  import numpy as np
58
  import onnxruntime as ort
59
 
60
- sess = ort.InferenceSession(
61
- "model.onnx",
62
- providers=["DmlExecutionProvider", "CPUExecutionProvider"],
63
- )
64
 
65
- a = np.random.rand(1, 1, 128, 128).astype(np.float32) # 灰度值 / 255
 
66
  b = a.copy()
67
 
68
- score = sess.run(["score"], {"frame_a": a, "frame_b": b})[0][0, 0]
69
- print(float(score)) # 1.0 表示两帧重复
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
70
  ```
71
 
72
- 完整的预处理与调用示例见仓库内 `example_infer.py`。
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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 样本,按视频隔离)