企业官网建设流程全解析

简介：这是一套面向工业质检场景的计算机视觉实战源码，基于Python与图像识别技术实现主板质量检测，适合具备一定深度学习基础、希望将目标检测与关键点识别落地到电子制造质检的开发者与高校学生。资源包共41个文件，以34个Python脚本为核心，涵盖推理、预处理、后处理与可视化等模块，另含2个ui界面文件、2个说明文档及yml配置、txt依赖清单等，压缩包约102KB，结构紧凑便于快速上手。内容涉及检测与关键点联合推理、多目标跟踪、属性识别及SAHI切片推理等典型流程，并配有可视化与部署相关脚本，可帮助读者理解从模型推理到界面展示的完整链路。目前已有447人学习下载，适合作为课程设计、毕业设计或质检算法原型的参考方案，便于在此基础上替换数据集与模型，快速搭建自己的主板缺陷检测系统。

1. 拆开这份主板质量检测源码：它到底能跑出什么结果

产线上最怕的不是没算法，而是算法跑在 demo 里好好的，一上工位就翻车。这份基于 Python 和图像识别的主板质量检测系统源码，解决的就是从「单张图能识别」到「整条检测流程能落地」之间的那段距离。它把目标检测、关键点检测、多目标跟踪、属性识别、动作识别这几条链路都塞进了一个可运行的工程里，前端用 PyQt 搭了可视化界面，后端有 Server 和 ServerFunction 做服务化封装，还带了 SAHI 切片推理和 deeplearn 目录下的模型推理脚本。适合两类人：一类是想拿现成工程改造成自己产线检测逻辑的算法工程师，另一类是正在做课程设计或毕设、需要一套完整可跑通的主板缺陷检测系统的学生。源码包里的文件结构已经按推理、跟踪、关键点、UI 分好了，不用从零搭架子。

2. 环境与依赖：把 requirements.txt 跑通之前先看这几处

2.1 为什么这套工程对 Python 版本和 CUDA 这么敏感

这份源码的推理链路依赖 PaddleDetection 系的模型导出格式，infer.py、keypoint_infer.py、mot_jde_infer.py这些脚本里调用的预测器对 Paddle Inference 的版本有硬要求。我一般会先确认三件事：Python 版本、CUDA 驱动版本、PaddlePaddle 是 GPU 版还是 CPU 版。requirements.txt 里列了基础依赖，但它不会帮你锁定 Paddle 的版本，这是第一个容易翻车的地方。

常见做法是建一个干净的虚拟环境，Python 用 3.8 或 3.9，太新的版本有些旧版 Paddle 轮子找不到。如果你机器上没有 GPU，也能跑，但deploy目录下的推理配置要改成 CPU 模式，速度会明显下降，主板检测这种需要实时出结果的场景基本只能用来验证逻辑。

# 创建虚拟环境，Python 版本建议 3.8/3.9 python -m venv board_inspect_env source board_inspect_env/bin/activate # Windows 用 board_inspect_env\Scripts\activate # 先装 PaddlePaddle，GPU 版按官网命令替换 pip install paddlepaddle-gpu==2.5.2 -i https://mirror.baidu.com/pypi/simple # 再装工程依赖 pip install -r requirements.txt

逻辑说明：先装 Paddle 再装 requirements，是因为 requirements 里可能包含 paddle 相关包，顺序反了会把 GPU 版覆盖成 CPU 版。参数上，paddlepaddle-gpu的版本号要和你 CUDA 版本对应，2.5.x 对应 CUDA 11.7 左右，具体以官方安装命令为准。装完后用python -c "import paddle; paddle.utils.run_check()"验证，输出里能看到 GPU 数量才算真正通了。

2.2 目录结构里哪些是入口、哪些是工具

源码包解压后有两层，外层是A10-main.zip，里层是A10-main目录。真正要关注的文件分几类：

infer.py.bak是备份文件，不要直接改它，改infer.py。visualize.py负责可视化输出，调试阶段可以打开看检测框和关键点画得对不对。

提示：Ui_mainwindow.py是mainwindow.ui用 pyuic 生成的，改界面要改.ui文件再重新生成，直接改.py下次生成会被覆盖。

3. 推理链路怎么跑：从单图检测到多目标跟踪的实操

3.1 单图推理：infer.py 的参数怎么设

infer.py是最直接的入口，适合先验证模型能不能出结果。它一般接收图片路径、模型路径、阈值这几个参数。我习惯先用一张已知有缺陷的主板图跑通，再换批量。

