简介这套基于Python的SSD-Demo项目专注于空停车位自动识别面向智能交通、智能停车场管理及深度学习目标检测学习者可用于快速理解SSD算法从训练到部署的完整流程。压缩包共78个文件其中61个Python源码文件构成主体覆盖SSD网络结构、数据预处理、训练评估与推理逻辑5个XML配置文件定义模型参数与IDE工作区另含YAML配置文件、说明文档、Git管理文件及测试图片等整体包体仅282KB结构清晰易检索。目前已有314人浏览学习适合具备一定Python基础、希望结合具体场景上手SSD检测的开发者。借助demo、server、client等脚本可搭建简单的客户端-服务器架构实时查看车位检测结果通过分析工程目录中的anchors、backbone、box_head等模块设计还能掌握模型搭建与模块化组织的实践思路为后续二次开发或竞赛项目提供可复用范本。1. 空停车位识别实战把 SSD 检测器从 54 个 Python 文件里拆明白停车场摄像头画面里真正稀缺的不是“识别”这个动作而是响应速度——车开进通道时模型必须在一个画面周期里判断哪些车位是空的。SSDSingle Shot MultiBox Detector恰好是这条路线上最经典的选择之一一次前向完成边框回归和分类不需要区域提议。这份源码包用 Python 实现了 SSD 的空停车位识别 Demo68 个文件里 54 个是 Python 源码覆盖数据读取、anchor 生成、模型训练、NMS 后处理还有 server.py 与 client_show.py 组成的客户端-服务器演示链路。适合两类人刚开始学目标检测想有一份能完整读懂的项目或者已经在调参想对照看看常见配置边界和踩坑记录。2. 源码结构排查54 个 Python 文件怎么分成三条主链路拿到压缩包先不要急着跑 demo.py先把目录摊开。这个工程不是单文件脚本而是按训练、推理、部署三条链路组织的。先花十分钟把结构认清后面调参会少走很多弯路。2.1 关键目录与文件职责映射第一遍看源码建议按“配置 → 数据 → 模型 → 训练引擎 → 工具函数”这条线扫不要从上往下挨个读。下面这张表是我排查时画的功能映射可以直接对着找文件目录 / 文件承担的职责你在调参时最可能动它的位置configs/vgg_ssd512_voc0712.yaml全局配置模型、输入尺寸、anchor、学习率所有参数的唯一入口data/datasets/build.py构建 VOC 格式数据集把 xml 标注转成训练样本改类别数、改标注路径data/transforms/图像预处理缩放、翻转、颜色抖动、归一化训练和推理必须保持一致data/samplers/正负样本采样策略基本不用动modeling/backbone/VGG16 骨干网络换骨干时替换这里modeling/box_head/分类头 回归头输出预测框偏移调输出通道数时注意modeling/anchors/生成默认框anchor检测精度不稳时先查这里engine/trainer.py训练主循环改 batch size、梯度裁剪engine/inference.py推理主流程改置信度阈值solver/lr_scheduler.py学习率调度训练后期掉点先看这里utils/box_utils.pyanchor 编解码、IoU 计算预测框位置不对时重点查utils/nms.py非极大值抑制重叠框多就调 NMS 阈值utils/checkpoint.py保存和恢复断点恢复训练时用到utils/model_zoo.py加载预训练权重训练不收敛时改加载方式这份工程里有一个容易被忽略的文件是modeling/backbone下面的separable_conv.py。它不是 SSD 原始论文必带的部分而是把标准卷积替换成深度可分离卷积的轻量化改动后面单独展开讲。2.2 vgg_ssd512_voc0712.yaml 参数解读整个项目的配置集中在configs/vgg_ssd512_voc0712.yaml这个文件里。文件名已经很直白骨干是 VGG输入分辨率 512数据集按 VOC0712 的协议组织。它的核心段落大致长这样我摘出几个关键字段model: num_classes: 21 # VOC 的 20 类 背景 backbone: vgg16 input_size: [512, 512] anchors: feature_maps: [64, 32, 16, 8, 4, 2] # 6 层特征图 aspect_ratios: - [2, 3] - [2, 3] - [2, 3] - [2, 3] - [2, 3] - [2, 3] scales: [0.07, 0.15, 0.33, 0.51, 0.69, 0.87] box_coder: center_variance: 0.1 size_variance: 0.2 train: batch_size: 8 base_lr: 0.001 epochs: 120这里的feature_maps是 512 输入下六层特征图的尺寸每一层负责检测不同尺度的目标64×64 的浅层特征图感受野小负责小目标2×2 的深层特征图负责大目标。aspect_ratios是每个 anchor 的宽高比2 和 3 代表横向拉长的框对停车位这种扁长形状相对友好。scales是每层 anchor 相对输入图像的尺度比例从 0.07 到 0.87 逐层放大。box_coder里的两个 variance 是 SSD 官方实现里 decode 预测框时的缩放系数center_variance0.1和size_variance0.2是论文配套代码的默认值。这两个数字直接影响预测框从“偏移量”还原成“真实坐标”时的抖动幅度后面避坑章节会专门说。2.3 separable_conv.py 与轻量化改法原始 SSD 的 VGG 骨干在 512 输入下计算量不低边缘设备跑实时推理会吃力。separable_conv.py这文件做的就是拆解把一个标准卷积拆成 depthwise 卷积和 pointwise 卷积两步。常见的实现写法是这样的import torch.nn as nn class SeparableConv2d(nn.Module): def __init__(self, in_channels, out_channels, kernel_size3, stride1, padding1): super().__init__() self.depthwise nn.Conv2d( in_channels, in_channels, kernel_sizekernel_size, stridestride, paddingpadding, groupsin_channels ) self.pointwise nn.Conv2d(in_channels, out_channels, kernel_size1) def forward(self, x): return self.pointwise(self.depthwise(x))groupsin_channels是深度可分离卷积的关键每个输入通道先单独做卷积再用 1×1 卷积把通道信息混合。相比标准卷积参数大约减少到原来的三分之一在车位上部署时帧率能明显提上去。但要注意一点训练时如果用标准 VGG 加载预训练权重结构对不上。我一般建议轻量化改造放在训练完成后做或者直接从头训这个轻量版不要想着半路切结构。2.4 model_zoo.py 和 checkpoint.py 的配合model_zoo.py负责加载预训练权重checkpoint.py负责保存训练中间结果。两者容易混淆我踩过一次把 checkpoint 直接往 model_zoo 的加载函数里塞结果 key 对不上模型参数全随机初始化了。常见做法是预训练权重只给骨干网络用完整模型参数走 checkpoint 恢复import torch from utils.model_zoo import load_pretrained from utils.checkpoint import save_checkpoint, load_checkpoint model build_ssd_model(cfg) load_pretrained(model.backbone, vgg16_reducedfc.pth, strictFalse) # 训练中断后恢复 state load_checkpoint(outputs/vgg_ssd512_voc0712/checkpoint.pth) model.load_state_dict(state[model])strictFalse是有意为之预训练权重缺少分类头或额外层时跳过缺失 key 而不是报错。恢复训练时则必须用strictTrue否则有些层没加载进去训练等于从头开始。3. 数据准备把停车位图片整理成 SSD 能吃的 VOC 格式SSD 的训练代码通常直接吃 Pascal VOC 目录结构这份工程也延续了这个约定。你从网上下载的停车场图片不会天然是这个格式需要先转换。3.1 目录结构与 label 文件标准的 VOC 目录三段式结构是这样组织的VOCdevkit/ VOC2007/ JPEGImages/ # 原始图片 Annotations/ # 每张图对应的 xml 标注 ImageSets/ Main/ train.txt # 训练图片名列表 val.txt # 验证图片名列表xml 里关键字段是bndbox里面是目标框的左上角和右下角坐标。我见过不少新手把 xml 里的xmin/ymin和xmax/ymax顺序搞反或者把width/height当成框坐标用。标注框坐标一定是像素级整数直接画到图上能框住车位线才说明标注是对的。3.2 一个能直接跑的 VOCDataset 读取代码工程里的data/datasets/build.py是现成的读取器核心逻辑是解析 xml 并返回图像、真实框、类别。如果你想自己控制标注格式常见做法是写一个最小的 VOCDatasetimport os import xml.etree.ElementTree as ET import torch from PIL import Image class VOCDataset(torch.utils.data.Dataset): def __init__(self, root, image_set, transformsNone): self.root root self.transforms transforms self.ids [] with open(os.path.join(root, ImageSets, Main, f{image_set}.txt)) as f: for line in f: self.ids.append(line.strip()) def __getitem__(self, idx): img_id self.ids[idx] img_path os.path.join(self.root, JPEGImages, f{img_id}.jpg) xml_path os.path.join(self.root, Annotations, f{img_id}.xml) img Image.open(img_path).convert(RGB) boxes, labels [], [] root ET.parse(xml_path).getroot() for obj in root.findall(object): name obj.find(name).text bndbox obj.find(bndbox) xmin float(bndbox.find(xmin).text) ymin float(bndbox.find(ymin).text) xmax float(bndbox.find(xmax).text) ymax float(bndbox.find(ymax).text) boxes.append([xmin, ymin, xmax, ymax]) labels.append(self.class_names.index(name)) return img, torch.tensor(boxes), torch.tensor(labels)这段代码有两个参数值得注意image_set是train还是val决定了读哪份图片列表self.transforms不能为 None因为后续训练代码会强制要求输出固定尺寸的 tensor。如果你把标注框坐标读进来直接用记得归一化到 [0,1]否则和 anchor 计算的位置全乱套。3.3 transforms 流水线翻转、颜色抖动、归一化SSD 数据增强的核心是随机翻转、随机裁剪和颜色抖动。data/transforms里实现的顺序一般是先随机水平翻转再随机裁剪出包含至少一个真实框的区域然后缩放到 512×512最后做减均值除方差的归一化。随机裁剪这一步对停车位场景很重要。摄像头画面里车位上经常有其他车辆遮挡随机裁剪能让模型学会从局部特征判断车位状态而不是依赖全局布局。归一化时要注意工程里如果用的是 RGB 顺序推理时就不要切 BGR很多 OpenCV 读图踩坑就是通道顺序不一致导致的。3.4 类别定义从 VOC 21 类改成空车位专用VOC 默认 21 类而空车位识别只需要“车位空/占用”甚至只分“空车位”和“背景”两类。修改时有三处必须同步第一配置文件里的num_classes从 21 改成 2 或 3第二数据集的class_names列表按你的标注顺序重排背景永远是索引 0然后才是空车位、占用车位第三box_head 末尾的输出通道数是num_classes * 4改配置后模型结构会自动变。我建议标签最简方案用两类0 是背景1 是空车位。占用车位不单独标注没标成空车位的框全部算背景。这样训练难度小评估指标也直观。4. 训练流程从 train 命令到 loss 曲线阅读数据准备好之后进入训练环节。这份工程没有把训练封装成一条命令打天下而是把逻辑拆在engine/trainer.py和solver/里读代码比跑代码更重要。4.1 trainer.py 每一轮在做什么训练主循环做的事情是标准的 SSD 流程从 dataloader 拿一个 batch图像过 backbone 提特征六层特征图分别进分类头和回归头得到预测偏移量和类别分数同时用真实框与 anchor 做匹配分配正负样本最后计算定位损失和分类损失反传更新参数。锚点匹配是这里最容易出问题的一步。真实框和 anchor 的 IoU 大于 0.5 才被当成正样本低于 0.5 且高于负样本阈值的才参与负样本挖掘。如果数据集标注框偏小正样本数量可能不够loss 看起来正常但检测效果很差。我一般会在训练前打印一下每个 epoch 正样本的平均数量低于 50 就得检查标注和 anchor 配置。4.2 常用训练命令与参数训练入口不是自动发现的我的习惯是直接走 engine 模块python -m engine.trainer \ --config configs/vgg_ssd512_voc0712.yaml \ --batch-size 8 \ --base-lr 1e-3 \ --epochs 120 \ --eval-interval 10 \ --output-dir outputs/vgg_ssd512_voc0712 \ --resume outputs/vgg_ssd512_voc0712/checkpoint.pth--base-lr用 1e-3 是 SSD 系列比较常见的起点如果显存大把 batch size 提到 16学习率可以相应提到 2e-3。--eval-interval表示每训练 10 个 epoch 在验证集上跑一次 mAP这一步不建议省不然训完发现全是背景才算白跑。--resume是可选参数训练中断后带着这个参数重跑会从断点继续。如果训练时显存报 OOM先把 batch size 降到 4不要直接改输入尺寸。输入尺寸改了anchor 配置里所有 feature map 尺寸、scale 参数全部要跟着改很容易翻车。4.3 loss 怎么读训练日志会逐 epoch 打印 loss 分量典型输出长这样Epoch 10 | loc_loss 1.231 | conf_loss 1.872 | total 3.103 | lr 1.0e-3 Epoch 20 | loc_loss 0.984 | conf_loss 1.216 | total 2.200 | lr 1.0e-3loc_loss是回归损失conf_loss是分类损失。前 30 个 epoch 里conf_loss比loc_loss高是正常的因为负样本数量远大于正样本。如果 50 个 epoch 后conf_loss还在 1.5 以上多半是类别不均衡或者标注错误太多。total loss下降到 1.0 之后速度会明显变慢这是正常的。此时不要盲目加 epoch先看验证 mAP 有没有跟着涨如果 loss 在降但 mAP 不动大概率是正样本匹配出了问题。4.4 checkpoint 保存与恢复checkpoint.py的保存内容一般包含 model 参数、优化器状态、当前 epoch 和 best mAP。恢复时只恢复 model 不恢复优化器学习率会回到初始值这会导致后半段训练效果变差。from utils.checkpoint import save_checkpoint, load_checkpoint save_checkpoint({ epoch: epoch, model: model.state_dict(), optimizer: optimizer.state_dict(), best_mAP: best_mAP, }, output_dir) state load_checkpoint(os.path.join(output_dir, checkpoint.pth)) model.load_state_dict(state[model]) optimizer.load_state_dict(state[optimizer])训练中断恢复最怕的坑是数据加载器的随机种子不一致。恢复训练后前几个 epoch 的 loss 可能小幅回升这不一定是最佳权重注意自动保存 best mAP 模型即可。5. 空停车位识别避坑5 条踩过的问题和解决办法这个工程跑通不难跑好很难。下面五条是我实际调这个项目时踩过的前两条是原理问题后三条更偏部署。5.1 训练 loss 前几个 epoch 不降反升现象loss 一上来就是 12 左右前 10 个 epoch 不降反升甚至飙到 20。 原因最常见的是学习率过大SSD 在 batch size 8 的情况下base_lr超过 2e-3 很容易震荡另一个隐蔽原因是标注框没有归一化导致匹配时 IoU 全是 0。 解决先把base_lr降到 1e-3确认 xml 里的坐标经过img_width和img_height归一化后再进匹配器。改完这两个地方loss 通常会在 5 个 epoch 内掉头向下。5.2 预测框全部偏到图像边缘现象验证时大量检测框紧贴图片上下左右边缘置信度还很高框的尺寸也基本都是同一个尺度。 原因这是 anchor decode 的问题。center_variance和size_variance设成 1 或者干脆缺失时预测偏移量会被放大极端情况下直接推出画面边界。另一个可能原因是对特征图上的每个 anchor 没有做clip到 [0,1]。 解决先确认box_coder的 variance 是[0.1, 0.1, 0.2, 0.2]再用一个已知单框图片做单元测试手动标注一个框看 decode 出来的坐标和标注是否接近。5.3 512 分辨率把显卡显存吃满现象batch size 开到 16 直接 OOM8 也有时候不稳定。 原因VGG16 骨干在 512 输入下中间特征图尺寸是 256×256加上 6 层 SSD 预测头显存占用比 300 输入翻了一倍还多。 解决第一优先降 batch size 到 4同时把eval-interval拉长第二优先用separable_conv.py里的轻量化卷积替换标准 3×3 卷积第三个办法是打开 AMP 混合精度训练把torch.cuda.amp包在 forward 和 backward 外面显存占用能再降三分之一。5.4 demo.py 推理出来的图是全黑的现象用demo.py test.jpg跑推理输出图完全黑色但程序没有报错。 原因输入图片在 transforms 阶段做了减均值推理时没有做反变换或者样本归一化后没有乘回原图范围直接转 uint8 保存。 解决在保存前把 tensor 恢复成 [0,255]。如果你用的是归一化到 [0,1] 的流程保存时乘以 255 再 clamp如果你用了 ImageNet 均值和方差要先把均值加回来。检查顺序先打印输出 tensor 的 min 和 max如果都是负数或接近 0问题就出在这。5.5 server.py 与 client_show.py 之间连不上现象先启动server.py再启动client_show.py客户端窗口一直黑屏或者直接抛 connection refused。 原因两类原因最多——客户端连的 IP 写成了别的机器地址或者端口不一致另一种是服务器端没有把检测结果显示到帧上就发送客户端拿到的是空帧。 解决先用127.0.0.1和固定端口在本地测通再换成实际部署 IP。测通后先用client.py打一段纯文本测试确认服务器响应正常再开显示画面的client_show.py。如果画面还是空检查 server 端发送的帧有没有经过编码cv2.imencode(.jpg, frame)这一步容易漏。6. 最后一步把模型接到 client_show.py完整跑一遍验证链路训练完的模型不要只停在测试图片上把它接到部署脚本里跑通一次才能算真正落地。6.1 调用顺序与基本命令部署链路分三段顺序不能乱python demo.py --image test.jpg --config configs/vgg_ssd512_voc0712.yaml \ --weights outputs/vgg_ssd512_voc0712/best_mAP.pth python server.py --config configs/vgg_ssd512_voc0712.yaml \ --weights outputs/vgg_ssd512_voc0712/best_mAP.pth \ --port 8085 python client_show.py --server 127.0.0.1 --port 8085demo.py先验证模型本身能不能跑出结果server.py把模型包装成服务client_show.py作为展示端。这三条命令各自独立demo.py跑不通就不要往后面走了。6.2 一个验证模型的直接技巧训练指标好看不等于停车位识别靠谱。我会额外写一段小脚本把模型预测框和标注框的中心点距离算出来距离小于框宽的 30% 就算命中import numpy as np def judge_hit(pred_box, gt_box, threshold_ratio0.3): pred_cx (pred_box[0] pred_box[2]) / 2 pred_cy (pred_box[1] pred_box[3]) / 2 gt_cx (gt_box[0] gt_box[2]) / 2 gt_cy (gt_box[1] gt_box[3]) / 2 dist np.sqrt((pred_cx - gt_cx) ** 2 (pred_cy - gt_cy) ** 2) gt_w gt_box[2] - gt_box[0] return dist gt_w * threshold_ratiothreshold_ratio设 0.3 是经验值这个比例下既能容忍检测框轻微偏移又不会把明显错位的框算成命中。把这个函数套到验证集上跑一遍比 mAP 更直观地反映“空车位有没有被找到”。从那以后我每次调完模型都强制把demo.py → server.py → client_show.py这条链路完整走一遍再顺手算一轮中心点命中率。光看训练曲线永远发现不了通道顺序、NMS 阈值、端口配置这些藏在链路深处的坑。希望这份拆解能让你拿到源码包后少花几个晚上在环境配置和玄学调参上把时间留给真正该调的模型参数帮到你。本文还有配套的精品资源点击获取 SSD目标检测实战：拆解54个Python文件，实现空停车位识别
简介这套基于Python的SSD-Demo项目专注于空停车位自动识别面向智能交通、智能停车场管理及深度学习目标检测学习者可用于快速理解SSD算法从训练到部署的完整流程。压缩包共78个文件其中61个Python源码文件构成主体覆盖SSD网络结构、数据预处理、训练评估与推理逻辑5个XML配置文件定义模型参数与IDE工作区另含YAML配置文件、说明文档、Git管理文件及测试图片等整体包体仅282KB结构清晰易检索。目前已有314人浏览学习适合具备一定Python基础、希望结合具体场景上手SSD检测的开发者。借助demo、server、client等脚本可搭建简单的客户端-服务器架构实时查看车位检测结果通过分析工程目录中的anchors、backbone、box_head等模块设计还能掌握模型搭建与模块化组织的实践思路为后续二次开发或竞赛项目提供可复用范本。1. 空停车位识别实战把 SSD 检测器从 54 个 Python 文件里拆明白停车场摄像头画面里真正稀缺的不是“识别”这个动作而是响应速度——车开进通道时模型必须在一个画面周期里判断哪些车位是空的。SSDSingle Shot MultiBox Detector恰好是这条路线上最经典的选择之一一次前向完成边框回归和分类不需要区域提议。这份源码包用 Python 实现了 SSD 的空停车位识别 Demo68 个文件里 54 个是 Python 源码覆盖数据读取、anchor 生成、模型训练、NMS 后处理还有 server.py 与 client_show.py 组成的客户端-服务器演示链路。适合两类人刚开始学目标检测想有一份能完整读懂的项目或者已经在调参想对照看看常见配置边界和踩坑记录。2. 源码结构排查54 个 Python 文件怎么分成三条主链路拿到压缩包先不要急着跑 demo.py先把目录摊开。这个工程不是单文件脚本而是按训练、推理、部署三条链路组织的。先花十分钟把结构认清后面调参会少走很多弯路。2.1 关键目录与文件职责映射第一遍看源码建议按“配置 → 数据 → 模型 → 训练引擎 → 工具函数”这条线扫不要从上往下挨个读。下面这张表是我排查时画的功能映射可以直接对着找文件目录 / 文件承担的职责你在调参时最可能动它的位置configs/vgg_ssd512_voc0712.yaml全局配置模型、输入尺寸、anchor、学习率所有参数的唯一入口data/datasets/build.py构建 VOC 格式数据集把 xml 标注转成训练样本改类别数、改标注路径data/transforms/图像预处理缩放、翻转、颜色抖动、归一化训练和推理必须保持一致data/samplers/正负样本采样策略基本不用动modeling/backbone/VGG16 骨干网络换骨干时替换这里modeling/box_head/分类头 回归头输出预测框偏移调输出通道数时注意modeling/anchors/生成默认框anchor检测精度不稳时先查这里engine/trainer.py训练主循环改 batch size、梯度裁剪engine/inference.py推理主流程改置信度阈值solver/lr_scheduler.py学习率调度训练后期掉点先看这里utils/box_utils.pyanchor 编解码、IoU 计算预测框位置不对时重点查utils/nms.py非极大值抑制重叠框多就调 NMS 阈值utils/checkpoint.py保存和恢复断点恢复训练时用到utils/model_zoo.py加载预训练权重训练不收敛时改加载方式这份工程里有一个容易被忽略的文件是modeling/backbone下面的separable_conv.py。它不是 SSD 原始论文必带的部分而是把标准卷积替换成深度可分离卷积的轻量化改动后面单独展开讲。2.2 vgg_ssd512_voc0712.yaml 参数解读整个项目的配置集中在configs/vgg_ssd512_voc0712.yaml这个文件里。文件名已经很直白骨干是 VGG输入分辨率 512数据集按 VOC0712 的协议组织。它的核心段落大致长这样我摘出几个关键字段model: num_classes: 21 # VOC 的 20 类 背景 backbone: vgg16 input_size: [512, 512] anchors: feature_maps: [64, 32, 16, 8, 4, 2] # 6 层特征图 aspect_ratios: - [2, 3] - [2, 3] - [2, 3] - [2, 3] - [2, 3] - [2, 3] scales: [0.07, 0.15, 0.33, 0.51, 0.69, 0.87] box_coder: center_variance: 0.1 size_variance: 0.2 train: batch_size: 8 base_lr: 0.001 epochs: 120这里的feature_maps是 512 输入下六层特征图的尺寸每一层负责检测不同尺度的目标64×64 的浅层特征图感受野小负责小目标2×2 的深层特征图负责大目标。aspect_ratios是每个 anchor 的宽高比2 和 3 代表横向拉长的框对停车位这种扁长形状相对友好。scales是每层 anchor 相对输入图像的尺度比例从 0.07 到 0.87 逐层放大。box_coder里的两个 variance 是 SSD 官方实现里 decode 预测框时的缩放系数center_variance0.1和size_variance0.2是论文配套代码的默认值。这两个数字直接影响预测框从“偏移量”还原成“真实坐标”时的抖动幅度后面避坑章节会专门说。2.3 separable_conv.py 与轻量化改法原始 SSD 的 VGG 骨干在 512 输入下计算量不低边缘设备跑实时推理会吃力。separable_conv.py这文件做的就是拆解把一个标准卷积拆成 depthwise 卷积和 pointwise 卷积两步。常见的实现写法是这样的import torch.nn as nn class SeparableConv2d(nn.Module): def __init__(self, in_channels, out_channels, kernel_size3, stride1, padding1): super().__init__() self.depthwise nn.Conv2d( in_channels, in_channels, kernel_sizekernel_size, stridestride, paddingpadding, groupsin_channels ) self.pointwise nn.Conv2d(in_channels, out_channels, kernel_size1) def forward(self, x): return self.pointwise(self.depthwise(x))groupsin_channels是深度可分离卷积的关键每个输入通道先单独做卷积再用 1×1 卷积把通道信息混合。相比标准卷积参数大约减少到原来的三分之一在车位上部署时帧率能明显提上去。但要注意一点训练时如果用标准 VGG 加载预训练权重结构对不上。我一般建议轻量化改造放在训练完成后做或者直接从头训这个轻量版不要想着半路切结构。2.4 model_zoo.py 和 checkpoint.py 的配合model_zoo.py负责加载预训练权重checkpoint.py负责保存训练中间结果。两者容易混淆我踩过一次把 checkpoint 直接往 model_zoo 的加载函数里塞结果 key 对不上模型参数全随机初始化了。常见做法是预训练权重只给骨干网络用完整模型参数走 checkpoint 恢复import torch from utils.model_zoo import load_pretrained from utils.checkpoint import save_checkpoint, load_checkpoint model build_ssd_model(cfg) load_pretrained(model.backbone, vgg16_reducedfc.pth, strictFalse) # 训练中断后恢复 state load_checkpoint(outputs/vgg_ssd512_voc0712/checkpoint.pth) model.load_state_dict(state[model])strictFalse是有意为之预训练权重缺少分类头或额外层时跳过缺失 key 而不是报错。恢复训练时则必须用strictTrue否则有些层没加载进去训练等于从头开始。3. 数据准备把停车位图片整理成 SSD 能吃的 VOC 格式SSD 的训练代码通常直接吃 Pascal VOC 目录结构这份工程也延续了这个约定。你从网上下载的停车场图片不会天然是这个格式需要先转换。3.1 目录结构与 label 文件标准的 VOC 目录三段式结构是这样组织的VOCdevkit/ VOC2007/ JPEGImages/ # 原始图片 Annotations/ # 每张图对应的 xml 标注 ImageSets/ Main/ train.txt # 训练图片名列表 val.txt # 验证图片名列表xml 里关键字段是bndbox里面是目标框的左上角和右下角坐标。我见过不少新手把 xml 里的xmin/ymin和xmax/ymax顺序搞反或者把width/height当成框坐标用。标注框坐标一定是像素级整数直接画到图上能框住车位线才说明标注是对的。3.2 一个能直接跑的 VOCDataset 读取代码工程里的data/datasets/build.py是现成的读取器核心逻辑是解析 xml 并返回图像、真实框、类别。如果你想自己控制标注格式常见做法是写一个最小的 VOCDatasetimport os import xml.etree.ElementTree as ET import torch from PIL import Image class VOCDataset(torch.utils.data.Dataset): def __init__(self, root, image_set, transformsNone): self.root root self.transforms transforms self.ids [] with open(os.path.join(root, ImageSets, Main, f{image_set}.txt)) as f: for line in f: self.ids.append(line.strip()) def __getitem__(self, idx): img_id self.ids[idx] img_path os.path.join(self.root, JPEGImages, f{img_id}.jpg) xml_path os.path.join(self.root, Annotations, f{img_id}.xml) img Image.open(img_path).convert(RGB) boxes, labels [], [] root ET.parse(xml_path).getroot() for obj in root.findall(object): name obj.find(name).text bndbox obj.find(bndbox) xmin float(bndbox.find(xmin).text) ymin float(bndbox.find(ymin).text) xmax float(bndbox.find(xmax).text) ymax float(bndbox.find(ymax).text) boxes.append([xmin, ymin, xmax, ymax]) labels.append(self.class_names.index(name)) return img, torch.tensor(boxes), torch.tensor(labels)这段代码有两个参数值得注意image_set是train还是val决定了读哪份图片列表self.transforms不能为 None因为后续训练代码会强制要求输出固定尺寸的 tensor。如果你把标注框坐标读进来直接用记得归一化到 [0,1]否则和 anchor 计算的位置全乱套。3.3 transforms 流水线翻转、颜色抖动、归一化SSD 数据增强的核心是随机翻转、随机裁剪和颜色抖动。data/transforms里实现的顺序一般是先随机水平翻转再随机裁剪出包含至少一个真实框的区域然后缩放到 512×512最后做减均值除方差的归一化。随机裁剪这一步对停车位场景很重要。摄像头画面里车位上经常有其他车辆遮挡随机裁剪能让模型学会从局部特征判断车位状态而不是依赖全局布局。归一化时要注意工程里如果用的是 RGB 顺序推理时就不要切 BGR很多 OpenCV 读图踩坑就是通道顺序不一致导致的。3.4 类别定义从 VOC 21 类改成空车位专用VOC 默认 21 类而空车位识别只需要“车位空/占用”甚至只分“空车位”和“背景”两类。修改时有三处必须同步第一配置文件里的num_classes从 21 改成 2 或 3第二数据集的class_names列表按你的标注顺序重排背景永远是索引 0然后才是空车位、占用车位第三box_head 末尾的输出通道数是num_classes * 4改配置后模型结构会自动变。我建议标签最简方案用两类0 是背景1 是空车位。占用车位不单独标注没标成空车位的框全部算背景。这样训练难度小评估指标也直观。4. 训练流程从 train 命令到 loss 曲线阅读数据准备好之后进入训练环节。这份工程没有把训练封装成一条命令打天下而是把逻辑拆在engine/trainer.py和solver/里读代码比跑代码更重要。4.1 trainer.py 每一轮在做什么训练主循环做的事情是标准的 SSD 流程从 dataloader 拿一个 batch图像过 backbone 提特征六层特征图分别进分类头和回归头得到预测偏移量和类别分数同时用真实框与 anchor 做匹配分配正负样本最后计算定位损失和分类损失反传更新参数。锚点匹配是这里最容易出问题的一步。真实框和 anchor 的 IoU 大于 0.5 才被当成正样本低于 0.5 且高于负样本阈值的才参与负样本挖掘。如果数据集标注框偏小正样本数量可能不够loss 看起来正常但检测效果很差。我一般会在训练前打印一下每个 epoch 正样本的平均数量低于 50 就得检查标注和 anchor 配置。4.2 常用训练命令与参数训练入口不是自动发现的我的习惯是直接走 engine 模块python -m engine.trainer \ --config configs/vgg_ssd512_voc0712.yaml \ --batch-size 8 \ --base-lr 1e-3 \ --epochs 120 \ --eval-interval 10 \ --output-dir outputs/vgg_ssd512_voc0712 \ --resume outputs/vgg_ssd512_voc0712/checkpoint.pth--base-lr用 1e-3 是 SSD 系列比较常见的起点如果显存大把 batch size 提到 16学习率可以相应提到 2e-3。--eval-interval表示每训练 10 个 epoch 在验证集上跑一次 mAP这一步不建议省不然训完发现全是背景才算白跑。--resume是可选参数训练中断后带着这个参数重跑会从断点继续。如果训练时显存报 OOM先把 batch size 降到 4不要直接改输入尺寸。输入尺寸改了anchor 配置里所有 feature map 尺寸、scale 参数全部要跟着改很容易翻车。4.3 loss 怎么读训练日志会逐 epoch 打印 loss 分量典型输出长这样Epoch 10 | loc_loss 1.231 | conf_loss 1.872 | total 3.103 | lr 1.0e-3 Epoch 20 | loc_loss 0.984 | conf_loss 1.216 | total 2.200 | lr 1.0e-3loc_loss是回归损失conf_loss是分类损失。前 30 个 epoch 里conf_loss比loc_loss高是正常的因为负样本数量远大于正样本。如果 50 个 epoch 后conf_loss还在 1.5 以上多半是类别不均衡或者标注错误太多。total loss下降到 1.0 之后速度会明显变慢这是正常的。此时不要盲目加 epoch先看验证 mAP 有没有跟着涨如果 loss 在降但 mAP 不动大概率是正样本匹配出了问题。4.4 checkpoint 保存与恢复checkpoint.py的保存内容一般包含 model 参数、优化器状态、当前 epoch 和 best mAP。恢复时只恢复 model 不恢复优化器学习率会回到初始值这会导致后半段训练效果变差。from utils.checkpoint import save_checkpoint, load_checkpoint save_checkpoint({ epoch: epoch, model: model.state_dict(), optimizer: optimizer.state_dict(), best_mAP: best_mAP, }, output_dir) state load_checkpoint(os.path.join(output_dir, checkpoint.pth)) model.load_state_dict(state[model]) optimizer.load_state_dict(state[optimizer])训练中断恢复最怕的坑是数据加载器的随机种子不一致。恢复训练后前几个 epoch 的 loss 可能小幅回升这不一定是最佳权重注意自动保存 best mAP 模型即可。5. 空停车位识别避坑5 条踩过的问题和解决办法这个工程跑通不难跑好很难。下面五条是我实际调这个项目时踩过的前两条是原理问题后三条更偏部署。5.1 训练 loss 前几个 epoch 不降反升现象loss 一上来就是 12 左右前 10 个 epoch 不降反升甚至飙到 20。 原因最常见的是学习率过大SSD 在 batch size 8 的情况下base_lr超过 2e-3 很容易震荡另一个隐蔽原因是标注框没有归一化导致匹配时 IoU 全是 0。 解决先把base_lr降到 1e-3确认 xml 里的坐标经过img_width和img_height归一化后再进匹配器。改完这两个地方loss 通常会在 5 个 epoch 内掉头向下。5.2 预测框全部偏到图像边缘现象验证时大量检测框紧贴图片上下左右边缘置信度还很高框的尺寸也基本都是同一个尺度。 原因这是 anchor decode 的问题。center_variance和size_variance设成 1 或者干脆缺失时预测偏移量会被放大极端情况下直接推出画面边界。另一个可能原因是对特征图上的每个 anchor 没有做clip到 [0,1]。 解决先确认box_coder的 variance 是[0.1, 0.1, 0.2, 0.2]再用一个已知单框图片做单元测试手动标注一个框看 decode 出来的坐标和标注是否接近。5.3 512 分辨率把显卡显存吃满现象batch size 开到 16 直接 OOM8 也有时候不稳定。 原因VGG16 骨干在 512 输入下中间特征图尺寸是 256×256加上 6 层 SSD 预测头显存占用比 300 输入翻了一倍还多。 解决第一优先降 batch size 到 4同时把eval-interval拉长第二优先用separable_conv.py里的轻量化卷积替换标准 3×3 卷积第三个办法是打开 AMP 混合精度训练把torch.cuda.amp包在 forward 和 backward 外面显存占用能再降三分之一。5.4 demo.py 推理出来的图是全黑的现象用demo.py test.jpg跑推理输出图完全黑色但程序没有报错。 原因输入图片在 transforms 阶段做了减均值推理时没有做反变换或者样本归一化后没有乘回原图范围直接转 uint8 保存。 解决在保存前把 tensor 恢复成 [0,255]。如果你用的是归一化到 [0,1] 的流程保存时乘以 255 再 clamp如果你用了 ImageNet 均值和方差要先把均值加回来。检查顺序先打印输出 tensor 的 min 和 max如果都是负数或接近 0问题就出在这。5.5 server.py 与 client_show.py 之间连不上现象先启动server.py再启动client_show.py客户端窗口一直黑屏或者直接抛 connection refused。 原因两类原因最多——客户端连的 IP 写成了别的机器地址或者端口不一致另一种是服务器端没有把检测结果显示到帧上就发送客户端拿到的是空帧。 解决先用127.0.0.1和固定端口在本地测通再换成实际部署 IP。测通后先用client.py打一段纯文本测试确认服务器响应正常再开显示画面的client_show.py。如果画面还是空检查 server 端发送的帧有没有经过编码cv2.imencode(.jpg, frame)这一步容易漏。6. 最后一步把模型接到 client_show.py完整跑一遍验证链路训练完的模型不要只停在测试图片上把它接到部署脚本里跑通一次才能算真正落地。6.1 调用顺序与基本命令部署链路分三段顺序不能乱python demo.py --image test.jpg --config configs/vgg_ssd512_voc0712.yaml \ --weights outputs/vgg_ssd512_voc0712/best_mAP.pth python server.py --config configs/vgg_ssd512_voc0712.yaml \ --weights outputs/vgg_ssd512_voc0712/best_mAP.pth \ --port 8085 python client_show.py --server 127.0.0.1 --port 8085demo.py先验证模型本身能不能跑出结果server.py把模型包装成服务client_show.py作为展示端。这三条命令各自独立demo.py跑不通就不要往后面走了。6.2 一个验证模型的直接技巧训练指标好看不等于停车位识别靠谱。我会额外写一段小脚本把模型预测框和标注框的中心点距离算出来距离小于框宽的 30% 就算命中import numpy as np def judge_hit(pred_box, gt_box, threshold_ratio0.3): pred_cx (pred_box[0] pred_box[2]) / 2 pred_cy (pred_box[1] pred_box[3]) / 2 gt_cx (gt_box[0] gt_box[2]) / 2 gt_cy (gt_box[1] gt_box[3]) / 2 dist np.sqrt((pred_cx - gt_cx) ** 2 (pred_cy - gt_cy) ** 2) gt_w gt_box[2] - gt_box[0] return dist gt_w * threshold_ratiothreshold_ratio设 0.3 是经验值这个比例下既能容忍检测框轻微偏移又不会把明显错位的框算成命中。把这个函数套到验证集上跑一遍比 mAP 更直观地反映“空车位有没有被找到”。从那以后我每次调完模型都强制把demo.py → server.py → client_show.py这条链路完整走一遍再顺手算一轮中心点命中率。光看训练曲线永远发现不了通道顺序、NMS 阈值、端口配置这些藏在链路深处的坑。希望这份拆解能让你拿到源码包后少花几个晚上在环境配置和玄学调参上把时间留给真正该调的模型参数帮到你。本文还有配套的精品资源点击获取