YOLO毕设项目实战：从模型部署到工程化落地的完整链路
背景痛点：跑通≠落地
做毕设时，很多同学把官方仓库 clone 下来，跑通python detect.py --source 0就以为大功告成。结果一到答辩现场：
- 笔记本风扇狂转，Demo 卡成 PPT
- 换一台机器 CUDA 版本不对，直接罢工
- 老师一句“并发 10 路视频流能扛住吗？”瞬间沉默
“能跑”与“能落地”之间，差着整整一个工程化周期：数据清洗、模型微调、格式转换、推理加速、服务封装、监控运维。本文把踩过的坑写成一条可复现的流水线，让你把 YOLO 从“实验”变成“产品”，直接塞进毕设仓库或 GitHub README，毫无违和。
技术选型：YOLOv5 vs v8 vs v11
先给一张速览表，再看选择逻辑。
| 版本 | 官方维护 | 精度(mAP) | 1080Ti 速度(FPS) | 导出生态 | 备注 |
|---|---|---|---|---|---|
| v5 | 社区 | 37.4 | 105 | ONNX/TensorRT 成熟 | 代码稳定，资料多 |
| v8 | Ultralytics | 44.9 | 120 | 官方原生支持 | 新特性多，API 友好 |
| v11 | 社区尝鲜 | 46.3 | 135 | 支持但文档少 | 刚开源，坑多 |
毕设场景优先考虑“资料多+部署稳”，于是锁定YOLOv8n作为基线。后续若需更高精度，可无缝切换 v8x 或 v11，流程完全一致。
核心实现：一条命令端到端
整个链路只有 5 个环节，每个环节都给出可拷贝脚本，确保第二天就能复现。
数据预处理
把实验室拍到的 1 万张手机外观图，按 8:1:1 划分。用roboflow一键生成 YOLO 格式，再跑yolo detect train自动数据增强（HSV、mosaic、flip）。
关键：类别文件data.yaml里把背景类 id 设为 0，避免后续 ONNX 节点错位。模型微调
单卡 3060Ti 12G 足够，batch=32，img=640，epoch=100，早停 patience=20。训练完在runs/detect/train/weights/best.pt拿到 3.4 MB 的 v8n 模型，mAP@0.5=0.87，满足“轻量+够用”。导出 ONNX
yolo export model=best.pt format=onnx imgsz=640 batch=1 simplify=True生成
best.onnx，节点数 240+，方便后续 TensorRT 做融合优化。TensorRT 引擎构建
在部署机（Jetson Orin Nano）上执行：trtexec --onnx=best.onnx \ --saveEngine=best.trt \ --workspace=1024 \ --fp16 \ --verbose实测 FP16 比 FP32 提速 2.3 倍，显存占用降 40%，推理 640×640 单张 7 ms。
Flask API 封装
目录结构遵循 Clean Code：project ├─app.py // 服务入口 ├─inference.py // 推理引擎 ├─preprocess.py // 前处理 └─utils.py // 日志、校验、异常关键代码片段（已删无关 import，完整文件放 GitHub）：
app.py
from flask import Flask, request, jsonify from inference import TRTInference from utils import limit_max_content_length, validate_image app = Flask(__name__) engine = TRTInference("best.trt") @app.route("/v1/detect", methods=["POST"]) @limit_max_content_length(4 * 1024 * 1024) # 4 MB def detect(): file = request.files.get('image') if not file: return jsonify(code=400, msg="missing image"), 400 img_bytes = file.read() if not validate_image(img_bytes): return jsonify(code=400, msg="invalid image"), 400 bboxes, cls, conf = engine.predict(img_bytes) return jsonify( code=200, data={"boxes": bboxed, "classes": cls, "scores": conf} ) if __name__ == "__main__": app.run(host="0.0.0.0", port=8080, threaded=True)inference.py
import cv2 import numpy as np import tensorrt as trt import pycuda.driver as cuda class TRTInference: def __init__(self, engine_path): logger = trt.Logger(trt.Logger.WARNING) with open(engine_path, 'rb') as f, trt.Runtime(logger) as runtime: self.engine = runtime.deserialize_cuda_engine(f.read()) self.context = self.engine.create_execution_context() self.inputs, self.outputs, self.bindings = [], [], [] self.stream = cuda.Stream() for binding in self.engine: size = trt.volume(self.engine.get_binding_shape(binding)) dtype = trt.nptype(self.engine.get_binding_dtype(binding)) host_mem = cuda.pagelocked_empty(size, dtype) device_mem = cuda.mem_alloc(host_mem.nbytes) self.bindings.append(int(device_mem)) if self.engine.binding_is_input(binding): self.inputs.append({'host': host_mem, 'device': device_mem}) else: self.outputs.append({'host': host_mem, 'device': device_mem}) def predict(self, img_bytes): img = cv2.imdecode(np.frombuffer(img_bytes, np.uint8), 1) blob = preprocess_letterbox(img) # 640x640, BGR np.copyto(self.inputs[0]['host'], blob.ravel()) cuda.memcpy_htod_async(self.inputs[0]['device'], self.inputs[0]['host'], self.stream) self.context.execute_async_v2(bindings=self.bindings, stream_handle=self.stream.handle) cuda.memcpy_dtoh_async(self.outputs[0]['host'], self.outputs[0]['device'], self.stream) self.stream.synchronize() return postprocess(self.outputs[0]['host'])预处理统一做 letterbox + BGR→RGB + CHW + /255 归一化，后处理做 NMS@0.45，置信度阈值 0.25，返回绝对坐标方便前端直接画框。
性能与安全：并发 50 路也不慌
冷启动
TensorRT 引擎首次反序列化耗时 1.2 s，把best.trt提前加载到内存，Flask 启动完成即可接单，避免用户第一次请求卡死。并发模型
Gunicorn + Gevent，4 Workers×4 Threads，压测工具locust模拟 50 并发，QPS≈130，GPU 占用 55 %，显存 1.7 G，满足实验室 16 路摄像头实时流。输入校验
- 文件头校验：只接受
0xFF 0xD8/0x89 0x50两类魔数 - 分辨率限制：长边≤2048，防止 OOM
- 内容长度：4 MB 封顶，Nginx 层再加一层
client_max_body_size
- 文件头校验：只接受
异常兜底
捕获CudaError自动重启 Worker，防止 GPU Context 崩掉后整个服务 500。
生产环境避坑指南
模型版本管理
目录挂时间戳：models/20240611_1432/best.trt，通过软链models/latest指向当前版本，实现热更新零 downtime。日志监控
结构化 JSON 日志 + Loki + Grafana，面板里盯这三行：gpu_mem_percent、inference_ms、http_status=5xx。GPU 内存连续 3 分钟>90 % 就短信告警，十有八九是忘了释放 Context。显存泄漏排查
nvidia-smi看到显存只增不减，八成是pycuda的device_mem没 free。在TRTInference.__del__里加device_mem.free()，并封装成上下文管理器，保证异常退出也释放。低功耗设备掉帧
Jetson 默认动态频率，负载低时自动降频，导致首帧 40 ms，后面 7 ms。jetson_clocks锁频到最大，再关闭桌面，推理抖动<1 ms。
效果展示
下一步：多模型服务 & Docker 化
单模型只是起点。把TRTInference抽象成基类，派生YoloV8Face、YoloV8License，用 Redis 做请求路由，即可在 1 个进程里加载 3 个引擎，显存共享，CPU 隔离。再写一份Dockerfile：
FROM nvcr.io/nvidia/tensorrt:22.08-py3 COPY requirements.txt /tmp RUN pip install -r /tmp/requirements.txt COPY . /app WORKDIR /app CMD ["gunicorn", "-k", "gevent", "-w", "4", "-b", "0.0.0.0:8080", "app:app"]多阶段镜像 1.3 GB，CI 自动推送到仓库，答辩老师看到docker run -it -p 8080:8080 your_id/yolo:v8就能复现，印象分直接+20。
把这套流水线跑通，你的毕设就不再是“跑通 Demo”，而是“可部署、可扩展、可维护”的微型产品。下一步不妨动手试试 Kubernetes 弹性伸缩，或者把检测与跟踪级联，做成真正的视频结构化平台。祝你答辩顺利，代码常 Green！