# 单图推理，具体参数名以 infer.py 内 argparse 为准 python infer.py \ --image_path ./test_imgs/board_01.jpg \ --model_dir ./deploy/model \ --threshold 0.4 \ --output_dir ./output

逻辑说明：--image_path指向待检图，--model_dir是导出后的推理模型目录，--threshold控制置信度阈值。阈值设 0.4 是主板缺陷检测的常见起点，太高会漏检小缺陷，太低会误报。跑完后去output目录看可视化结果，如果框的位置明显偏，先检查预处理里的 resize 和归一化参数是否和训练时一致，这是最常见的坐标错位原因。

3.2 关键点检测：det_keypoint_unite_infer.py 在做什么

主板检测里关键点不是用来做人脸那种，而是定位主板上的基准点、螺丝孔、接口位置。det_keypoint_unite_infer.py把目标检测和关键点检测串在一起：先检测出主板区域，再在区域内回归关键点。keypoint_preprocess.py和keypoint_postprocess.py分别管前后处理，det_keypoint_unite_utils.py管两者的结果融合。

# 关键点推理的核心调用逻辑（示意，以实际脚本为准） from keypoint_infer import KeypointInfer from det_keypoint_unite_utils import unite_results det_results = detector.predict(image) # 先检测主板区域 kp_results = keypoint_model.predict(image, det_results) # 再回归关键点 final = unite_results(det_results, kp_results) # 融合输出

逻辑说明：det_results给出主板 bounding box，kp_results在框内输出关键点坐标和置信度，unite_results把两者拼成结构化结果。参数上要关注关键点数量配置，keypoint_postprocess.py里通常有num_joints之类的字段，改错了会导致输出维度对不上。如果关键点全挤在一个位置，多半是后处理里的 heatmap 解码参数和模型输出尺寸不匹配。

3.3 多目标跟踪：mot_jde_infer.py 与 tracker_config.yml 的配合

产线上主板是连续过站的，单帧检测不够，要跟踪同一块板在不同帧里的状态。mot_jde_infer.py和mot_sde_infer.py是两种跟踪推理模式，JDE 是检测和嵌入联合，SDE 是分开跑。tracker_config.yml里配跟踪器参数。

# tracker_config.yml 关键字段示意 tracker: type: JDE max_time_lost: 30 # 丢失多少帧后删除轨迹 min_box_area: 100 # 最小框面积，过滤噪声 match_threshold: 0.7 # 匹配阈值

逻辑说明：max_time_lost设太小，主板被遮挡一下就丢轨迹；设太大，已经离开的板还会被跟踪。min_box_area用来滤掉小噪点框。match_threshold影响新旧轨迹的关联，太高会频繁新建 ID，太低会串 ID。调这三个参数时建议开visualize.py看轨迹线，直观判断。

3.4 属性与动作识别：attr_infer.py 和 action_infer.py 的适用场景

attr_infer.py做属性识别，比如主板颜色、有无标签；action_infer.py做动作识别，比如机械臂抓取动作是否到位。这两个不是所有检测场景都要用，按需开启。action_utils.py里有动作序列的后处理逻辑，如果动作识别结果跳变，先看这里的滑窗参数。

4. 界面与服务化：ui.py 和 Server.py 怎么串起来

4.1 PyQt 界面：mainwindow.ui 到 ui.py 的生成链路

界面部分用 Qt Designer 画mainwindow.ui，再用 pyuic 生成Ui_mainwindow.py，ui.py和window.py负责业务逻辑绑定。这套结构的好处是界面和逻辑分离，改布局不用动代码。

# 从 .ui 生成 .py，注意版本对应 pyuic5 mainwindow.ui -o Ui_mainwindow.py

逻辑说明：pyuic5对应 PyQt5，如果你装的是 PyQt6 要用pyuic6。生成后的Ui_mainwindow.py只包含控件定义，不要在里面写业务逻辑，所有信号槽连接放在ui.py或window.py。常见翻车是改了.ui忘了重新生成，界面一直不更新。

4.2 服务端封装：Server.py 与 ServerFunction.py 的职责划分

Server.py管网络通信和请求分发，ServerFunction.py管具体检测函数的实现。这种拆法方便把检测能力暴露成接口给其他系统调。index.py可能是 Web 入口或路由定义。

# ServerFunction.py 里典型的检测函数结构（示意） def detect_board(image_bytes): image = decode_image(image_bytes) results = infer_pipeline(image) return format_response(results)

逻辑说明：detect_board接收字节流，解码后走推理管线，最后格式化返回。参数上要注意图像编码格式和返回的 JSON 结构，前后端约定好字段名，否则解析会报错。如果服务起来后请求超时，先看Server.py里的端口和并发配置，再确认模型是否常驻内存，每次请求都重新加载模型会非常慢。

