简介基于Python和Faster-RCNN的PCB元器件缺陷检测项目提供完整源码、开发文档与项目解析面向毕业设计、课程设计与实际项目开发场景。项目代码已经过严格测试可直接运行并在此基础上二次扩展。资源包共79个文件其中Python源码35个编译缓存39个另含Markdown文档、配置文件与许可证说明压缩包整体仅214KB轻量且便于部署。内容覆盖VOC0712及自定义数据集的训练、预测、评估全流程包含数据标注与划分脚本、数据扩充工具、多种骨干网络如VGG16、ResNet50以及NMS等后处理模块能够清晰展示Faster-RCNN从数据准备到模型推理的实现细节。附带的项目解析和开发文档对训练参数、预测流程及评估指标做了说明可帮助读者快速理解算法结构并迁移到自身场景目前已有379人浏览学习适合具备一定深度学习基础、希望系统掌握目标检测项目开发的用户参考使用。1. PCB缺陷检测这套源码先跑通再谈mAP很多同学拿到这套基于 python Faster-RCNN 的 PCB 元器件缺陷检测源码第一反应是把环境配好然后直接跑 train.py。但真正按毕业设计标准去复现时前面跑得顺不代表后面不出事直接用 VOC0712 的默认 anchors 跑自己的 PCB 板子图像训练到一半 Loss 就开始震荡最后 mAP 惨不忍睹。这份资源的好处是开发文档和源码是配套的Data_preproces、nets、utils 这些模块都分得清清楚楚适合当课程设计或毕业设计的主项目。读完这篇笔记你会知道这套代码的数据准备、训练、预测、评估四条线分别怎么走以及哪些参数必须改、哪些坑必须提前绕开。2. 项目全貌与选型Faster-RCNN做PCB缺陷检测为什么更稳2.1 源码结构从数据处理到推理的完整链路打开压缩包先别急着点 train.py。这套代码不是单文件 demo而是一个带数据预处理、模型训练、预测、评估闭环的完整工程。按职责来划分大致是下面这张表里的模块模块主要文件职责数据准备Data_preproces/voc_annotation.py、order_name.py、data_expansion.py将 VOC 标注转成训练格式、统一类别顺序、做数据扩张网络结构nets/rpn.py、classifier.py、resnet50.py、resnet101.py、vgg16.py、resnet50_FPN.py、resnet50_ECA_FPN.pyRPN 候选区域提取与分类回归头多个骨干网络可切换训练流程train.py、FasterRCNN_train.py、dataloader.py、utils_fit.py、callbacks.py训练入口、数据加载、损失计算、回调与模型保存预测推理predict.py、frcnn_predict.py加载权重做单张图片预测也支持批量处理评估指标get_map.py、utils_map.py计算 mAP、Precision、Recall输出 PR 曲线这个工程和常见的单文件训练脚本最大的差别是替换数据集不需要动网络主体。你换一批自己的板卡图像只需要改 Data_preproces 下的脚本和类别文件nets 和 utils 基本不用碰。训练步骤直接写在 README 里跟着走就是先数据、后训练、再评估的顺序和下面几章的内容一一对应。对课程设计和毕业设计来说这种模块化的好处是你答辩时可以清楚地说出每个文件的作用老师追问起来也不慌。2.2 为什么选两阶段的Faster-RCNN而不是单阶段模型PCB 元器件缺陷检测和通用目标检测有个很大区别缺陷区域往往非常小。比如焊点虚焊、电容极性反、贴片偏移在整张板卡图像里经常只占几十个像素。单阶段检测器直接在特征图上回归类别和坐标对小目标的特征表达不够充分Faster-RCNN 先由 RPN 生成候选区域再对每个候选框做二次分类和回归天然适合这种小目标多、漏检代价高的场景。你的板卡图像里元件密度越高这个优势越明显。另外一点对做课题很重要Faster-RCNN 的 RPN 和检测网络是分开的训练时哪个环节出问题更容易定位。我可以把 RPN 输出的候选框可视化给老师看证明候选区域确实覆盖到了元件位置这比只丢一张训练曲线有说服力得多。骨干网络方面项目里给了五个选择我的建议是骨干网络特点适用场景vgg16结构简单、参数多、训练慢学习网络原理、单机跑通流程resnet50参数适中、训练快、显存友好自制 PCB 数据集首选resnet101更深、理论精度上限更高显存充足、样本量大时使用resnet50_FPN特征金字塔、多尺度融合板卡上元件大小差异大的情况resnet50_ECA_FPNFPN 加 ECA 通道注意力丝印复杂、背景干扰多的板卡这里解释一下 ECA它是在通道注意力上用一维卷积替代全连接层相比 SENet 少了降维操作计算量增加很小但对小目标的特征表达有实际帮助。如果你训练的板卡图像背景比较复杂丝印和走线密集优先试 resnet50_ECA_FPN如果只是想快速把流程跑通先用 resnet50 最省事。注意切换骨干不是改一行配置就能解决的。不同骨干对应的预训练权重文件不同从 resnet50 切换到 resnet50_ECA_FPN 时model_path 必须同步指向对应骨干的权重否则加载时会报 shape 不匹配。这是新手最容易翻车的地方权重和骨干各说各话训练出来的模型完全不能用。3. 数据准备VOC标注、先验框聚类和数据扩张三板斧3.1 数据集目录与VOC标注转换从xml到txt的核心代码训练前必须把数据整理成 VOC 格式目录结构长这样VOCdevkit/ VOC2007/ JPEGImages/ # 板卡原图 Annotations/ # 每张图对应的 xml 标注 ImageSets/Main/ # train.txt、val.txt、test.txt这个格式不用重新发明用 LabelImg 标注出来的结果就是这个结构。xml 里每个 object 节点记录类别名和 bndbox 四个坐标voc_annotation.py 的职责就是把 xml 解析出来转成一行一条训练标注文本。下面是这个脚本的核心逻辑import xml.etree.ElementTree as ET sets [(2007, train), (2007, val), (2007, test)] # classes 顺序要和 model_data/voc_classes.txt 完全一致 classes [solder, capacitor, resistor, chip] def convert_annotation(year, image_id, list_file): xml_path VOCdevkit/VOC%s/Annotations/%s.xml % (year, image_id) in_file open(xml_path, encodingutf-8) tree ET.parse(in_file) root tree.getroot() for obj in root.iter(object): difficult obj.find(difficult).text cls obj.find(name).text # difficult 为 1 的样本训练时直接跳过避免把难例当噪声 if int(difficult) 1 or cls not in classes: continue xmlbox obj.find(bndbox) b (int(float(xmlbox.find(xmin).text)), int(float(xmlbox.find(ymin).text)), int(float(xmlbox.find(xmax).text)), int(float(xmlbox.find(ymax).text))) list_file.write( %s,%s,%s,%s,%s % (b[0], b[1], b[2], b[3], cls))这段代码里最容易被忽略的是 classes 列表的顺序。voc_annotation.py 写进 txt 的是类别名而训练时类别名会按 model_data/voc_classes.txt 的顺序映射成索引。两个文件的顺序如果对不上模型就会把 A 类的框当成 B 类来学。我一般会先跑一遍 Data_preproces 下的 order_name.py 把类别排好顺序再执行 voc_annotation.py 生成标注文件这样两边顺序一定是一致的后面训练就不用回头排查这种低级错误。3.2 先验框聚类kmeans_anchors 里两个必须改的参数Faster-RCNN 虽然不像 YOLO 那样强依赖先验框但 anchors 的尺寸如果和你的 PCB 缺陷尺寸差太远RPN 的召回率会明显掉下去。项目里的 kmeans_anchors 脚本干的就是这个事把标注框的宽高做聚类得到一组适合你数据集的先验框替代默认的通用 anchors。import numpy as np def iou(box, clusters): # box: [w, h] 单个标注框, clusters: [k, 2] 当前聚类中心 x np.minimum(clusters[:, 0], box[0]) y np.minimum(clusters[:, 1], box[1]) intersection x * y box_area box[0] * box[1] cluster_area clusters[:, 0] * clusters[:, 1] iou_ intersection / (box_area cluster_area - intersection 1e-6) return iou_跑聚类的时候我会先把标注框的像素宽高除以输入尺寸比如统一除以 600得到归一化值再聚类。这样换不同分辨率的板卡图像时anchors 还能复用。聚类数量 k 默认取 9对应 RPN 的 anchor 数量。如果你的板卡上元件大小非常统一取 6 到 9 都行效果差距不大如果同一张图上既有大的电解电容又有小的贴片电阻9 个 anchors 更稳妥。提示聚类跑完后输出的 anchors 要写回模型配置里同时把训练脚本里对应的 anchor 参数同步替换。这块不改的话前面数据准备做得再好训练出来的候选框也天生偏大或偏小RPN 的召回率会一直上不去。3.3 数据扩张翻转和亮度扰动标签必须跟着图像一起变PCB 板卡图像的采集成本高不少同学手里只有几百张图直接训练很容易过拟合。项目里的 data_expansion.py 提供水平翻转、垂直翻转、亮度扰动等增强方式。这里有一个很多人踩过坑的细节图像翻转后标注框坐标必须同步变换否则模型学的是错位标签训练 Loss 再低预测框也是歪的。# 水平翻转时xmin 和 xmax 的换算 w img.width new_xmin w - box[xmax] new_xmax w - box[xmin]翻转必须做坐标换算亮度扰动则不用动标注框因为目标位置没有变。我一般会把扩张倍数控制在 2 到 3 倍不要贪多。PCB 缺陷样本本身特征集中翻太多反而让模型学到翻转产生的伪特征这是我自己做类似项目时用血泪换来的经验。另外做了数据扩张之后验证集里不能出现扩张出来的图像否则评估结果虚高答辩时被追问数据来源会很尴尬。4. 训练流程从VOC0712到自制数据集的参数配置4.1 环境准备与依赖安装训练跑不起来大概率是环境问题不是代码问题。项目里有 requirements.txt安装依赖时注意两点一是 PyTorch 版本必须和本机 CUDA 匹配优先用官方安装命令不要直接 pip 装 CPU 版本然后去跑 GPU 训练二是 opencv-python 装完要验证一下导入是否正常部分版本对某些格式的图像读入有兼容问题Dataloader 读图失败会直接中断训练。python -m pip install -r requirements.txt python -c import torch, cv2; print(torch.__version__, cv2.__version__)如果机房或自己的电脑没有 GPU纯 CPU 也能跑通整个流程只是要把 batch_size 调小、迭代轮数减少。用来验证代码逻辑、完成课程设计的功能演示没有问题但想要在论文里写有说服力的实验对比还是建议找个显卡环境最低 8G 显存就够用。4.2 训练VOC0712默认参数下的完整操作第一步先拿 VOC0712 把流程整体跑通确认环境没问题再换自己的数据。train.py 是训练入口里面有几组参数是核心我一般会这样配置if __name__ __main__: # 数据集路径和类别文件 VOCdevkit_path VOCdevkit classes_path model_data/voc_classes.txt # 骨干网络选择 # 0resnet50, 1resnet101, 2vgg16, # 3resnet50_FPN, 4resnet50_ECA_FPN backbone resnet50 # 输入尺寸Faster-RCNN 常用 600x600 input_shape [600, 600] # 冻结阶段骨干网络参数不更新显存占用小 Init_Epoch 0 Freeze_Epoch 50 Freeze_batch_size 4 # 解冻阶段全部参数参与训练需要更小 batch UnFreeze_Epoch 100 Unfreeze_batch_size 2这段配置的逻辑是典型的先冻结后解冻。前 50 轮骨干网络梯度不更新只训练 RPN 和分类回归头部显存压力小收敛也快50 轮之后解冻全部层用更小的 batch_size 和更低的学习率做整体精调。Freeze_batch_size 和 Unfreeze_batch_size 不一样是有原因的解冻后所有层都要算梯度显存占用接近翻倍8G 显存的卡按这个配置基本是上限了。4.3 训练自己的PCB数据集类别、anchor、权重三处对齐把 VOC0712 跑通后换成自己的板卡图像需要在三个地方对齐第一类别文件。model_data/voc_classes.txt 改成你的类别列表顺序必须和 3.1 节里 voc_annotation.py 的 classes 列表完全一致。第二先验框。按 3.2 节的方法用 kmeans_anchors 对自制数据集的标注框重新聚类把得到的 anchors 替换回模型配置。这一步不能省PCB 元件尺寸和自然图像目标差太远。第三预训练权重。如果数据集中以贴片电阻、电容这类小目标为主建议保留 ImageNet 预训练权重来初始化骨干不要从头训练。原因很简单PCB 缺陷数据集往往只有几百到上千张从头训练卷积特征根本学不够收敛又慢又容易过拟合。train.py 里加载权重的部分会检查字典形状如果骨干选了 FPN 版本权重路径也必须换成 FPN 版的。这里我吃过亏权重和骨干不一致时程序不一定会显式报错可能只是静默加载失败等训练完一看 Loss 根本没降白跑十几个小时才意识到问题出在权重。4.4 训练过程的监控callbacks 与模型保存项目里的 callbacks.py 实现了训练过程中的回调逻辑包括每个 epoch 结束时保存验证 Loss 最低的权重、学习率衰减、早停等。训练时我建议盯三个指标训练 Loss、验证 Loss、以及当前 epoch 保存的权重路径。如果验证 Loss 在某个阶段之后持续上升而训练 Loss 还在降就是过拟合信号这时应该把 UnFreeze_Epoch 调小或者加大数据扩张的强度。不用纠结每次训练都完整跑完 100 轮验证集 Loss 连续 15 个 epoch 不降就可以提前停掉模型保存在中间那轮后面再补几次小学习率精调就行。5. 预测与评估权重加载、mAP计算与避坑清单5.1 预测阶段预训练权重和自己训练权重的加载区别预测入口有两个predict.py 适合一张一张验证效果frcnn_predict.py 适合批量处理目录下的图片。权重加载逻辑在模型里关键是 model_path 和 backbone 必须配对下面是单张图片预测的常见写法from frcnn import FRCNN # 换成自己训练好的权重路径即可 model_path model_data/frcnn_weights.pth frcnn FRCNN() img Image.open(test_pcb.jpg) r_image frcnn.detect_image(img) r_image.save(result.jpg)detect_image 内部做了四件事把输入图缩放到 600x600、前向推理、解码 bbox 和置信度、NMS 去重。用自己的权重时只改 model_path 即可其余代码不用动。有一个细节要注意训练时做了数据扩张但预测时绝对不要做同样的扩张预测输入永远用原图扩张只会把框的位置带偏。5.2 评估get_map.py 的流程与指标解读get_map.py 会遍历测试集逐张图预测并记录置信度、类别、bbox然后按类别计算 Precision 和 Recall最终得到 mAP。运行方式很直接python get_map.py跑完后会生成评估结果目录里面有每个类别的 PR 曲线和指标文件。看结果时留意两个点一是 mAP 只是整体指标对 PCB 缺陷检测来说虚焊、桥连这类小目标应该单独看它的 Recall这个值才算数二是如果某个类别的样本特别少它的 AP 波动会非常大这是数据集分布问题不是模型调参的问题。5.3 避坑清单五个常见的训练与预测问题现象训练到第 20 个 epoch 左右 Loss 变成 NaN。原因学习率偏大或者 anchors 没针对数据集重新聚类RPN 的回归梯度爆掉了。解决把初始学习率降到原来的五分之一用 kmeans_anchors 重新聚类并在训练配置里加上梯度裁剪。现象训练 Loss 正常下降但预测框整体偏向图片左上角。原因数据扩张时只翻了图像标注框坐标没有做水平翻转的换算标签和内容错位。解决检查 data_expansion.py 的坐标变换逻辑水平翻转后新 xmin 等于原图宽度减原 xmax。现象mAP 一直卡在低位怎么调参都上不去。原因类别索引错位voc_classes.txt 的顺序和 voc_annotation.py 里的 classes 列表顺序不一致模型把 A 类的框当成 B 类来学。解决先跑 order_name.py 统一类别顺序重新生成标注文件再训练。现象8G 显存跑冻结阶段没问题解冻后直接 Out of Memory。原因解冻后所有层都要计算梯度显存占用接近翻倍。解决把 Unfreeze_batch_size 调到 1如果还溢出再把输入尺寸调到 512x512代价是检测精度略微下降。现象预测速度很慢一张 600x600 的图要好几秒。原因在 CPU 上跑完整推理。解决评估阶段用 get_map.py 批量处理比单张循环快得多如果要在实际场景用把骨干换成 resnet50并考虑用 torchscript 导出加速。6. 进阶用 soft_nms 与数据扩张把检测结果再提一档6.1 soft_nms重叠缺陷漏检的救星PCB 板上元件排列密集普通 NMS 在去重时会把重叠度高的真目标一并删掉。项目里的 soft_nms.py 思路是不直接删除高 IoU 的框而是按重叠程度降低它的置信度这样密集排列的元件有机会被保留下来。# soft_nms 核心参数sigma 越大置信度衰减越平缓 def soft_nms(dets, sigma0.5, Nt0.3, threshold0.001, method2): # method2 表示 Gaussian 加权对重叠目标最友好 for i in range(N): if scores[i] threshold: for j in range(i 1, N): iou_ compute_iou(dets[i], dets[j]) if iou_ Nt: weights np.exp(-(iou_ * iou_) / sigma) scores[j] * weightssigma 一般取 0.5。调小会让衰减更剧烈适合遮挡较少的场景调大则保留更多重叠框适合贴片元器件密集的板卡。我建议把普通 NMS 和 soft_nms 各跑一遍 get_map.py对比 mAP 再决定正式用哪个这是最省事的验证方法不用凭感觉拍脑袋。6.2 训练完必做的验证动作以及我的一个教训每个模型训练结束后我有一个强制习惯先跑 get_map.py 看指标再随机抽 20 张测试图可视化预测结果最后把预测错误最集中的图挑出来回看原图标注。上次做课程设计时偷懒跳过了这步以为指标和之前差不多就直接打包提交结果答辩现场放出一张漏检图老师一眼看出问题被问得有点狼狈。从那以后我每次换数据集都会强制走一遍聚类 anchors、跑 VOC 数据验证环境、确认类别顺序、训练后可视化抽检。把这套源码和开发文档放在一起对照着做一遍按这个顺序能把大部分问题挡在训练之前希望帮到你。本文还有配套的精品资源点击获取