简介YOLOv5搭建与目标检测详解是一份面向初级研究人员与工程技术人员的实操教程帮助具备一定Python和计算机视觉基础的学习者从零完成YOLOv5环境配置、依赖安装与模型调用并进一步掌握自定义数据集训练等进阶用法。内容涉及系统环境与CUDA、cuDNN版本匹配PyTorch安装、官方源码克隆及预训练模型使用整体思路清晰适合理论教学与实际项目参考。资源包内含1个docx格式文档整包仅19KB轻便易读便于快速查阅完整流程。文档从系统要求讲起逐步覆盖依赖库安装、示例检测脚本执行、结果目录查看以及训练自定义数据集的方法可帮助读者按步骤实践并自行调整实验条件进行验证。目前已有238人学习对于希望快速上手YOLOv5目标检测的初学者来说是一份简洁实用的入门材料。1. YOLOv5 搭建与目标检测多数人卡在环境配置而不是算法本身去年帮一个同事调 YOLOv5他按教程装完跑 detect.py第一行就报 CUDA error: no kernel image。折腾一晚上才发现是 PyTorch 的 CUDA 编译版本比显卡驱动支持的高一截。这类事在 YOLOv5 搭建和跑通目标检测的流程里太常见框架本身已经足够傻瓜化真正的门槛全在环境Python、CUDA、PyTorch wheel、依赖列表任何一个失配都能卡住半天。这篇笔记把从零搭建到第一次跑通目标检测的完整流程拆开讲重点放在环境选型、detect.py 参数语义、自定义数据集训练和模型导出这几段容易踩坑的地方。适合有 Python 基础、正准备跑 YOLOv5 做检测或训练自己数据的工程师照着走一遍能少踩一半的坑。2. 环境搭建CUDA 版本与 PyTorch 的匹配关系90% 的报错源头2.1 为什么先建 conda 环境环境隔离就是后悔药很多新手拿到教程第一步就是把 torch 直接装进全局 Python。当时能用跑第二个项目时依赖冲突torchvision 升级把 torch 顶掉然后 YOLOv5 莫名其妙跑不起来最后只能重装系统解释器——这个场景我见过不止一次。conda 的虚拟环境把 Python、pip 包和依赖全部隔离在一个目录里删掉重建都不影响系统其他软件我一般把它当后悔药用。conda create --name yolov5_env python3.8 conda activate yolov5_env第一条命令创建名为 yolov5_env 的独立环境指定 Python 3.8。为什么用 3.8YOLOv5 v5.0 时代官方依赖对 3.8 支持最稳3.6 部分算子缺失3.10 以上某些旧依赖编译会报错。第二条命令激活环境激活后终端前缀会变成(yolov5_env)后续所有 pip 安装都装进这个隔离区。激活后建议先执行python --version和pip --version确认指向 conda 环境。这一步很多人忽略结果 pip 装到全局路径跑 detect.py 时解释器却用 conda 环境里的报 ModuleNotFoundError 时根本找不到包装哪去了。如果机器上还有别的 Python 项目更应该坚持一个项目一个环境这是长期不吃亏的习惯。2.2 PyTorch 安装GPU 与 CPU 两条路线怎么选官方系统要求写的是 CUDA 10.2、cuDNN 7.6这是 v5.0 时代的基线现在多数驱动都高于它。但要注意一个概念nvidia-smi显示的 CUDA Version 是驱动支持上限不代表 PyTorch 一定用它编译。PyTorch 必须装与驱动匹配的 CUDA 编译版装高了报 no kernel image装低了白白浪费显卡。# 先看驱动支持到什么 CUDA 版本 nvidia-smi # GPU 版CUDA 11.8 对应 wheel pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # CPU 版默认 PyPI 源 pip install torch torchvisionGPU 版用官方 cu118 源是因为这个编译版本对旧显卡兼容性好从 GTX 10 系到 RTX 40 系都能跑是目前踩坑最少的组合。装完立即做一次验证不要直接去跑 detect.pyimport torch print(torch.__version__) # 例如 2.0.1cu118 print(torch.cuda.is_available()) # True 才说明 GPU 可用 print(torch.cuda.get_device_name(0)) # 显卡型号三个输出分别确认版本号带cu118说明装的是 CUDA 版is_available()返回 True 说明 CUDA 上下文能正常建立返回 False 且版本号不带 cu 就是装成 CPU 版了得重装最后一行确认驱动识别显卡。这三行输出搞不定环境问题会一路带到训练和部署阶段越早暴露越好。cuDNN 也是官方写在系统要求里的项但新手阶段可以暂时不管。PyTorch 的预编译 wheel 自带经过测试的 cuDNN 运行时大多数时候装完 torch 就能用只有源码编译 PyTorch 或接 TensorRT 时才需要单独盯 cuDNN 版本。碰到 CUDA 相关报错时先查 torch 版本与驱动不要一上来就重装 cuDNN。2.3 克隆源码与安装依赖requirements 里暗藏的 torch 陷阱环境就绪后克隆 YOLOv5 仓库并安装依赖git clone --depth 1 https://github.com/ultralytics/yolov5.git cd yolov5加--depth 1只拉最新一次提交仓库体积小很多网络不好的时候不容易卡死。随后是常规的依赖安装但这里藏着 YOLOv5 环境配置里最容易翻车的一步。# 安装前先看一眼 requirements.txt 前几行 head -n 10 requirements.txt # 把 torch/torchvision 两行注释掉后再装 pip install -r requirements.txtrequirements.txt 里 torch 那行用的是范围声明直接装一般不会强制覆盖但 pip 解析时可能把 PyPI 通道的 torch 相关包带进来和 conda 渠道的 CUDA 版产生冲突轻则环境里混着两份 torch 残留文件重则直接在推理时报版本不一致。我一般先把 torch、torchvision 两行注释掉再装剩余依赖剩下的是 opencv-python、matplotlib、seaborn、pandas、tqdm、pyyaml 这些辅助库和 torch 版本无关。如果已经全部装完导致 torch 被替换执行pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118强制装回来即可不用删环境重来。3. 用预训练模型跑通检测detect.py 参数拆解与输出解读3.1 预训练模型怎么选s/m/l/x 不是越大越好YOLOv5 官方提供 s、m、l、x 四档预训练权重体积和精度递增速度递减。选型逻辑很简单先跑通流程用 s确认效果再考虑更大的。模型参数量推荐场景yolov5s约 7.2M入门、CPU 试跑、速度优先yolov5m约 21.2M平衡档多数场景首选yolov5l约 46.5M追求精度、有 GPU 资源yolov5x约 86.7M高精度研究、慢速推理参数量写进模型结构 yaml 里对应下载体积也有明显差距yolov5s.pt 约 14MBx 档超过 170MB。对新手s 足够验证流程如果检测场景里小目标占比高再考虑 m 起步。模型越大显存占用越高稍后训练时会直接影响 batch size选型时把显卡显存一起算进去。3.2 获取 yolov5s.ptwget 与手动下载两条路预训练权重在官方 release 页面用命令下载最快# Linux/macOS wget https://github.com/ultralytics/yolov5/releases/download/v5.0/yolov5s.pt # Windows PowerShell 或 CMD curl -L -o yolov5s.pt https://github.com/ultralytics/yolov5/releases/download/v5.0/yolov5s.ptWindows 没有 wget用 curl 加-L跟随重定向、-o指定输出文件名即可。下载可以放仓库根目录也可以放任意路径detect.py 的--weights参数按路径引用。如果下载一直卡住浏览器手动下载后扔进目录效果一样。这个 .pt 文件是 PyTorch 序列化格式里面同时包含模型结构、权重和训练时的超参数记录加载后可直接推理。3.3 运行 detect.py关键参数逐个拆下载完成后用一张包含目标的图片跑第一个检测python detect.py --weights yolov5s.pt --source test.jpg --img 416 --conf 0.4 --iou 0.5这是 YOLOv5 源码最基础的一组入口参数逐项拆开参数作用调节建议--weights模型权重路径换 best.pt 或 onnx 时在这改--source输入来源图片/视频/文件夹/摄像头摄像头传 0视频传 .mp4--img推理缩放尺寸默认 640416 更快但小目标易丢--conf置信度阈值0.4 偏严0.25 会看到更多框--iouNMS 的 IoU 阈值0.5 常用重叠目标多可调 0.4--img 416是推理时把原图缩放到 416×416不是模型训练尺寸只影响本次推理的计算量和小目标召回。--conf 0.4是最直观的过滤阀调低到 0.25同一个目标可能被多个框套住调高到 0.7漏检变多但框基本可靠。--iou 0.5控制 NMS 去重力度两个框重叠超过 50% 就合并这是 YOLO 后处理里最关键的一步。实际调参时优先动 confiou 一般不碰。# 摄像头实时检测0 代表第一个摄像头 python detect.py --weights yolov5s.pt --source 0 --img 640 --conf 0.4 # 批量检测整个文件夹 python detect.py --weights yolov5s.pt --source ./test_images --img 640摄像头和文件夹是实际工程里最常用的两种输入形式。文件夹模式下所有支持格式的图片被逐个处理后写入结果目录摄像头模式会弹预览窗口按 q 退出。3.4 结果去哪了runs/detect 的自动编号每次运行 detect.py结果写入runs/detect/exp。如果已存在 exp新结果写 exp2、exp3依次递增绝不覆盖旧文件夹。这个设计对调参特别友好连着跑三次不同阈值三个结果目录摆在面前直接对比。目录下是画好框的图或视频框上方标注类别名和置信度例如person 0.83。如果想拿到坐标供下游程序用加--save-txt每个框的类别、中心点坐标、宽高以归一化格式写入同名 txt。批量处理时这个输出是后续逻辑直接能吃的。提示--save-txt输出的坐标范围是 0~1使用前要按原图宽高换算回像素坐标。要控制结果落盘位置用--project指定根目录、--name指定子目录名配起来就是固定的输出路径。批量任务里我习惯写成--project ./runs --name bird_batch_v1方便和训练批次对应。4. 高频踩坑排查五个常见报错的现象、原因与解决4.1 报错速查表YOLOv5 环境配置里的报错有规律可循大部分集中在 torch 版本、numpy 版本和系统库缺失三块。先对照速查表定位再动手排报错现象直接原因一句话解法CUDA error: no kernel imagetorch 的 CUDA 编译版本高于驱动支持换 cu118 或更低版本 wheelCUDA unavailabletorch 装成了 CPU 版用官方源重装 GPU 版libGL.so.1 not found系统缺 OpenCV 依赖安装 libgl1 系统库numpy ndarray size changedopencv 与 numpy 2.x 不兼容装 numpy2git clone 长时间卡死仓库含完整历史提交--depth 1 或下载 zip4.2 五个场景逐个拆开讲第一个是 CUDA error: no kernel image。现象是模型加载时直接崩报错尾部带 device 编号。原因十有八九是装了 cu121 甚至更新的 torch wheel而显卡驱动停留在支持 CUDA 11.x 的版本。解决方式照抄 2.2 的 cu118 源重装装完必须确认版本号带cu118再继续这不放水。第二个是 CUDA unavailable。现象是检测脚本能跑但极慢说明在走 CPU 推理或者--device 0被直接拒绝。原因通常是默认 PyPI 源安装的 torch 没有带 CUDA 支持。解决不复杂重装 GPU 版再跑一遍 torch.cuda.is_available()输出 True 才算过。yolov5 环境配置里这条是最常见的隐性翻车点因为脚本不会报错只是慢到让人误以为代码有问题。第三个是 libGL.so.1 缺失。现象是 import cv2 瞬间报错常见于精简版 Linux 和 Docker 容器。原因很简单opencv-python 的预编译包依赖系统 libGL 动态库容器镜像默认不带。解决方式因系统而异Debian/Ubuntu 系执行apt-get install -y libgl1CentOS 用 yum 装同名 libgl 包。第四个是 numpy ndarray size changed。现象是跑 detect.py 时 numpy 操作突然抛维度错误报错里带 binary incompatibility 字样。原因是 opencv 是预编译的而 numpy 升到 2.x 后底层 C 接口数组结构尺寸对不上。解决是降级pip install numpy2装完重启 Python 进程再跑一次检测验证。这类报错现在越来越常见因为新项目习惯直接拉最新 numpy而 YOLOv5 v5.0 的依赖列表定稿时 numpy 2.x 还没发布。第五个是 git clone 卡死。现象是拉仓库时进度条长时间不动。原因不是网速而是完整克隆会把所有历史提交拉下来体积可观。解决用git clone --depth 1只取最新提交或者直接到 release 页面下载 zip 源码包。zip 方式最简单但如果后续要切换版本分支还是 git 方式方便。4.3 环境坏了别硬扛一套归零重来的标准动作环境问题缠成一团时与其逐个排不如归零重来。我一般用三行命令完成重置conda deactivate conda env remove --name yolov5_env -y conda create --name yolov5_env python3.8 conda activate yolov5_env删除环境这条命令-y表示不询问确认。整套动作的好处是干净把 torch 装坏留下的半残依赖全部清掉重装一次通常不超过十分钟。很多人舍不得删环境结果在报错里耗一下午。我现在的做法是torch.cuda.is_available() 始终 False 且排查两轮没结果直接删了重建这个习惯回头看不亏。5. 训练自定义数据集从 YOLO 标注格式到 train.py 的完整闭环5.1 数据准备YOLO 格式与目录约定训练自己的检测模型第一关是数据格式。YOLOv5 不认 VOC 的 xml也不用 COCO 的 json它要的是每个图片对应一个同名 txt放在 labels 目录里目录结构固定dataset/ images/ train/ img001.jpg val/ img002.jpg labels/ train/ img001.txt val/ img002.txt同名是硬性要求图片和标签文件名必须完全一致靠序号关联。每个 txt 的一行对应一个目标0 0.583984 0.471354 0.076172 0.155729五个数字依次是类别编号、目标中心 x、目标中心 y、目标宽、目标高后四个全部归一化到 0~1即除以原图宽高后的相对坐标。归一化的好处是训练时无论图片缩放到 416 还是 640坐标都不变形。手工写这个格式容易出错通常做法是先标注成 VOC 或 COCO 格式再写脚本转成 YOLO txtyolov5 仓库的 utils 里有转换工具但实际用下来自己写十几行脚本最可控。5.2 两个配置文件data.yaml 与模型 yaml数据集就绪后写一个数据描述文件例如 dataset.yamltrain: /absolute/path/to/dataset/images/train val: /absolute/path/to/dataset/images/val nc: 1 names: [bird]这里最容易翻车的坑是路径yaml 里的路径相对于运行 train.py 时所在目录解析用相对路径很容易出现 Dataset not found 然后直接退出。我一般写绝对路径一步到位。nc是类别数names是类别名列表顺序必须和标注 txt 里的编号一致——编号 0 对应 names[0]错一位全乱。然后改模型结构配置models/yolov5s.yamlnc: 1打开文件找到顶部 nc 字段改成自己的类别数即可。这个文件描述网络层结构除了 nc其他层数不要动。新手常犯的错误是训练时--cfg忘了指定导致实际用的还是 80 类的 COCO 配置。训练前打印一遍配置文件确认 nc五秒钟的事能避免训练到一半发现结构不对。5.3 启动训练train.py 核心参数与显存预估python train.py \ --img 640 \ --batch 16 \ --epochs 100 \ --data dataset.yaml \ --cfg models/yolov5s.yaml \ --weights yolov5s.pt \ --cache \ --patience 20这套是我跑自定义检测比较稳的起点参数。--weights yolov5s.pt是迁移学习从 COCO 预训练权重初始化新类别数据量少也能较快收敛不写这个参数就是随机初始化效果差一截。--img 640是训练输入尺寸和推理保持一致时效果最好。--batch 16受显存约束OOM 时 train.py 会直接报 CUDA out of memory。--patience 20是早停验证 mAP 连续 20 轮不提升自动停训练不白耗时间。超参数是联动的batch 越大每个 epoch 越快但显存占用和梯度稳定性跟着变epochs 从 100 起步看曲线如果还在上升就加。原教程给的是--img 416 --epochs 300不是不能用而是新手往往等不起我一般先跑 100 看走势再决定延长。显存与 batch 的对应关系按这个量级估比较稳显存batch 建议4GB4~88GB1616GB32如果显卡驱动支持且显存足够--cache会把图像缓存进内存训练时省去每次读盘的 IOepoch 轮数多时总时间能省不少。首次训练用数据集里几百张图跑通流程不要一上来就全量数据流程没验证前数据再多都是浪费时间。5.4 训练产物怎么看best.pt 与检测回验训练结束输出在 runs/train/exp 目录核心文件三个weights/best.pt是验证集上 mAP 最高的权重部署就用它weights/last.pt是最后一个 epoch 的权重中断恢复用results.csv记录每个 epoch 的 loss、精确率、召回率、mAP。判断训练是否健康看 results.csv 里的 val 曲线loss 持续下降说明正常train loss 降而 val loss 回升是过拟合信号这时要加数据增强或减 epochs。拿 best.pt 验证效果python detect.py --weights runs/train/exp/weights/best.pt --source test.jpg --img 640 --conf 0.25验证阶段把 conf 放开到 0.25目的是看模型找全目标的能力而不是看过滤噪声的能力。如果这张图里该框的都框了、没有漏检训练闭环就真正走通。后续所有迭代都围绕 best.pt 展开换数据、调超参、重训练流程不变。6. 导出 ONNX把 YOLOv5 模型变成可移植的单文件部署单元6.1 从 PyTorch 到 ONNX一条命令完成导出训练产物是 .pt部署时不能要求每台机器都装 PyTorch常见做法是导成 ONNX交给 onnxruntime 或 TensorRT 去跑。仓库自带 export.pypython export.py --weights runs/train/exp/weights/best.pt --include onnx --img 640 --batch 1导出后权重同目录会多一个 best.onnx。这个文件不依赖 yolov5 源码也不依赖 Python 端的模型结构定义任何支持 ONNX 的推理框架都能加载。树莓派这类低算力设备上onnxruntime 比直接跑 PyTorch 合理得多内存占用和启动时间都小一个量级。6.2 部署前先验证输出头再谈接入拿到 onnx 后第一件事不是写业务代码而是确认模型输出头的 shape。以 640 输入为例原始检测头输出维度是 [1, 25200, nc5]25200 是三种尺度特征图 80×80、40×40、20×20 乘以每个网格 3 个 anchor 得到的总候选框数后面跟的 5 是中心点 xy、宽高 wh 和 objectness 置信度再往后是 nc 个类别分数。这个结构是 YOLO 后处理所有逻辑的依据解码和 NMS 都在这些数据上操作。用 onnxruntime 验证 shapeimport onnxruntime as ort import numpy as np session ort.InferenceSession(best.onnx) x np.random.rand(1, 3, 640, 640).astype(np.float32) out session.run(None, {session.get_inputs()[0].name: x})[0] print(out.shape) # (1, 25200, 6)6 5 1 个类别这里用随机张量验证已经足够不需要真实图片。shape 和自己模型对上再往下写解码逻辑就顺理成章对不上多半是导出参数不对回到上一步重导。从那以后我每次导出部署模型都强制先跑一遍这个 shape 检查再往下写后处理避免在错误的数据结构上调试半天也希望这个习惯能帮到你少走一次弯路。本文还有配套的精品资源点击获取