4.3 SAHI 切片推理：小缺陷检测的补救方案

主板上的小缺陷在大图里可能只占几十个像素，直接整图推理容易漏。SAHI目录就是干这个的，把大图切成重叠小图分别推理再合并。

from sahi import AutoDetectionModel from sahi.predict import get_sliced_prediction detection_model = AutoDetectionModel.from_pretrained( model_type="paddledetection", model_path="./deploy/model", confidence_threshold=0.3 ) result = get_sliced_prediction( "board_01.jpg", detection_model, slice_height=640, slice_width=640, overlap_height_ratio=0.2, overlap_width_ratio=0.2 )

逻辑说明：slice_height/width是切片尺寸，overlap_*_ratio是重叠比例，重叠是为了避免缺陷正好被切在边界上。切片越小越容易检出小目标，但推理次数成倍增加。主板检测一般 640 配 0.2 重叠是速度和召回的平衡点。如果合并后框重复，调 NMS 的 IoU 阈值。

5. 避坑与排查：这份源码跑不起来时先查这五处

5.1 现象：ImportError 报 paddle 相关模块找不到

原因：PaddlePaddle 没装或装成了 CPU 版但代码里走了 GPU 分支。解决：先pip list | grep paddle确认版本，再检查deploy里的配置文件是否指定了 GPU。CPU 环境要把use_gpu改成 False。

5.2 现象：推理结果框全部偏移或缩放错误

原因：预处理 resize 参数和模型训练时不一致，或者preprocess.py里的 mean/std 归一化写错。解决：对照训练配置核对输入尺寸和归一化参数，preprocess.py里通常有Resize和Normalize两段，逐项比对。

5.3 现象：跟踪 ID 频繁跳变，同一块板换了好几个 ID

原因：tracker_config.yml里match_threshold设太高，或者检测框抖动太大。解决：先把match_threshold降到 0.5 左右试，再检查检测阈值是否太低导致框不稳定。必要时在检测后加平滑。

5.4 现象：界面能打开但点检测没反应

原因：信号槽没连上，或者Ui_mainwindow.py重新生成后控件名变了但ui.py里没同步。解决：检查ui.py里的connect语句，确认控件对象名和.ui里一致。改完.ui一定要重新生成并检查差异。

5.5 现象：Server 启动后请求返回 500 或超时

原因：模型加载失败、端口被占、或者请求体格式不对。解决：先看Server.py启动日志有没有模型加载报错，再用curl或 Postman 发一个最小请求测通路。如果每次请求都重新加载模型，改成启动时加载一次常驻。

6. 进阶技巧：把检测阈值调稳的一个笨办法

阈值这东西，调高了漏检，调低了误报，产线上最怕的就是今天好好的明天一堆误报。我自己的习惯是做一个小的阈值扫描脚本，拿一批已知标签的图跑一遍，把不同阈值下的准确率和召回率画出来，选拐点。这份源码里benchmark_utils.py已经有评测的底子，可以直接拿来改。

# 阈值扫描示意，基于 benchmark_utils.py 改造 import numpy as np from benchmark_utils import evaluate thresholds = np.arange(0.2, 0.8, 0.05) results = [] for t in thresholds: acc, recall = evaluate(threshold=t, data_dir="./val_imgs") results.append((t, acc, recall)) # 选召回优先且准确率不低于 0.9 的阈值 best = max([r for r in results if r[1] >= 0.9], key=lambda x: x[2]) print(f"推荐阈值: {best[0]:.2f}, 准确率: {best[1]:.3f}, 召回率: {best[2]:.3f}")

逻辑说明：evaluate是封装好的评测函数，接收阈值和数据目录，返回准确率和召回率。扫描范围 0.2 到 0.8 覆盖了大多数场景，步长 0.05 够用。选阈值的原则是产线优先保召回，漏检比误报代价大，所以先卡准确率下限再最大化召回。跑完这个脚本，阈值就有数据支撑了，不用凭感觉。

还有一个容易忽略的点：visualize.py不只是用来看图的，它输出的可视化结果可以当回归测试的基准。每次改完预处理或后处理，跑同一批图对比可视化输出，能快速发现坐标偏移、框消失这类问题。我一般会把一批典型图的可视化结果存下来，改代码后 diff 一下，比看指标更直观。

从那以后我每次拿到新的检测工程，都强制先跑一遍阈值扫描和可视化回归，再谈调优。希望帮到你。

本文还有配套的精品资源，点击获取