Speed Detect
基于 torchvision R3D-18 的 RGB 视频速度三分类器，输出 slow / normal / fast 分数。仓库包含推理、训练、resume、checkpoint 和一条合成示例视频。
该模型判断的是画面呈现出的运动速度，不是读取播放器倍速，也不输出精确的 0.5x / 2x 倍率。模型来源和限制见 MODEL_CARD.md。
仓库内容
3_speed_detect.py # 批量推理
3_speed_detect.sh # 推理入口
train_rgb_speed3.py # 训练/验证
train_rgb_speed3_resume.sh # 训练与resume入口
checkpoints/rgb_speed3_best.pt # best checkpoint
examples/videos/demo.mp4 # 3秒合成视频
examples/training/ # 单条训练/验证/hard-label示例
environment.yml # Conda环境
1. 环境
推荐 Linux、Python 3.10 和 NVIDIA GPU：
cd /mnt/workspace/speed_detect
conda env create -f environment.yml
conda activate speed_detect
锁定版本为 PyTorch 2.4.0、torchvision 0.19.0、CUDA 12.1、NumPy 1.26.0、OpenCV headless 4.11.0.86 和 tqdm 4.67.1。CPU 环境请按 PyTorch 官方安装矩阵将 PyTorch 安装源改为 CPU。
2. 推理
仓库自带一条 smoke-test metadata 和视频：
conda activate speed_detect
sha256sum -c checkpoints/SHA256SUMS
source 3_speed_detect.sh
cat outputs/metadata_speed_detect.jsonl
输出会在原记录中增加：
{"speed_scores":{"slow":0.1,"normal":0.7,"fast":0.2}}
处理真实数据时修改 3_speed_detect.sh：
INPUT_METADATA_JSONL="/data/videos/metadata.jsonl"
SPEED_METADATA_JSONL="/data/videos/metadata_speed_detect.jsonl"
OUTPUT_ROOT="/data/videos"
MODEL_CKPT="checkpoints/rgb_speed3_best.pt"
输入 JSONL 最小格式：
{"name":"clip_0001","video_path":"videos/clip_0001.mp4"}
相对 video_path 以 OUTPUT_ROOT 为根。已有 speed_scores 默认跳过；设 FORCE="1" 可重算。失败记录保存在 ${OUTPUT_ROOT}/speed_detect_logs/。
3. 训练
默认训练入口只使用同一个合成视频生成 4 个训练 clip 和 1 个验证 clip，用来检查 decode、forward、backward、optimizer step、评估和保存：
conda activate speed_detect
source train_rgb_speed3_resume.sh
cat outputs/training_smoke/train_log.csv
这是 pipeline smoke test，不是精度评测。首次运行会保存 best/last 两个 checkpoint，合计约 760 MiB；outputs/ 已被忽略。
正式训练时修改：
TRAIN_LIST="/data/speed_train/train.txt"
VAL_LIST="/data/speed_train/val.txt"
HARD_LABELS="/data/speed_train/hard_labels.jsonl"
OUTPUT_DIR="/data/speed_train/outputs"
EPOCHS="30"
SAMPLES_PER_EPOCH="5000"
VAL_SAMPLES="900"
BATCH_SIZE="16"
NUM_WORKERS="2"
HARD_PROB="0.65"
初始化方式：
| 模式 | 配置 |
|---|---|
| checkpoint 微调 | RESUME_CKPT="checkpoints/rgb_speed3_best.pt"、RESUME_OPTIMIZER="0" |
| 完整续训 | 设置 checkpoint、RESUME_OPTIMIZER="1"；EPOCHS 是最终 epoch 编号 |
| Kinetics-400 初始化 | RESUME_CKPT=""、USE_PRETRAINED="1" |
| 随机初始化 | RESUME_CKPT=""、USE_PRETRAINED="0" |
完整续训会恢复 optimizer/scaler/best/epoch，同时恢复 checkpoint 中的学习率。训练脚本是单卡实现；NUM_WORKERS 建议从 1–2 开始，调试时设为 0。
4. 训练数据格式
train.txt 和 val.txt 每行一个视频路径，不需要类别：
/data/source_videos/clip_0001.mp4
训练时在线合成三类速度：
slow: 0.50 / 0.67 / 0.75
normal: 1.00
fast: 1.50 / 2.00 / 2.50
默认配置为 16 FPS、16 帧、112×112。为了覆盖最快的 2.5 rate，重采样后至少需要 40 帧。
可选 hard-label 文件为 JSONL：
{"video_path":"/data/hard/clip.mp4","label":"fast","note":"human confirmed"}
label 只能是 slow / normal / fast，HARD_PROB 控制 hard samples 的训练采样概率。仓库只提供一条合成格式示例，不包含原内部训练数据。
训练输出：
rgb_speed3_last.pt
rgb_speed3_best.pt
train_log.csv
hard_eval_best.csv
best 按 (hard_acc, val_acc) 排序。hard labels 可能同时参与训练，因此 hard_acc 不是独立测试指标。
5. 常用参数
推理：
WINDOW_STRIDE：时间窗口步长，默认8。BATCH_SIZE：每次 forward 的窗口数，默认8。WORKER_NUM：每张 GPU 的进程数，默认1。SHARD_NUM / SHARD_ID：按样本名稳定分片。MAX_VIDEOS：0表示不限制。DEVICE：cuda或cpu。
训练：
SAMPLES_PER_EPOCH / VAL_SAMPLES：每轮随机采样数。HARD_PROB：hard-label 采样概率。USE_PRETRAINED：是否使用 Kinetics-400 初始化。RESUME_OPTIMIZER：是否恢复完整训练状态。
6. Checkpoint
文件：checkpoints/rgb_speed3_best.pt
大小：398150602 bytes（约380 MiB）
SHA256：c048c00b6e2ac4d5b23fbf4d4604aa7f79405fd0d907f7d4d939ccd68692aa07
sha256sum -c checkpoints/SHA256SUMS
推理和训练 resume 都使用 torch.load(..., weights_only=True)。checkpoint 通过 Git 托管时需要 Git LFS；通过 Hugging Face、共享盘或 rsync 迁移时无需手动拆分。
Hugging Face：wendell0218/speed_detect
本仓库没有为原内部代码和 checkpoint 新增对外分发许可证；公开再分发前请确认授权范围。