PyTorch图像分类与目标检测双轨训练框架

简介本资源是一套基于Python与PyTorch实现的深度学习图像处理完整源码工程面向AI初学者、计算机视觉方向学生及工程实践者聚焦图像分类、目标检测与语义分割等核心任务提供从模型训练、验证到轻量部署的全流程参考。压缩包共436个文件4.13MB含360个Python脚本涵盖pytorch_classification、pytorch_object_detection等模块的训练/推理代码、30个JSON配置文件管理超参与模型结构、25个文本与Markdown文档含readme、问题总结、使用指南、10个PNG示例图及checkpoint、cfg、yaml等关键配置与权重文件。已有351人学习下载资源结构清晰、模块解耦明确附带TensorBoard日志文件、调色板定义、ImageNet类别索引等实用组件便于快速复现实验、理解模型设计逻辑并开展二次开发。1. 这不是又一个“YOLOResNet”拼凑包它用 PyTorch 实现了可复现的分类/检测双轨训练闭环含完整数据预处理链、模型热启动机制与轻量部署接口你下载过太多标着“深度学习图像处理”的 GitHub 仓库——点开一看train.py里model ResNet50()硬编码、test.py直接cv2.imread(demo.jpg)、config.json里 learning_rate 写死 0.001连 batch_size 都没参数化。而这个项目不同它把「从原始图像到服务端推理」拆成了 7 个可插拔模块每个模块都有独立入口、明确输入输出契约和配套的.md验证说明。比如pytorch_classification/data_loader.py不仅支持 ImageFolder还内置了AutoBalanceSampler解决长尾类别偏移pytorch_object_detection/utils/anchor_generator.py会根据你传入的train_dataset自动重算 anchor 尺寸不是靠k-means脚本跑完再手动填进yolov3-spp.cfg。它适合两类人一是正在写毕设/小论文、需要快速搭出可复现 baseline 的学生所有实验参数都存于configs/下带时间戳的 JSON二是工业场景中要快速验证新数据集适配性的工程师deploying_service/里flask_api.py已预留 ONNX 推理路径requirements.txt明确标注 CUDA 11.3 PyTorch 1.10.2 兼容组合。别被 453 个文件吓到——真正要改的只有configs/classification/resnet50_imagenet.yaml和datasets/your_custom_data/两处。2. 模块化设计原理与核心文件定位为什么pytorch_classification和pytorch_object_detection必须分离2.1 分类与检测任务的本质差异决定了代码组织逻辑图像分类任务的核心是「全局语义判别」输入一张图输出一个类别概率分布。其数据流是单向的——预处理 → 特征提取 → 分类头 → loss。而目标检测是「局部定位全局判别」耦合既要预测每个 anchor 的类别又要回归 bounding box 坐标。这导致二者在三个层面必须隔离数据加载层分类只需(image, label)对检测需(image, boxes, labels, image_size)四元组且boxes是变长 tensor每张图目标数不同必须用collate_fn重写批处理逻辑损失函数层分类用CrossEntropyLoss即可检测需FocalLoss解决正负样本不平衡CIoULoss提升 bbox 回归精度且 loss 计算需分 stage如 YOLO 的 confidence loss、class loss、box loss 三部分评估指标层分类看Top-1 Acc检测必须跑mAP0.5涉及 NMS、IoU 计算、PR 曲线绘制pytorch_object_detection/metrics/下的voc_eval.py已封装标准 VOC 评估流程。提示不要试图把 detection 模块的Dataset类直接塞进 classification 的Trainer。项目中pytorch_classification/trainer.py的train_epoch()方法只接受model(input)返回logits而pytorch_object_detection/trainer.py的同名方法要求model(input)返回(pred_conf, pred_cls, pred_box)三元组——类型系统已强制隔离。2.2 关键文件树解析哪些文件你必须打开哪些可以跳过项目未用setup.py或pyproject.toml构建而是采用「配置驱动」模式。核心控制点如下表路径文件类型必读性作用说明configs/YAML/JSON★★★★★所有超参集中地。classification/下按 backbone 分目录resnet50.yaml,efficientnet_b3.yamlobject_detection/下按算法分yolov3-spp.yaml,faster_rcnn_r50_fpn.yaml。每个 YAML 包含data_path,num_classes,input_size,optimizer,scheduler全字段。pytorch_classification/models/Python★★★★☆__init__.py定义create_model(name, num_classes)工厂函数。resnet.py重写了ResNet.forward()返回(features, logits)便于特征可视化非官方 torchvision 版本。pytorch_object_detection/models/yolo/Python★★★★☆yolo.py中YOLOv3SPP类继承nn.Module但forward()返回preds后自动调用self.decode(preds)得到(boxes, scores, labels)省去用户手写 decode 逻辑。datasets/目录★★★★★必须按ImageNet标准结构组织train/cls1/xxx.jpg,val/cls1/xxx.jpg。检测数据集需提供annotations/下的 PASCAL VOC XML 或 COCO JSON。datasets/utils.py的VOC2YOLOConverter可一键转换。deploying_service/flask_api.pyPython★★★☆☆已实现/predict/classify和/predict/detect两个 endpoint。注意model.load_state_dict(torch.load(checkpoint.pth, map_locationcpu))——生产环境默认 CPU 加载若需 GPU 需改map_location并确保 Flask 进程可见 CUDA 设备。2.3 为什么events.out.tfevents.*文件不能删它们不是日志而是训练状态快照TensorBoard 日志文件events.out.tfevents.*在此项目中承担双重角色可视化监控tensorboard --logdirlogs/可查看 loss 曲线、grad norm、learning rate decay断点续训凭证pytorch_classification/trainer.py的resume_from_checkpoint()方法会扫描logs/下最新tfevents文件从中提取global_step和best_metric再加载对应checkpoint.pth。若删除tfeventsresume会退化为从头训练。注意checkpoint.pth是模型权重 优化器状态 epoch 数的完整保存而tfevents只存 scalar/metric 数据。二者缺一不可但tfevents文件体积小通常 1MB建议保留。3. 从零启动训练分类任务实操步骤与参数详解3.1 准备数据集ImageNet 格式是硬性前提但可绕过下载全流程项目不提供 ImageNet 原始数据版权原因但datasets/imagenet/README.md给出了合规获取路径使用imagenet-downloader工具项目others_project/下已打包cd others_project/imagenet-downloader python download.py --subset ILSVRC2012_val --save_dir ../../datasets/imagenet/val或用torchvision.datasets.ImageNetAPI需自行申请授权from torchvision.datasets import ImageNet # 需提前将 ILSVRC2012_img_train.tar 解压至 /path/to/imagenet/train dataset ImageNet(root/path/to/imagenet, splittrain)关键约束train/和val/下必须是cls1/,cls2/... 子目录且cls1/内全为同一类别图片。若你的数据是 CSV 标签如img_path,label用datasets/utils.py的CSV2ImageFolder转换from datasets.utils import CSV2ImageFolder CSV2ImageFolder( csv_pathyour_data.csv, image_rootraw_images/, output_rootdatasets/custom/, train_ratio0.8 )该脚本会自动创建train//val/目录并按比例划分同时生成class_to_idx.json供后续读取。3.2 修改配置YAML 中 5 个必调参数决定训练成败打开configs/classification/resnet50_imagenet.yaml以下字段必须按需修改data: train_dir: datasets/imagenet/train # ← 必须指向你的 train 目录绝对路径 val_dir: datasets/imagenet/val # ← 必须指向你的 val 目录绝对路径 num_classes: 1000 # ← 若自定义数据集改为实际类别数如 12 input_size: [3, 224, 224] # ← 输入尺寸ResNet50 默认 224x224 batch_size: 64 # ← 根据 GPU 显存调整V100 用 64RTX3090 用 128 model: name: resnet50 # ← 可选resnet50, efficientnet_b3, vit_base_patch16_224 pretrained: true # ← True 时加载 ImageNet 预训练权重自动下载 optimizer: name: sgd # ← 可选sgd, adamw lr: 0.1 # ← 初始学习率ResNet50 常用 0.1配合 LinearWarmup weight_decay: 1e-4 # ← L2 正则强度 scheduler: name: cosine # ← 可选cosine, step, linear_warmup_cosine warmup_epochs: 5 # ← 前 5 epoch 线性增大学习率至 lr total_epochs: 100 # ← 总训练 epoch 数 output: save_dir: outputs/classification/resnet50_custom # ← 模型和日志保存路径逻辑说明pretrained: true会触发torch.hub.load(pytorch/vision, resnet50, pretrainedTrue)自动下载权重到~/.cache/torch/hub/若网络受限可提前下载resnet50-0676ba61.pth放入pretrained_weights/并改pretrained: pretrained_weights/resnet50-0676ba61.pth。3.3 启动训练一条命令跑通但需理解背后的数据流执行训练命令cd pytorch_classification python train.py --config ../configs/classification/resnet50_imagenet.yaml该命令触发以下流程train.py加载 YAML 配置 → 初始化DatasetImageFolder→ 构建DataLoader含AutoBalanceSampler创建modelResNet50→ 加载预训练权重 → 替换fc层为nn.Linear(2048, num_classes)初始化optimizerSGD和schedulerCosineAnnealingLR with Warmup进入Trainer.train()循环每个 epoch 调用train_epoch()→val_epoch()→ 保存 best checkpointtrain_epoch()中model.train()→loss criterion(outputs, targets)→loss.backward()→optimizer.step()。关键细节criterion默认为LabelSmoothingCrossEntropy(smoothing0.1)比原始CrossEntropyLoss更鲁棒AutoBalanceSampler会动态调整每个类别的采样概率公式为p_i (N_total / N_i) / sum(N_total / N_i)有效缓解类别不平衡。4. 目标检测实战YOLOv3-SPP 训练全流程与 anchor 重生成4.1 数据准备PASCAL VOC XML 是唯一受支持格式但转换脚本已就位项目pytorch_object_detection/datasets/voc.py仅解析 PASCAL VOC 格式 XMLannotationobjectnamecat/namebndboxxmin10/xmin.../bndbox/object/annotation。若你手握 COCO JSON用datasets/utils.py的COCO2VOCConverterfrom datasets.utils import COCO2VOCConverter COCO2VOCConverter( coco_jsoncoco_train.json, image_rootcoco_images/, output_dirdatasets/voc_custom/ )该脚本会生成VOCdevkit/VOC2007/Annotations/和JPEGImages/目录并创建ImageSets/Main/trainval.txt含所有图片名无后缀。注意VOC2007是目录名约定非年份要求。pytorch_object_detection/datasets/voc.py通过os.path.join(root, VOCdevkit, VOC2007)拼接路径故你的数据必须放在此结构下。4.2 Anchor 重生成为什么不能直接用yolov3-spp.cfg里的默认值YOLO 系列性能高度依赖 anchor 尺寸匹配数据集目标尺度。项目pytorch_object_detection/utils/anchor_generator.py提供自动化工具cd pytorch_object_detection python generate_anchors.py \ --dataset_dir ../datasets/voc_custom/VOCdevkit/VOC2007 \ --cfg ../configs/object_detection/yolov3-spp.yaml \ --num_clusters 9 \ --size 416该脚本执行扫描Annotations/下所有 XML提取全部bndbox宽高比w/h和归一化尺寸w/416, h/416对宽高比聚类K-means输出 9 个最优 anchor 尺寸如[12,16, 19,36, 40,28, ...]覆盖yolov3-spp.cfg中[region]下的anchors ...行。参数说明--size 416是 YOLO 输入分辨率必须与yolov3-spp.yaml中input_size一致--num_clusters 9对应 YOLOv3 的 3 个 scale × 3 anchors/scale。4.3 训练命令与 cfg 解析.cfg文件不是黑匣子而是可读的模型蓝图运行检测训练cd pytorch_object_detection python train.py --config ../configs/object_detection/yolov3-spp.yamlyolov3-spp.yaml关键字段data: train_dir: ../datasets/voc_custom/VOCdevkit/VOC2007 # ← 必须含 JPEGImages/ Annotations/ classes: [aeroplane, bicycle, bird, ...] # ← 按 XML 中 name 顺序列出长度 num_classes num_classes: 20 # ← VOC 20 类自定义数据集需更新 model: cfg: ../configs/object_detection/yolov3-spp.cfg # ← 网络结构定义文件 weights: # ← 预训练权重路径空则随机初始化 input_size: [3, 416, 416] # ← 必须与 generate_anchors.py --size 一致 train: batch_size: 16 # ← YOLO 内存消耗大V100 建议 ≤16 accumulate_batches: 4 # ← 梯度累积步数等效 batch_size64 warmup_epochs: 2 # ← 前 2 epoch warmupyolov3-spp.cfg是纯文本文件按 section 组织[net]全局设置batch16,subdivisions1,width416,height416[convolutional]卷积层filters32,size3,stride1,pad1[yolo]检测头mask 0,1,2指定 anchor 索引anchors 12,16,19,36,...为重生成值。逻辑说明accumulate_batches: 4表示每 4 个 mini-batch 才optimizer.step()模拟大 batch 效果避免显存溢出。5. 避坑指南分类与检测训练中 4 个血泪经验总结5.1 现象分类训练val_acc一直卡在 10%随机猜测水平原因num_classes配置错误或class_to_idx.json未更新。项目pytorch_classification/datasets/imagenet.py会读取train/下子目录名生成class_to_idx若你新增类别但未重建class_to_idx.json模型输出维度仍为旧值CrossEntropyLoss计算时targets超出范围loss 变为 nanacc 归零。解决删除datasets/your_data/class_to_idx.json重新运行CSV2ImageFolder或手动检查train/目录结构是否与num_classes匹配。5.2 现象检测训练loss_box持续 10bbox 完全不收敛原因yolov3-spp.cfg中anchors未重生成或input_size与generate_anchors.py --size不一致。例如cfg里width416但generate_anchors.py --size 608导致 anchor 尺寸与网络感受野错配。解决确认yolov3-spp.yaml的input_size与generate_anchors.py参数一致检查yolov3-spp.cfg的[net]section 中width/height是否等于该值用grep anchors yolov3-spp.cfg验证 anchor 值已更新。5.3 现象flask_api.py启动后/predict/detect返回500 Internal Server Error原因checkpoint.pth中state_dict的 key 名与当前模型不匹配。常见于修改了模型结构如增减 layer后仍用旧 checkpoint 加载。PyTorch 默认 strictTruekey 缺失直接报错。解决在deploying_service/flask_api.py的load_model()函数中将model.load_state_dict(checkpoint[model_state_dict])改为model.load_state_dict(checkpoint[model_state_dict], strictFalse) # 并添加警告 missing_keys, unexpected_keys model.load_state_dict(..., strictFalse) if missing_keys: print(fMissing keys: {missing_keys}) if unexpected_keys: print(fUnexpected keys: {unexpected_keys})5.4 现象TensorBoard 无法显示events.out.tfevents.*提示No dashboards are active原因tfevents文件被其他进程占用如训练未正常退出writer.close()未执行或文件权限问题Linux 下chmod 644 events.*。解决先kill -9 $(lsof -t -i :6006)结束残留 tensorboard 进程再tensorboard --logdirlogs/ --bind_all --port6006若仍失败复制events.*到新目录logs_clean/并重试。6. 进阶技巧用 ONNX 导出模型并验证推理一致性6.1 分类模型 ONNX 导出避开 PyTorch 版本陷阱pytorch_classification/export_onnx.py提供导出脚本但需注意PyTorch ≥1.10 才支持torch.onnx.export的dynamic_axes参数处理变长 batchinput_shape必须与训练时input_size一致如[1,3,224,224]cd pytorch_classification python export_onnx.py \ --config ../configs/classification/resnet50_imagenet.yaml \ --checkpoint ../outputs/classification/resnet50_custom/best.pth \ --output ../outputs/classification/resnet50_custom/model.onnx \ --input_shape [1,3,224,224]该脚本核心逻辑# export_onnx.py model.eval() dummy_input torch.randn(*input_shape) torch.onnx.export( model, dummy_input, onnx_path, export_paramsTrue, opset_version11, # ← 必须 ≥11否则 Softmax 输出维度错误 do_constant_foldingTrue, input_names[input], output_names[output], dynamic_axes{ input: {0: batch_size}, # ← 允许 batch 维度动态 output: {0: batch_size} } )6.2 ONNX 推理验证用 PyTorch 和 ONNX Runtime 跑同一张图误差 1e-5 才可信导出后必须验证数值一致性import torch import onnxruntime as ort import numpy as np # PyTorch 推理 model_pt torch.load(best.pth, map_locationcpu) model_pt.eval() input_tensor torch.randn(1, 3, 224, 224) # 同 export 时 dummy_input with torch.no_grad(): pt_output model_pt(input_tensor).numpy() # ONNX 推理 ort_session ort.InferenceSession(model.onnx) ort_inputs {ort_session.get_inputs()[0].name: input_tensor.numpy()} onnx_output ort_session.run(None, ort_inputs)[0] # 验证 np.testing.assert_allclose(pt_output, onnx_output, rtol1e-5, atol1e-5) print(ONNX export PASS)关键参数rtol1e-5相对误差容忍和atol1e-5绝对误差容忍是工业级部署底线。若失败检查opset_version是否 ≥11或模型中是否有torch.nn.functional.interpolate需 ONNX opset 11。6.3 检测模型 ONNX 导出特殊处理YOLO 输出需后处理解码YOLO 的 ONNX 导出不能直接export(model, dummy_input)因为model.forward()返回的是 raw prediction未 decode而 ONNX 不支持动态 shape 的nms。项目pytorch_object_detection/export_onnx.py采用「导出 raw prediction 外部 decode」策略导出YOLOv3SPP的forward()输出(pred_conf, pred_cls, pred_box)三元组deploying_service/onnx_inference.py中用cv2.dnn.NMSBoxes执行 NMS# onnx_inference.py def infer_yolo_onnx(onnx_path, image): session ort.InferenceSession(onnx_path) input_name session.get_inputs()[0].name outputs session.run(None, {input_name: image}) # outputs[0]conf, [1]cls, [2]box boxes, scores, labels postprocess_yolo(outputs[0], outputs[1], outputs[2]) return boxes, scores, labels def postprocess_yolo(conf, cls, box): # conf: [B, A, H, W], cls: [B, A, H, W, C], box: [B, A, H, W, 4] # reshape to [N, 4], [N], [N] for cv2.dnn.NMSBoxes ...这样既保证 ONNX 兼容性又复用 OpenCV 高效 NMS。从那以后我每次导出 ONNX都强制走一遍np.testing.assert_allclose验证哪怕只是 demo。因为线上服务一旦因数值误差导致漏检根本没法回溯是 PyTorch 还是 ONNX 的锅——而这个 assert 就是我的后悔药。希望帮到你。本文还有配套的精品资源点击获取