简介这份文档面向具备一定Python与计算机视觉基础的入门级研究人员和工程技术人员系统讲解YOLOv5目标检测框架的本地环境搭建与基本检测流程。内容涵盖操作系统、Python版本、CUDA与cuDNN等系统要求说明Anaconda虚拟环境创建、PyTorch安装、官方源码克隆与依赖库配置并给出预训练模型下载及detect.py示例检测的完整命令参数解析最后简要介绍基于自定义数据集的模型训练与参数调整思路。资源包为1个docx文档大小约19KB结构紧凑便于按步骤对照操作。目前已有238人学习下载适合初次接触YOLOv5、希望快速跑通目标检测实例并了解定制训练入口的读者既可作为理论教学材料也可供实际工程项目参考。1. 从一张误检的工地照片说起YOLOv5 到底能帮你解决什么上周帮朋友看他工地的安全帽检测模型把夕阳下的一顶黄色安全帽识别成了 0.31 置信度的“鸟”。这不是模型笨是输入尺寸和置信度阈值没调对。YOLOv5 就是这样一个东西它把目标检测拆成“一次前向传播就出框”的回归问题速度快到能在普通笔记本上跑实时精度又足够应付大多数工业场景。你手里这份资源本质上是一套从零搭环境到跑通检测、再到训练自己数据集的完整路径。它适合谁刚接触计算机视觉、想用 Python 和 PyTorch 快速出结果的人手里有几百张标注图、想验证能不能落地的工程师以及被 YOLOv5 网络结构图绕晕、需要一份能照着敲的配置清单的从业者。别指望它教你反向传播推导但它能让你在半天内看到自己的图片被框出来。2. 环境搭建CUDA、cuDNN 与 PyTorch 的版本对齐2.1 为什么版本对齐比安装本身更重要YOLOv5 跑不起来十次有八次是 PyTorch 和 CUDA 版本打架。你装完torch.cuda.is_available()返回 False或者训练到一半报CUDA error: no kernel image is available都是这个原因。常见做法是先确定显卡驱动支持的 CUDA 最高版本再选 PyTorch 官方提供的对应轮子。比如驱动显示 CUDA 11.4你就装 cu113 的 torch别硬上 cu116。cuDNN 不用单独折腾PyTorch 的 conda 包或 pip 轮子已经绑好了匹配版本。我一般会先跑一条命令确认底线nvidia-smi看右上角CUDA Version: 11.4这是驱动能支持的上限不是你已经装了 11.4。然后去 PyTorch 官网找对应命令。如果你用 Anaconda虚拟环境能帮你把不同项目的依赖隔开避免今天装 YOLOv5 明天装 YOLOv8 时互相覆盖。conda create --name yolov5_env python3.8 conda activate yolov5_envPython 3.8 是 YOLOv5 官方 requirements 里验证最充分的版本3.6 能跑但有些依赖包已经不再更新3.10 以上偶尔遇到torchvision算子不兼容。这一步别图省事用 base 环境后面你会感谢自己。2.2 安装 PyTorch 与依赖CPU 和 GPU 的分岔路装 PyTorch 之前先问自己有没有 NVIDIA 显卡有就走 CUDA 路线没有就 CPU 版本别纠结。CPU 版本跑推理慢但能跑训练基本劝退。GPU 版本安装命令长这样# CUDA 11.3 对应的 PyTorch 安装命令 pip install torch torchvision --extra-index-url https://download.pytorch.org/whl/cu113--extra-index-url是指定 PyTorch 自己的轮子仓库不加的话 pip 会去默认源找可能下到 CPU 版。装完立刻验证import torch print(torch.__version__) # 应输出 1.x.xcu113 print(torch.cuda.is_available()) # 应输出 True print(torch.cuda.get_device_name(0)) # 显示你的显卡型号如果cuda.is_available()是 False先别急着重装检查三件事驱动版本是否够、装的是不是cu后缀的 torch、虚拟环境有没有激活错。确认 PyTorch 没问题后克隆仓库并装依赖git clone https://github.com/ultralytics/yolov5.git cd yolov5 pip install -r requirements.txtrequirements.txt里锁定了numpy、opencv-python、matplotlib等版本别手动升级其中某一个否则可能触发numpy版本冲突导致ImportError。如果 pip 下载慢可以临时换国内镜像源但注意镜像源同步可能有延迟遇到包找不到就换回官方源。2.3 预训练模型下载与目录结构确认YOLOv5 提供 s、m、l、x 四个尺度的预训练模型s 最小最快x 最准最慢。第一次跑通建议用yolov5s.pt文件大概 14MB。下载方式有两种脚本会自动从 GitHub Releases 拉或者你手动下好放到项目根目录。# 手动下载 yolov5s.pt如果自动下载失败 wget https://github.com/ultralytics/yolov5/releases/download/v5.0/yolov5s.pt下载完确认目录结构yolov5s.pt和detect.py在同一级。别把它塞进models/文件夹--weights参数默认从当前目录找。如果你用的是 Windows没有wget直接浏览器下载后拖进项目根目录就行。这一步的坑在于有些人克隆的是最新 main 分支但预训练模型是 v5.0 的版本不匹配会报KeyError: model。稳妥做法是克隆时指定 taggit clone -b v5.0 https://github.com/ultralytics/yolov5.git。3. 跑通第一次检测detect.py 的参数怎么设才不翻车3.1 从一张图片开始最小可运行命令环境好了模型有了现在跑一张图看看。假设你有一张test.jpg在项目根目录python detect.py --weights yolov5s.pt --source test.jpg --img 416 --conf 0.4 --iou 0.5这条命令的意思是用yolov5s.pt权重检测test.jpg输入网络前把图片缩放到 416×416只保留置信度大于 0.4 的框NMS 的 IoU 阈值设为 0.5。跑完结果在runs/detect/exp/下。第一次跑会看到终端打印每张图的检测耗时和类别如果输出全是person但图里没人别慌往下看参数部分。--img不是越大越好。416 适合快速验证640 是默认值精度更高但显存占用翻倍。如果你显卡只有 4GB 显存跑 640 的yolov5s推理没问题但训练会 OOM。--conf设太低会出大量误检设太高会漏掉小目标。工地安全帽那种场景0.4 到 0.5 之间比较稳。--iou控制重叠框的合并力度0.5 是通用值如果发现同一个物体被框了两次降到 0.45 试试。3.2 批量检测与视频流source 参数的多种写法--source不只能接单张图。接文件夹它会遍历里面所有图片接0它会调用摄像头接视频文件路径它逐帧检测并输出新视频。# 检测整个文件夹 python detect.py --weights yolov5s.pt --source ./images/ --img 640 --conf 0.5 # 调用本机摄像头按 q 退出 python detect.py --weights yolov5s.pt --source 0 --img 640 # 检测视频并保存结果 python detect.py --weights yolov5s.pt --source demo.mp4 --img 640 --conf 0.4摄像头模式在服务器上跑会报Cannot open camera因为没图形界面这是正常的。视频检测的输出帧率取决于你的 GPU用yolov5s在 1080Ti 上大概 30FPSCPU 上可能只有 2FPS。如果你要做树莓派 4B 部署建议先量化模型再跑否则帧率感人。批量检测时注意--nosave可以只打印结果不存图省磁盘。3.3 结果解读runs/detect/exp 里有什么每次运行detect.py它会在runs/detect/下新建exp、exp2、exp3……依次递增。里面有你检测后的图片或视频文件名和原文件一致。图片上会画好框和类别标签标签格式是类别 置信度。如果你发现框的位置偏了大概率是--img和原图长宽比不一致导致的 letterbox 填充问题YOLOv5 会自动处理但极端长宽比下会有偏差。终端还会打印类似1/1: 0.123s, 8.1 FPS的信息这是纯推理时间不包括前后处理。如果你要评估模型在特定数据集上的 mAP得用test.py而不是detect.py。detect.py只负责可视化不输出精度指标。这一点新手容易混淆拿detect.py的结果去算准确率是不准的。4. 训练自己的数据集从标注格式到超参数调整4.1 YOLO 格式标注一张图一个 txt 的规矩YOLOv5 不认 XML 或 JSON它要的是每张图片对应一个同名.txt文件每行一个物体格式为类别索引 中心x 中心y 宽度 高度所有坐标都归一化到 0 到 1 之间。比如一张 640×480 的图里有个框在 (100, 200) 到 (300, 400)中心点是 (200, 300)宽 200高 200归一化后就是0 0.3125 0.625 0.3125 0.4167。常见做法是用labelImg或CVAT标注后导出 YOLO 格式。如果你手里是 COCO 的 JSON需要转换脚本。我一般会写个简单的 Python 脚本检查标注文件有没有越界或空文件import os label_dir datasets/labels/train for txt in os.listdir(label_dir): path os.path.join(label_dir, txt) if os.path.getsize(path) 0: print(f空标注文件: {txt}) continue with open(path) as f: for i, line in enumerate(f): parts line.strip().split() if len(parts) ! 5: print(f{txt} 第{i1}行格式错误: {line}) continue cls, x, y, w, h map(float, parts) if not (0 x 1 and 0 y 1 and 0 w 1 and 0 h 1): print(f{txt} 第{i1}行坐标越界: {line})这个脚本能帮你提前发现标注问题别等到训练时 loss 不降才回头查。空标注文件会导致训练时该图被跳过如果大量为空等于白标。4.2 数据集 yaml 配置路径、类别数与下载脚本YOLOv5 用 yaml 文件描述数据集。你需要在data/下新建一个mydata.yaml# 数据集配置示例 path: ./datasets/mydata # 数据集根目录 train: images/train # 训练集图片相对路径 val: images/val # 验证集图片相对路径 nc: 3 # 类别数 names: [helmet, vest, person] # 类别名称顺序要和标注索引一致nc必须等于names的长度且标注里的类别索引从 0 开始对应names的顺序。如果你把helmet写成索引 1但names里helmet在第一个训练就会学错。path可以是绝对路径但相对路径更利于迁移。验证集不能和训练集用同一批图否则 mAP 虚高实际部署翻车。4.3 启动训练batch、epochs 与 cache 的取舍配置好了跑训练命令python train.py --img 416 --batch 16 --epochs 300 --data data/mydata.yaml --cfg models/yolov5s.yaml --weights yolov5s.pt --cache--weights yolov5s.pt表示从预训练权重开始微调不是从零训练。从零训练需要几千张图加几百轮微调通常 100 到 300 轮就收敛。--batch 16是每次喂给网络的图片数显存不够就降到 8 或 4但 batch 太小会导致 BN 层统计不准训练不稳定。--cache把图片缓存到内存加速读取但如果数据集超过 8GB内存会爆这时候去掉--cache或者用--cache disk。训练过程中看runs/train/exp/下的results.csv重点关注mAP0.5和box_loss。如果box_loss震荡不降检查学习率是不是太大如果mAP一直 0检查标注类别索引和 yaml 是否对齐。300 轮不是硬性规定看验证集 mAP 不再提升就可以停YOLOv5 默认会保存最好的和最后的权重。5. 避坑与排查那些让我重装三次环境的问题5.1 现象torch.cuda.is_available()返回 False原因最常见的是装成了 CPU 版 PyTorch或者驱动版本低于 PyTorch 要求的 CUDA 版本。也有小概率是虚拟环境没激活对你在 base 里装了 GPU 版但跑代码时用的是另一个环境。解决先pip list | grep torch看版本号有没有cu后缀。没有就卸载重装指定--extra-index-url。然后nvidia-smi确认驱动版本对照 PyTorch 官网的 CUDA 版本要求。如果驱动太老去显卡官网更新驱动别在 conda 里折腾cudatoolkit那个和系统驱动是两回事。5.2 现象训练时 loss 变成 NaN原因学习率过大、标注坐标越界、或者 batch 里有损坏图片。YOLOv5 默认学习率是 0.01对某些小数据集偏大。解决先跑一遍第 4.1 节的标注检查脚本排除坐标问题。然后把--lr0降到 0.001 试试。如果还 NaN检查图片有没有全黑或全白的用opencv读一下像素均值。另外--batch太小也会导致 NaN至少设 8。5.3 现象检测结果框位置偏移或框不全原因--img和原图长宽比差异太大letterbox 填充后坐标映射回原图时出现偏差。或者--conf设太高小目标被过滤。解决把--img设成 640 或 1280尽量接近原图分辨率。小目标检测把--conf降到 0.2 到 0.3同时--iou提到 0.6 让重叠框保留更多。如果还不行考虑用yolov5m或yolov5l小目标对大模型更友好。5.4 现象runs/detect/exp目录找不到原因YOLOv5 不同版本输出路径不一样v5.0 是runs/detect/expv6.0 以后是runs/detect/exp但如果你在别的目录跑脚本相对路径会变。解决跑完命令后终端会打印Results saved to runs/detect/exp直接复制那个路径。如果终端没打印检查detect.py有没有被修改过。最稳的办法是加--project ./my_results --name test1自己指定输出目录。5.5 现象pip 安装 requirements 时卡在opencv-python原因opencv-python轮子较大国内网络下载慢或超时。或者 Python 版本太新没有对应轮子。解决单独装opencv-python-headless它不带 GUI 依赖体积小很多服务器上够用。命令是pip install opencv-python-headless然后在requirements.txt里把opencv-python注释掉。如果还慢换清华源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple。6. 进阶技巧用 test.py 验证 mAP 与模型导出训练完别急着部署先用test.py在验证集上跑一遍 mAP确认模型不是只记住了训练集。命令和detect.py类似但输出的是精度指标python test.py --weights runs/train/exp/weights/best.pt --data data/mydata.yaml --img 416 --batch 16 --task val--task val表示只验证不测试--task test会在测试集上跑。终端会打印每个类别的P、R、mAP0.5、mAP0.5:0.95。如果mAP0.5高但mAP0.5:0.95低说明框的位置不够准考虑增加训练轮数或调--img到 640。如果某个类别P很低检查那个类别的标注是不是漏标或错标。验证通过后导出模型给部署用。YOLOv5 支持导出 ONNX、TorchScript、CoreML 等格式# 导出 ONNXopset 12 兼容性较好 python export.py --weights runs/train/exp/weights/best.pt --include onnx --opset 12 --img 416 # 导出 TorchScript适合 C 调用 python export.py --weights runs/train/exp/weights/best.pt --include torchscript --img 416导出 ONNX 后可以用onnxruntime推理速度比 PyTorch 快 20% 到 30%。如果你要部署到 RK3568 或树莓派导出 ONNX 后再走量化工具链。注意--img要和训练时一致否则精度掉点。导出完用onnxruntime跑一张图对比结果确认和 PyTorch 输出一致再上线。从那以后我每次训练完都强制走一遍test.py不看到 mAP 数字不部署。希望帮到你。本文还有配套的精品资源点击获取