基于YOLOv5的毕业设计实战：从环境搭建到模型部署全流程解析

背景痛点：为什么“跑通”YOLOv5毕设这么难

做毕设选目标检测，十之八九会碰到下面几类“坑”：

1. 环境配置：CUDA、PyTorch、ultralytics版本三角恋，一升级就报错，实验室服务器还没外网，conda install 卡半天。
2. 数据稀缺：公开数据集类别太多，导师只要“瓶盖缺陷”这一类，结果只有两百张手机随手拍，分辨率还参差不齐。
3. 训练玄学：loss 一直下不去，mAP 波动像股票，调大 batch 显存就炸，调小 batch 又收敛慢。
4. 部署翻车：好不容易训练完，导出 ONNX 节点爆红；Flask 一并发就阻塞；边缘盒子只有 2 GB 内存，模型加载直接 Oom-killer。

这些问题把“学术 Demo”和“工业交付”活生生撕成两截。下面用一次真实毕设——“饮料瓶外观缺陷检测”——把整个闭环跑通，并给出可复现的脚本和踩坑记录。

图片占位：

技术选型：YOLOv5 凭啥还能打

很多同学问：YOLOv8、RT-DETR 不是更新更强吗？在本科毕设场景里，YOLOv5 仍是最稳的“六边形战士”：

1. 社区存量大：GitHub issue 4k+，StackOverflow 一搜就有答案，导师也能看懂。
2. 文档完整：ultralytics 官方 wiki 把“训练-验证-导出”写成一行命令，毕设报告里直接截图就能当“系统流程”。
3. PyTorch 原生：改 backbone、加注意力、剪枝，代码都在.py里，无需翻 C++。
4. 硬件友好：v5s 权重 14 MB，树莓派 4B 也能跑到 3 FPS，方便现场演示。

一句话：在“时间紧、算力少、经验浅”的三角约束下，YOLOv5 是最低成本拿到 80 分以上的方案。

核心实现细节：数据→训练→验证一条龙

1. 自定义数据集：VOC→YOLO 一键转

标注工具用 LabelImg，保存成 Pascal VOC 的 XML。写个voc2yolo.py，把 bbox 从(xmin,ymin,xmax,ymax)转成归一化(cx,cy,w,h)，同时生成train/val.txt：

import xml.etree.ElementTree as ET, os, shutil def convert(size, box): dw, dh = 1./size[0], 1./size[1] x, y, w, h = (box[0]+box[1])/2.0, (box[2]+box[3])/2.0, box[1]-box[0], box[3]-box[2] return x*dw, y*dh, w*dw, h*dh

跑完目录结构如下：

