YOLOv5目标检测实战：从环境配置、模型训练到部署导出全流程

只要你在做跟计算机视觉、图像识别相关的事情大概率绕不开一个名字YOLOv5。这是一个目标检测框架核心作用就是让程序告诉你“画面里有什么东西、分别出现在什么位置”常用于工业质检、安防监控、交通识别、医学影像辅助判断以及各类竞赛Demo。很多人第一次接触它都是被“安装”劝退的其实YOLOv5本身的安装并不难难的是你在装的过程里踩到的那一堆版本坑CUDA对不上、PyTorch装错、依赖冲突、权重下载卡死。这篇记录我按自己多年实操的路径把从环境准备、快速推理、数据集训练到模型导出的完整流程从头到尾捋一遍一方面帮你少走弯路另一方面也把那些“文档里不会写”的坑一并讲清楚。适合刚入门目标检测的开发者、需要快速复现实验的学生以及准备把模型部署到实际业务里的工程人员。1. YOLOv5是什么安装之前先想清楚这几件事1.1 YOLO系列是怎么走到今天的YOLO这个名字取自“You Only Look Once”意思是目标检测只用看一次。早期的检测算法往往要分两步走先产生候选区域再对区域做分类速度慢、流程繁琐。YOLO把检测当成一个回归问题输入一张图输出所有目标的类别和坐标真正做到端到端。第一代YOLO出来的时候思路很惊艳但精度和召回都不太行小目标尤其差。到YOLOv3的时候引入了多尺度预测和特征金字塔这些结构检测效果已经很能打很多项目开始把它当基线用。YOLOv4则是在工程调优上做了大量工作引入了数据增强、跨阶段局部连接等一系列技巧把速度和精度又推了一截。YOLOv5严格来说不是一个纯学术论文驱动的版本它更偏向工程化实现。它在YOLOv4思路的基础上把整个训练、推理、部署流程做得极其顺手源码组织清晰、配置方式简单、预训练权重丰富、导出ONNX和TensorRT也几乎一条命令搞定。这也解释了为什么那么多人选它而不是选那个“论文指标更高”的版本。你要搞懂的是YOLOv5不只是一个模型结构它是一整套目标检测工具箱里面的模型定义、训练策略、数据增强、推理脚本都是配套好的。1.2 v5和后续的新版本到底怎么选每次我写YOLOv5教程都有人问“官方后面都出YOLOv8了还学v5有必要吗”。这个问题得分场景看。YOLOv5最大的优势是稳定、资料多、坑基本都被前人踩平了社区里随便一搜就是现成方案。对于课程设计、竞赛、快速原型验证、中小型项目落地v5完全够用而且它的代码结构清晰很适合用来理解目标检测的训练全流程。后续的v8等版本在结构设计上做了不少更新训练策略也更现代但依然保留了YOLO“简单好用”的内核你如果已经吃透了v5再切到新版本几乎是无痛迁移。我给的建议很简单如果你是第一次接触目标检测或者急着把模型跑起来交差直接学YOLOv5如果你是在做长期项目、准备从零搭一套生产级检测系统可以先从v5练手再去看新版本的改进点。版本本身不是重点检测任务的完整链路才是重点。1.3 装之前需要建立的基本概念在正式安装前有几个名词你要先建立概念不至于后面看到报错就懵。模型权重weights你可以理解成是模型训练好的“经验记忆”YOLOv5提供按尺寸分档的预训练权重下载后直接拿来推理不用自己从头训练。PyTorch跑YOLOv5的底层深度学习框架负责张量计算和自动求导绝大多数安装问题都出在它和CUDA的匹配上。CUDA与cuDNNNVIDIA显卡的并行计算平台和深度神经网络加速库用来让GPU真正跑起来没有它PyTorch就只能用CPU慢慢算。数据集和标签YOLOv5训练时每张训练图片都会配一个同名的txt文件里面写了图中每个目标的位置和类别这就是YOLO格式的标签。这几个概念贯穿安装、推理、训练、导出全程。先把它们的关系搞顺再动手装效率会高得多。2. 环境准备与安装这一步能排掉80%的坑2.1 先看显卡把驱动、CUDA和PyTorch的版本关系摸清我遇到过太多人一上来就装最新版PyTorch然后跑YOLOv5报错“CUDA driver version is insufficient”其实问题就出在版本不匹配。这里有个逻辑链显卡驱动决定你能用多高版本的CUDACUDA决定PyTorch能不能调用GPU。你先在命令行执行 nvidia-smi看右上角的CUDA Version比如显示12.3这说明你的显卡驱动最高支持到CUDA 12.3你可以安装任意不高于这个版本的CUDA工具包但实际很多场景下你不一定需要单独装CUDA Toolkit因为PyTorch会自带一套它需要的CUDA运行时。我的日常做法是先确定PyTorch版本再让CUDA跟着PyTorch走。比如PyTorch官网提供了cu118、cu121等不同CUDA版本的安装命令你只需要按自己机器的驱动选一个即可。原则很简单驱动支持的版本不能低于PyTorch所对应CUDA版本。大多数近几年的显卡驱动都支持CUDA 11.8以上所以我一般推荐直接用 cu118 版本兼容性最好。如果你没有NVIDIA显卡也没关系。YOLOv5支持纯CPU推理只是训练会比较慢。像我以前在没GPU的笔记本上试过用yolov5s推理一张图片大概需要几百毫秒做验证和Debug完全能接受只是别指望它跑实时视频流。2.2 用conda创建一个干净的环境别祸害系统Python我强烈建议不要直接在系统Python里装YOLOv5依赖尤其是你机器上还跑着其他项目的时候。深度学习框架之间的版本冲突非常折磨人明明上一个项目还能跑装完新的东西再回去就报错了。用conda隔离环境是最省心的方案。安装Anaconda或Miniconda之后执行conda create -n yolov5 python3.9 -y conda activate yolov5Python版本我通常选3.9或3.10这两个版本对YOLOv5的兼容性很好Python 3.12之前有不少依赖还没完全跟上容易出幺蛾子。创建完之后后续所有安装都在这个环境里操作。出了任何问题直接删掉环境重建就行完全不影响宿主机这对反复折腾的人来说是刚需。2.3 安装PyTorchCPU版还是GPU版一次说清激活环境之后下一步是安装PyTorch。千万别直接 pip install torch 完事这样默认装的版本不一定带CUDA支持。正确做法是打开PyTorch官网的安装页面选好你的系统、包管理器、CUDA版本它会生成对应的安装命令。一个典型命令长这样pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118如果你没有GPU就选CPU版本安装命令会更简单。装完以后一定做一次验证确保PyTorch真能调用显卡python -c import torch; print(torch.__version__); print(torch.cuda.is_available())如果输出 True说明GPU环境已经通了。这一步是整个安装流程成败的关键很多人后面训练半天发现用的是CPU白白浪费时间。我在实际项目中每次装完环境都会先执行这一句把这个变成肌肉记忆。2.4 拉取YOLOv5源码并安装依赖环境好了接下来就是克隆YOLOv5官方仓库。直接在命令行执行git clone [YOLOv5官方仓库地址] cd yolov5 pip install -r requirements.txt官方仓库地址去项目主页复制即可。requirements.txt里面包含了运行YOLOv5需要的全部Python包torch、torchvision、opencv-python、matplotlib、numpy、seaborn、pandas等。这里有两个非常常见的问题要注意。第一opencv-python不要装太新的版本某些过新版本会要求更高版本的numpy而YOLOv5代码对numpy版本又比较敏感容易报一个与np.int或np.float相关的错误。我的建议是如果遇到兼容性问题就把numpy固定到1.23.x左右再重装opencv-python基本能解决。第二不要额外安装不必要的包YOLOv5装依赖已经是按需安装你多装的大概率不会用到反而增加冲突概率。装完依赖后再验证一下python -c import cv2, torch; print(cv2.__version__); print(torch.__version__)如果没有报错并且能看到版本号环境就绪可以进入下一步了。3. 五分钟跑通第一张图用预训练模型做推理3.1 先准备权重文件理解四个档位的选择YOLOv5官方在COCO数据集上预训练了四档模型yolov5s、yolov5m、yolov5l、yolov5x。数字越大模型参数越多精度更高但推理速度更慢。初学者用yolov5s就够了它体积小推理快能跑通流程是你当下的主要目标。权重文件不需要手动放置你在执行检测命令时YOLOv5会自动从官方下载对应权重。但如果网络环境不好下载容易卡住我建议你提前把权重文件下载好放到项目根目录下的 weights 文件夹里没有就自己创建这样后面再执行检测或训练就不会因为网络问题中断。权重文件不大yolov5s.pt大概十几MB其他几个档位会大一些但整体都还在可接受范围。3.2 第一条检测命令搞清楚这几个核心参数在源码目录下执行python detect.py --weights yolov5s.pt --source data/images/bus.jpg这条命令会加载YOLOv5s权重去检测官方示例图片中的公交车和行人检测结果输出到 runs/detect/exp 目录下。第一次跑出来的那张标注图片就是你入门目标检测的里程碑。你后面所有检测操作基本都是在给这条命令换参数。最常改的七个参数我给你列一下--weights指定权重文件路径换成自己训练的best.pt就能检测自定义目标。--source检测来源可以是图片、视频文件、文件夹路径填0表示调用摄像头。--conf-thres置信度阈值默认0.25只有置信度高于该值的目标才会被显示调低会漏出更多疑似目标调高则更严格。--iou-thresNMS交并比阈值默认0.45控制重叠框的合并策略通常情况下不需要动。--max-det单张图片最大检测目标数默认1000防止画面里目标过多导致输出爆炸。--device指定运行设备填0表示用第一块GPU填cpu表示纯CPU推理。--project/--name指定输出目录和子目录默认在runs/detect下面按exp、exp2这样递增。举个例子我想检测视频文件并限制只输出行人命令可以这样写python detect.py --weights yolov5s.pt --source traffic.mp4 --conf-thres 0.3 --classes 0 --project my_runs --name person_detectCOCO数据集里类别0就是person--classes参数可以直接限定输出类别这个功能在工业场景里特别实用比如只关注车、只关注缺陷品过滤掉无关目标能大幅减少误报干扰。3.3 视频、摄像头和批量图片的检测当你的 --source 换成视频文件路径时YOLOv5会逐帧推理并合成带标注的输出视频。换成0时会打开本机摄像头做实时检测。我建议第一次跑摄像头时先测一下设备编号有些笔记本摄像头编号不是0而是1直接填0打不开时改成1或2试一下就好。批量图片检测也很简单--source 直接填一个文件夹路径它会把文件夹内所有图片检测完并统一输出。这个功能在做数据集初筛、批量标注质量检查的时候特别好用。我经常把一批待质检图片丢进去跑一遍输出框一标哪些图有问题、哪里有问题一目了然。4. 训练你自己的数据集从标注到跑通全流程4.1 数据标注与YOLO文件格式新手最容易乱的地方预训练模型只能检测COCO那80类目标你想检测自己业务里的东西比如产品缺陷、工地违规行为、特殊车辆就必须用自己的数据集训练。数据标注是第一步业内最常用的工具是LabelImg类的标注GUI画框后直接导出YOLO格式。YOLO格式的标签要记住一个关键点它存的不是像素坐标而是归一化后的比例值。每张图片对应一个同名txt文件每一行代表一个目标格式是class_id x_center y_center width height所有坐标都除以了图片宽高所以取值范围是0到1。举个例子一张宽1000、高800的图片某个目标的中心点像素坐标是(500, 400)宽高是(200, 100)那txt里存的就是0 0.5 0.5 0.2 0.125标签文件必须和图片同名只是扩展名不同图片是JPG标签就是同名的txt。目录结构一般这样组织datasets/ mydata/ images/ train/ val/ labels/ train/ val/训练集和验证集大概按8:2或9:1划分同一张图片的image和label要放在对应的train或val下不能错位。这个目录结构非常关键后面很多报错都是因为标签文件和图片不在对应位置。4.2 写data yaml和模型配置参数含义一条条讲透YOLOv5训练前要准备两个配置文件一个是数据集描述文件一个是模型结构文件。数据集描述文件是一个yaml内容类似path: datasets/mydata train: images/train val: images/val nc: 2 names: [cat, dog]path是指数据集根目录train和val填的是相对path的图片文件夹路径nc是类别总数names是类别名称列表顺序必须和标注时的class_id一一对应。如果names顺序写错训练出来的模型预测结果就全乱了这是个非常隐蔽的坑。模型结构文件用的是源码里的yolov5s.yaml正常情况下你不需要改它的结构但要注意里面的nc字段。如果你用的是预训练权重做迁移学习训练时以下一条命令为准命令行里传的data文件的nc会覆盖模型yaml里的nc所以很多教程说只改data yaml就行。但如果你是直接从零训练最好把模型yaml里的nc也改成自己的类别数避免某些环节读到错误参数。4.3 启动训练学会看懂训练日志数据准备好了下一步就是训练。我先给你一个最稳妥的起步命令python train.py --data mydata.yaml --weights yolov5s.pt --batch-size 16 --epochs 100 --img 640 --device 0--weights 填yolov5s.pt表示在预训练权重基础上继续训练这叫迁移学习能大幅缩短训练时间、提高收敛精度。--batch-size根据你显存来定8GB显存用yolov5s和640分辨率16是个安全值显存不足就减到8或4。--epochs新手可以先跑50轮看效果不用一上来就追求几百轮。训练开始后你会看到类似这样的日志输出Epoch gpu_mem box obj cls labels img_size 1/50 2.31G 0.036 0.018 0.001 7 640 P R mAP50 mAP50-95 0.142 0.115 0.103 0.051这里面重点看P精确率、R召回率、mAP50IOU阈值0.5时的平均精度、mAP50-95更严格的综合指标。P高代表预测得准R高代表漏得少mAP是综合指标。训练完成后模型会保存为best.pt和last.pt两个文件best是验证集上效果最好的last是最后一轮的实际部署用best.pt。我习惯在训练时把--project指定好并在不同实验里用不同--name区分这样每次训练的日志和权重都会单独保存后期对比实验不会相互覆盖。如果你开启了可视化面板也能在浏览器里看训练曲线但实际判断收敛更多还是看日志里的P、R、mAP变化趋势。4.4 训练翻车现场这些问题我基本每轮项目都会遇到第一个问题是显存不足报错关键词是 OutOfMemoryError。解决办法优先级依次是降低batch-size、降低--img分辨率、换更小的模型档位比如从yolov5m降到yolov5s。把batch从16减到8显存占用直接减半这是最立竿见影的操作。第二个问题是标签没有加载常见报错是 No labels found 或者训练日志里labels列一直为0。这种基本都是路径或格式问题先检查标签txt是否和图片同名同目录再打开txt文件确认内容是归一化坐标出现负数或大于1的数值肯定不对。还有一种情况是标注工具导出的坐标没归一化需要自己处理一下。第三个问题是类别数不一致报错时提示 nc mismatch。这是因为data yaml里的nc和模型结构文件里的nc不一致或者names列表长度和nc对不上仔细检查这两个文件的每个字段。第四个问题是过拟合典型特征是训练集P/R都接近1但验证集mAP很低。这种情况往往是数据集太小、标注噪声大或者训练轮数过多。我一般先检查标注框有没有明显偏移再减少训练轮数也可以加一些数据增强参数缓解。5. 训练完之后模型导出与轻量部署路线图5.1 为什么要导出其他格式很多人训练完模型就停在best.pt这一步不走了。其实detect.py只能用来做验证和演示真正要在生产环境跑尤其在边缘设备上跑你得把权重导出成更适配目标平台的格式。YOLOv5支持导出ONNX、TensorRT、OpenVINO、CoreML、TorchScript等多种格式最重要的是ONNX它是一种开放的模型交换格式能被各种推理引擎加载是你连接训练环境和部署环境的桥梁。5.2 导出ONNX格式并用ONNX Runtime跑起来导出命令非常简单python export.py --weights best.pt --include onnx执行成功后目录下会多出一个best.onnx文件。你可能会看到一些兼容性警告比如某个算子版本低不用太担心大部分部署框架都能处理。接下来用ONNX Runtime做推理验证最简单的方式是这样import onnxruntime as ort import numpy as np import cv2 session ort.InferenceSession(best.onnx) input_name session.get_inputs()[0].name image cv2.imread(test.jpg) image cv2.resize(image, (640, 640)) image image[:, :, ::-1].transpose(2, 0, 1)[None].astype(np.float32) / 255.0 outputs session.run(None, {input_name: image})ONNX Runtime推理出来的结果需要自己解析这比直接调用YOLOv5源码要麻烦一点。但好处是不依赖PyTorch环境部署机器上只需要安装体积很小的onnxruntime特别适合服务端推理场景。我第一次把模型切到ONNX Runtime后推理延迟降了不少部署机器也不需要再装一整套深度学习框架。5.3 嵌入式设备部署的大方向如果你的目标是部署到Jetson这类边缘设备可以走TensorRT路线它能把模型进一步优化成引擎文件推理速度能比ONNX再快好几倍。如果是Intel CPU平台OpenVINO是推荐方向优化效果同样明显。还有一个轻量级的ncnn专门为移动端设计。这些工具的详细操作每个都能单独开一篇完整教程我的建议是先掌握导出ONNX这一环再按目标平台去学对应的部署框架。导出是共通的部署框架各有各的路数先有可交付的模型文件再研究怎么把它跑得最快。6. 安装使用高频报错排查速查表我在多个环境、多台机器上装过YOLOv5这里把新手最常遇到的报错整理成一张速查表基本覆盖了八成使用场景遇到问题先来这里对照一下。ModuleNotFoundError: No module named torch当前conda环境没装PyTorch或没有激活正确环境。执行conda activate yolov5再检查一遍安装步骤。AttributeError: Upsample object has no attribute recompute_scale_factorPyTorch版本和YOLOv5不兼容常见于PyTorch版本偏新或偏旧。解决办法是把PyTorch装回2.x早期或1.13版本。RuntimeError: CUDA out of memory显存不足。降低batch-size或imgsize或换更小的模型档位。Downloading yolov5s.pt 卡住不动网络问题导致权重下载失败。手动下载权重放到weights目录下再重跑命令。No labels found in ...标签文件缺失或路径不对。检查图片和标签文件是否同名、是否都在正确目录、txt内容是否为空。ValueError: Invalid classes ...data yaml里names列表与标注的类别索引对不上检查names顺序。ImportError: numpy.core.multiarray failed to importnumpy版本与opencv-python不兼容。卸载numpy后安装1.23.x版本重新装opencv-python。摄像头打开一片黑或报错--source 0改1或2或者检查系统摄像头权限是否开启。预测结果全是一个框、框住整张图置信度阈值太低或模型没训练好先调高conf-thres再检查训练数据和参数。训练时loss不下降学习率或数据集有问题先用coco128小数据集验证环境是否正常。这些排查经验里我想再多说一句遇到报错先读最后三行别从第一行开始看。Python报错的核心原因通常在末尾前面几百行都是调用栈。把末尾的异常类型和提示读明白再对照上面的表大部分问题五分钟内能定位。这套流程我前后在十多台不同配置的机器上跑过最大的体会是版本对齐比命令本身更重要。只要PyTorch版本、numpy版本和环境隔离做对了YOLOv5几乎可以做到克隆源码加装完依赖就能直接跑。至于训练自己的数据集我更建议你第一条训练命令先别上自己的真实数据先跑一遍官方自带的coco128小数据集把流程走通、日志看懂再换自己的数据和类别。因为路径问题、标签格式问题、参数配置问题只有在真跑起来之后才会暴露出来先用小数据集做冒烟测试代价最小。最后记住一点目标检测是实操性极强的活计看一百篇教程不如自己完整跑通一遍从安装到推理再到训练能坚持走完这一轮你基本就入门了。