YOLOv3-tiny (TensorFlow 2) 目标检测项目

基于 TensorFlow 2 的 YOLOv3-tiny 实现，当前训练 4 类（person / car / dog / cat，VOC 数据子集）。 另有 C++ 版实现（minigrad 自动微分 + cuDNN），见文末。

环境准备

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# GPU 支持: 给 TF 配置 CUDA 运行时库路径
source setup_env.sh

目录结构

config/                 # 网络/训练配置 (yolov3-tiny.cfg 等)
main/                   # 库代码: Detector / Trainer / Evaluater / 数据加载
utils/                  # 工具: bbox / image / build / visual 等
data/
  tfrecord/             # 训练/验证 tfrecord
  checkpoint/           # 训练产生的 ckpt, best/ 存最佳
  weights/              # yolov3-tiny.weights (darknet 预训练)
  detect_out/           # 预测可视化输出
scripts/
  train/                # 训练入口
  predict/              # 预测/检测
  eval/                 # 评估
  convert/              # 权重转换
tutorials/mini_autograd/ # C++ 版实现 (captcha + yolo)

所有脚本均可从任意目录运行（脚本内部会自动 chdir 到仓库根）。

---

训练

# 从零训练 (读取 config/yolov3-tiny.cfg, epoch=60)
python scripts/train/run_train.py

# 加载 darknet 预训练骨干微调 (推荐)
PRETRAIN=data/weights/yolov3-tiny.weights python scripts/train/run_train.py

# 断点续训
RESTORE_CKPT=data/checkpoint/ckpt-60 python scripts/train/run_train.py

配置说明 (config/yolov3-tiny.cfg)

参数	说明
batch	批量 (默认 16, 12GB 显存够用)
epoch	训练轮数
learning_rate	Adam 学习率 (0.001)
train/val	tfrecord 路径
name	类别名文件 (data/data.names)

注意: cfg 里 max_batches / steps / scales / burn_in / decay 是 darknet 遗留参数，本训练器不生效；学习率实际走 cosine 调度，decay 等效的权重衰减未启用。

每 epoch 日志

epoch 1 started!, last epoch cost 4.6 sec every step cost 62 ms   # 真实秒数
checkpoint saved in data/checkpoint/ckpt-2
...每类 AP 表...
mean ap is 0.0451
best map is 0.0451

最佳模型按验证 mAP 保存到 data/checkpoint/best/（best 文件记录最佳 mAP 值）。

---

预测

单图/多图检测 (JPEG)

python scripts/predict/predict.py

• 从 JPEG_DIR 遍历图片，输出检测最多的图到 data/detect_out/。
• 修改脚本顶部 CKPT / JPEG_DIR。

验证集可视化 (GT 绿框 + 预测蓝框 + 置信度)

python scripts/predict/predict_val.py

• 读 val tfrecord，画 GT 与预测框，存 8 张到 data/detect_out/val/。
• 改 CKPT 指向目标模型。

训练集单图预览

python scripts/predict/predict_train.py

• 读 train tfrecord 第一张，画 GT+预测到 data/detect_out/pred_train.jpg。

实时视频检测

python scripts/predict/realtime_detect.py

• 打开视频逐帧检测（q/ESC 退出）。改 VIDEO、CKPT、SCORE。

通用检测 (saved_model)

python scripts/predict/detect.py <net.cfg> <saved_model> --conf_thresh 0.5 --file <图片目录>

所有预测脚本默认 score 阈值 0.5、NMS iou 0.3（降 FP 的推荐配置，见评估一节）。

---

评估

eval_fp.py (推荐，可调阈值看 FP/mAP 权衡)

# 单点评估: score 阈值 + NMS iou
python scripts/eval/eval_fp.py --score 0.5 --iou 0.3
python scripts/eval/eval_fp.py --score 0.5 --iou 0.3 --agnostic   # 类无关重复框抑制
# 全阈值扫描表
python scripts/eval/eval_fp.py
# 指定模型/数据
python scripts/eval/eval_fp.py --ckpt data/checkpoint/best/ckpt-59 --tfrecord data/tfrecord/val/voc2007-val-0000

