1. 项目概述为什么YOLOv5依然是目标检测的“硬通货”如果你正在计算机视觉领域摸索或者想快速上手一个能跑起来、效果还不错的检测模型YOLOv5大概率是你绕不开的一个名字。尽管学术界新模型层出不穷但在工业界、学生项目乃至个人开发者中YOLOv5凭借其极致的工程友好性、清晰的文档和活跃的社区依然是入门和快速部署的“首选”。很多人卡在第一步安装和配置。网上的教程要么过于零散要么环境依赖写得不清不楚导致跟着做一遍各种报错最后从入门到放弃。这篇文章我就以一个踩过无数坑的过来人身份带你从头到尾、手把手地走通YOLOv5的安装、配置到基本使用的全流程。我们不只讲“怎么装”更会深入讲清楚“为什么要这么装”以及那些官方文档里不会写的、只有实际跑过项目才知道的“坑点”和“骚操作”。无论你是用Windows、macOS还是Linux无论你的显卡是RTX 4090还是GTX 1060甚至是只用CPU这里都有对应的解决方案。我们的目标很简单让你在30分钟内拥有一个可以检测图片、视频甚至调用摄像头的YOLOv5环境。2. 环境准备构建一个稳定、可复现的Python工作区在直接pip install之前花10分钟做好环境规划能为你后续节省数小时的排错时间。YOLOv5的核心是PyTorch而PyTorch对CUDA显卡计算平台和cuDNN深度神经网络加速库的版本有严格匹配要求。乱装一气最常见的就是遇到“Torch not compiled with CUDA enabled”这种令人崩溃的错误。2.1 核心依赖解析PyTorch、CUDA与cuDNN的“铁三角”首先你需要理解这三者的关系。PyTorch是深度学习框架是我们要用的“大脑”。CUDA是NVIDIA推出的通用并行计算架构让PyTorch可以利用GPU进行高速计算。cuDNN则是NVIDIA针对深度神经网络操作的加速库是CUDA的“强化补丁”。它们的版本必须兼容。例如PyTorch 1.12.1可能只支持CUDA 11.3或11.6如果你系统里装的是CUDA 12.0那就会出问题。因此正确的安装顺序是先确定你的显卡驱动能支持的最高CUDA版本然后去PyTorch官网找到对应此CUDA版本的PyTorch安装命令最后用这个命令安装PyTorch。cuDNN通常会在安装PyTorch时作为依赖自动处理但了解其存在很重要。注意如果你没有NVIDIA显卡或者暂时不想用GPU完全可以安装CPU版本的PyTorchYOLOv5同样可以运行只是速度会慢很多。这对于验证流程和轻量级学习是完全可行的。2.2 实操一步步搭建专属Python环境我强烈建议使用Conda或**Python虚拟环境venv**来管理你的项目环境。这能保证每个项目的依赖库互不干扰就像给每个项目一个独立的“房间”避免因为库版本冲突导致的各种诡异问题。步骤一检查显卡与驱动打开命令行Windows的CMD/PowerShellmacOS/Linux的Terminal输入nvidia-smi如果你看到显卡信息和驱动版本说明驱动已安装。输出顶部会显示你当前驱动支持的最高CUDA版本例如“CUDA Version: 12.2”。记下这个版本号。如果命令未找到你需要先去NVIDIA官网下载并安装显卡驱动。对于没有NVIDIA显卡的机器这一步可以跳过。步骤二创建并激活虚拟环境这里以Conda为例如果你没有安装Conda推荐安装Miniconda它更轻量。# 创建一个名为yolov5的Python3.9环境 conda create -n yolov5 python3.9 # 激活环境 conda activate yolov5使用Python 3.8或3.9是最稳妥的选择对各类库的兼容性最好。Python 3.10及以上版本可能会遇到一些较老库的编译问题。步骤三安装匹配的PyTorch前往 PyTorch官网 利用它的安装命令生成器。PyTorch Build: 选择稳定版Stable。Your OS: 选择你的操作系统。Package: 推荐使用pip除非你有特殊需求用Conda。Language: Python。Compute Platform: 这里就是关键根据你nvidia-smi看到的CUDA版本选择。例如看到“CUDA 12.2”就选择CUDA 12.2。如果你的驱动支持CUDA 11.8就选CUDA 11.8。如果没有GPU或想装CPU版这里就选择CPU。网站会生成一行命令比如对于CUDA 12.1的可能是pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121复制这行命令在你激活的yolov5环境中执行。步骤四验证PyTorch与GPU安装完成后进入Python交互环境验证import torch print(torch.__version__) # 打印PyTorch版本 print(torch.cuda.is_available()) # 打印True说明GPU可用 print(torch.cuda.get_device_name(0)) # 打印你的GPU型号如果torch.cuda.is_available()返回False但你有GPU说明PyTorch的CUDA版本和系统CUDA驱动版本不匹配需要回到步骤三重新选择。3. YOLOv5源码获取与依赖安装环境准备好了现在可以把YOLOv5的“本体”请下来了。3.1 克隆仓库与目录结构初窥YOLOv5的代码托管在GitHub上。我们使用git来克隆这是最标准的方式。# 克隆YOLOv5官方仓库 git clone https://github.com/ultralytics/yolov5 # 进入项目目录 cd yolov5克隆下来的yolov5文件夹里有什么快速浏览一下data/: 存放数据集配置文件和脚本如coco.yaml。models/: 模型定义文件包括yolov5s.yaml,yolov5m.yaml等不同大小的模型。utils/: 工具函数库包括损失计算、指标评估、日志记录等。weights/: 空文件夹用于存放下载的预训练模型权重。detect.py:用于推理的脚本对图像、视频、流进行检测。train.py:用于训练的脚本。val.py:用于验证的脚本。export.py:用于模型导出的脚本可以导出为ONNX、TensorRT等格式。requirements.txt:项目依赖包列表这是我们下一步要安装的。3.2 安装项目依赖解读requirements.txt在项目根目录下执行pip install -r requirements.txt这个命令会安装requirements.txt里列出的所有Python包。我们来看看其中几个关键角色opencv-python 图像处理核心库用于读取图片、视频画检测框。pycocotools 用于COCO数据集格式的评估安装这个有时会报错特别是在Windows上。如果失败可以尝试pip install pycocotools-windows。torch1.8.0 我们之前已经安装了这里会检查版本。tensorboard 训练可视化工具可以在浏览器中实时查看损失曲线、指标变化。pandas,seaborn 用于生成训练结果的分析图表。实操心得requirements.txt里的版本号有时是“”这意味着可能会安装最新的版本。而最新版有时会引入不兼容的改动。如果安装后运行报错可以尝试指定稍旧一点的稳定版本。例如我曾遇到过最新版的matplotlib导致图表显示异常回退到3.5.3就解决了。记住这个排查思路当遇到莫名其妙的库错误时版本冲突是首要怀疑对象。安装过程可能会持续几分钟取决于你的网络。如果遇到某个包下载慢或失败可以考虑使用国内镜像源例如清华源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple4. 预训练模型与初步测试验证安装成功依赖装好了但模型还是个空壳。我们需要用预训练权重来赋予它“视力”。4.1 下载预训练权重YOLOv5提供了从轻量到重量的多个模型yolov5n(nano),yolov5s(small),yolov5m(medium),yolov5l(large),yolov5x(extra large)。模型越大精度通常越高但速度越慢所需资源也越多。对于初次测试和大多数应用yolov5s在速度和精度上取得了很好的平衡。你可以通过detect.py脚本自动下载但我更推荐手动下载因为网络问题可能导致自动下载失败。访问YOLOv5的 GitHub Releases页面 。找到最新的发布版本在Assets里找到yolov5s.pt或其他你想要的模型权重文件。下载后将其放入项目根目录下的weights/文件夹中如果没有就新建一个。4.2 运行第一个检测让模型“看见”世界现在激动人心的时刻到了。我们用官方自带的测试图片来跑一下检测。python detect.py --source data/images --weights weights/yolov5s.pt --conf 0.25我们来拆解这条命令--source data/images: 指定检测源。data/images是项目自带的两个测试图片bus.jpg和zidane.jpg所在的文件夹。你也可以指定单张图片路径、视频文件、摄像头编号如0或一个包含图片的URL。--weights weights/yolov5s.pt: 指定使用的模型权重路径。--conf 0.25: 置信度阈值。只有检测框的置信度高于0.25的才会被显示出来。调高这个值如0.5结果会更严格漏检可能增加调低则可能看到更多误检。执行命令后你会看到终端开始输出信息加载模型、处理图片、输出检测结果。处理完成后结果会保存在runs/detect/exp/目录下每次运行都会新建一个expn文件夹n是数字自动递增。打开结果图片你应该能看到图片中的行人、汽车等被画上了框并标注了类别和置信度。恭喜你YOLOv5已经成功运行起来了4.3 测试你的自定义图片和视频把你想检测的图片比如my_pic.jpg放到项目根目录然后运行python detect.py --source my_pic.jpg --weights weights/yolov5s.pt检测视频比如my_video.mp4python detect.py --source my_video.mp4 --weights weights/yolov5s.pt使用电脑摄像头通常编号为0进行实时检测python detect.py --source 0 --weights weights/yolov5s.pt按q键可以退出实时检测窗口。5. 训练自己的数据集从“用模型”到“造模型”使用预训练模型做检测只是第一步。要让YOLOv5认识你关心的特定物体比如识别某种零件、某种动物你需要用自己的数据训练它。这是YOLOv5最核心的价值所在。5.1 数据准备YOLO格式详解YOLOv5要求一种特定的标注格式。你需要为每张图片准备一个同名的.txt标注文件。图片可以是.jpg,.png等常见格式。标注文件.txt文件每一行代表图片中的一个物体。标注行格式class_id x_center y_center width heightclass_id: 物体的类别索引从0开始。比如“猫”是0“狗”是1。x_center, y_center: 物体边界框中心的x和y坐标归一化到图片宽度和高度即值在0到1之间。计算公式x_center (x_min x_max) / 2 / image_widthwidth, height: 物体边界框的宽度和高度同样归一化到图片宽度和高度。计算公式width (x_max - x_min) / image_width例如一张1000x800的图片上有一个“猫”class_id0的边界框其左上角坐标(100, 120)右下角坐标(300, 400)。那么x_center (100 300)/2 / 1000 0.2y_center (120 400)/2 / 800 0.325width (300 - 100) / 1000 0.2height (400 - 120) / 800 0.35对应的标注行就是0 0.2 0.325 0.2 0.35你可以使用标注工具来生成这种格式最常用的是LabelImg设置输出格式为YOLO或Roboflow在线平台提供数据增强和格式转换。5.2 数据集配置文件告诉YOLOv5你的数据在哪数据准备好后需要创建一个YAML配置文件来告诉训练脚本数据的路径和类别信息。在data/目录下新建一个文件例如my_custom_data.yaml内容如下# 训练和验证图像的路径可以是相对路径或绝对路径 train: ../datasets/my_data/images/train/ val: ../datasets/my_data/images/val/ # 类别数量 nc: 2 # 例如我只有猫和狗两类 # 类别名称列表 names: [cat, dog]train和val: 分别指向训练集和验证集图片所在的文件夹。YOLOv5会读取这些文件夹下所有的图片并自动在同一目录下寻找同名的.txt标注文件。nc: 类别的总数。names: 类别名称列表顺序必须与标注文件中的class_id对应。你需要按照这个结构组织你的数据datasets/ └── my_data/ ├── images/ │ ├── train/ # 存放所有训练图片 │ └── val/ # 存放所有验证图片 └── labels/ ├── train/ # 存放所有训练图片对应的.txt标注文件 └── val/ # 存放所有验证图片对应的.txt标注文件注意images/train/和labels/train/里的文件必须一一对应且文件名不含后缀相同。5.3 启动训练参数解析与监控准备好数据和配置文件后就可以开始训练了。基础训练命令如下python train.py --img 640 --batch 16 --epochs 100 --data data/my_custom_data.yaml --weights weights/yolov5s.pt --device 0这是一个非常强大的命令我们来详细解读每个参数--img 640: 输入图像的大小。YOLOv5会将所有图片缩放保持长宽比并填充到这个尺寸。更大的尺寸如1280可能提升精度但会显著增加显存消耗和训练时间。640是一个在精度和速度间平衡的常用值。--batch 16: 批处理大小。一次输入多少张图片进行前向和反向传播。越大训练越稳定、越快但需要更多显存。如果出现“CUDA out of memory”错误首先尝试减小batch大小。--epochs 100: 训练轮数。整个训练集被完整遍历一次称为一个epoch。通常需要几十到几百个epoch模型才能收敛。--data data/my_custom_data.yaml: 指向你刚刚创建的数据集配置文件。--weights weights/yolov5s.pt:迁移学习的起点。这里我们使用在COCO数据集上预训练的yolov5s.pt作为初始权重。这是训练自己数据集的关键技巧能极大加快收敛速度并提升最终性能远比从零开始训练要好。--device 0: 指定使用的GPU设备编号。如果是多卡可以用--device 0,1。使用CPU则设为--device cpu。训练开始后终端会输出每个epoch的损失值、评估指标如mAP0.5。同时TensorBoard日志会保存在runs/train/exp/目录下。你可以启动TensorBoard来可视化训练过程tensorboard --logdir runs/train然后在浏览器中打开http://localhost:6006就可以看到损失曲线、精度曲线、验证样本的检测结果等非常直观。5.4 训练中的关键技巧与调参学习率--lr0这是最重要的超参数之一。默认是0.01。如果训练过程中损失值剧烈震荡或变成NaN可以尝试调小学习率如0.001。如果损失下降非常缓慢可以尝试调大。数据增强YOLOv5默认开启了丰富的数据增强如 mosaic, mixup, 色彩抖动随机翻转等这能有效防止过拟合提升模型泛化能力。除非你的数据非常特殊否则不建议关闭。早停--patience可以设置--patience 50表示如果连续50个epoch验证集指标没有提升就自动停止训练防止过拟合。恢复训练如果训练意外中断可以使用--resume参数从上次保存的最后一个权重继续训练。例如--resume runs/train/exp/weights/last.pt。6. 模型验证与导出从训练结果到实际应用训练完成后我们需要评估模型的好坏并把它转换成可以在不同平台上部署的格式。6.1 模型性能验证训练脚本在结束时会自动在验证集上运行一次评估结果保存在runs/train/exp/results.csv和图片中。你也可以手动运行更详细的验证python val.py --weights runs/train/exp/weights/best.pt --data data/my_custom_data.yaml --img 640--weights: 这里指定训练得到的最佳权重best.pt验证集指标最高的权重。运行后会输出一系列指标其中最关键的是mAP0.5和mAP0.5:0.95。mAP0.5当交并比IoU阈值为0.5时的平均精度均值。这是最常用的一个指标值越高越好通常达到0.8以上就算很不错了。mAP0.5:0.95在IoU阈值从0.5到0.95步长0.05区间内的平均mAP。这是一个更严格的指标。6.2 模型导出适配不同部署环境训练好的.pt文件是PyTorch格式要在某些边缘设备如Jetson Nano或追求极致速度的场景使用TensorRT下运行需要转换成其他格式。export.py脚本就是干这个的。导出为ONNX格式一种开放的模型交换格式python export.py --weights runs/train/exp/weights/best.pt --include onnx导出为TensorRT引擎NVIDIA GPU上的极致推理加速python export.py --weights runs/train/exp/weights/best.pt --include engine --device 0导出为CoreML格式用于iOS/macOS应用python export.py --weights runs/train/exp/weights/best.pt --include coreml导出的文件会保存在和权重文件相同的目录下。注意导出TensorRT引擎需要你的环境已正确安装TensorRT。7. 常见问题与深度排错指南即使按照步骤操作也难免会遇到问题。这里我汇总了一些高频问题和解决方法。7.1 安装与依赖类问题Q1:pip install -r requirements.txt时pycocotools安装失败特别是在Windows上。A1:这是最常见的问题。pycocotools在Windows上需要Visual C Build Tools。最简单的解决方案是安装预编译的Windows版本pip install pycocotools-windows或者如果你不需要在COCO格式的数据集上做精确评估可以在requirements.txt中暂时注释掉pycocotools这一行对基础训练和检测影响不大。Q2: 运行detect.py或train.py时报错ModuleNotFoundError: No module named ‘XXX‘。A2:这通常是某个依赖包没有成功安装。首先请确保你是在激活的虚拟环境conda activate yolov5中操作。然后手动安装缺失的包例如pip install XXX。如果问题依旧尝试升级pip并重新安装所有依赖pip install --upgrade pip然后pip install -r requirements.txt。Q3: 使用GPU训练时报错RuntimeError: CUDA out of memory。A3:显存不足。按以下顺序尝试解决减小批处理大小这是最有效的方法。将--batch从16降到8、4甚至2。减小输入图像尺寸将--img从640降到416或320。使用更小的模型从yolov5s.pt换到yolov5n.pt作为预训练权重。检查是否有其他程序占用显存在命令行输入nvidia-smi关闭不必要的GPU进程。使用梯度累积如果显存实在太小可以设置--accumulate 2例如这相当于模拟一个更大的batch size但会稍微增加训练时间。7.2 训练与数据类问题Q4: 训练时损失loss不下降或者下降得非常慢。A4:检查数据这是首要原因。确保你的标注文件.txt格式正确没有空文件并且class_id在范围内。可以用detect.py快速验证一下标注是否正确python detect.py --weights yolov5s.pt --source path/to/your/image.jpg看看预训练模型能否在你图片上检测出东西至少背景是能处理的。如果预训练模型都表现异常可能是图片本身格式有问题。调整学习率默认学习率0.01可能对你的数据太大或太小。尝试使用--lr0 0.001调小或--lr0 0.1调大需谨慎。关闭数据增强极少数情况下默认的数据增强可能干扰了特定数据的训练。可以尝试在训练命令后加上--noaug来关闭所有增强看看损失是否开始下降。检查预训练权重确保--weights参数指向了正确的、已下载的预训练权重文件如yolov5s.pt。Q5: 训练出的模型在验证集上mAP很低或者检测时“瞎猜”乱标框。A5:数据量不足深度学习是数据驱动的。每个类别的目标至少需要几百甚至上千个样本。如果数据太少模型无法学习到有效特征。类别不平衡某个类别的样本数量远多于其他类别导致模型偏向于预测多数类。需要收集更多少数类的数据或在数据加载时进行采样平衡。验证集和训练集分布不一致确保验证集和训练集来自相同的场景、相同的采集条件。不要把白天数据用于训练晚上数据用于验证。过拟合模型在训练集上表现很好在验证集上很差。现象是训练损失持续下降但验证损失在某个点后开始上升。解决方法增加数据增强、使用更小的模型、添加正则化如权重衰减--weight_decay、减少训练轮数--epochs或使用早停--patience。7.3 推理与部署类问题Q6: 使用detect.py推理时速度很慢。A6:确认是否在使用GPU运行python -c import torch; print(torch.cuda.is_available())确保输出为True。如果为False你正在使用CPU推理速度会慢几十倍。请检查PyTorch的CUDA版本是否安装正确。使用更小的模型yolov5n比yolov5s快很多精度略有牺牲。减小推理尺寸在detect.py中使用--imgsz 320默认640。使用半精度FP16推理添加参数--half可以显著提升GPU上的推理速度并减少显存占用对精度影响很小。命令如python detect.py --source ... --weights ... --half。导出为TensorRT或ONNX并使用对应推理引擎这是生产环境下获得极致速度的终极方案。PyTorch的动态图本身有一定开销转换为静态图如ONNX并由专用推理引擎如TensorRT, ONNX Runtime执行速度会有大幅提升。Q7: 导出的ONNX或TensorRT模型推理结果和PyTorch模型不一致。A7:这是精度转换和算子兼容的常见问题。确保导出时输入尺寸固定有些模型结构对动态尺寸支持不好。在export.py中指定固定的--imgsz例如--imgsz 640 640。检查ONNX opset版本尝试不同的--opset版本如12, 13, 17。进行精度对齐测试在导出后编写一个简单的脚本用相同的随机输入分别运行PyTorch模型和导出的模型比较输出张量的差异。微小的差异1e-5级别是正常的如果差异巨大则需要排查模型结构中是否有不支持的算子。查阅YOLOv5的导出文档Ultralytics团队会持续更新对不同部署后端的支持情况可能你遇到的问题在新版本中已经修复。整个流程走下来从环境配置到训练出自己的模型看似步骤不少但每一步都有其明确的目的。YOLOv5的优秀之处就在于它把很多复杂的工程细节都封装好了让我们能更专注于数据、业务和模型调优本身。记住在深度学习项目中数据质量决定了模型的上限而代码和调参只是让我们不断逼近这个上限。多花时间在数据清洗和标注上往往比盲目调整超参数回报率更高。当你第一次用自己训练的模型准确识别出目标时那种成就感就是驱动你继续深入这个领域的最好动力。如果在实践中遇到上面没覆盖到的新问题最好的方法是去YOLOv5的GitHub Issues区搜索你遇到的大部分问题很可能已经有前人遇到过并提供了解决方案。