YOLO毕设项目实战：从模型部署到工程化落地的完整链路-平芜编程栈

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！