dataset/ ├── images/train/*.jpg ├── labels/train/*.txt ├── images/val/*.jpg ├── labels/val/*.txt ├── data.yaml # 关键，下文给出

2. data.yaml：三行别写错

train: ../dataset/images/train val: ../dataset/images/val nc: 3 # 缺陷类别数 names: ['logo_missing', 'dent', 'scratch']

血泪提醒：names顺序必须与标注时一致，否则后期pycocotools算 mAP 会错位，答辩时被老师一句“你的 PR 曲线为什么掉点？”直接问懵。

3. 训练超参：显存与精度的跷跷板

实验室 1080Ti 11 GB，实测 batch 16 能把imgsz=640吃满；batch 32 会 CUDA OOM。epochs 设 300，配合cos_lr余弦退火，前 20 epoch 冻住 backbone，可省 30 % 时间。关键命令：

python train.py --img 640 --batch 16 --epochs 300 \ --data data.yaml --cfg yolov5s.yaml \ --weights yolov5s.pt --name bottle_defect \ --cache --cos-lr --freeze 10

4. 验证策略：训练中途每 10 epoch 测一次

用val.py生成results.csv，重点看mAP@0.5:0.95。若 100 epoch 后仍 < 0.55，大概率数据分布偏了，立刻回去检查标注。另写脚本把val_batch0_labels.jpg与val_batch0_pred.jpg并排贴进 PPT，答辩老师一眼就能看效果，比放 loss 曲线更直观。

代码示例：训练→导出→API 三件套

1. train.py（官方仓库已带，核心调用）

# 克隆 ultralytics/yolov5 git clone https://github.com/ultralytics/yolov5.git cd yolov5 pip install -r requirements.txt # 上面训练命令直接跑

2. export.py：转 ONNX，节点数最少

python export.py --weights runs/train/bottle_defect/weights/best.pt \ --imgsz 640 --batch 1 --device 0 --include onnx

注意：

• --opset 12默认即可，边缘端推理框架（ONNXRuntime、MNN）都认。
• 动态维度--dynamic在 Flask 并发场景下会反复 reallocate，反而更慢，毕设演示建议固定尺寸。

3. Flask 轻量级服务：单文件可跑

# infer_server.py import cv2, numpy as np, onnxruntime as ort from flask import Flask, request, jsonify app = Flask(__name__) ort_sess = ort.InferenceSession("best.onnx", providers=['CUDAExecutionProvider']) def letterbox(im, new_shape=(640,640)): # 保持比例缩放，边缘灰条 shape = im.shape[:2] r = min(new_shape[0]/im.shape[0], new_shape[1]/im.shape[1]) unpad_h, unpad_w = int(im.shape[0]*r), int(im.shape[1]*r) im = cv2.resize(im, (unpad_w, unpad_h)) top = (new_shape[0]-unpad_h)//2 left = (new_shape[1]-unpad_w)//2 canvas = np.full((new_shape[0],new_shape[1],3), 114, dtype=np.uint8) canvas[top:top+unpad_h, left:left+unpad_w] = im return canvas, r, (left, top) @app.route("/predict", methods=["POST"]) def predict(): file = request.files['image'] nparr = np.frombuffer(file.read(), np.uint8) img0 = cv2.imdecode(nparr, cv2.IMREAD_COLOR) img, ratio, dwdh = letterbox(img0) img = img[:,:,::-1].transpose(2,0,1)[None]/255.0 outputs = ort_sess.run(None, {ort_sess.get_inputs()[0].name: img.astype(np.float32)}) # 后处理：nms + 阈值过滤 conf_thres, iou_thres = 0.25, 0.45 # …省略 20 行 numpy 后处理… return jsonify(boxes=boxes, scores=scores, classes=classes) if __name__ == "__main__": app.run(host="0.0.0.0", port=5000)

并发测试：
locust -f locustfile.py --host=http://localhost:5000 -u 20 -r 5 -t 30s
1080Ti 上 20 并发，平均延迟 90 ms，GPU 占用 40 %，足够毕设现场拍照上传。

性能与安全：让模型跑得又快又稳

1. 模型大小：v5s 14 MB，v5m 42 MB。毕设展板写“轻量化”时，直接贴体积数字，评阅老师一眼秒懂。
2. 推理延迟：640×640 输入，1080Ti 上 v5s 6 ms，Jetson Nano 15 ms；把--img 416再降 30 %，精度只掉 1.2 %。
3. 输入校验：Flask 接口里加try/except，防止非 JPG 头直接抛 500；限制最大尺寸 2 MB，避免 4K 大图瞬间吃爆内存。
4. 异常处理：ONNXRuntime 若CUDA out of mem自动 fallback 到 CPU，日志写文件，演示时不会尴尬黑屏。

图片占位：

生产环境避坑指南：把“能跑”变“能扛”

1. 路径硬编码：Windows 路径\与 Linux/混用，打包 Docker 镜像后找不到best.onnx。统一用pathlib.Path。
2. GPU 内存泄漏：Flask 多线程 + CUDA context 不释放，压测 10 min 后显存飙满。解决：把ort.InferenceSession做成全局单例，禁用providers的cuda再重建。
3. 类别标签错位：训练时names顺序与客户端 JSON 不一致，导致前端红色框标成“dent”其实是“scratch”。前后端共用同一份labels.txt，CI 自动检测。
4. 忘记关--cache：训练机重启后cache*.tensor占 50 GB，新同学一登录就“磁盘满”。写进Makefile：clean: find . -name "*.tensor" -delete。
5. 演示现场光照变化：展台 LED 偏蓝，模型 AP 掉 10 %。提前在albumentations里加HueSaturationValue，把色偏拉满，鲁棒性肉眼可见提升。

下一步：把毕设做成产品

1. 调 NMS：把iou_thres从 0.45 降到 0.35，密集瓶胚场景下可减少漏检，mAP 提升 1.8 %。
2. TensorRT 加速：Jetson Xavier 上trtexec --fp16可把延迟再砍半，毕业旅行拍 Vlog 也能实时检测。
3. 边缘设备：尝试 OpenVINO + NPU，把模型塞进 2 W 功耗的 ARM 盒子，看能否在流水线 7×24 小时扛住。

动手改一行代码，把 Flask 换成 FastAPI，再加一个 WebSocket 推流，你的“学术项目”就悄悄长成了“工业原型”。毕业答辩结束，代码仓库还能继续迭代——也许下一次面试，你就用这段经历讲清楚“端到端 AI 交付”是怎么一回事。祝你毕设高分，也祝你在真正的生产环境里继续乘风破浪。