输出每类 TP/FP/AP + mAP + FP/图 + FP 置信度分布。

evaluate.py (mAP 计算, 需要 pred.csv/gt.csv)

python scripts/eval/evaluate.py

• 读 data/map/gt.csv 与 pred.csv 计算 mAP。

---

权重转换

python scripts/convert/convert_weight.py <net.cfg> <ckpt> <saved_model输出目录>

• 把 TF checkpoint 导出为 tf.saved_model（供 detect.py 使用）。

---

C++ 版实现 (minigrad + cuDNN)

tutorials/mini_autograd/yolo/ 是纯 C++ 的 YOLOv3-tiny（自动微分 + cuDNN 卷积）：

cd tutorials/mini_autograd/yolo
./build_yolo_gpu.sh

# 训练 (支持 darknet 预训练 + 冻结微调)
./build/yolo_train data/voc_train.bin data/voc_val.bin 30 16 0.001 123 \
    --pretrain=/home/gugugu/Repo/yolov3/data/weights/yolov3-tiny.weights --freeze

# 断点续训 (权重 + Adam 状态 + 已跑 epoch 全部恢复; 续训的 shuffle 序列与连续训练一致)
./build/yolo_train data/voc_train.bin data/voc_val.bin 30 16 0.001 123 \
    --resume=yolo/data/yolo_tiny_ckpt.bin
# 训练产物:
#   yolo/data/yolo_tiny_ckpt.bin   滚动 checkpoint (每 epoch 保存, 供 --resume)
#   yolo/data/yolo_tiny_best.bin   best mAP 模型 (同样可 --resume 或直接预测)
#   yolo/data/yolo_tiny.bin        训练结束最终权重

# 用 Python 训练的最佳 ckpt 预测 (需先转换权重)
python tf2cpp_convert.py data/checkpoint/best/ckpt-6 data/yolo_tiny_py.bin
./build/yolo_predict_img data/yolo_tiny_py.bin data/voc_val.bin 0 data/pred.ppm data/pred.txt
python yolo_draw.py data/pred.ppm data/pred.txt out.png

Qt 训练前端 (可选)

需要 Qt5/Qt6 Widgets（CMake 找到即构建 build/yolo_gui）：

cd tutorials/mini_autograd/yolo
./build_yolo_gui.sh        # 若已 ./build_yolo_gpu.sh 则直接 ./build/yolo_gui
./build/yolo_gui

功能：表单配置训练参数（epochs/batch/lr/freeze/pretrain/resume…）、启动/停止训练子进程、 实时绘制每 epoch 的 box/obj/noobj/cls/total loss 曲线（对数轴）+ mAP 曲线 + 当前 epoch step loss/lr + 训练进度条和完整日志。数据/权重路径可在表单里填，相对路径自动解析到项目目录。

预测 tab：图片/视频实时检测显示（Qt Multimedia 解码 + GPU 推理 worker 线程），支持：

• 保存预测图片；视频预测可勾选「另存预测视频」（ffmpeg 编码为 mp4）
• 批量图片预测：选文件夹 → 预测并保存到 <folder>/annotated/ + 缩略图网格
• 检测结果表格（类别/置信度/框坐标，可排序）+ 导出 CSV

详细说明见 tutorials/mini_autograd/yolo/。

---

常见问题

• loss 变 NaN / 不下降：检查 PRETRAIN 是否加载、学习率是否过大；冻结骨干（--freeze）通常更稳。
• 显存不足：调小 batch。
• FP 太多：提高 score 阈值 / 降低 NMS iou（eval_fp.py --score 0.5 --iou 0.3），或用类无关抑制。
• 日志秒数不对：已修复（毫秒/60 → 毫秒/1000）。