简介这是一套面向工业质检场景与计算机视觉学习者的主板质量检测系统源码基于Python与图像识别技术实现可用于电子制造环节的缺陷检测、目标识别与关键点分析等任务适合具备一定Python与深度学习基础、希望动手实践视觉检测项目的开发者参考。资源包共41个文件以34个Python脚本为核心涵盖推理、预处理、后处理与工具模块另含2个UI界面文件、2份说明文档及配置文件整体约102KB结构紧凑便于快速上手。内容涉及检测、关键点、多目标跟踪等多条推理链路并配有可视化与部署相关脚本能帮助读者理解从模型推理到界面展示的完整流程。目前已有447人学习下载可作为课程设计、毕业设计或工业视觉入门项目的参考素材便于在此基础上二次开发与功能扩展。1. 拆开这份主板质量检测源码它到底能跑出什么结果产线上最怕的不是没算法而是算法跑在笔记本上好好的一上工位就翻车。这份基于 Python 和图像识别的主板质量检测系统源码解决的就是从「单张图能识别」到「整条检测流程能落地」之间的那段距离。它把目标检测、关键点定位、多目标跟踪、属性识别这几条链路串在一起配合 PyQt 界面和 SAHI 切片推理做成了一套能直接对着主板图像做缺陷检测的桌面工具。适合谁做工业质检的算法同学、想拿图像识别做课程设计的学生、以及需要快速搭一个检测 Demo 给产线看的工程师。你拿到的是一个完整的工程目录不是单个脚本这意味着它更接近真实项目结构也意味着依赖和配置的坑会更多。2. 工程目录拆解从 A10-main 到 deeplearn 的模块分工2.1 核心推理链路infer.py 与 mot_jde_infer.py 各管什么拿到源码先别急着装环境把目录结构看明白能省掉后面一半的调试时间。根目录下最显眼的是infer.py这是整个检测系统的入口脚本负责加载模型、读取图像、执行推理并输出结果。旁边还有一个infer.py.bak这是备份文件说明作者在迭代过程中改过推理逻辑遇到infer.py跑不通时可以对比.bak看差异。mot_jde_infer.py和mot_sde_infer.py是两条不同的多目标跟踪推理路径。JDE 是 Joint Detection and Embedding 的缩写把检测和特征提取放在一个网络里做SDE 是 Separate Detection and Embedding检测和 ReID 分开跑。主板检测场景下如果只是单帧缺陷判断用infer.py就够如果要跟踪主板在传送带上的连续状态才需要动这两个文件。det_keypoint_unite_infer.py和mot_keypoint_unite_infer.py是把检测框和关键点联合推理的脚本。主板上的电容、接口、螺丝孔这些位置光靠检测框不够关键点能给出更精确的定位。keypoint_infer.py、keypoint_preprocess.py、keypoint_postprocess.py这三个文件构成关键点推理的完整前后处理链路。action_infer.py和attr_infer.py分别处理动作识别和属性识别。主板检测里动作识别可能用于判断机械臂是否完成插拔属性识别用于判断元件颜色、方向是否正确。deploy目录下是部署相关代码deeplearn目录放的是深度学习模型定义和权重加载逻辑SAHI目录是切片辅助推理的实现tools目录是辅助工具脚本opencv目录放的是 OpenCV 相关的封装。2.2 界面与配置ui.py、window.py 和 requirements.txt 的配合ui.py和mainwindow.ui是 PyQt 的界面文件。.ui文件是 Qt Designer 生成的 XML 布局描述ui.py是编译后的 Python 代码。Ui_mainwindow.py是另一个界面入口window.py负责窗口逻辑。这套界面不是摆设它把图像加载、推理触发、结果展示串成了一个可操作的流程。tracker_config.yml是跟踪器的配置文件里面定义了跟踪算法的参数比如最大丢失帧数、匹配阈值等。requirements.txt是依赖清单但这类项目的依赖清单往往不完整后面会专门讲怎么补。preprocess.py和utils.py是通用预处理和工具函数。benchmark_utils.py用于性能基准测试picodet_postprocess.py是 PicoDet 检测模型的后处理visualize.py负责把推理结果画到图上。提示先通读README.md里面通常有作者留下的环境版本和运行命令比你自己猜要快得多。3. 环境搭建与依赖安装Python 版本、CUDA 和那些没写进 requirements 的包3.1 Python 与 CUDA 版本选择别用最新版这类图像识别项目对版本很敏感。常见做法是 Python 3.8 到 3.10 之间选一个CUDA 用 11.6 或 11.8对应 PyTorch 1.12 到 2.0 的版本。如果你用 Python 3.12 配最新 PyTorch大概率会在加载模型权重时报错因为很多旧版算子已经废弃了。先确认显卡驱动支持的 CUDA 版本nvidia-smi输出右上角会显示CUDA Version: 11.8这样的信息这是驱动支持的最高 CUDA 版本不是你必须装的版本。装比它低的版本没问题装比它高的会直接报错。创建虚拟环境conda create -n mbqc python3.9 conda activate mbqcmbqc是环境名你可以改成任何名字。用 conda 而不是 venv 的原因是 conda 能同时管理 Python 版本和非 Python 依赖后面装 OpenCV 和 PyQt 时省事。3.2 安装 PyTorch 与补齐 requirements 之外的依赖先装 PyTorch不要直接pip install -r requirements.txt因为 requirements 里通常只写了torch没写版本pip 会拉最新版和 CUDA 对不上。pip install torch1.13.1cu117 torchvision0.14.1cu117 -f https://download.pytorch.org/whl/torch_stable.htmlcu117表示 CUDA 11.7你要根据自己驱动支持的版本改。装完后验证import torch print(torch.__version__) print(torch.cuda.is_available())如果第二行输出False说明 CUDA 没配好检查驱动版本和 PyTorch 版本是否匹配。然后装 requirements 里的其他包pip install -r requirements.txt装完后大概率会缺这几个pyqt5、opencv-python、pyyaml、scipy、motmetrics。缺什么补什么pip install pyqt5 opencv-python pyyaml scipy motmetricspyqt5是界面依赖opencv-python是图像处理pyyaml读tracker_config.ymlscipy和motmetrics用于跟踪评估。注意如果pip install opencv-python后import cv2报错试试pip install opencv-python-headless服务器环境没有图形界面时用这个。4. 跑通第一次推理从单张主板图到检测结果可视化4.1 用 infer.py 做单图推理命令、参数与输出解读环境配好后先拿一张主板图跑通infer.py。常见命令格式是python infer.py --image_path ./test_images/board_01.jpg --model_path ./deeplearn/weights/model.pth --output_dir ./results--image_path指定输入图像--model_path指定模型权重--output_dir指定结果保存目录。如果源码里的参数名不一样打开infer.py看argparse部分的定义参数名以源码为准。跑完后results目录下会生成一张画了检测框的图和一个文本文件。文本文件里每行是一条检测结果格式通常是类别 置信度 x1 y1 x2 y2。置信度低于阈值的框会被过滤掉阈值一般在infer.py里定义搜conf_thres或score_thres能找到。如果报错ModuleNotFoundError: No module named xxx说明还有依赖没装。如果报错RuntimeError: Error(s) in loading state_dict说明模型权重和网络结构对不上检查deeplearn目录下的模型定义是否和权重匹配。4.2 启动 PyQt 界面ui.py 与 window.py 的调用关系命令行跑通后可以试试界面。入口通常是ui.py或run.pypython ui.py如果报错No module named PyQt5回到上一步装 PyQt5。如果界面能打开但按钮没反应检查window.py里的信号槽连接是否完整。mainwindow.ui和Ui_mainwindow.py是两套界面定义确认ui.py导入的是哪一个。界面上一般有「加载图像」「开始检测」「保存结果」三个核心按钮。加载图像后点检测结果会显示在右侧或下方。如果检测结果为空先确认模型权重路径是否正确再确认图像是否被正确读取。提示界面跑不通不影响命令行推理先保证infer.py能出结果界面问题可以后面慢慢调。5. 避坑与排查模型加载失败、依赖冲突和界面卡死的处理5.1 模型加载失败state_dict 不匹配的三种原因现象运行infer.py时报RuntimeError: Error(s) in loading state_dict for XXX: Missing key(s) in state_dict。原因一模型定义和权重版本不一致。源码里的deeplearn目录可能包含多个模型定义文件权重只对应其中一个。解决方法是看README.md里指定的模型结构或者对比infer.py里build_model函数的调用。原因二权重文件下载不完整。如果权重是从网盘下的检查文件大小是否和说明一致。不完整的权重加载时会报unexpected EOF或pickle data was truncated。原因三PyTorch 版本差异导致 key 名变化。比如旧版用module.layer1.weight新版去掉了module.前缀。解决方法是用torch.load加载后手动改 key 名或者升级/降级 PyTorch。5.2 依赖冲突numpy 版本与 opencv 的兼容问题现象import cv2时报ImportError: numpy.core.multiarray failed to import。原因numpy 版本过高或过低和 opencv 编译时用的版本不匹配。常见做法是锁定 numpy 版本pip install numpy1.23.5如果还不行先卸载再重装pip uninstall numpy opencv-python -y pip install numpy1.23.5 opencv-python4.7.0.72opencv-python4.7 之后的版本对 numpy 2.x 支持不好降到 4.7 或 4.8 比较稳。5.3 界面卡死主线程阻塞与推理耗时现象点「开始检测」后界面无响应鼠标转圈。原因推理在主线程里跑模型加载和前向传播耗时超过界面刷新间隔。解决方法是把推理放到子线程里用QThread或threading包一层。如果不想改代码可以先在命令行确认单张图推理耗时如果超过 2 秒界面卡死是必然的。另一个原因是模型在 CPU 上跑。检查torch.cuda.is_available()是否为True如果是False模型默认在 CPU 上推理速度会慢很多。5.4 SAHI 切片推理的边界问题现象大尺寸主板图检测时边缘的缺陷漏检。原因SAHI 把大图切成小图分别推理再合并结果。如果切片重叠率设得太低边缘目标会被切掉。SAHI目录下的配置文件里通常有overlap_ratio参数常见做法是设成 0.2 到 0.3。解决方法调大重叠率或者把slice_size调小。但重叠率太大会增加推理时间需要权衡。5.5 跟踪器配置不生效tracker_config.yml 的加载路径现象改了tracker_config.yml里的参数但跟踪结果没变化。原因代码里加载配置的路径是硬编码的或者加载的是另一个同名文件。搜tracker_config在代码里的引用位置确认加载的是你改的那个文件。常见做法是把配置路径改成绝对路径避免相对路径歧义。6. 进阶技巧用 SAHI 切片推理提升小目标检出率SAHI 的核心思路是把高分辨率图像切成重叠的小块每块单独推理再把结果映射回原图坐标做非极大值抑制。主板上的小元件比如 0402 封装的电阻电容在整图缩放后可能只有几个像素直接推理很容易漏。切片后每个元件在切片图里占的像素更多检出率会明显提升。具体操作上先确认SAHI目录下的配置文件找到slice_height和slice_width。常见做法是设成 512 或 640取决于模型输入尺寸。overlap_ratio设 0.2 到 0.3太小会漏边缘目标太大推理时间翻倍。from sahi import AutoDetectionModel from sahi.predict import get_sliced_prediction detection_model AutoDetectionModel.from_pretrained( model_typeyolov5, model_path./deeplearn/weights/model.pth, confidence_threshold0.3, devicecuda:0 ) result get_sliced_prediction( ./test_images/board_large.jpg, detection_model, slice_height640, slice_width640, overlap_height_ratio0.25, overlap_width_ratio0.25 )confidence_threshold是置信度阈值切片推理时建议比整图推理低一点因为切片后目标更大置信度分布会变化。device指定 GPU没有 GPU 就写cpu。跑完后对比整图推理和切片推理的结果数量。如果切片后检出数量明显增加说明小目标确实被漏了。但也要注意误检切片边缘的重复检测需要靠 NMS 合并。验证方法拿一张已知缺陷位置的主板图分别跑整图和切片看切片是否能检出整图漏掉的目标。如果切片也检不出可能是模型本身没学好这类目标需要重新训练或换模型。从那以后我每次拿到新的检测源码都强制先跑一遍单图推理再跑一遍切片推理对比结果差异。这个习惯帮我省掉了很多「以为模型不行其实是推理方式不对」的返工。希望帮到你。本文还有配套的精品资源点击获取