简介这份指南面向具备Python与计算机视觉基础的入门研究人员系统讲解YOLOv5环境搭建与目标检测全流程帮助读者从系统准备开始快速跑通依赖安装、仓库克隆、模型下载与实例检测的完整链路。压缩包内仅含1个docx格式教程文档大小约19KB内容覆盖操作系统与Python版本要求、CUDA/cuDNN加速环境配置、PyTorch安装、Anaconda虚拟环境创建、官方源码获取及检测命令参数详解同时列出检测结果的输出位置。目前已有238人学习该资源。教程不仅提供逐步操作命令还延伸介绍了自定义数据集训练与模型调优的进阶用法适合作为高校教学材料或工程落地参考通过对照实践读者能掌握YOLOv5的基本应用并尝试调整输入尺寸、置信度阈值等实验条件深化对目标检测原理的理解。1. YOLOv5搭建与目标检测从跑通到部署的最短路径YOLOv5搭建与目标检测是很多开发者接触计算机视觉的第一站。做工业质检、安防监控、农业计数的朋友第一反应都是先拿YOLOv5把流程跑通——数据进去、检测框出来心里才有底。虽然YOLOv8、YOLOv9已经陆续发布但YOLOv5的教程密度、硬件门槛和部署成熟度仍然是最适合快速落地的选择。我按自己从搭建、读源码到训练、部署的完整路径来写环境怎么配、代码怎么读、数据怎么标、参数怎么调、哪些坑最容易翻车一次讲透。新手能照着做完整个流程熟手也能对一遍自己的实现有没有遗漏。2. 搭建运行环境CUDA、PyTorch与依赖版本的一次性讲清先明确目标我们只解决“让YOLOv5在本地把检测跑起来”。搭建环境翻车率最高的原因往往不是YOLOv5本身而是PyTorch和CUDA、显卡驱动之间的版本对应关系。把这层关系理清楚后面90%的环境坑都能避开。2.1 硬件底线与选型顺序先查显卡驱动支持的CUDA版本先说硬件底线。YOLOv5官方仓库说CPU也能做推理但训练别指望CPU一个batch要跑几十秒几百个epoch跑下来直接劝退。我一般会建议训练至少一张NVIDIA显卡显存6GB起步GTX 1660 Super或RTX 3060这个级别刚好如果你做的是遥感大图、高分辨率小目标检测显存12GB以上更稳妥。推理阶段CPU勉强能用单张图几秒延迟视频流就别想了。预算有限的可以用云GPU或者Colab先把流程跑通。然后是软件选型的顺序问题。常见做法是三步走第一步执行nvidia-smi看右上角CUDA Version。这个数字是显卡驱动支持的CUDA上限不代表你已经装了完整CUDA环境。第二步根据它倒推PyTorch版本选一个PyTorch内置CUDA运行库版本小于等于驱动上限的组合。第三步Python版本用3.8到3.10不要赶新用3.12很多依赖还没跟上。提示不需要额外安装完整CUDA Toolkit。PyTorch在pip安装时已经内置了运行需要的CUDA库额外装一套反而可能出现路径冲突。nvidia-smi里的CUDA Version只是驱动支持能力的标识并不是环境里已装CUDA的版本。我这几组组合都用过目前仍然是稳定搭配驱动支持的CUDA上限Python推荐PyTorchpip安装参数CUDA 11.x3.8~3.10torch 1.8~1.12--index-url .../cu113CUDA 11.83.8~3.10torch 1.13~2.0--index-url .../cu118CUDA 12.x3.9~3.10torch 2.1--index-url .../cu121如果驱动版本偏老比如只支持CUDA 11.2你硬装torch 2.0的cu118版本训练启动时会直接报no kernel image available这就是驱动不认新版CUDA运行时的典型症状。解法只有两个升级驱动或者降回匹配的torch版本。驱动升级有风险老卡升级后可能带来兼容性变化生产环境的机器我一般是降torch而不是动驱动。2.2 创建虚拟环境与安装依赖先装PyTorch再装其余依赖我习惯用conda把项目环境隔离开不污染系统Python。后面做YOLOv5多个分支对比时一个环境一个版本切换成本最低。conda create -n yolov5 python3.9 -y conda activate yolov5然后克隆YOLOv5官方仓库并进入目录。git clone https://github.com/ultralytics/yolov5 cd yolov5这里有一个很多新手容易忽略的坑不要立刻执行pip install -r requirements.txt。requirements.txt里也包含了torch和torchvision如果直接装pip可能从PyPI默认源拉一个CPU版torch或者跟你已有的显卡驱动不匹配。正确顺序是先手动装好PyTorch再装其他依赖。# 第1步安装PyTorchcu118对应CUDA 11.8按2.1查到的驱动上限替换 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # 第2步安装YOLOv5其余依赖 pip install -r requirements.txt先装PyTorch之后pip检查requirements.txt时发现torch已经满足就会跳过它只补装opencv-python、numpy、matplotlib、pandas这些辅助库避免重复安装把torch覆盖回CPU版。参数说明--index-url https://download.pytorch.org/whl/cu118指定从PyTorch官方whl源的cu118分支下载。cu118对应CUDA 11.8cu113对应CUDA 11.3cpu对应无独显环境conda create -n yolov5 python3.9 -y创建名为yolov5的独立环境并指定Python版本-y表示不交互确认。装完以后不要急着往下走先验证当前环境里torch是否真能调用GPU。python -c import torch; print(torch.__version__, torch.cuda.is_available())输出类似2.0.1cu118 True才算通过。如果输出里带着cpu后缀或者False说明装成CPU版了。检查两件事安装命令中的cu后缀是否和驱动上限匹配以及pip是不是从默认源装的。重装时先pip uninstall torch torchvision再执行第1步。2.3 跑通第一张图的推理环境通了才算开始环境通没通一张图就能验证。在yolov5目录下执行python detect.py --weights yolov5s.pt --source data/images/bus.jpg --img 640第一次运行会自动下载yolov5s.pt权重大约14MB。如果你在公司网络环境下载卡住手动把权重文件通过浏览器放进yolov5目录就能跳过自动下载再重新执行命令。跑完会在runs/detect/exp目录生成一张标注好了的图片公交车上的人和bus分别被两个颜色的框圈出来。这条命令里的三个参数是理解YOLOv5的起点--weights yolov5s.pt权重文件。s是small型号速度最快精度最低往上还有m、l、x三档文件更大更准。入门先跑s别着急上x显存和推理速度都撑不住--source data/images/bus.jpg输入来源。支持单张图片、文件夹路径、视频文件路径以及摄像头ID0表示第一个摄像头--img 640推理分辨率。YOLOv5会把输入图缩放到640x640再推理。分辨率越高精度越好但延迟成倍增加。这个值后面训练要和推理保持一致不然检测框会偏移。另外提醒一点runs/detect/下面的exp、exp2、exp3是自动递增的每次运行不会覆盖上一次结果。做对比实验时非常方便想清空就手动删掉runs目录。到这一步环境搭建和基本推理已经走通。接下来要解决的才是真正的核心问题YOLOv5内部到底怎么工作。不了解这一层后面模型效果差时你连从哪里排查都不知道。3. 读懂YOLOv5的检测流程从源码结构到后处理环境跑通只是开始。真正做项目时你会发现同样的代码有的人调出来又准又快有的人调出来漏检误检一堆。差别就在于有没有理解YOLOv5内部的数据流。这里不讲空泛的网络结构图而是跟着一张图从输入走到输出把源码里对应的关键位置都点出来。3.1 目录结构与关键文件先读四个文件就够克隆下来的仓库文件很多真正要读的是少数几个。我把职责列清楚文件职责detect.py推理主流程从读图到出结果train.py训练主流程models/yolov5s.yaml网络结构定义控制深度与宽度models/yolo.py模型组装与多尺度的前向逻辑utils/general.pyNMS、坐标转换、标签工具都在这里utils/augmentations.py训练与推理时的数据增强和letterbox实现如果时间有限只看前两个就能跑起来想理解原理再把models/yolo.py和utils/augmentations.py里的letterbox读了。我的读法是按数据流动线走detect.py读入图片、调用模型、拿到输出、执行后处理。不要从头到尾把每个工具函数看一遍那些和你的业务大概率没关系。3.2 预处理letterbox为什么比直接拉伸强detect.py拿到图片后不会直接resize到640x640而是调用letterbox操作。你在utils/augmentations.py里能找到这个函数先把原图缩放保持宽高比不变然后把短边的空白区域用灰色填充拼成640x640。为什么不直接拉伸因为拉伸会改变目标的长宽比。YOLOv5的anchor是照着目标形状学出来的训练时目标都是原始比例推理时你把目标拉宽或压扁框自然对不准。而letterbox保留了目标的真实形状只是用灰边补齐了比例差异。这个细节在你之后自己写推理脚本时最容易忽略很多人图省事用OpenCV的resize一步到位结果检测框系统性偏移还以为是模型过拟合。3.3 模型前向三个尺度的输出各自负责什么预处理后的输入张量形状是(1, 3, 640, 640)。YOLOv5s的网络结构定义在models/yolov5s.yaml里主干是CSPDarknetNeck用的是PANet结构Head输出预测。和你看到的那张流传很广的网络结构图一致但结构图画得再好也不如自己打印一遍。想验证网络结构直接运行python models/yolo.py --cfg models/yolov5s.yaml终端会逐层打印每一层的类型、输出shape、参数量和stride。这里的stride就是下采样倍数8、16、32。下采样8倍的特征图分辨率最大、感受野最小负责检测小目标下采样32倍的特征图分辨率最小、感受野最大负责检测大目标。三个尺度的预测拼在一起才覆盖了不同尺寸的目标。如果你的数据里小目标特别多模型还漏检先别急着调参回到yaml里看是不是小目标的标注数量太少。如果嫌终端输出不直观把模型导出成ONNX后用Netron打开每层的输入输出形状一眼就能看明白。这个做法在做网络剪枝或者替换Backbone时特别有用。3.4 后处理模型输出到人能看到的目标框之间还有三步模型前向拿到的不是最终检测框而是一堆相对anchor的偏移量。以COCO的80类为例每个尺度的输出特征图最后一维是854个位置偏移、1个目标置信度、80个类别概率。要变成你肉眼看到的框后处理还要做三件事。第一步anchor解码把偏移量结合grid坐标和预设anchor框还原成原图上的真实框坐标。第二步置信度过滤每个预测框有一个综合置信度低于conf_thres的直接扔掉默认0.25。第三步NMS剩下的框里可能同一个目标被多个anchor框捕获NMS按IoU阈值合并重复框默认iou_thres0.45。看一下detect.py里实际用到的那组参数这是影响结果最直接的因素# 后处理关键参数在detect.py命令行或调用NMS时设置 conf_thres 0.25 # 置信度低于此值的预测直接丢弃调高减少误检、调低减少漏检 iou_thres 0.45 # NMS中两个框IoU高于此值视为同一个目标调高区分紧邻目标、调低合并重叠框这两个参数是实际部署时最该调的东西而不是去改模型结构。推理结果不满意时先按网格试几组conf_thres和iou_thres再考虑重新训练。我见过不少项目一上来就重新训练几百个epoch最后发现只是NMS阈值设得不合理白白浪费大量算力。4. 训练自己的数据集从标注到拿到专属权重推理流程理解了重头戏才开始训练自己的数据集。前面detect.py跑的是COCO预训练权重只能检测80类常见目标。要检测你自己场景里的目标比如工业零件、特定鸟类或车辆类型就得用自己的数据微调训练。下面按数据标注、配置文件、启动训练、验证评估四步走完。4.1 数据采集与标注每张图对应一个同名txt数据量没有绝对标准一个可操作的经验线是每类至少收集500个标注实例并保证场景多样性。以鸟类检测为例不能全是蓝天背景飞行的鸟得有树枝遮挡、不同光照、不同姿态的鸟否则模型学到的其实是背景模式换一个环境就翻车。类别开始不要贪多先做2到3类把流程跑通后面再加类别。标注工具我常用labelImg它支持YOLO格式导出操作简单安装也方便pip install labelimg labelimg打开后把界面上的格式切换成YOLO一张图一张图地框目标。标注完每张图片都会生成一个同名txt文件比如0001.jpg对应0001.txt。txt里每一行是一条目标记录class_id x_center y_center width height四个坐标值是归一化的范围在0到1之间。x_center和y_center是目标中心点坐标分别除以图片宽高width和height是目标框宽高分别除以图片宽高。labelImg导出时已经帮你归一化但如果你自己用脚本整理数据集这里是重灾区——有人直接把像素值填进去了训练时loss剧烈上涨甚至出现NaN。标注完成后的目录结构应该是这样dataset/ ├── images/ │ ├── train/ │ │ ├── 0001.jpg │ │ └── ... │ └── val/ │ ├── 0002.jpg │ └── ... └── labels/ ├── train/ │ ├── 0001.txt │ └── ... └── val/ ├── 0002.txt └── ...train和val的比例我按8:2处理。val集至少要保证每一类目标都有几十个框不然评估指标的波动很大一次训练和另一次训练的mAP差好几个点你会分不清是模型原因还是验证集太小。4.2 编写数据配置文件yaml里写什么、顺序为什么不能错YOLOv5不直接扫描文件夹而是靠一个yaml文件告诉它去哪找数据、有几类、类名是什么。复制data/coco128.yaml改成自己的即可。# data/my_dataset.yaml path: ../dataset # 数据集根目录相对yolov5仓库的位置 train: images/train # 训练图片相对路径 val: images/val # 验证图片相对路径 # 类别信息顺序必须和标注txt里的class_id一致 nc: 2 names: [bird, cat]最容易翻车的点在names的顺序。标注时0代表bird、1代表catyaml里就必须保持这个顺序。一旦顺序反了训练不会报错但推理时bird全显示成cat整个系统看起来正常但结果全错而且很难发现。排查方法是在训练前跑一次val.py看可视化的标签名确认每个类别框上的文字和图片内容一致。4.3 启动训练train.py参数逐个说明数据集和yaml都备好了执行训练命令python train.py \ --data data/my_dataset.yaml \ --weights yolov5s.pt \ --img 640 \ --batch-size 16 \ --epochs 100 \ --name my_model为什么--weights要填yolov5s.pt而不是从零开始因为COCO预训练权重已经学到了通用的图像特征迁移到自己的小而专的数据集上收敛快得多精度也更稳。只有你的数据量特别大且和COCO场景差异极大时才考虑用--weights 从头训练。对大多数实际项目微调就是默认选择。逐个看参数--data数据集yaml的路径--weights初始权重。可以是yolov5s.pt这种预训练权重也可以填自己之前训练好的best.pt继续喂--img 640训练分辨率。和推理保持同一值。想要更高精度可以调到1280但显存占用和训练时间成倍增长入门先640--batch-size 16每批送入16张图。显存不足就降到8或4不要硬跑具体看第5章的显存问题--epochs 100训练轮数。小数据集通常50轮左右就收敛了先跑100轮看整体趋势更稳--name my_model本次训练的输出目录名同时跑多个对比实验时不会互相覆盖。训练过程会在终端打印每轮的box_loss、obj_loss、cls_loss同时生成runs/train/my_model目录。这里面最该看的文件是results.png上半部分是三条loss曲线下半部分是precision、recall、mAP50、mAP50-95四条验证曲线。曲线比终端日志直观loss下降再看mAP是否跟着涨。4.4 验证与可视化不要只看loss数字训练结束用验证集评估python val.py --data data/my_dataset.yaml --weights runs/train/my_model/best.ptval.py会输出precision、recall、mAP50、mAP50-95四组指标并在runs/val/exp下生成混淆矩阵和带检测框的验证图片。mAP50是IoU阈值0.5下的平均精度超过0.7说明模型已经能用了mAP50-95是0.5到0.95区间多个阈值的平均更严格小数点后每涨一位都需要数据或调参的实质性提升。看到指标之后一定打开预测图片肉眼检查。重点看两类错误该框没框出来的漏检和误把背景框出来的误检。漏检多先补数据和调阈值误检多先怀疑标注数据里漏标太多。模型把漏标的区域当成负样本学习了自然会把相似背景错判成目标。这一点靠调参解决不了只能回头清理数据。5. 搭建与训练的避坑指南五个高频踩坑记录把我在多个YOLOv5项目里踩过、也见过别人反复踩的坑集中列出来每条按现象、原因、解决三部分写查起来比较快。5.1 loss出现NaN或剧烈震荡现象训练前几轮loss正常某几轮突然变成NaN之后再也降不下来或者是loss卡在某个点剧烈震荡验证集指标跟着上下乱跳。原因最常是数据问题。txt标注里出现了超出0~1范围的坐标值比如width填了像素值而不是归一化值模型的损失计算里出现了无穷大特征。其次是学习率设置过高YOLOv5默认学习率对小数据集已经很激进再手动调高更容易发散。解决先扫描全体txt检查每行5个值是否合法。class_id必须是整数四个坐标必须在0到1之间。用一个小脚本就能查python -c import glob for txt in glob.glob(dataset/labels/**/*.txt, recursiveTrue): for line in open(txt): vals line.split() if len(vals) ! 5: print(txt, 字段数不对:, vals) elif not vals[0].isdigit(): print(txt, class_id非法:, vals) elif not all(0 float(v) 1 for v in vals[1:]): print(txt, 坐标越界:, vals) 数据没问题就把学习率调回默认或者用命令行--lr 0.001降一个数量级。记住先查数据再动参数这两步顺序搞反会浪费大量时间。5.2 CUDA out of memory显存溢出现象train.py刚启动没几步就报CUDA out of memory整张卡被杀严重时连桌面都黑屏闪一下。原因最常见是batch-size或分辨率超出了显卡物理显存。模型级别也有影响yolov5l或x级参数比s级多几倍显存需求跟着翻倍。另一个高频原因是后台有上次任务的残留进程占着显存尤其是Notebook里跑崩过的Kernel还活着。解决先执行nvidia-smi看显存和进程把残留的Python进程清掉。然后batch-size直接减半从16降到8再不行降到4。模型级别从l、x退到s。我的血泪经验是数据量不够大的时候s级和l级的精度差距很小但显存和训练时间差好几倍。不要为了显得专业硬上大模型先跑通s级精度确实不足再逐级升级。5.3 检测时什么都框不出来或框了一堆现象训练完毕跑detect.py有时候一个框都没有有时候每张图框出几十个完全不相关的东西。原因多数不是模型问题而是后处理阈值不对。conf_thres调到0.9时只有极度自信的预测才能通过自然什么都没剩下调到0.05时背景噪声也全成了目标。还有一个隐蔽原因推理时--img和训练时不一致。训练640推理1280模型看到的尺度全变了漏检误检一起来。解决先把--conf-thres降到0.1跑一遍--iou-thres保持0.5。如果0.1下能框出合理目标说明模型没问题是阈值太严然后从0.1往上升找到平衡点一般0.3到0.4比较合理。同时保证推理--img和训练时一致这是首次部署最容易翻车的点。5.4 训练100轮后mAP仍然很低现象results.png里loss已经收敛平滑但mAP50一直卡在0.3以下怎么跑都上不去。原因数据量不足或类别不平衡。某一类只有20个标注实例另一类有2000个模型自然倾向学多数据那类。另外一个更隐蔽的原因是标注漏标太多大量目标被当成背景训练数据本身的监督信号就是脏的模型在错误的标签上练出了错误的能力。解决先看混淆矩阵确定最差的那一类优先给它补数据每类至少500个实例。数据短期内补不了可以对少类别的图片做重复采样让它每个epoch出现次数更多。补完数据还不行就需要抽查标注质量拿几十张图重新标注一遍对比确认之前是否漏标了目标。5.5 Windows下路径与中文编码报错现象Windows上运行train.py或detect.py报文件找不到、路径分隔符错误或图片加载是空的但不报错。原因YOLOv5的工具函数对Windows路径和中文路径的支持不算完善。最常见的坑是数据集路径或图片名带中文OpenCV的imread遇到中文路径直接失败而且这个失败不报异常只返回一个空对象图片就变成None程序可能到很后面才出错。解决项目路径、数据集路径、图片文件名全部用英文或数字不要中文和空格这是成本最低的解法。yaml配置文件里的path一律写相对路径从yolov5目录出发不要写带盘符的绝对路径。如果数据集已经存在且带中文名宁可花半小时批量重命名复制一份也不要在代码里做编码转换OpenCV这层很难绕过去。五条避坑里5.1和5.3是新手最容易遇到又最难以自己排查的。遇到问题先从前端数据层排查再动训练参数最后才考虑改网络结构。YOLOv5的默认结构非常成熟绝大多数效果不好是数据或配置问题而不是结构问题。6. 部署与提速从best.pt到可上线的最小动作训练完拿到best.pt还有最后一步要走部署。部署不是把detect.py再跑一遍而是把模型转成目标平台能直接用的格式并且确认转换后精度不掉。这里给两个最常用的动作导出ONNX以及用save-txt批量验证预测结果。6.1 导出ONNX跨平台推理的第一步官方export.py一行命令就能导出ONNXpython export.py --weights runs/train/my_model/best.pt --include onnx导出后在runs/train/my_model/下生成best.onnx。ONNX的好处是不再依赖PyTorch环境可以交给ONNX Runtime跑CPU推理也可以再转TensorRT、OpenVINO这些平台加速。转换完成必须做精度对比拿同一张图分别用best.pt和best.onnx跑对比输出框坐标和置信度。常见的坑是某些算子优化后框轻微偏移出现这种情况就换opset版本再导一次一般能解决。6.2 批量预测验证save-txt输出结果部署上线前我习惯先用一批真实测试图把预测结果全部导出来python detect.py --weights runs/train/my_model/best.pt --source test_images/ --conf-thres 0.3 --save-txt --save-conf--save-txt会把每张图的框坐标存成txt--save-conf把置信度一并写入。这在批量验证预测质量时非常实用你可以直接写脚本统计test_images目录下所有图的检出数量和类别分布快速发现模型在哪类图片上大面积漏检。很多生产项目接入时也是直接读这个txt文件而不是解析图片上的框。我在每个项目收尾时都会保持一个习惯把conf_thres、iou_thres和img这三个值记在项目笔记里。因为下次换场景、换数据时这三项永远是需要重新调的变量模型本身反而不是最关键的。希望这一套从搭建到部署的流程能帮到你少走我翻过的那些车。本文还有配套的精品资源点击获取