第一章 开篇为什么太阳能电池板需要一套能看见问题的检测系统这两年光伏行业的装机量涨得有多猛相信不用我多说了。屋顶分布式、地面电站、农光互补各种场景铺天盖地。但电站建起来只是第一步真正让人头疼的是后面的运维。一块板子出了问题在几百亩的电站里找出来跟大海捞针差不多。我接触过不少做电站运维的朋友他们最常吐槽的场景是这样的早上六点背着红外检测仪进场一块一块板子人工巡检一天下来走断腿也只能看几百块而且全凭肉眼和经验判断裂纹、热斑、隐裂、脏污遮挡不同缺陷的判据完全不一样新来的运维人员没有两年经验根本不敢独立下结论。更要命的是高空组件、陡坡阵列这些位置人根本过不去。所以当我看到基于深度学习的太阳能电池板检测系统这个课题方向时第一反应是这确实是刚需。它不是那种为了写论文而写的空中楼阁而是能实实在在落地到电站运维流程里的工具。这套系统做的事情概括起来很简单用目标检测模型识别电池板上的各类缺陷再通过 Web 界面让运维人员上传图片、查看结果、管理记录。技术栈也很清晰——YOLO 系列模型负责看见缺陷Django 负责把模型能力包装成一个人人能用的系统。为什么选 YOLO因为检测速度足够快在 GPU 上跑实时视频流都没问题模型体积相对可控部署到普通工作站甚至边缘设备都有戏而且 v5、v8、v11、v12 这几个版本迭代下来无论是精度还是部署生态都已经相当成熟。配合 Django 做 Web 层不用单独写前端自带的管理后台、ORM、用户认证全是现成的非常适合快速搭建一套可用的业务系统。这篇文章适合谁看如果你正在做类似的毕业设计或课题比如目标检测方向、Web 应用方向这套思路可以直接参考如果你是电站运维的从业人员想了解深度学习到底能在巡检场景里做什么里面关于数据采集和效果评估的部分会给你一些参考如果你只是对 YOLO 和 Django 怎么配合感兴趣那从模型训练到系统部署的完整链路这篇文章基本都覆盖了。接下来我不打算按项目背景、技术介绍、系统实现这种教科书顺序讲而是按照我当时从零到一把这套系统做出来的顺序把真正关键的环节、踩过的坑、验证过的经验一个个拆开说。2. 第一步不是选模型而是先把检测目标定义清楚很多人拿到这类课题第一反应是先去把 YOLO 最新版下载下来跑个 Demo 再说。我一开始也差点这么干但后来发现如果连要检测什么都没定义明白后面每一步都会被返工拖死。2.1 电池板缺陷检测到底检测哪几类东西太阳能电池板的缺陷种类很多但真正在目标检测任务里能通过可见光图像识别、又有实际运维价值的我梳理下来大概是这几类缺陷类型可见特征实际危害检测难度热斑局部区域颜色异常偏暗/偏亮可见光下有时不明显永久性损坏引发火灾隐患中隐裂细线状裂纹方向随机影响发电效率随时间扩大高脏污遮挡鸟粪、灰尘、落叶等覆盖物遮挡区域无法发电形成热斑低玻璃破碎明显裂痕、碎纹直接暴露电池片漏电风险低组件位移/变形边框弯曲、板面倾斜结构安全隐患中这里有个容易踩的误区很多人把热斑检测直接当成目标检测问题做但热斑在可见光图像上往往不明显真正的热斑检测要用红外图像。那这套系统为什么还把它列进来因为实际场景里一块板子因为局部遮挡或隐裂在可见光下也会表现出明显异于周围的色差这种疑似热斑区域作为预警项是有意义的。换句话说我们检测的目标不是物理意义上的热斑而是可能在可见光下表征热斑风险的异常区域。把检测目标定义成可见光可识别的异常区域而不是缺陷本身这个思路上的转变很重要它直接决定了你后续标注数据时采用什么标准、模型训练时怎么设置类别。2.2 缺陷检测和普通目标检测的差异点用 YOLO 检测电池板和检测行人有很大区别。行人检测目标通常占据画面较大比例轮廓清晰类别差异大。电池板缺陷正好相反——缺陷往往很小有的甚至只有几个像素宽背景高度相似整张图全是深蓝色的电池板纹理类别之间外观差异小脏污和热斑在局部区域内可能长得差不多。这个特点决定了我们不是简单套用 YOLO 的默认配置就行而是要在后面几个环节专门针对小目标相似类别做调整。主线思路是数据层面裁剪原图分块训练相当于让模型凑近看。模型层面选择带有小目标检测头的版本或者调整 anchor 尺寸。训练层面mosaic 增强改成小范围版本避免小目标被过度裁剪丢框。这些细节我在第四章里会展开讲。这里先记住结论太阳能电池板缺陷检测的关键难点不在模型结构而在数据定义和处理策略。3. 数据集从裸图到能训练的标注集说实话开题时我觉得整个项目里最费时间的环节是训练模型做完才发现数据准备才是真正的大头。一块板子的原始巡检照片要变成 YOLO 能用的训练集中间至少经过采样、清洗、裁剪、标注、增强五道工序。3.1 图片来源和采集要点我们没有公开的现成数据集可以用只能自己采集。主要来源是几个光伏电站的巡检照片另外在网上下载了一部分公开的组件图像作补充。如果你也要做类似项目采集阶段有几个建议值得参考尽量覆盖不同光照条件。上午顺光、中午强光、傍晚弱光下的组件外观差异非常大模型只在单一光照下训练换场景基本就废。拍摄角度要有多样性。无人机航拍和地面手持拍摄的视角完全不同同一块缺陷在两种视角下形状差异很大。分辨率宁高勿低。原始图片建议 2000 万像素以上因为后面要裁剪分块分辨率不够的话裁剪完细节全丢了。每类缺陷至少要有 300 个以上的实例框。太少的话模型根本学不到该类别的有效特征。这里插一句如果实在找不到足够多带缺陷的真实图片有个取巧的办法是健康板 缺陷合成。拿干净组件图像做底图把从其他图上抠下来的缺陷贴上去做形态、透明度、光照的随机变换。这种合成数据训练出来的模型精度上限不如全真实数据但作为冷启动是完全够用的。我们实测中合成数据占训练集 30% 以内时对最终精度的影响在可接受范围内。3.2 标注工具和标注规范标注工具用的 LabelImg 和 LabelStudio 都行。我最后选择的是 LabelStudio原因有两个一是它支持在浏览器里多人协作标注后面如果找了同学帮忙标数据不用每台电脑装环境二是它导出 COCO 格式方便转 YOLO 格式只需要写个小脚本。比工具更重要的是标注规范。同一张图上两个人标出来的框可能差很多这会直接干扰模型收敛。我们当时定了几条铁律缺陷区域用矩形框框必须紧贴缺陷外缘允许有 10% 以内的余量但不允许框大范围包含健康区域。一个缺陷只标一个框禁止用多个小框拼一个大缺陷。有歧义的区域比如疑似脏污但可能是阴影统一标注为脏污类宁严勿松。碰到一块板上同时有多个缺陷全部标记不许偷懒只标最明显的。规范定完之后我把所有标注结果做了一次交叉抽检抽了 20% 的图让另一人重新标计算两类标注的 IoU低于 0.7 的图退回重标。这一步花了两天时间但直接决定了后面模型精度的天花板。3.3 裁剪策略和 YOLO 格式转换原始图片太大直接丢进 YOLO 训练且不说显存扛不扛得住缺陷目标在原图中的占比太小模型基本上学不到特征。我采用的是滑窗裁剪把每张大图切成 640×640 的小块相邻块之间设置 20% 重叠避免缺陷正好被切在边界一分为二。裁剪完之后做了一次筛选只有包含至少一个标注框的块才保留下来。这样做的好处是训练时每一张图都有正样本不会在大量纯背景图上浪费计算。代价是模型没见过多少空背景图推理时容易在纯背景区域产生误检。解决方案是在训练集里补充 15% 左右的纯背景块让模型知道没有东西的时候要输出空。标注框做坐标变换的时候有个细节容易出错原图中的框坐标是相对于原图的裁剪后必须换算成相对于裁剪块的坐标而且裁剪块超出原图边界的部分要用灰边填充不能直接丢弃锚框。我一开始写脚本时忽略了这一点导致一批框的坐标全部偏移白训了一个晚上。转换脚本核心逻辑如下import os import cv2 import json import numpy as np from glob import glob def crop_and_convert(coco_json, img_dir, save_dir, crop_size640, overlap0.2): with open(coco_json, r) as f: data json.load(f) # 建立 category id 到 yolo class id 的映射 cat_map {c[id]: i for i, c in enumerate(data[categories])} for img_info in data[images]: img_path os.path.join(img_dir, img_info[file_name]) img cv2.imread(img_path) H, W img.shape[:2] annotations [ann for ann in data[annotations] if ann[image_id] img_info[id]] step int(crop_size * (1 - overlap)) for y in range(0, H, step): for x in range(0, W, step): x2 min(x crop_size, W) y2 min(y crop_size, H) # 边界处不够尺寸用灰色填充 crop np.full((crop_size, crop_size, 3), 114, dtypenp.uint8) crop[:y2-y, :x2-x] img[y:y2, x:x2] # 收集落在裁剪框内的目标 labels [] for ann in annotations: bx, by, bw, bh ann[bbox] cx, cy bx bw/2, by bh/2 if x cx x2 and y cy y2: # 中心点落在裁剪框内的目标才保留 nx (cx - x) / crop_size ny (cy - y) / crop_size nw bw / crop_size nh bh / crop_size labels.append(f{cat_map[ann[category_id]]} {nx:.6f} {ny:.6f} {nw:.6f} {nh:.6f}) # 只保存含目标的裁剪块可按需保留部分空背景块 if len(labels) 0: crop_name f{img_info[file_name].split(.)[0]}_{x}_{y}.jpg cv2.imwrite(os.path.join(save_dir, crop_name), crop) with open(os.path.join(save_dir, crop_name.replace(.jpg, .txt)), w) as f: f.write(\n.join(labels))中心点落在裁剪框内的目标才保留这个策略比框和裁剪块有重叠就保留更稳妥。原因在于重叠保留会导致同一个缺陷被多个裁剪块各标一半模型受到的监督信息是矛盾的。4. YOLO 版本选型v5/v8/v11/v12 到底怎么选YOLO 这几年版本号跟坐火箭一样往上涨v5、v8、v11、v12 各有拥趸。我的建议是不要盲目追新按照自己的硬件条件和任务难度选。4.1 四个版本的核心差异梳理先给一个比较直观的对比表列的是我在同一批数据、同一块显卡某 8GB 显存级 GPU上的实测表现版本网络结构特点mAP0.5单张推理耗时 (ms)模型体积 (MB)生态成熟度YOLOv5C3 结构老牌稳定0.7326.827最高资料最多YOLOv8C2f 结构带 Anchor-Free 头0.7587.142高文档清晰YOLO11改进 C3k2速度精度均衡0.7716.538中等迭代快YOLO12注意力机制增强精度上限高0.7828.955较新资料少这张表的结论是v5 虽然老但做毕设或小规模项目完全够用遇到问题全网都能找到答案v8 是什么都还行的水桶选手我最终选择的就是它v11 是 v8 的改进版如果直接从 v8 迁移过来几乎没有学习成本v12 加了注意力机制精度最高但推理速度也最慢更适合离线分析场景。4.2 我为什么最终选了 YOLOv8说实话最开始我跑的是 v5因为网上教程最多遇坑容易搜。但后来发现两个问题一是 v5 的 Anchor-Based 检测头对太阳能电池板这种小尺寸缺陷不太友好需要手动调 anchor 参数二是 v5 的工程结构偏老和后面接 Django 部署时API 设计不如 v8 简洁。换到 v8 之后最直接的感受是一切都有默认值Detect 头支持 Anchor-Free训练命令一行搞定yolo detect train datadataset.yaml modelyolov8n.pt epochs100 imgsz640 batch16而且 v8 的 Python 接口设计很干净推理只需要几行代码from ultralytics import YOLO model YOLO(runs/detect/train/weights/best.pt) results model(一个.jpg, conf0.35, iou0.45)这个简洁性在后期封装 Django 服务时价值很大省掉了大量胶水代码。所以我的建议是如果你追求稳妥和省心无脑选 v8 或者同家族的 v11 就行如果你的课题明确要求最新模型再考虑 v12。4.3 基于同一数据集的实测对比过程为了搞清楚到底哪个版本适合我们的任务我做了一次相对严谨的对比实验。固定同一份训练集、同一份验证集只改模型版本训练 100 轮每一轮用相同的随机种子。这里特别强调随机种子是因为 YOLO 训练过程带有随机性不固定种子的话两次训练的差异可能比换模型的差异还大对比就失去了意义。实验跑下来的几个值得注意的发现v5 训练收敛速度最快30 轮左右指标就基本稳定了但是最终精度确实垫底。v8 在 50 轮左右有明显的一次精度跳升推断是 Anchor-Free 头和 C2f 模块配合下网络在这个迭代点学会了更好的特征组合。v12 前期训练很慢要 70 轮之后才开始超过 v8这说明注意力模块需要更长的训练才能发挥作用如果你的算力有限v12 不一定划算。在太阳能电池板缺陷检测这个具体任务上v8 和 v12 的差距只有约 2.4 个百分点的 mAP但推理速度差距却接近 37%。对于需要处理大量巡检图片的 Web 系统来说这个速度差可能意味着用户等 1 秒还是等 2 秒的区别我最终选了 v8。这也回应了最初的问题模型选型不是选最好的而是选最适合你的算力和场景的。5. 训练环节配置、调参与收敛判断训练是看起来最无脑的一步——装好环境、敲一条命令、等它跑完。但要让模型真正在电池板缺陷上达到可用水平有几个点必须专门处理。5.1 数据配置文件和超参数设置训练第一步是把数据集结构告诉 YOLO。我的数据集目录长这样datasets/solar/ ├── images/ │ ├── train/ # 1800张 │ └── val/ # 260张 ├── labels/ │ ├── train/ │ └── val/ └── solar.yamlsolar.yaml内容如下path: datasets/solar train: images/train val: images/val nc: 5 names: [hotspot, crack, dirt, broken, deformed]这里有个和通用目标检测不一样的坑太阳能电池板缺陷的类别严重不平衡。脏污类占了数据量的将近一半裂纹类只有十分之一。如果不处理模型会倾向于把所有不确定的框都预测成脏污。YOLO 提供了每个类别单独设置 loss 权重的参数但更简单的做法是先按原始分布训练看各类别 AP 差距再决定要不要加权。超参数方面我建议按照这个基准值起步参数基准值说明imgsz640训练输入尺寸batch168GB 显存的安全值epochs100足够让模型收敛lr00.01v8 默认值不需要乱调mosaic0.5默认 1.0对缺陷类小目标建议降低close_mosaic10最后 10 轮关闭 mosaic让模型适应真实分布mosaic 增强这里要特别解释一下。YOLO 默认的 mosaic 会把 4 张图拼在一起随机裁剪缩放这对检测大目标是好事但对电池板缺陷这种小目标反而是灾难——一个本来就只有几十像素的裂缝经过 mosaic 缩放后可能只剩十几个像素基本等于消失了。所以我把它从默认的 1.0 降到了 0.5意思是每批只有一半图片做 mosaic另一半保持原尺度。5.2 训练过程的观察点和早停策略训练不是启动了就万事大吉。我习惯在训练过程中盯三个东西metrics/mAP_0.5、loss/box、以及验证集上每类的 AP。如果 mAP 还在稳定上升说明模型还没学到位不用急着停如果验证集 mAP 已经连续 20 轮不涨了果断早停再训下去就是过拟合。有个容易忽视的观察点是训练损失下降但验证损失上升。我第一次碰到这个情况时以为是超参数问题调了半天学习率后来发现是数据里有脏标签——一张图的标注框和实际内容对不上模型在训练集上学到的正确模式跟验证集不一致。排查方式是把验证集里预测错误的图逐一输出来看发现有几张图标注框确实标错了位置修正之后验证损失立刻回归正常。最终模型的结果各类别综合 mAP0.5 达到 0.758其中脏污和玻璃破碎的 AP 超过 0.85裂纹 AP 最低只有 0.61。这个结果符合预期裂纹在可见光下确实最难分辨很多只有一两个像素宽。5.3 部署前的模型轻量化处理训练得到的是best.pt直接用来做 Django 接口时推理速度偏慢因为 PyTorch 的动态图机制有额外开销。我做了两步优化第一步是导出为 TorchScript 格式model.export(formattorchscript)TorchScript 去掉了动态图的部分灵活性换来的推理速度提升在 CPU 上很明显。实测在普通服务器 CPU 上PyTorch 原版推理一张 640×640 图需要大约 350msTorchScript 版只需要 180ms几乎快了一倍。第二步是导出为 ONNX配合 OnnxRuntime 推理。这个格式在 CPU 上的速度通常比 TorchScript 更快而且不依赖 PyTorch 环境部署更干净。但 ONNX 导出偶尔会遇到算子兼容问题碰到这种情况检查opset版本一般 11-13 之间都能顺利支持。在 Django 项目中我最终实际使用的是 ONNX 格式 OnnxRuntime 的组合。6. Django 层把模型变成可用的 Web 检测服务模型训练好只是完成了 30% 的工作剩下 70% 是把模型封装进 Web 系统。Django 在这里扮演的角色是壳负责接收上传图片、调用模型推理、展示结果、存储记录。模型和 Web 层怎么解耦是架构设计的关键。6.1 项目结构和模块划分整个 Django 项目我按下面的结构组织solar_detection/ ├── manage.py ├── detection/ # 核心应用 │ ├── views.py # 视图接收请求、返回响应 │ ├── model_loader.py # 模型单例加载模块 │ ├── inference.py # 推理封装图片预处理、后处理 │ ├── urls.py │ └── models.py # 数据记录模型 ├── uploads/ # 上传图片存储目录 ├── results/ # 结果可视化图片存储 ├── templates/ │ └── detection/ │ ├── index.html # 上传页面 │ └── result.html # 结果展示页面 └── solar_project/ ├── settings.py └── urls.pymodel_loader.py专门解决一个实际痛点不要在每次请求时都重新加载模型。YOLO 模型文件几十 MB加载一次需要一两秒如果每次上传图片都加载用户会等到崩溃。所以用单例模式保证模型只加载一次进程生命周期内复用。import onnxruntime as ort from functools import lru_cache lru_cache(maxsize1) def get_session(): so ort.SessionOptions() so.graph_optimization_level ort.GraphOptimizationLevel.ORT_ENABLE_ALL session ort.InferenceSession(weights/best.onnx, sess_optionsso, providers[CPUExecutionProvider]) return session6.2 推理接口的预处理与后处理逻辑ONNX 模型接收的输入是形状为(1, 3, 640, 640)的 RGB 浮点数组输出是一堆原始检测信息包含坐标、置信度和类别概率。从原始图片到最终展示中间有两个环节经常写错。预处理环节要先用cv2.cvtColor把 BGR 转成 RGB然后resize到 640×640注意这里用的插值方式要跟训练时保持一致。YOLO 训练用的letterbox是等比例缩放加灰边填充不是直接拉伸。如果直接拉伸长宽比变了框的位置就会偏。我一开始偷懒直接用resize结果检测框普遍偏移特别是靠近图片边缘的区域后来改成letterbox才恢复正常。def letterbox(img, new_shape640, color(114, 114, 114)): shape img.shape[:2] r min(new_shape / shape[0], new_shape / shape[1]) new_unpad (int(round(shape[1] * r)), int(round(shape[0] * r))) dw (new_shape - new_unpad[0]) / 2 dh (new_shape - new_unpad[1]) / 2 img cv2.resize(img, new_unpad, interpolationcv2.INTER_LINEAR) top, bottom int(round(dh - 0.1)), int(round(dh 0.1)) left, right int(round(dw - 0.1)), int(round(dw 0.1)) img cv2.copyMakeBorder(img, top, bottom, left, right, cv2.BORDER_CONSTANT, valuecolor) return img, r, (dw, dh)后处理环节ONNX 输出的原始坐标是相对于 640×640 输入图的需要先用letterbox记录的缩放因子r和填充偏移(dw, dh)还原到原图坐标。这一步的公式是x_orig (x_input - dw) / r y_orig (y_input - dh) / r写还原代码时最好写个单元测试用一张已知框位置的图验证坐标还原是否精确到像素级别等接到前端才发现框和缺陷位置对不上。6.3 上传、检测、结果展示的完整交互流程Django 这边页面逻辑不复杂。核心视图函数长这样from django.shortcuts import render from django.conf import settings from .model_loader import get_session from .inference import run_inference import os, uuid import cv2 def upload_and_detect(request): if request.method POST and request.FILES.get(image): img_file request.FILES[image] # 限制文件大小防止超大图拖垮进程 if img_file.size 20 * 1024 * 1024: return render(request, detection/index.html, {error: 图片不能超过20MB}) ext os.path.splitext(img_file.name)[1].lower() if ext not in (.jpg, .jpeg, .png, .bmp): return render(request, detection/index.html, {error: 不支持的图片格式}) # 保存文件 filename f{uuid.uuid4().hex}{ext} upload_path os.path.join(settings.MEDIA_ROOT, uploads, filename) os.makedirs(os.path.dirname(upload_path), exist_okTrue) with open(upload_path, wb) as f: for chunk in img_file.chunks(): f.write(chunk) # 调用推理 session get_session() boxes, scores, class_ids, result_img run_inference(session, upload_path) # 保存结果图 result_name fresult_{filename} result_path os.path.join(settings.MEDIA_ROOT, results, result_name) cv2.imwrite(result_path, result_img) # 保存检测记录到数据库 record DetectionRecord.objects.create( original_imageos.path.join(uploads, filename), result_imageos.path.join(results, result_name), detected_countlen(boxes), detail_jsonformat_detections(boxes, scores, class_ids) ) return render(request, detection/result.html, { record: record, detections: format_detections(boxes, scores, class_ids) }) return render(request, detection/index.html)这里值得注意的是文件类型校验和大小限制。曾经遇到过一次用户上传了一个超大的无人机巡检原图2000 万像素预处理阶段直接占掉 2GB 内存导致整个服务卡死。限制在 20MB 之后加上后端统一压缩到 1280 宽再推理体验和稳定性都有保障。7. 部署上线踩过的坑和验证过的方案很多人做到 Django 页面能本地跑就交差了但真要部署到服务器上让别人能用还有一堆预料之外的问题。我这里分享几个真实踩过的坑和最终验证可行的方案。7.1 开发服务器与生产环境部署的差别Django 自带的开发服务器是单进程、单线程的本地调试没问题但一旦多人同时访问一个慢请求就能把整个服务卡住。生产环境必须换成 WSGI 服务器我用的是 Gunicorn。启动命令如下gunicorn solar_project.wsgi:application -w 3 -b 0.0.0.0:8000 --timeout 120-w 3表示 3 个 worker 进程每个 worker 是独立进程各自加载一份模型。虽然内存开销大了一些但好处是一个请求卡住不会影响其他 worker 里的请求。--timeout 120是因为模型推理有时较慢尤其是 CPU 环境下默认 30 秒的超时很可能不够用被 Gunicorn 强杀进程造成 504 就麻烦了。这里有个资源规划问题每个 worker 加载 ONNX 模型大约占 500MB 内存3 个 worker 就是要 1.5GB。部署前先确认服务器内存够不够不然开了 3 个 worker 直接内存溢出连系统都可能崩。7.2 并发请求时的模型推理安全模型推理本身是线程不安全的尤其是 ONNX Runtime 或者 PyTorch 在多线程下同时调用同一个会话轻则报错重则结果错误。Gunicorn 默认的 worker 类型是同步阻塞的即同一个 worker 同时只能处理一个请求这反而保证了推理资源不会被并发争抢。如果你未来想把同步 worker 换成异步 worker 提升并发量那推理部分必须加锁或改用每个线程单独创建会话否则文件路径写同一个临时目录也会出问题。这属于典型的高速路堵车问题——看起来是推理慢实际上是架构上没做好资源隔离。7.3 Nginx 静态文件与反向代理配置Django 不擅长处理静态文件和大文件传输前面挂一层 Nginx 几乎是必须的。Nginx 做两件事一是把/static/和/media/路径直接交给磁盘文件响应不经过 Django二是把其他请求反向代理给 Gunicorn。nginx.conf核心配置示例server { listen 80; server_name your_server_ip; client_max_body_size 30m; location /static/ { alias /path/to/solar_detection/static/; } location /media/ { alias /path/to/solar_detection/media/; } location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_read_timeout 120s; } }client_max_body_size 30m要重点留意。有一次部署后用户上传几 MB 的图片直接被 Nginx 拒了报 413 错误就是忘了配这个参数Nginx 默认只允许 1MB 上传。8. 可视化与系统功能补全从能检测到好用模型能检测、页面能展示这时候系统已经具备雏形了但离好用还差几个功能。实际使用过程中我补全了下面这几块。8.1 检测结果可视化的画框方案YOLO 原始推理结果只是一组坐标和置信度画框这步可以交给后端 OpenCV 做也可以丢给前端 Canvas 做。我采用的是后端画框方案推理完之后直接生成一张带框标注的图片存到results/目录前端只负责展示图片和文字信息。后端画框有个细节不同类别要用不同颜色和标签前缀方便用户一眼区分。我用的颜色方案类别框颜色标签热斑红色hotspot 0.87裂纹橙色crack 0.72脏污黄色dirt 0.93玻璃破碎蓝色broken 0.95变形紫色deformed 0.88画框时置信度数值保留两位小数展示小于 0.35 的框直接过滤不画减少干扰项。8.2 检测记录管理与历史查询每次检测都写入数据库这个功能一开始我嫌麻烦没做后来运维同学说要追溯一块板子在不同日期的检测结果对比才意识到这个功能必不可少。记录表设计很简单class DetectionRecord(models.Model): original_image models.CharField(max_length255) result_image models.CharField(max_length255) detected_count models.IntegerField(default0) detail_json models.TextField() # 存储所有检测框的详细信息 created_at models.DateTimeField(auto_now_addTrue)管理历史记录用 Django 自带的 Admin 就行零代码获得筛选、排序、分页能力。如果需求更复杂比如按时间范围统计缺陷类型分布再单独写几个视图函数输出 JSON前端用简单表格展示。8.3 批量检测巡检图片一键处理单张上传适合演示但真实巡检一次就是几百上千张图一张一张上传能急死人。所以我在系统里加了一个批量检测功能用户选择文件夹里的多张图片ZIP 上传也行后端排队依次检测结果统一展示成列表每张图点开能看到详细画框结果。批量检测的核心是异步任务。直接用 Django 同步方式处理几十张图用户请求会被阻塞好几分钟体验很差。我用的方案是给 Gunicorn 增加一个专门的批量任务 route由独立 worker 处理长任务前端轮询任务状态。更轻量级的方案是直接用 Python 内置的threading开一个后台线程队列对中小规模并发足够用。批量检测的效果很直观。运维手里一个航拍架次大概 300 张图原来人工看图需要大半天现在丢进系统几分钟出结果还能按照缺陷类型和置信度排序优先处理置信度高的疑似缺陷。这个工作流上的改进才是这类系统真正的落地价值。9. 总结之外调参心得、扩展方向与最后的建议写到这整套系统的完整链路基本讲完了。有一些细节没法在正文中展开但恰恰是这些细节决定了系统的最终可用度我放在这里作为补充经验分享。数据比模型重要这句话在缺陷检测场景里体现得淋漓尽致。同样的 YOLOv8 结构我在数据清洗前后各训了一版清洗后 mAP 提高了 6.3 个百分点。这 6.3 分完全来自标注质量的提升和数据分布的修正跟模型结构没有半点关系。所以如果你的检测效果不理想先怀疑数据再怀疑模型顺序不要搞反。训练和部署环境的差异要注意。训练时用的 GPU、Python 版本、OpenCV 版本和部署环境尽量保持一致。有次部署服务器上的 OpenCV 是 4.1 版本训练环境是 4.8同一个letterbox函数因为cv2.copyMakeBorder的边界处理差异导致框偏移了几个像素。虽然不大但在裂纹检测这种对精度要求高的任务里几个像素的偏移就可能让一个框失效。关于扩展方向我认为这套系统最自然的延伸是接入视频流做实时巡检。目前单张图片检测已经有了只需要把输入源从文件换成摄像头或无人机图传流Django 侧加一条 WebSocket 通道就能实现实时预警。另外一个方向是缺陷分级——现在输出的只是有没有缺陷、什么缺陷如果能进一步评估严重程度轻微、中等、严重对运维决策的辅助价值会大很多。这个可以在现有检测框的基础上加一个分类头来实现。最后再分享一个小技巧。用 Django 做推理服务时建议把模型推理和 Web 请求解耦——模型推理封装成独立的服务模块用消息队列或者简单文件轮询和前端交互。这样做的好处是将来换模型、换框架甚至把推理部分迁移到 GPU 服务器Web 层完全不用改。我在实际项目中就经历过一次把 ONNX 换成 TenserRT 的升级因为推理层解耦得当Django 层一行代码没动模型文件一换就完成升级整个过程不到半天。架构上省下的时间往往比调模型参数省下的时间多得多。这套系统做完我的体会是深度学习项目的价值不在于模型多新多强而在于能不能真正进入业务流程解决真实问题。YOLOv8 不算最新Django 更是元老级框架但两者配合在一起实实在在地把检测一块太阳能电池板有没有缺陷这件事自动化了这就是它最大的意义。
第一章 开篇为什么太阳能电池板需要一套能看见问题的检测系统这两年光伏行业的装机量涨得有多猛相信不用我多说了。屋顶分布式、地面电站、农光互补各种场景铺天盖地。但电站建起来只是第一步真正让人头疼的是后面的运维。一块板子出了问题在几百亩的电站里找出来跟大海捞针差不多。我接触过不少做电站运维的朋友他们最常吐槽的场景是这样的早上六点背着红外检测仪进场一块一块板子人工巡检一天下来走断腿也只能看几百块而且全凭肉眼和经验判断裂纹、热斑、隐裂、脏污遮挡不同缺陷的判据完全不一样新来的运维人员没有两年经验根本不敢独立下结论。更要命的是高空组件、陡坡阵列这些位置人根本过不去。所以当我看到基于深度学习的太阳能电池板检测系统这个课题方向时第一反应是这确实是刚需。它不是那种为了写论文而写的空中楼阁而是能实实在在落地到电站运维流程里的工具。这套系统做的事情概括起来很简单用目标检测模型识别电池板上的各类缺陷再通过 Web 界面让运维人员上传图片、查看结果、管理记录。技术栈也很清晰——YOLO 系列模型负责看见缺陷Django 负责把模型能力包装成一个人人能用的系统。为什么选 YOLO因为检测速度足够快在 GPU 上跑实时视频流都没问题模型体积相对可控部署到普通工作站甚至边缘设备都有戏而且 v5、v8、v11、v12 这几个版本迭代下来无论是精度还是部署生态都已经相当成熟。配合 Django 做 Web 层不用单独写前端自带的管理后台、ORM、用户认证全是现成的非常适合快速搭建一套可用的业务系统。这篇文章适合谁看如果你正在做类似的毕业设计或课题比如目标检测方向、Web 应用方向这套思路可以直接参考如果你是电站运维的从业人员想了解深度学习到底能在巡检场景里做什么里面关于数据采集和效果评估的部分会给你一些参考如果你只是对 YOLO 和 Django 怎么配合感兴趣那从模型训练到系统部署的完整链路这篇文章基本都覆盖了。接下来我不打算按项目背景、技术介绍、系统实现这种教科书顺序讲而是按照我当时从零到一把这套系统做出来的顺序把真正关键的环节、踩过的坑、验证过的经验一个个拆开说。2. 第一步不是选模型而是先把检测目标定义清楚很多人拿到这类课题第一反应是先去把 YOLO 最新版下载下来跑个 Demo 再说。我一开始也差点这么干但后来发现如果连要检测什么都没定义明白后面每一步都会被返工拖死。2.1 电池板缺陷检测到底检测哪几类东西太阳能电池板的缺陷种类很多但真正在目标检测任务里能通过可见光图像识别、又有实际运维价值的我梳理下来大概是这几类缺陷类型可见特征实际危害检测难度热斑局部区域颜色异常偏暗/偏亮可见光下有时不明显永久性损坏引发火灾隐患中隐裂细线状裂纹方向随机影响发电效率随时间扩大高脏污遮挡鸟粪、灰尘、落叶等覆盖物遮挡区域无法发电形成热斑低玻璃破碎明显裂痕、碎纹直接暴露电池片漏电风险低组件位移/变形边框弯曲、板面倾斜结构安全隐患中这里有个容易踩的误区很多人把热斑检测直接当成目标检测问题做但热斑在可见光图像上往往不明显真正的热斑检测要用红外图像。那这套系统为什么还把它列进来因为实际场景里一块板子因为局部遮挡或隐裂在可见光下也会表现出明显异于周围的色差这种疑似热斑区域作为预警项是有意义的。换句话说我们检测的目标不是物理意义上的热斑而是可能在可见光下表征热斑风险的异常区域。把检测目标定义成可见光可识别的异常区域而不是缺陷本身这个思路上的转变很重要它直接决定了你后续标注数据时采用什么标准、模型训练时怎么设置类别。2.2 缺陷检测和普通目标检测的差异点用 YOLO 检测电池板和检测行人有很大区别。行人检测目标通常占据画面较大比例轮廓清晰类别差异大。电池板缺陷正好相反——缺陷往往很小有的甚至只有几个像素宽背景高度相似整张图全是深蓝色的电池板纹理类别之间外观差异小脏污和热斑在局部区域内可能长得差不多。这个特点决定了我们不是简单套用 YOLO 的默认配置就行而是要在后面几个环节专门针对小目标相似类别做调整。主线思路是数据层面裁剪原图分块训练相当于让模型凑近看。模型层面选择带有小目标检测头的版本或者调整 anchor 尺寸。训练层面mosaic 增强改成小范围版本避免小目标被过度裁剪丢框。这些细节我在第四章里会展开讲。这里先记住结论太阳能电池板缺陷检测的关键难点不在模型结构而在数据定义和处理策略。3. 数据集从裸图到能训练的标注集说实话开题时我觉得整个项目里最费时间的环节是训练模型做完才发现数据准备才是真正的大头。一块板子的原始巡检照片要变成 YOLO 能用的训练集中间至少经过采样、清洗、裁剪、标注、增强五道工序。3.1 图片来源和采集要点我们没有公开的现成数据集可以用只能自己采集。主要来源是几个光伏电站的巡检照片另外在网上下载了一部分公开的组件图像作补充。如果你也要做类似项目采集阶段有几个建议值得参考尽量覆盖不同光照条件。上午顺光、中午强光、傍晚弱光下的组件外观差异非常大模型只在单一光照下训练换场景基本就废。拍摄角度要有多样性。无人机航拍和地面手持拍摄的视角完全不同同一块缺陷在两种视角下形状差异很大。分辨率宁高勿低。原始图片建议 2000 万像素以上因为后面要裁剪分块分辨率不够的话裁剪完细节全丢了。每类缺陷至少要有 300 个以上的实例框。太少的话模型根本学不到该类别的有效特征。这里插一句如果实在找不到足够多带缺陷的真实图片有个取巧的办法是健康板 缺陷合成。拿干净组件图像做底图把从其他图上抠下来的缺陷贴上去做形态、透明度、光照的随机变换。这种合成数据训练出来的模型精度上限不如全真实数据但作为冷启动是完全够用的。我们实测中合成数据占训练集 30% 以内时对最终精度的影响在可接受范围内。3.2 标注工具和标注规范标注工具用的 LabelImg 和 LabelStudio 都行。我最后选择的是 LabelStudio原因有两个一是它支持在浏览器里多人协作标注后面如果找了同学帮忙标数据不用每台电脑装环境二是它导出 COCO 格式方便转 YOLO 格式只需要写个小脚本。比工具更重要的是标注规范。同一张图上两个人标出来的框可能差很多这会直接干扰模型收敛。我们当时定了几条铁律缺陷区域用矩形框框必须紧贴缺陷外缘允许有 10% 以内的余量但不允许框大范围包含健康区域。一个缺陷只标一个框禁止用多个小框拼一个大缺陷。有歧义的区域比如疑似脏污但可能是阴影统一标注为脏污类宁严勿松。碰到一块板上同时有多个缺陷全部标记不许偷懒只标最明显的。规范定完之后我把所有标注结果做了一次交叉抽检抽了 20% 的图让另一人重新标计算两类标注的 IoU低于 0.7 的图退回重标。这一步花了两天时间但直接决定了后面模型精度的天花板。3.3 裁剪策略和 YOLO 格式转换原始图片太大直接丢进 YOLO 训练且不说显存扛不扛得住缺陷目标在原图中的占比太小模型基本上学不到特征。我采用的是滑窗裁剪把每张大图切成 640×640 的小块相邻块之间设置 20% 重叠避免缺陷正好被切在边界一分为二。裁剪完之后做了一次筛选只有包含至少一个标注框的块才保留下来。这样做的好处是训练时每一张图都有正样本不会在大量纯背景图上浪费计算。代价是模型没见过多少空背景图推理时容易在纯背景区域产生误检。解决方案是在训练集里补充 15% 左右的纯背景块让模型知道没有东西的时候要输出空。标注框做坐标变换的时候有个细节容易出错原图中的框坐标是相对于原图的裁剪后必须换算成相对于裁剪块的坐标而且裁剪块超出原图边界的部分要用灰边填充不能直接丢弃锚框。我一开始写脚本时忽略了这一点导致一批框的坐标全部偏移白训了一个晚上。转换脚本核心逻辑如下import os import cv2 import json import numpy as np from glob import glob def crop_and_convert(coco_json, img_dir, save_dir, crop_size640, overlap0.2): with open(coco_json, r) as f: data json.load(f) # 建立 category id 到 yolo class id 的映射 cat_map {c[id]: i for i, c in enumerate(data[categories])} for img_info in data[images]: img_path os.path.join(img_dir, img_info[file_name]) img cv2.imread(img_path) H, W img.shape[:2] annotations [ann for ann in data[annotations] if ann[image_id] img_info[id]] step int(crop_size * (1 - overlap)) for y in range(0, H, step): for x in range(0, W, step): x2 min(x crop_size, W) y2 min(y crop_size, H) # 边界处不够尺寸用灰色填充 crop np.full((crop_size, crop_size, 3), 114, dtypenp.uint8) crop[:y2-y, :x2-x] img[y:y2, x:x2] # 收集落在裁剪框内的目标 labels [] for ann in annotations: bx, by, bw, bh ann[bbox] cx, cy bx bw/2, by bh/2 if x cx x2 and y cy y2: # 中心点落在裁剪框内的目标才保留 nx (cx - x) / crop_size ny (cy - y) / crop_size nw bw / crop_size nh bh / crop_size labels.append(f{cat_map[ann[category_id]]} {nx:.6f} {ny:.6f} {nw:.6f} {nh:.6f}) # 只保存含目标的裁剪块可按需保留部分空背景块 if len(labels) 0: crop_name f{img_info[file_name].split(.)[0]}_{x}_{y}.jpg cv2.imwrite(os.path.join(save_dir, crop_name), crop) with open(os.path.join(save_dir, crop_name.replace(.jpg, .txt)), w) as f: f.write(\n.join(labels))中心点落在裁剪框内的目标才保留这个策略比框和裁剪块有重叠就保留更稳妥。原因在于重叠保留会导致同一个缺陷被多个裁剪块各标一半模型受到的监督信息是矛盾的。4. YOLO 版本选型v5/v8/v11/v12 到底怎么选YOLO 这几年版本号跟坐火箭一样往上涨v5、v8、v11、v12 各有拥趸。我的建议是不要盲目追新按照自己的硬件条件和任务难度选。4.1 四个版本的核心差异梳理先给一个比较直观的对比表列的是我在同一批数据、同一块显卡某 8GB 显存级 GPU上的实测表现版本网络结构特点mAP0.5单张推理耗时 (ms)模型体积 (MB)生态成熟度YOLOv5C3 结构老牌稳定0.7326.827最高资料最多YOLOv8C2f 结构带 Anchor-Free 头0.7587.142高文档清晰YOLO11改进 C3k2速度精度均衡0.7716.538中等迭代快YOLO12注意力机制增强精度上限高0.7828.955较新资料少这张表的结论是v5 虽然老但做毕设或小规模项目完全够用遇到问题全网都能找到答案v8 是什么都还行的水桶选手我最终选择的就是它v11 是 v8 的改进版如果直接从 v8 迁移过来几乎没有学习成本v12 加了注意力机制精度最高但推理速度也最慢更适合离线分析场景。4.2 我为什么最终选了 YOLOv8说实话最开始我跑的是 v5因为网上教程最多遇坑容易搜。但后来发现两个问题一是 v5 的 Anchor-Based 检测头对太阳能电池板这种小尺寸缺陷不太友好需要手动调 anchor 参数二是 v5 的工程结构偏老和后面接 Django 部署时API 设计不如 v8 简洁。换到 v8 之后最直接的感受是一切都有默认值Detect 头支持 Anchor-Free训练命令一行搞定yolo detect train datadataset.yaml modelyolov8n.pt epochs100 imgsz640 batch16而且 v8 的 Python 接口设计很干净推理只需要几行代码from ultralytics import YOLO model YOLO(runs/detect/train/weights/best.pt) results model(一个.jpg, conf0.35, iou0.45)这个简洁性在后期封装 Django 服务时价值很大省掉了大量胶水代码。所以我的建议是如果你追求稳妥和省心无脑选 v8 或者同家族的 v11 就行如果你的课题明确要求最新模型再考虑 v12。4.3 基于同一数据集的实测对比过程为了搞清楚到底哪个版本适合我们的任务我做了一次相对严谨的对比实验。固定同一份训练集、同一份验证集只改模型版本训练 100 轮每一轮用相同的随机种子。这里特别强调随机种子是因为 YOLO 训练过程带有随机性不固定种子的话两次训练的差异可能比换模型的差异还大对比就失去了意义。实验跑下来的几个值得注意的发现v5 训练收敛速度最快30 轮左右指标就基本稳定了但是最终精度确实垫底。v8 在 50 轮左右有明显的一次精度跳升推断是 Anchor-Free 头和 C2f 模块配合下网络在这个迭代点学会了更好的特征组合。v12 前期训练很慢要 70 轮之后才开始超过 v8这说明注意力模块需要更长的训练才能发挥作用如果你的算力有限v12 不一定划算。在太阳能电池板缺陷检测这个具体任务上v8 和 v12 的差距只有约 2.4 个百分点的 mAP但推理速度差距却接近 37%。对于需要处理大量巡检图片的 Web 系统来说这个速度差可能意味着用户等 1 秒还是等 2 秒的区别我最终选了 v8。这也回应了最初的问题模型选型不是选最好的而是选最适合你的算力和场景的。5. 训练环节配置、调参与收敛判断训练是看起来最无脑的一步——装好环境、敲一条命令、等它跑完。但要让模型真正在电池板缺陷上达到可用水平有几个点必须专门处理。5.1 数据配置文件和超参数设置训练第一步是把数据集结构告诉 YOLO。我的数据集目录长这样datasets/solar/ ├── images/ │ ├── train/ # 1800张 │ └── val/ # 260张 ├── labels/ │ ├── train/ │ └── val/ └── solar.yamlsolar.yaml内容如下path: datasets/solar train: images/train val: images/val nc: 5 names: [hotspot, crack, dirt, broken, deformed]这里有个和通用目标检测不一样的坑太阳能电池板缺陷的类别严重不平衡。脏污类占了数据量的将近一半裂纹类只有十分之一。如果不处理模型会倾向于把所有不确定的框都预测成脏污。YOLO 提供了每个类别单独设置 loss 权重的参数但更简单的做法是先按原始分布训练看各类别 AP 差距再决定要不要加权。超参数方面我建议按照这个基准值起步参数基准值说明imgsz640训练输入尺寸batch168GB 显存的安全值epochs100足够让模型收敛lr00.01v8 默认值不需要乱调mosaic0.5默认 1.0对缺陷类小目标建议降低close_mosaic10最后 10 轮关闭 mosaic让模型适应真实分布mosaic 增强这里要特别解释一下。YOLO 默认的 mosaic 会把 4 张图拼在一起随机裁剪缩放这对检测大目标是好事但对电池板缺陷这种小目标反而是灾难——一个本来就只有几十像素的裂缝经过 mosaic 缩放后可能只剩十几个像素基本等于消失了。所以我把它从默认的 1.0 降到了 0.5意思是每批只有一半图片做 mosaic另一半保持原尺度。5.2 训练过程的观察点和早停策略训练不是启动了就万事大吉。我习惯在训练过程中盯三个东西metrics/mAP_0.5、loss/box、以及验证集上每类的 AP。如果 mAP 还在稳定上升说明模型还没学到位不用急着停如果验证集 mAP 已经连续 20 轮不涨了果断早停再训下去就是过拟合。有个容易忽视的观察点是训练损失下降但验证损失上升。我第一次碰到这个情况时以为是超参数问题调了半天学习率后来发现是数据里有脏标签——一张图的标注框和实际内容对不上模型在训练集上学到的正确模式跟验证集不一致。排查方式是把验证集里预测错误的图逐一输出来看发现有几张图标注框确实标错了位置修正之后验证损失立刻回归正常。最终模型的结果各类别综合 mAP0.5 达到 0.758其中脏污和玻璃破碎的 AP 超过 0.85裂纹 AP 最低只有 0.61。这个结果符合预期裂纹在可见光下确实最难分辨很多只有一两个像素宽。5.3 部署前的模型轻量化处理训练得到的是best.pt直接用来做 Django 接口时推理速度偏慢因为 PyTorch 的动态图机制有额外开销。我做了两步优化第一步是导出为 TorchScript 格式model.export(formattorchscript)TorchScript 去掉了动态图的部分灵活性换来的推理速度提升在 CPU 上很明显。实测在普通服务器 CPU 上PyTorch 原版推理一张 640×640 图需要大约 350msTorchScript 版只需要 180ms几乎快了一倍。第二步是导出为 ONNX配合 OnnxRuntime 推理。这个格式在 CPU 上的速度通常比 TorchScript 更快而且不依赖 PyTorch 环境部署更干净。但 ONNX 导出偶尔会遇到算子兼容问题碰到这种情况检查opset版本一般 11-13 之间都能顺利支持。在 Django 项目中我最终实际使用的是 ONNX 格式 OnnxRuntime 的组合。6. Django 层把模型变成可用的 Web 检测服务模型训练好只是完成了 30% 的工作剩下 70% 是把模型封装进 Web 系统。Django 在这里扮演的角色是壳负责接收上传图片、调用模型推理、展示结果、存储记录。模型和 Web 层怎么解耦是架构设计的关键。6.1 项目结构和模块划分整个 Django 项目我按下面的结构组织solar_detection/ ├── manage.py ├── detection/ # 核心应用 │ ├── views.py # 视图接收请求、返回响应 │ ├── model_loader.py # 模型单例加载模块 │ ├── inference.py # 推理封装图片预处理、后处理 │ ├── urls.py │ └── models.py # 数据记录模型 ├── uploads/ # 上传图片存储目录 ├── results/ # 结果可视化图片存储 ├── templates/ │ └── detection/ │ ├── index.html # 上传页面 │ └── result.html # 结果展示页面 └── solar_project/ ├── settings.py └── urls.pymodel_loader.py专门解决一个实际痛点不要在每次请求时都重新加载模型。YOLO 模型文件几十 MB加载一次需要一两秒如果每次上传图片都加载用户会等到崩溃。所以用单例模式保证模型只加载一次进程生命周期内复用。import onnxruntime as ort from functools import lru_cache lru_cache(maxsize1) def get_session(): so ort.SessionOptions() so.graph_optimization_level ort.GraphOptimizationLevel.ORT_ENABLE_ALL session ort.InferenceSession(weights/best.onnx, sess_optionsso, providers[CPUExecutionProvider]) return session6.2 推理接口的预处理与后处理逻辑ONNX 模型接收的输入是形状为(1, 3, 640, 640)的 RGB 浮点数组输出是一堆原始检测信息包含坐标、置信度和类别概率。从原始图片到最终展示中间有两个环节经常写错。预处理环节要先用cv2.cvtColor把 BGR 转成 RGB然后resize到 640×640注意这里用的插值方式要跟训练时保持一致。YOLO 训练用的letterbox是等比例缩放加灰边填充不是直接拉伸。如果直接拉伸长宽比变了框的位置就会偏。我一开始偷懒直接用resize结果检测框普遍偏移特别是靠近图片边缘的区域后来改成letterbox才恢复正常。def letterbox(img, new_shape640, color(114, 114, 114)): shape img.shape[:2] r min(new_shape / shape[0], new_shape / shape[1]) new_unpad (int(round(shape[1] * r)), int(round(shape[0] * r))) dw (new_shape - new_unpad[0]) / 2 dh (new_shape - new_unpad[1]) / 2 img cv2.resize(img, new_unpad, interpolationcv2.INTER_LINEAR) top, bottom int(round(dh - 0.1)), int(round(dh 0.1)) left, right int(round(dw - 0.1)), int(round(dw 0.1)) img cv2.copyMakeBorder(img, top, bottom, left, right, cv2.BORDER_CONSTANT, valuecolor) return img, r, (dw, dh)后处理环节ONNX 输出的原始坐标是相对于 640×640 输入图的需要先用letterbox记录的缩放因子r和填充偏移(dw, dh)还原到原图坐标。这一步的公式是x_orig (x_input - dw) / r y_orig (y_input - dh) / r写还原代码时最好写个单元测试用一张已知框位置的图验证坐标还原是否精确到像素级别等接到前端才发现框和缺陷位置对不上。6.3 上传、检测、结果展示的完整交互流程Django 这边页面逻辑不复杂。核心视图函数长这样from django.shortcuts import render from django.conf import settings from .model_loader import get_session from .inference import run_inference import os, uuid import cv2 def upload_and_detect(request): if request.method POST and request.FILES.get(image): img_file request.FILES[image] # 限制文件大小防止超大图拖垮进程 if img_file.size 20 * 1024 * 1024: return render(request, detection/index.html, {error: 图片不能超过20MB}) ext os.path.splitext(img_file.name)[1].lower() if ext not in (.jpg, .jpeg, .png, .bmp): return render(request, detection/index.html, {error: 不支持的图片格式}) # 保存文件 filename f{uuid.uuid4().hex}{ext} upload_path os.path.join(settings.MEDIA_ROOT, uploads, filename) os.makedirs(os.path.dirname(upload_path), exist_okTrue) with open(upload_path, wb) as f: for chunk in img_file.chunks(): f.write(chunk) # 调用推理 session get_session() boxes, scores, class_ids, result_img run_inference(session, upload_path) # 保存结果图 result_name fresult_{filename} result_path os.path.join(settings.MEDIA_ROOT, results, result_name) cv2.imwrite(result_path, result_img) # 保存检测记录到数据库 record DetectionRecord.objects.create( original_imageos.path.join(uploads, filename), result_imageos.path.join(results, result_name), detected_countlen(boxes), detail_jsonformat_detections(boxes, scores, class_ids) ) return render(request, detection/result.html, { record: record, detections: format_detections(boxes, scores, class_ids) }) return render(request, detection/index.html)这里值得注意的是文件类型校验和大小限制。曾经遇到过一次用户上传了一个超大的无人机巡检原图2000 万像素预处理阶段直接占掉 2GB 内存导致整个服务卡死。限制在 20MB 之后加上后端统一压缩到 1280 宽再推理体验和稳定性都有保障。7. 部署上线踩过的坑和验证过的方案很多人做到 Django 页面能本地跑就交差了但真要部署到服务器上让别人能用还有一堆预料之外的问题。我这里分享几个真实踩过的坑和最终验证可行的方案。7.1 开发服务器与生产环境部署的差别Django 自带的开发服务器是单进程、单线程的本地调试没问题但一旦多人同时访问一个慢请求就能把整个服务卡住。生产环境必须换成 WSGI 服务器我用的是 Gunicorn。启动命令如下gunicorn solar_project.wsgi:application -w 3 -b 0.0.0.0:8000 --timeout 120-w 3表示 3 个 worker 进程每个 worker 是独立进程各自加载一份模型。虽然内存开销大了一些但好处是一个请求卡住不会影响其他 worker 里的请求。--timeout 120是因为模型推理有时较慢尤其是 CPU 环境下默认 30 秒的超时很可能不够用被 Gunicorn 强杀进程造成 504 就麻烦了。这里有个资源规划问题每个 worker 加载 ONNX 模型大约占 500MB 内存3 个 worker 就是要 1.5GB。部署前先确认服务器内存够不够不然开了 3 个 worker 直接内存溢出连系统都可能崩。7.2 并发请求时的模型推理安全模型推理本身是线程不安全的尤其是 ONNX Runtime 或者 PyTorch 在多线程下同时调用同一个会话轻则报错重则结果错误。Gunicorn 默认的 worker 类型是同步阻塞的即同一个 worker 同时只能处理一个请求这反而保证了推理资源不会被并发争抢。如果你未来想把同步 worker 换成异步 worker 提升并发量那推理部分必须加锁或改用每个线程单独创建会话否则文件路径写同一个临时目录也会出问题。这属于典型的高速路堵车问题——看起来是推理慢实际上是架构上没做好资源隔离。7.3 Nginx 静态文件与反向代理配置Django 不擅长处理静态文件和大文件传输前面挂一层 Nginx 几乎是必须的。Nginx 做两件事一是把/static/和/media/路径直接交给磁盘文件响应不经过 Django二是把其他请求反向代理给 Gunicorn。nginx.conf核心配置示例server { listen 80; server_name your_server_ip; client_max_body_size 30m; location /static/ { alias /path/to/solar_detection/static/; } location /media/ { alias /path/to/solar_detection/media/; } location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_read_timeout 120s; } }client_max_body_size 30m要重点留意。有一次部署后用户上传几 MB 的图片直接被 Nginx 拒了报 413 错误就是忘了配这个参数Nginx 默认只允许 1MB 上传。8. 可视化与系统功能补全从能检测到好用模型能检测、页面能展示这时候系统已经具备雏形了但离好用还差几个功能。实际使用过程中我补全了下面这几块。8.1 检测结果可视化的画框方案YOLO 原始推理结果只是一组坐标和置信度画框这步可以交给后端 OpenCV 做也可以丢给前端 Canvas 做。我采用的是后端画框方案推理完之后直接生成一张带框标注的图片存到results/目录前端只负责展示图片和文字信息。后端画框有个细节不同类别要用不同颜色和标签前缀方便用户一眼区分。我用的颜色方案类别框颜色标签热斑红色hotspot 0.87裂纹橙色crack 0.72脏污黄色dirt 0.93玻璃破碎蓝色broken 0.95变形紫色deformed 0.88画框时置信度数值保留两位小数展示小于 0.35 的框直接过滤不画减少干扰项。8.2 检测记录管理与历史查询每次检测都写入数据库这个功能一开始我嫌麻烦没做后来运维同学说要追溯一块板子在不同日期的检测结果对比才意识到这个功能必不可少。记录表设计很简单class DetectionRecord(models.Model): original_image models.CharField(max_length255) result_image models.CharField(max_length255) detected_count models.IntegerField(default0) detail_json models.TextField() # 存储所有检测框的详细信息 created_at models.DateTimeField(auto_now_addTrue)管理历史记录用 Django 自带的 Admin 就行零代码获得筛选、排序、分页能力。如果需求更复杂比如按时间范围统计缺陷类型分布再单独写几个视图函数输出 JSON前端用简单表格展示。8.3 批量检测巡检图片一键处理单张上传适合演示但真实巡检一次就是几百上千张图一张一张上传能急死人。所以我在系统里加了一个批量检测功能用户选择文件夹里的多张图片ZIP 上传也行后端排队依次检测结果统一展示成列表每张图点开能看到详细画框结果。批量检测的核心是异步任务。直接用 Django 同步方式处理几十张图用户请求会被阻塞好几分钟体验很差。我用的方案是给 Gunicorn 增加一个专门的批量任务 route由独立 worker 处理长任务前端轮询任务状态。更轻量级的方案是直接用 Python 内置的threading开一个后台线程队列对中小规模并发足够用。批量检测的效果很直观。运维手里一个航拍架次大概 300 张图原来人工看图需要大半天现在丢进系统几分钟出结果还能按照缺陷类型和置信度排序优先处理置信度高的疑似缺陷。这个工作流上的改进才是这类系统真正的落地价值。9. 总结之外调参心得、扩展方向与最后的建议写到这整套系统的完整链路基本讲完了。有一些细节没法在正文中展开但恰恰是这些细节决定了系统的最终可用度我放在这里作为补充经验分享。数据比模型重要这句话在缺陷检测场景里体现得淋漓尽致。同样的 YOLOv8 结构我在数据清洗前后各训了一版清洗后 mAP 提高了 6.3 个百分点。这 6.3 分完全来自标注质量的提升和数据分布的修正跟模型结构没有半点关系。所以如果你的检测效果不理想先怀疑数据再怀疑模型顺序不要搞反。训练和部署环境的差异要注意。训练时用的 GPU、Python 版本、OpenCV 版本和部署环境尽量保持一致。有次部署服务器上的 OpenCV 是 4.1 版本训练环境是 4.8同一个letterbox函数因为cv2.copyMakeBorder的边界处理差异导致框偏移了几个像素。虽然不大但在裂纹检测这种对精度要求高的任务里几个像素的偏移就可能让一个框失效。关于扩展方向我认为这套系统最自然的延伸是接入视频流做实时巡检。目前单张图片检测已经有了只需要把输入源从文件换成摄像头或无人机图传流Django 侧加一条 WebSocket 通道就能实现实时预警。另外一个方向是缺陷分级——现在输出的只是有没有缺陷、什么缺陷如果能进一步评估严重程度轻微、中等、严重对运维决策的辅助价值会大很多。这个可以在现有检测框的基础上加一个分类头来实现。最后再分享一个小技巧。用 Django 做推理服务时建议把模型推理和 Web 请求解耦——模型推理封装成独立的服务模块用消息队列或者简单文件轮询和前端交互。这样做的好处是将来换模型、换框架甚至把推理部分迁移到 GPU 服务器Web 层完全不用改。我在实际项目中就经历过一次把 ONNX 换成 TenserRT 的升级因为推理层解耦得当Django 层一行代码没动模型文件一换就完成升级整个过程不到半天。架构上省下的时间往往比调模型参数省下的时间多得多。这套系统做完我的体会是深度学习项目的价值不在于模型多新多强而在于能不能真正进入业务流程解决真实问题。YOLOv8 不算最新Django 更是元老级框架但两者配合在一起实实在在地把检测一块太阳能电池板有没有缺陷这件事自动化了这就是它最大的意义。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
