1. 系统框架梳理一块木板是怎么被“盯住”的1.1 为什么选YOLOv11做木材缺陷检测木材缺陷检测本质上是一个目标检测问题但它跟通用目标检测不一样的地方在于缺陷和木材天然纹理之间的边界非常模糊。板材表面有年轮、木纹、色差、毛刺缺陷混在里面别说算法有时候人眼不凑近看都分不清。常见的木材缺陷主要有四类节子knot、裂纹crack、虫眼insect_hole和腐朽decay。节子颜色深、纹理中断但浅色节子和正常木纹几乎一样裂纹是细长线状可能只有几个像素宽顺着纹理方向延伸稍不注意就漏检虫眼是小圆孔尺寸通常只有几十个像素属于典型的小目标腐朽面积大但边界模糊框怎么打都感觉不贴边。我最早试过传统图像处理方案灰度阈值、边缘检测、形态学操作都上了。固定光源、固定木材品种的简单场景下能用但只要换一种木材、换一个光照强度特征分布立刻变阈值参数得重新调。某个周末我把一批带虎斑纹的板材丢进去测误报率高得离谱木纹阴影全被当成了裂纹。这时候才下决心换深度学习方案。YOLOv11作为YOLO系列的新版本在精度和推理速度之间做了更好的平衡对小目标和细长目标的特征提取也有针对性的改进正好适合木材缺陷这种纹理干扰大、缺陷形态不固定的场景。再加上ultralytics框架把数据加载、增强、训练、导出、推理全部封装好了一个Python环境从头跑到尾工程落地成本比早期YOLO版本低太多。1.2 系统整体流程与模块划分整个系统拆开看就是四层数据层、训练层、推理层、界面层。数据层负责把采集到的板材图像转成YOLO格式数据集也就是每张图片配一个同名的txt标注文件里面记录类别ID和归一化坐标。训练层用ultralytics加载数据集训练出best.pt权重文件。推理层封装检测函数输入图像输出类别、边界框坐标和置信度。界面层用PyQt5做登录注册界面和检测主界面把推理结果可视化同时提供批量检测、摄像头检测、结果导出这些功能。推理过程可以简单描述为原始图像输入后先做letterbox预处理也就是不直接拉伸图片而是保持宽高比缩放到固定尺寸四周用灰色填充这样能避免目标变形失真。然后Backbone提取多尺度特征Neck做特征融合Head输出多个尺度的预测框最后NMS非极大值抑制去掉重叠框再把这些坐标映射回原始图像尺寸。NMS这一步很关键一条裂纹可能被模型生成几十个候选框NMS只保留置信度最高的那个同时抑制与它高度重合的其他框不然画面上全是框根本没法看。1.3 工程目录结构与基础配置我习惯把项目目录从一开始就整理清楚免得训练到一半文件乱成一团。下面是这套系统最终的目录结构wood_defect_detector/ ├── data/ │ ├── images/ │ │ ├── train/ │ │ └── val/ │ ├── labels/ │ │ ├── train/ │ │ └── val/ │ └── wood.yaml ├── models/ │ ├── yolov11n.pt │ └── best.pt ├── utils/ │ ├── dataset_utils.py │ └── model_utils.py ├── ui/ │ ├── login_dialog.py │ ├── main_window.py │ └── style.qss ├── app.py ├── train.py ├── requirements.txt └── README.mddata目录下images和labels分别放原图和标注txttrain和val子目录对应训练集、验证集。wood.yaml是数据集配置文件内容包括数据路径、类别映射。models目录放预训练权重和训练出的最佳权重。ui目录放PyQt5界面代码和样式表。app.py是程序入口train.py是训练脚本。这里的wood.yaml是核心配置内容大致长这样path: data train: images/train val: images/val names: 0: knot 1: crack 2: insect_hole 3: decay注意path配的是相对于工程根目录的路径要是换机器或者换目录第一件事就是检查这个映射对不对否则后面训练会报找不到数据集的错。2. 数据集准备最容易决定成败的一环2.1 缺陷类别的定义与标注难点数据集质量直接决定模型上限这个项目里我对四类缺陷的标注规范做了区分因为它们的形态差异非常大统一套标注规则会出问题。类别ID类别名典型特征标注难点0knot节子深色圆形或椭圆斑块纹理中断浅色节子与木纹区分1crack裂纹细长线条方向随机或顺纹理细长目标宽高比极大2insect_hole虫眼小而圆通常成簇出现小目标易漏标忽略3decay腐朽面积较大颜色发暗边界模糊边界界定主观性强节子标注时不要只框深色中心应该把周围的环状纹理一起包进去否则模型学到的是“深色圆斑”而不是“节子”遇到浅色节子就失效。裂纹这种细长目标框可以适当放宽一点线宽让框包含几像素的背景给模型更多上下文信息。虫眼成簇出现时我规定每个独立的孔单独框只有距离极近无法区分时才合并否则训练时标注风格不一致模型学到的尺度特征会乱掉。腐朽是最难标注的边界完全是渐变的框太小漏掉变质区域框太大又包含正常木材这类样本我让三个参与标注的人都框一遍取多数交集降低主观偏差。2.2 标注工具选择与数据划分策略标注工具我用的是X-anylabeling它支持YOLO格式还能加载一个预训练检测模型做辅助预标注。先让辅助模型跑一遍人工再修正结果效率比从零开始框高很多尤其在裂纹、虫眼这种小目标上自动预标注能减少漏标的概率。导出格式选YOLO生成的每个txt文件内容格式是“class cx cy w h”cx、cy是中心点坐标w、h是宽高全部都除以了图像宽高做了归一化。标注规范我踩过不少坑总结几条铁律框要紧贴目标边缘不要故意留白目标被遮挡时框住可见部分同一张图上同类缺陷全部标注漏标等于在教模型“这个位置没问题”推理时就会漏检人眼都看不清的模糊样本直接删掉硬标进去只会给训练数据引入噪声没有缺陷的干净板材图片也要保留一批作为背景负样本能显著降低误检率这一点很多人忽略。数据划分我按照7:2:1拆成训练集、验证集、测试集。划分脚本要特别注意防止同一块板材在不同位置拍的图被拆到不同集合否则存在数据泄露验证集指标会虚高部署到新环境直接打回原形。我的做法是先按板材样本编号做分组同一组内的图要么都进训练集要么都进验证集彻底打散重来。2.3 数据增强配置与数据量经验数据量是新手最爱问的问题。我的经验是每类缺陷至少200到300个实例起步想效果好一点尽量往500以上凑。刚开始项目时我只收集了不到800张图节子样本多虫眼样本少训练完一测节子AP能到0.9虫眼AP只有0.35完全没法用。后来对虫眼样本专门补采了一批又对已有样本做了裁剪增强AP才拉到0.7以上。工业场景下样本不够是常事我一般用三个办法补救一是同一块板材换角度、换光照多次采集成本最低增加的是真实多样性二是对已有样本做旋转、平移、翻转、HSV颜色扰动用ultralytics自带的增强就够三是用预训练权重做迁移学习模型已经具备通用的特征提取能力小数据集也能微调出不错效果。增强方面ultralytics默认开了mosaic、翻转、HSV抖动这些确实能提升模型对小目标的鲁棒性因为mosaic会把多张图拼起来等效缩小目标尺寸。不过数据量很小的时候mosaic概率太高反而让模型困惑目标被切得四分五裂标注反而失真。我在数据量低于500张时会把mosaic降到0.5甚至关掉数据量大了再开满。3. 模型训练从零到best.pt的完整过程3.1 环境配置与依赖安装训练环境我建议用Python 3.10、PyTorch 2.x、ultralytics最新版。GPU方面N卡是首选6GB以上显存跑起来会比较舒服纯CPU也能训练但速度慢得离谱一个200轮的训练可能要跑好几天不推荐。安装命令很简单pip install ultralytics torch torchvision安装完成后先验证一下CUDA是否可用python -c import torch; print(torch.cuda.is_available())输出True说明GPU环境没问题。如果CUDA不可用多半是PyTorch版本和驱动不匹配要去PyTorch官网按本机CUDA版本对应安装。这里提醒一句如果训练时报“CUDA out of memory”优先查两件事batch是不是太大imgsz是不是设得太高。新手最容易在这两个参数上翻车。3.2 训练参数的选择与调优逻辑训练脚本我直接写在train.py里内容不长但每个参数都是调过的。from ultralytics import YOLO model YOLO(models/yolov11n.pt) # 使用预训练权重做迁移学习 model.train( datadata/wood.yaml, epochs200, imgsz640, batch16, lr00.001, optimizerAdamW, patience20, device0, workers8, ampTrue, seed42, )逐个说下关键参数。imgsz640是训练输入尺寸木材原图分辨率很高但训练时统一缩到640速度和精度最平衡。如果想要提高小目标召回率可以在推理时把imgsz调到960甚至1280但推理时间会明显变长。batch16按显存来定8GB显存建议816GB建议1624GB以上可以冲32OOM就把batch减半。epochs200对几百张的数据集够了配合patience20验证指标连续20个epoch不提升就自动停止省时间。lr00.001配合AdamW收敛比较稳用SGD的话可以调到0.01起步。ampTrue开启混合精度训练显存占用直接减半吞吐量提升明显精度损失可以忽略这个开关必开。迁移学习是这套方案能快速见效的关键。用models/yolov11n.pt做预训练权重相当于模型已经学会了通用物体的特征比如边缘、颜色、纹理现在只需要在木材缺陷数据上做微调。对比下来不加载预训练权重的效果要差一大截尤其在数据量少的情况下所以一定不要省略这一步。3.3 训练结果评估与模型选择训练结束后输出都在runs/wood_train/下。先看results.png它包含训练loss、验证loss、precision、recall、mAP等曲线。如果训练loss持续下降而验证loss上升就是过拟合信号回头去补数据或者加强正则。再看val目录下的PR_curve.png和confusion_matrix.pngPR曲线能直观看到每个类别的查准查全关系。评估脚本可以这样写from ultralytics import YOLO model YOLO(runs/wood_train/weights/best.pt) results model.val(datadata/wood.yaml, imgsz640) print(results.box.map) # mAP0.5:0.95 print(results.box.map50) # mAP0.5 print(results.box.mp) # precision print(results.box.mr) # recall我当时训练完的参考指标大致是mAP0.5在0.87左右mAP0.5:0.95在0.56左右precision约0.89recall约0.83。从全局看还行但细看每个类别的AP节子最高裂纹和虫眼明显偏低。所以评估阶段一定要看每个类别的AP不能只看总体mAP。裂纹和虫眼都是容易漏检的类别针对它们单独扩样本、提高推理分辨率、或者把置信度阈值调低才能实际提升产线的检出率。4. UI界面与登录注册把模型变成可用产品4.1 UI技术选型PyQt5为什么够用模型训练出来只是开始真正交给工厂操作员用一个友好的界面比命令行输入有价值得多。我对比过三个方案最终选了PyQt5。Tkinter是Python自带的部署简单但控件老旧想做个像样的登录界面得费很大劲用Flask搭Web界面前段灵活性高但还需要部署浏览器环境而且摄像头画面、拖拽图片这些交互体验在桌面程序里更顺畅。PyQt5控件丰富支持QSS样式表可以把它理解成网页里的CSS一套样式套上去界面立刻好看不少还能用PyInstaller打包成exe给没有Python环境的电脑装上就能用。界面层一共两部分登录注册页和检测主界面。登录注册是所有桌面软件成熟的标配虽然单机质检工具不做登录也能跑但有了账号体系就能区分不同操作员的责任范围也方便后续记录谁在什么时间检测了哪批板材。4.2 登录注册模块的实现细节用户信息存在SQLite数据库里这是Python自带的库不需要额外部署数据库服务。密码存储绝对不能用明文我用的是PBKDF2加盐哈希也就是对每个用户生成一个随机的salt再把密码和salt一起做10万次哈希迭代。这样即使数据库文件被人拷走也无法反推出原始密码。核心代码如下import hashlib import os import sqlite3 DB_PATH users.db def create_table(): conn sqlite3.connect(DB_PATH) c conn.cursor() c.execute(CREATE TABLE IF NOT EXISTS users ( id INTEGER PRIMARY KEY AUTOINCREMENT, username TEXT UNIQUE NOT NULL, salt TEXT NOT NULL, password_hash TEXT NOT NULL, created_at TEXT DEFAULT (datetime(now)) )) conn.commit() conn.close() def hash_password(password: str, salt: str) - str: return hashlib.pbkdf2_hmac( sha256, password.encode(), salt.encode(), 100_000 ).hex() def register_user(username, password): if len(password) 6: return False, 密码长度至少6位 conn sqlite3.connect(DB_PATH) cur conn.cursor() cur.execute(SELECT id FROM users WHERE username?, (username,)) if cur.fetchone(): conn.close() return False, 用户名已存在 salt os.urandom(16).hex() pwd_hash hash_password(password, salt) cur.execute( INSERT INTO users (username, salt, password_hash) VALUES (?,?,?), (username, salt, pwd_hash) ) conn.commit() conn.close() return True, 注册成功 def verify_login(username, password): conn sqlite3.connect(DB_PATH) cur conn.cursor() cur.execute(SELECT salt, password_hash FROM users WHERE username?, (username,)) row cur.fetchone() conn.close() if row is None: return False salt, stored_hash row return hash_password(password, salt) stored_hash登录和注册界面我都用了PyQt5的QDialog用户名和密码输入框设置回显模式为密码遮挡登录成功后销毁登录窗口再创建主窗口。登录失败弹一个QMessageBox提示不告诉用户具体是用户名不存在还是密码错误只统一提示“用户名或密码不正确”这样能防止别人遍历用户名。4.3 检测主界面设计与多线程处理主界面布局我做了左右分栏。左侧大区域用来显示检测后的图片可以缩放、拖动画布。右侧是一个信息面板上方是检测结果表格每一行显示类别、置信度、坐标下方是缺陷统计用柱状图展示各类缺陷数量。顶部菜单栏放了打开图片、打开文件夹、摄像头检测、导出报告等入口。底部是一个状态栏显示当前模型名称、推理耗时和检测数量。单个图片的检测逻辑封装成了函数from ultralytics import YOLO model YOLO(models/best.pt) def detect_image(image_path, conf_thres0.35): results model.predict( sourceimage_path, confconf_thres, iou0.5, imgsz640, verboseFalse, ) boxes results[0].boxes detections [] for box in boxes: cls_id int(box.cls[0]) conf float(box.conf[0]) x1, y1, x2, y2 map(int, box.xyxy[0].tolist()) detections.append({ class_id: cls_id, confidence: conf, bbox: (x1, y1, x2, y2), }) return detections在UI上绘制检测框我用OpenCV完成直接在原图上画矩形和标签文字再转成QPixmap显示到QLabel上。这段的绘制很简单但有一个问题必须处理界面可能在主线程里直接调用推理函数模型推理需要几百毫秒到几秒不等期间UI会卡死窗口无响应操作系统甚至会弹“程序未响应”的提示。解决办法是PyQt5的QThread。每次点检测按钮启动一个工作线程在线程里跑模型推理推理完成后通过信号把结果传回主线程更新界面。核心结构是这样的from PyQt5.QtCore import QThread, pyqtSignal class DetectThread(QThread): result_ready pyqtSignal(list, float) def __init__(self, image_path): super().__init__() self.image_path image_path def run(self): import time start time.time() detections detect_image(self.image_path) elapsed time.time() - start self.result_ready.emit(detections, elapsed)主窗口里连接信号槽收到结果再刷新表格和图片。这样即使推理时间再长窗口也能正常操作操作员还能点取消。摄像头检测同样是这个思路从摄像头读帧送到线程再把标记好的画面传回来。5. 实际项目里的坑与排查记录5.1 训练阶段的典型问题速查表现象可能原因解决方案训练loss降不下去学习率过高或标注错误降低lr0逐张检查labelsval mAP低、train mAP高过拟合或数据重复划分增加增强按板材分组划分数据虫眼几乎全漏检小目标样本少、分辨率不够补样本推理imgsz提到960显存OOMbatch或imgsz太大减batch开启AMP混合精度训练正常但推理框偏移训练与推理imgsz不一致统一imgsz参数这些全是真实踩过的问题。比如说标注错误有一批标注文件的坐标没有做归一化训练的时候loss一直居高不下我第一次看到还以为是模型结构问题排了半天才发现是标注数值超界。后来加了一个数据校验脚本每次训练前先扫描标注文件检查坐标是否在0到1之间、类别ID是否越界、图片和标注文件是否一一对应。5.2 部署阶段的四个高频坑UI卡死这个前面已经说了用QThread解决。摄像头检测掉帧是第二个常见问题因为每帧都做一次全尺寸推理时间根本不够。解决办法是设置帧间隔比如每秒只处理5帧同时推理分辨率降到640画面流畅度会好很多缺陷是运动中的板材可能漏检所以真实产线一般用相机触发拍照而不是连续视频流。第三个坑是模型和资源文件的打包。PyInstaller打包PyQt5程序经常报缺模块需要在spec文件里手动加datas把best.pt、QSS样式、ico图标都收集进来。我第一次打包完双击运行直接报找不到模型文件原因就是模型没有被打进包后来统一用相对路径加资源路径映射函数解决。第四个坑是模型推理速度。如果现场只有CPU没有GPUYOLOv11的推理时间会放大好几倍单张图可能到几百毫秒。这时可以先把模型导出成ONNX格式用ONNX Runtime推理速度会提升不少有专业加速卡的话直接导出TensorRT引擎能把推理压到毫秒级。ultralytics导出非常简单一行命令yolo export modelmodels/best.pt formatonnx5.3 从这次项目里总结的三点心得第一模型只是整个系统里最简单的一环。真正花时间的永远是数据清洗、标注检查、UI交互和异常处理。训练本身一两小时就能跑完但让模型在不同光照、不同树种的板材上稳定工作调数据的时间至少是训练时间的五倍以上。第二不要试图一步到位。我的做法是先做一个最简版本命令行能跑通训练和推理再加登录注册再加界面最后才做批量检测和导出功能。每一步都保证可运行再往下一步走否则一堆问题混在一起排查起来无从下手。第三每次训练都留记录。训练结束把配置文件、指标结果、测试样例截图打包归档出了新版本可以对比提升还是倒退。我当时就是因为没留记录改了几个参数后重新训练指标明明更好却说不清是哪个参数起的作用又重新跑了一轮对照实验才搞明白。训练日志、结果目录、val曲线图、测试图片四件套每次训练必须留档。这个项目做完后我最大的感受是木材缺陷检测这类工业视觉场景真正的难点从来不是跑通一个模型而是让模型在不同环境里稳定、让操作员愿意用、让检测结果可追溯。如果你也在做类似的检测系统我建议从最小可跑的版本开始先把训练和推理链路打通再回头优化精度和UI一步一步来比憋大招稳得多。最后再分享一个小技巧把每次推理结果连同图片一并保存到当日文件夹文件名带上日期、时间、账号和缺陷数量出问题时有据可查操作员也更信任这套系统。