简介这份文档面向具备一定Python与计算机视觉基础的入门级研究人员和工程技术人员系统讲解YOLOv5目标检测框架在本地环境中的搭建与运行方法。内容从系统要求入手明确Windows、macOS或Linux平台及Python 3.6以上版本的前提并针对GPU加速场景说明CUDA 10.2与cuDNN 7.6以上的版本匹配要求随后依次覆盖依赖库安装、官方源码获取、预训练模型下载与首个检测实例运行最后简要引介基于自有数据集的模型训练与参数调整等进阶方向。资源包共1个docx文件约19KB以图文步骤形式组织便于按流程对照操作。目前已有238人学习适合初次接触YOLOv5、希望快速完成环境部署并理解目标检测实际应用流程的读者既可作为理论教学材料也能为工程项目提供参考。1. 从一张跑不通的 detect.py 说起YOLOv5 环境搭建到底卡在哪很多人第一次碰 YOLOv5不是卡在模型原理而是卡在detect.py跑不起来。明明照着教程pip install -r requirements.txt走完了一执行就报torch和 CUDA 版本对不上或者cv2导入失败。这份资源就是冲着这个场景来的它把 YOLOv5 从零搭建到跑通第一张检测图的全流程拆成了可照抄的步骤覆盖环境准备、依赖安装、预训练模型推理以及往自定义数据集训练延伸的入口。适合有 Python 基础、想快速把目标检测跑起来验证效果的工程技术人员也适合拿它当课程设计或项目预研的起步模板。下面按我实际拆包复现的顺序讲重点放在参数怎么设、哪一步最容易翻车。2. 环境选型与依赖安装Python 3.8 PyTorch 的版本咬合2.1 为什么先锁 Python 3.8 而不是追新YOLOv5 官方仓库对 Python 版本的容忍度看起来宽3.6但实际踩下来3.8 是兼容性最稳的一档。原因不玄学PyTorch 的预编译 wheel、torchvision 的算子、以及 requirements 里那堆科学计算包在 3.8 上的组合经过大量验证。上到 3.11 之后部分依赖的二进制轮子缺失pip 会退化成源码编译装到一半报编译错误是常事。我一般用 conda 建独立环境避免和系统 Python 打架# 创建名为 yolov5_env 的虚拟环境锁定 Python 3.8 conda create --name yolov5_env python3.8 -y # 激活环境后续所有命令都在这个环境里执行 conda activate yolov5_env # 确认解释器路径指向 conda 环境而不是系统 Python which python # Windows 下用 where python这里的关键参数是python3.8别写成python3否则 conda 可能拉到最新小版本。激活后务必用which python确认路径落在envs/yolov5_env下这一步是后面所有报错的“后悔药”——环境没激活对装再多包都是白装。2.2 PyTorch 安装CPU 版和 GPU 版别装混PyTorch 是整条链路的底座装错版本后面全崩。原文给的命令比较粗实际要按硬件分两条路走。GPU 用户的核心是 CUDA 版本要和驱动匹配CPU 用户则要显式装 cpuonly 版本否则 pip 可能默认拉一个带 CUDA 的大包白占几个 G。# GPU 路线CUDA 11.3 对应的 PyTorch版本号需与你的驱动兼容 pip install torch torchvision --extra-index-url https://download.pytorch.org/whl/cu113 # CPU 路线显式安装 CPU 版本避免误拉 CUDA 包 pip install torch torchvision cpuonly -f https://download.pytorch.org/whl/torch_stable.html参数说明--extra-index-url指向 PyTorch 官方 wheel 源cu113表示 CUDA 11.3 编译版换成cu118、cu121对应更高 CUDA。装完必须验证别信“安装成功”的提示import torch # 打印版本和 CUDA 可用性这是判断装没装对的第一手证据 print(torch.__version__) print(torch.cuda.is_available()) # GPU 用户应为 TrueCPU 用户为 False print(torch.version.cuda) # 显示 PyTorch 编译时用的 CUDA 版本如果cuda.is_available()返回 False 但你有 GPU八成是驱动版本低于 PyTorch 要求的 CUDA 运行时或者装成了 CPU 版。这时候别急着重装系统先nvidia-smi看驱动支持的 CUDA 上限再回头选对应的cuXXX包。2.3 克隆仓库与 requirements 的隐藏依赖拿到源码和装依赖是两步顺序不能反# 克隆官方仓库并进入目录 git clone https://github.com/ultralytics/yolov5.git cd yolov5 # 安装项目依赖这一步会拉 opencv、matplotlib、pandas 等 pip install -r requirements.txtrequirements.txt里最容易被忽略的是opencv-python它在无图形界面的服务器上装完 import 会报libGL.so.1找不到。常见做法是换成opencv-python-headless或者补装系统库。另一个坑是pycocotoolsWindows 上直接 pip 装经常编译失败需要预装 Visual C Build Tools。装完跑一句python -c import cv2, torch; print(ok)做冒烟测试比等到 detect 阶段才发现问题省时间。3. 预训练模型推理detect.py 的参数怎么调才不翻车3.1 下载权重与第一次推理权重文件是推理的前提yolov5s.pt是最小的 s 版本适合先跑通再谈精度# 下载 s 版本预训练权重约 14MBwget 在 Windows 下可用 curl 替代 wget https://github.com/ultralytics/yolov5/releases/download/v5.0/yolov5s.pt # 对单张图片做检测输出到 runs/detect/exp python detect.py --weights yolov5s.pt --source test.jpg --img 416 --conf 0.4 --iou 0.5逐参数说清楚--weights指定权重路径换成yolov5m.pt、yolov5l.pt精度递增但速度递减--source可以是单图、目录、视频甚至摄像头编号0--img是推理输入尺寸必须是 32 的倍数416 是速度和精度的折中设成 640 小目标召回更好但显存吃紧--conf是置信度阈值低于它的框直接丢0.4 偏保守漏检多就降到 0.25--iou是 NMS 的重叠阈值两个框 IoU 超过它就合并密集场景调高到 0.6 能减少误删。3.2 结果目录与输出解读跑完在runs/detect/exp下能看到带框的图exp2、exp3会随运行次数递增不会覆盖。终端会打印每个类别的检测数量和耗时。如果图里框明显偏移或类别错乱先别怀疑模型检查--img是否和训练时的输入尺度差太远——YOLOv5 对输入尺度敏感416 训的模型用 640 推框会系统性偏大。视频源推理时加--nosave可以只看不存省磁盘要保存带标签的 txt 结果加--save-txt方便后续做统计。提示首次运行会自动下载字体和部分资源离线环境会卡住提前在有网环境跑一次把缓存落盘。4. 自定义数据集训练从 yaml 配置到 train.py 的完整链路4.1 数据集格式与 data.yaml 的字段含义YOLOv5 要求标注是每张图一个同名 txt每行类别 中心x 中心y 宽 高坐标全部归一化到 0~1。目录结构常见做法是images/train、images/val配labels/train、labels/val。然后写一个 data.yaml 告诉训练脚本去哪找数据# data.yaml 示例路径按实际改 train: ../dataset/images/train # 训练集图片目录 val: ../dataset/images/val # 验证集图片目录 nc: 3 # 类别数必须和标注里的类别 id 对上 names: [cat, dog, person] # 类别名顺序即 id 0/1/2nc和names长度必须一致标注里出现 id 3 但 nc 写 3合法 id 只有 0~2会直接报索引越界。这是新手最高频的翻车点之一。4.2 改模型配置与启动训练模型结构文件在models/yolov5s.yaml只需改nc一处其余保持默认# models/yolov5s.yaml 片段 nc: 3 # 改成你的类别数和 data.yaml 保持一致启动训练# 基于预训练权重做迁移学习300 轮batch 16 python train.py --img 416 --batch 16 --epochs 300 \ --data data.yaml --cfg models/yolov5s.yaml \ --weights yolov5s.pt --cache参数逻辑--weights yolov5s.pt是迁移学习的关键从预训练权重起步比从零训收敛快得多--cache把图片缓存进内存加速读取数据集大超过内存时要去掉否则 OOM--batch 16在 8G 显存上比较稳显存够可以上 32。训练日志和权重落在runs/train/expbest.pt是验证集最优last.pt是最后一轮部署优先用best.pt。训练中 loss 不降先看学习率YOLOv5 默认用余弦退火前几轮 warmup 属正常mAP 长期不动检查标注坐标是否真的归一化了——忘了除以宽高是最隐蔽的错。5. 避坑与排查五个真实踩过的坑5.1 现象torch.cuda.is_available()为 False原因装成了 CPU 版 PyTorch或驱动支持的 CUDA 版本低于 wheel 要求。解决nvidia-smi看驱动 CUDA 上限重装对应cuXXX的 torch别用默认源。5.2 现象detect 报cv2导入失败提示 libGL 缺失原因服务器无图形界面opencv-python依赖系统 GL 库。解决卸载后装opencv-python-headless或补装libgl1系统包。5.3 现象训练一开始就报类别索引越界原因data.yaml 的nc小于标注里出现的最大类别 id。解决核对标注 txt 里的首列数字把nc设为最大 id1names同步补齐。5.4 现象推理框整体偏移或尺寸异常原因--img与模型训练尺度差异过大或输入图被异常缩放。解决推理尺寸尽量贴近训练尺寸保持 32 倍数别随意拉伸原图。5.5 现象--cache后进程被系统杀掉原因数据集图片全部读入内存超出物理内存触发 OOM Killer。解决去掉--cache或改用--cache ram前先估算数据集总大小。6. 验证训练效果与一个提速技巧训练跑完不能只看 loss 曲线得用验证脚本量化。val.py会输出 mAP0.5 和 mAP0.5:0.95前者宽松后者严格工程上先看前者是否达标# 用 best.pt 在验证集上评估--task val 只评估不训练 python val.py --weights runs/train/exp/weights/best.pt \ --data data.yaml --img 416 --task val输出里重点看每类的 P精确率和 R召回率。如果某类 R 很低说明漏检多优先补该类样本而不是调阈值P 低则误检多检查背景负样本是否足够。一个我常用的提速技巧是导出 ONNX 后用 onnxruntime 推理CPU 上通常比原生 PyTorch 快一截# 导出 ONNX--dynamic 支持动态输入尺寸 python export.py --weights best.pt --include onnx --img 416 416 --dynamic导出后注意 opset 版本默认值在部分旧环境不兼容遇到算子不支持就显式加--opset 12。ONNX 推理的预处理必须和训练时一致归一化、通道顺序否则精度掉得莫名其妙——这个坑我吃过一次排查了半天才发现是 BGR 和 RGB 搞反了。从那以后我每次导出模型都强制拿同一张图跑一遍 PyTorch 和 ONNX 的结果做对比数值对得上才敢往下走。希望帮到你。本文还有配套的精品资源点击获取