干了几年图像相关的东西经常有朋友拿着YOLOv5的代码问我“这玩意儿到底怎么跑起来为什么我照着网上的教程走了一遍不是报错就是结果全绿框框”我特别理解这种状态。YOLOv5作为目前目标检测领域最常用的开源框架之一功能确实强大但正因为强大很多人拿到手就乱试——今天换个参数、明天改个网络层结果越搞越玄最后“从入门到入狱”。这篇笔记是我自己从零跑通YOLOv5全流程的经验汇总覆盖基本功能使用流程、训练自己的数据集以及我最想强调的部分每个关键参数背后的逻辑和坑。适合刚接触目标检测、想用YOLOv5解决实际问题的同学也能给已经跑通代码、但卡在训练细节上的朋友一点参考。1. 环境搭建先把“坑”填平再上车1.1 为什么建议用Anaconda虚拟环境我见过太多人直接往系统Python里装torch、装opencv没过多久就发现某个库把另一个库的版本顶掉了。最典型的冲突就是numpy版本YOLOv5要求numpy小于某个版本而你另一个项目需要新numpy两边打架最后谁也跑不起来。所以我强烈建议第一步先用Anaconda创建独立虚拟环境。这相当于给项目单独开一间“房间”互不干扰。手动创建一个新环境其实很简单conda create -n yolov5 python3.8 -y conda activate yolov5为什么选Python 3.8而不是最新的3.11因为PyTorch和很多第三方库的预编译包对3.8的兼容性最稳定。虽然现在新版本PyTorch已经支持更高Python但在YOLOv5项目里3.8是经过大量人验证过不会出幺蛾子的版本。如果你用的是PyTorch 2.xPython 3.9或3.10也可以但别一上来就追最新。创建好环境后记得在终端确认python -V确保你已经在虚拟环境里。这一步看似简单但很多人后面报错的根本原因就是环境串了明明在A环境装的包却在B环境里运行代码。1.2 PyTorch和CUDA的版本关系怎么定PyTorch的安装命令会直接影响后面能不能用GPU训练。这里有个常见误区以为装了NVIDIA驱动就等于能用GPU。驱动只是底层的“许可”实际干活靠的是PyTorch调用的CUDA版本。先确认你的显卡驱动支持什么CUDA版本直接在终端执行nvidia-smi看右上角“CUDA Version”比如显示12.1说明驱动最高支持CUDA 12.1。然后去PyTorch官网选对应版本安装。判断是否装上GPU版可以用一行代码验证import torch print(torch.cuda.is_available())如果返回True说明GPU环境正常如果返回False大概率是安装的PyTorch是CPU版或者在CPU环境下运行。我有个朋友在这步卡了一个晚上最后发现他用pip装torch时系统默认选了CPU版本因为他安装的时候没指定CUDA版本号。显卡显存也是重要参数。如果显卡只有6G显存比如GTX 1660训练时batch size建议从8起步图片尺寸用640别一上来就想着用1080P大图训练显存一不够程序直接报CUDA out of memory。1.3 装依赖时最容易翻车的几个点YOLOv5项目目录下有个requirements.txt装依赖的常规操作是pip install -r requirements.txt但直接在裸环境里跑这个经常遇到两个问题一是下载超时二是部分包需要特定版本。先建议换国内镜像源能省下大量时间pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple你可能会问为什么用国内镜像不违规不安全这是正规的Python包镜像服务也是常用的国内加速方式——它和官网源内容一致只是网络距离近、速度快。装依赖时最常遇到的是ipython和pyqt5这类包的安装时间很长尤其是pyqt5动辄几百MB。如果只是训练和推理不需要跑标注工具其实pyqt5这类GUI依赖可以暂时不装。我一般建议按需安装不要一股脑全装完。另一个常见报错是安装某些包时提示需要编译环境这种基本都是Python版本太新导致的换回3.8就能解决。2. 基本功能使用流程拿到权重先跑通一次2.1 下载代码和权重文件YOLOv5的完整代码都在GitHub仓库里进入官方仓库后点击“Code”按钮下载zip包或者用git命令git clone https://github.com/ultralytics/yolov5.git cd yolov5通过这种方式拿到的代码是官方源仓库直接解压或克隆都能用。代码目录里比较关键的有detect.py推理、train.py训练、val.py验证、data/数据集配置、models/模型结构、runs/输出结果。权重文件的获取方式要和代码版本对应。你可以在仓库的README页面找到对应版本的权重下载链接通常提供yolov5s.pt、yolov5m.pt、yolov5l.pt、yolov5x.pt这几档。其中yolov5s最轻量、速度最快适合先跑通流程yolov5x精度高但显存占用大。如果你只是测试流程是否通畅直接下载yolov5s.pt即可。我遇到过一些朋友从网上随便下载了一个权重文件结果代码是v6.0版本、权重是v5.0的直接报错。所以这里多提醒一句权重版本和代码版本的匹配很重要。拿到代码后可以先查看版本信息再找对应权重官方仓库的Release页面会把每个版本的权重列清楚。2.2 detect.py 参数逐个说清楚跑通推理是检验环境是否装好的最快方式。使用默认的测试图片python detect.py --weights yolov5s.pt --source data/images/bus.jpg这条命令的含义是用yolov5s.pt这个权重文件去检测bus.jpg图片中的目标。运行完会在runs/detect/exp目录下生成带检测框的结果图。如果能看到人、巴士等目标被框出来说明环境已经跑通了。detect.py里最常用的参数我整理过一张表每次调试前都逐一确认参数作用常用示例--weights指定权重文件--weights yolov5s.pt--source指定检测来源支持图片、视频、文件夹、摄像头--source data/images/--conf-thres置信度阈值低于该值的目标被过滤默认0.25--conf-thres 0.4--iou-thres交并比阈值用于去重重叠框默认0.45--iou-thres 0.5--device指定运行设备cpu或显卡编号--device 0--classes只检测指定类别--classes 0 2 5--save-txt保存检测框坐标到txt文件--save-txt--project修改结果保存路径--project my_runs--name修改当前实验名称--name test_01其中置信度阈值是最常调的参数。如果你发现漏检严重可以把conf-thres往下调调到0.1试试但代价是会出现很多误报框。iou-thres则是控制两个重叠框是否合并的指标如果同一目标出现多个框调大iou-thres可以压掉重复框。2.3 图片、视频、摄像头三种测法图片检测直接给图片路径即可也可以指定一个文件夹让它批量检测。视频检测直接把source指定成视频文件路径它会逐帧推理并输出带框的视频。摄像头检测更简单source填0表示调用本机默认摄像头python detect.py --weights yolov5s.pt --source 0三种输入方式背后其实走的是同一条推理链路只是数据源不同。我第一次拿摄像头测的时候发现画面掉帧明显这是因为模型推理速度没跟上视频帧率。解决方案有两个方向换更小的权重yolov5s换成yolov5n或者跳过某些帧再检测比如每隔一帧检测一次。这里插一个非常有用的实测经验当你只想检测特定物体时比如在室内只关心人不关心杯子、椅子加上--classes 0能显著减少误检。因为默认权重训练于COCO数据集包含80类目标如果不限制类别模型会努力把每一个物体都挑出来反而容易出现低置信度的误报框干扰最终结果。3. 训练自己的数据集从标注到出权重全流程3.1 采集和整理图片数量与类别的平衡跑通默认权重只是“会走路”训练自己的数据集才是真正“跑起来”。训练前的图片采集决定了模型性能的天花板。图片数量没有绝对标准但有个经验值每个类别至少200到500张图片。如果做工业级应用每类1000张以上更稳妥。图片尺寸不需要统一手动裁剪YOLOv5会在训练时自动缩放。但图片质量一定要把关模糊的、曝光过度的、目标占比过小的图片能删就删。我做过一个水果识别项目最初训练集里有大量隔着塑料袋拍的模糊橘子照片模型学到的特征全是塑料袋纹理换到真实场景直接失效。这类数据放在训练集里就是噪音不如没有。图片的来源也值得警惕。网络爬图虽然方便但图片尺寸、清晰度、目标的姿态分布可能和你的实际场景差异很大。最理想的做法是从实际部署场景中采集不同时间段、不同光照、不同角度的图片。这样训练出来的模型才接地气。3.2 使用LabelImg做YOLO格式标注目标检测的标注方式有很多流派VOC格式是xml文件YOLO格式是txt文本文件COCO是json文件。YOLOv5训练时读取的是txt标注文件所以我们要把标注结果保存成YOLO格式。标注工具我用得最顺手的是LabelImg用pip安装pip install labelimg然后在虚拟环境中启动labelimg打开图片文件夹选择PascalVOC格式默认还是YOLO格式。我的建议是直接选YOLO格式保存因为YOLOv5只认这种。不过要注意LabelImg的YOLO格式保存界面和PascalVOC的操作略有不同需要先点击打开目录、再点击打开标注列表图源要选中“YOLO”。每画一个框标注一个类别然后点击保存会在图片同目录下生成同名txt文件。YOLO格式的txt内容长这样每一行对应一个目标0 0.53125 0.46875 0.2375 0.3125这五个数字的含义分别是类别id从0开始、归一化后的中心点x坐标、中心点y坐标、归一化后的框宽、框高。你需要知道这一行规则后面排查标签错误时会很有用。标注是纯人工活也是最容易出错的环节。我踩过的坑是有些图片漏标了目标导致训练时模型把“该框的地方”学成了背景。所以一个简单的自查方法标注完一批图后用LabelImg的“Next/Prev”把图片重新过一遍确认每个目标都被框到了。3.3 写data.yaml和调模型参数标注完成后的目录结构建议这样组织YOLOv5官方也推荐这个结构datasets/ └── mydata/ ├── images/ │ ├── train/ # 训练图片 │ └── val/ # 验证图片 ├── labels/ │ ├── train/ # 训练标注txt │ └── val/ # 验证标注txt └── data.yaml # 数据配置文件train和val图片数量比例建议8:2或9:1不要把所有图片都拿去做训练。验证集的作用是检查模型有没有过拟合、泛化能力有没有达到预期。没有验证集的训练就是盲人摸象。data.yaml是训练时的关键配置内容如下path: ../datasets/mydata # 数据集根目录 train: images/train # 训练图片目录 val: images/val # 验证图片目录 nc: 2 # 类别数 names: [cat, dog] # 类别名称顺序和标注id对应path字段尤其重要。它建议使用相对于项目所在目录的路径或者绝对路径。很多新手在这里填错导致训练时报错“train dataset not found”。如果报这个错优先检查path和train这两个字段是否正确拼接成了实际存在目录。3.4 训练命令与结果文件解释确认数据和配置文件无误后就可以开始训练了python train.py --data data.yaml --weights yolov5s.pt --epochs 100 --batch-size 16 --img 640 --device 0这条命令的含义是读取data.yaml配置加载yolov5s预训练权重作为初始权重训练100个epoch每个批次16张图片输入尺寸640x640。预训练权重本身在COCO数据集上训练过用它作为起点相当于让模型在“会看”的基础上再学你的数据收敛速度快得多。训练过程中终端会不断刷新loss和mAP指标。训练结束后在runs/train/exp目录下会有几个关键文件weights/best.pt验证集效果最好的权重和weights/last.pt最后一个epoch的权重。实际部署时用best.pt就对了。best.pt不是靠训练loss选出来的而是在验证集上mAP最高的权重文件。这就解释了为什么验证集这么重要——它是挑选“最优模型”的依据。如果不划分验证集你就只能猜测哪个epoch效果最好。4. 训练过程中的玄学与科学超参数怎么调4.1 学习率、batch size、imgsz怎么搭配YOLOv5的超参数定义在data/hyps/hyp.scratch.yaml里包含了学习率、动量、权重衰减、数据增强等设置。默认参数是官方在COCO数据集上调出来的经验值多数场景可以直接用不需要大改。但如果训练效果不理想有几个参数值得关注。初始学习率lr0默认0.01一般不需要动。如果你发现训练loss剧烈震荡可以把lr0降到0.001代价是收敛变慢。数据增强参数里面hsv_h、hsv_s、hsv_v控制颜色扰动fliplr控制水平翻转概率。如果任务对颜色敏感比如交通信号灯识别建议把颜色扰动调低否则模型容易学到错误的颜色关联。batch size和imgsz直接决定显存占用。显存不足时优先降低batch size而不是降低imgsz。因为imgsz影响模型感受野和精度而batch size主要影响训练稳定性和速度。模型输入尺寸越小小目标越难检测这个影响往往比batch size更明显。4.2 训练loss下不去的排查思路训练到一半loss不降或者val精度一直上不去这是最让人崩溃的。我按照排查频率给一个顺序第一步看训练集loss和验证集loss的差值。如果训练loss很低、验证loss很高说明过拟合解决办法是增加数据量、加大增强程度或者提前停止。如果两个loss都很高说明模型还没学够增加epochs试试。第二步检查标签是否正确。数据量不大时可以单独抽一张标注过的图片出来写个脚本把标注框画回去直观看看有没有框错位置、类别标错。第三步检查类别是否均衡。如果你做的是5类目标其中4类各有1000张第5类只有50张模型大概率把第5类学成背景。处理办法是收集更多少数类别的图片或者对少数类别做离线增强旋转、裁剪、调亮度。4.3 什么是好的mAP别被论文指标带偏训练结束时终端会打印mAP50和mAP50-95。mAP50指的是IoU阈值为0.5时的平均精度均值mAP50-95则是在多个IoU阈值下的平均值要求更严格。很多人以为mAP必须到90%以上才算成功其实要看任务复杂度。一个简单场景固定位置、固定光照、少量类别mAP95以上很正常如果是复杂场景多尺度、遮挡、密集目标mAP50到80%就已经可以上线了。我自己做车牌识别时mAP50做到92%mAP50-95只有61%实际运行时依然能满足业务需求。判断模型是否“够用”的最直接方式不是盯着mAP数字而是把best.pt跑一遍detect用真实图片看看检测框的位置准不准、置信度稳不稳定。指标的最终目的还是服务实际效果。5. 常见问题速查与防坑清单5.1 环境类问题报错信息原因解决方案torch.cuda.is_available() 返回False安装的是CPU版PyTorch重新安装对应CUDA版本的PyTorchModuleNotFoundError: No module named torch当前环境不是之前装包的环境conda activate到正确的虚拟环境CUDA out of memory显存不足降低batch size或imgszPython DLL load failedPython版本过低或过高换Python 3.8/3.9环境问题最忌反复重装。我的习惯是把能用的环境导出一份配置清单只记录关键包版本比如PyTorch、numpy、opencv其余依赖不记录。这样环境崩了以后重建成本很低也方便在其他机器上复现。5.2 数据标注类问题报错信息原因解决方案AssertionError: Label class X exceeds nc标注中出现了类别id大于nc的值检查标注txt和data.yaml是否一致No labels found in train dataset标签目录为空或路径不对确认labels/train下是否有txt文件图片路径里有中文导致读取失败中文路径编码问题整个项目目录、数据集目录统一改成英文路径标签文件比图片文件多有些图片没标注就生成了空txt删除对应的空txt或为漏标图片补标注5.3 显存与训练中断训练到一半程序崩了这是最不愿意遇到的情况。除了显存不足还有可能是显卡温度过高导致驱动重启。如果训练长时间中断建议开启resume功能继续训练python train.py --resume runs/train/exp/weights/last.pt它会从上次中断的权重继续训练而不是从头再来。这个功能救了我很多次尤其是长时间训练时电源不稳或者系统自动更新导致重启。5.4 检测结果不理想时检查什么如果你训练完的模型在测试时漏检、误检严重不要急着改超参数按照这个优先级排查先看训练集和测试集的分布是否一致。模型只认识它见过的东西如果训练图片全是室内灯光、测试全在户外强光下性能差是必然的。数据分布不一致后面的所有调参都是白费力气。再看是否用了正确的best.pt。我见过有人用last.pt做推理结果效果不对因为last.pt保存的是最后一个epoch的权重不一定是最优状态。训练时如果不小心把结果跑到了runs/train/exp2甚至exp3推理时又用了runs/train/exp/weights/best.pt新老权重混在一起看起来像是在“微调参数”实际问题是权重文件选错了。最后可以试试调低conf-thres。很多时候不是模型没检测到目标而是目标的置信度低于默认的0.25被过滤掉了。用0.1的置信度阈值跑一遍观察检测框是否出现。如果低阈值下能检测到但框不准确说明模型还需更多数据训练如果低阈值下依然检测不到那问题出在模型本身或数据分布。一些关于“不要乱用”的碎碎念我自己在YOLOv5上栽过的跟头大部分不是代码写错而是“想得太美”——总想用一个参数解决所有问题。实际上没有任何一个目标检测模型是万能的。YOLOv5适合大部分中高速检测场景但如果是极端小目标、极度重叠目标或者需要像素级分割的任务它并不是最优解。选型比调参更值得花时间。还有一个很容易被忽略的地方数据集的版权和合规。网上爬图做数据集虽然方便但涉及人物肖像、商业产品logo都存在风险。我后来做项目都优先用自己的设备采集图片或者使用明确授权的公开数据集。这也是“功能强大不要乱用”的另一层含义——技术能力再强也要注意使用边界。最后分享一个我自己始终保留的习惯每次训练前把data.yaml、超参数、训练命令、数据集版本完整记录在实验笔记里。两个月后再回来看模型你还是能清楚知道当初是怎么训练的。这种体系化的习惯比任何调参技巧都更能帮你少走弯路。这篇笔记是基于我个人实践整理的YOLOv5从使用到训练的完整流程里面的参数和命令都是经过验证的。接下来我打算继续更新这一系列比如如何优化模型速度、如何做模型迁移到嵌入式设备、如何处理训练数据不均衡的问题。如果你正在跑YOLOv5的过程里遇到什么奇怪的报错不妨按这个思路逐项排查很多问题在排查的过程中会自己现出原形。