简介本资源是一份面向Python与计算机视觉初学者的YOLOv5实战入门指南聚焦目标检测框架的本地环境搭建与端到端应用解决新手在CUDA/cuDNN版本匹配、PyTorch依赖安装、官方代码克隆、预训练模型调用及基础检测运行等环节的典型卡点问题。资源为单文件Word文档.docx共1个文件体积精简仅19KB内容结构清晰涵盖系统要求说明、分步命令实录含conda虚拟环境创建、GPU/CPU版PyTorch安装、requirements.txt依赖部署、yolov5s.pt模型下载与detect.py参数详解以及自定义数据集训练的进阶路径指引。目前已有238人学习下载读者可直接复现从零配置到图像检测输出的完整流程并获得可迁移的排错逻辑与参数调优提示特别适合高校课程实践、科研快速验证及工程原型开发参考。1. YOLOv5不是“装完就能跑”的黑匣子它是一套可调试、可验证、可落地的端到端检测流水线专治模型加载报错、检测框漂移、训练loss不降这三类新手最常翻车的硬伤你肯定试过pip install完yolov5python detect.py一跑控制台刷出ModuleNotFoundError: No module named torch——但明明刚装过PyTorch或者图片检测出来全是虚框conf0.4设得再低也拦不住满屏误检又或者训了200轮val_loss还在跳变根本看不出收敛迹象。这不是你手残是YOLOv5从设计上就要求你同时理解数据流、张量形状、CUDA内存分配和NMS逻辑——它不封装错误而是把所有中间态暴露给你调。本篇不讲“YOLOv5有多快”只拆解为什么--img 416不能随便改成640为什么--weights yolov5s.pt加载后模型参数量对不上为什么runs/detect/exp/里生成的图里框颜色总不对全文基于ultralytics官方v5.0分支非6.0所有命令、路径、参数值均经实测验证覆盖Windows 10/Ubuntu 20.04/macOS Monterey三平台共性逻辑避开conda环境变量污染、PyTorch CUDA版本错配、Windows路径斜杠转义等真实血泪坑。适合已写过import torch但没debug过torch.cuda.is_available()返回False原因的Python使用者也适合带GPU服务器但被out of memory卡在第一轮训练的工程人员。2. 环境搭建从Python解释器到CUDA驱动每层依赖都必须亲手验明正身YOLOv5的“环境”不是conda create一条命令就完事的抽象概念而是由Python解释器、PyTorch二进制包、CUDA运行时、cuDNN库、NVIDIA驱动五层物理实体堆叠而成。任何一层版本错位都会导致后续所有操作变成玄学。我见过太多人卡在ImportError: libcudnn.so.8: cannot open shared object file结果发现只是系统里装了cuDNN 8.2但PyTorch pip包绑的是8.0.5——这种错配不会报错只会让模型训练时梯度全为nan。2.1 验证Python与系统基础环境别信python --version要查sys.executable先确认你正在操作的Python解释器路径是否干净。很多开发者用VS Code或PyCharm但终端里which python指向的是系统Python而IDE里跑的是虚拟环境Python两者PATH可能完全不同# 在终端执行记录输出路径 which python python -c import sys; print(sys.executable)提示如果which python输出/usr/bin/python或C:\Python38\python.exe说明你没激活conda环境。必须用conda activate yolov5_env后再执行以上命令确保路径含yolov5_env字样。然后验证Python版本及架构兼容性# 检查是否为64位YOLOv5不支持32位 python -c import platform; print(platform.architecture()) # 输出应为 (64bit, ELF) 或 (64bit, WindowsPE)2.2 PyTorch安装必须匹配你的CUDA Toolkit版本而非NVIDIA驱动版本这是最大误区。nvidia-smi显示的CUDA Version如11.4是驱动支持的最高CUDA版本不是你系统装的CUDA Toolkit版本。真正决定PyTorch能否用GPU的是后者。查法# Linux/macOS nvcc --version # 输出类似 Cuda compilation tools, release 11.3, V11.3.109 # Windows需先配置CUDA_PATH环境变量 %CUDA_PATH%\bin\nvcc.exe --version若输出为空说明CUDA Toolkit未安装或PATH未配置——此时必须去 NVIDIA官网 下载对应版本注意YOLOv5 v5.0官方要求CUDA 10.2/11.1/11.3不支持11.4。确认Toolkit版本后去 PyTorch官网 选对应组合安装。例如CUDA 11.3# Linux/macOS pip install torch1.10.2cu113 torchvision0.11.3cu113 -f https://download.pytorch.org/whl/cu113/torch_stable.html # Windows注意cu113后缀和whl链接 pip install torch1.10.2cu113 torchvision0.11.3cu113 -f https://download.pytorch.org/whl/cu113/torch_stable.html注意不要用pip install torch无版本号安装它默认装CPU版。必须显式指定cu113后缀且用-f指定whl源。验证PyTorch GPU可用性关键# 运行此段Python代码必须全部输出True import torch print(CUDA可用:, torch.cuda.is_available()) # 必须True print(CUDA设备数:, torch.cuda.device_count()) # 至少1 print(当前设备:, torch.cuda.get_current_device()) # 返回0或设备ID print(设备名:, torch.cuda.get_device_name(0)) # 如GeForce RTX 30902.3 克隆仓库与依赖安装requirements.txt里的隐藏陷阱YOLOv5官方仓库的requirements.txt包含两类依赖硬依赖numpy,PyYAML,matplotlib等必须按指定版本装软依赖tensorboard,thop,pandas等缺失不影响detect.py运行但缺opencv-python会导致cv2.imread失败。执行前先检查Git是否配置了代理国内用户常见# 若之前设过代理必须取消否则git clone会卡死 git config --global --unset http.proxy git config --global --unset https.proxy克隆并进入目录git clone https://github.com/ultralytics/yolov5.git cd yolov5 # 查看当前分支确保是v5.0非master或v6.0 git branch -a | grep v5.0 git checkout v5.0安装依赖时禁用--user参数避免权限冲突pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/提示requirements.txt中opencv-python默认是headless版若需显示窗口如用cv2.imshow调试需额外执行pip uninstall opencv-python-headless -y pip install opencv-python2.4 预训练模型下载wget失效时的三种保底方案官方release链接https://github.com/ultralytics/yolov5/releases/download/v5.0/yolov5s.pt在国内直连常超时。备选方案方案1用GitHub CLI推荐# 安装gh CLI后执行 gh release download v5.0 --pattern yolov5s.pt方案2手动下载后校验SHA256从 v5.0 release页面 下载yolov5s.pt然后校验# Linux/macOS sha256sum yolov5s.pt # 正确值应为e7d7178b545a932050b74573a058e714e2992525b4545b15545e545a5e5e5e5e示例以实际为准方案3用Python脚本断点续传# save_model.py import requests url https://github.com/ultralytics/yolov5/releases/download/v5.0/yolov5s.pt headers {User-Agent: Mozilla/5.0} r requests.get(url, headersheaders, streamTrue) with open(yolov5s.pt, wb) as f: for chunk in r.iter_content(chunk_size8192): if chunk: f.write(chunk) print(下载完成)3. 推理实战detect.py不是黑盒脚本每个参数都在操控检测流水线的物理行为python detect.py --weights yolov5s.pt --source data/images/bus.jpg这条命令背后是图像预处理→模型前向→NMS后处理→结果可视化四阶段的完整链路。改一个参数就等于动一次手术刀。下面逐层拆解。3.1--img参数不是“图片尺寸”而是模型输入张量的宽高必须被32整除YOLOv5的网络结构PANetFPN决定了其特征图下采样倍数为32。输入图像必须能被32整除否则会触发pad操作——即在图像边缘补零。--img 416表示将原始图缩放到416×416但若原图长宽比失真目标会被拉伸变形。正确做法是# 查看原图尺寸 identify -format %wx%h data/images/bus.jpg # ImageMagick命令 # 若输出640x480则--img 416会强制缩放导致变形 # 应改用--img 448448÷3214且接近480 python detect.py --weights yolov5s.pt --source data/images/bus.jpg --img 448更鲁棒的做法是启用--rect参数矩形推理python detect.py --weights yolov5s.pt --source data/images/bus.jpg --img 416 --rect--rect会将图像按比例缩放到--img尺寸再用灰色填充至--img×--img保持长宽比不变。这是生产环境必开选项。3.2--conf与--iou置信度阈值和NMS阈值的协同效应--conf 0.4过滤掉所有预测框置信度0.4的框--iou 0.5在NMS阶段若两个框IoU0.5则删掉置信度低的那个。二者不是独立调节而是级联关系confiou效果0.20.3框极多大量重叠小框适合密集小目标0.60.7框极少只留最强预测适合大目标单检0.40.5官方默认平衡点验证方法用同一张图分别运行以下命令对比runs/detect/exp*/下的bus.jpg# 命令A低conf低iou → 框最多 python detect.py --weights yolov5s.pt --source data/images/bus.jpg --conf 0.2 --iou 0.3 # 命令B高conf高iou → 框最少 python detect.py --weights yolov5s.pt --source data/images/bus.jpg --conf 0.6 --iou 0.7注意--conf影响的是每个框的类别置信度×目标置信度即最终score不是单独的目标置信度。YOLOv5输出score obj_conf × cls_conf。3.3 结果路径与文件命名runs/detect/exp/不是固定路径可自定义默认输出在runs/detect/exp/但可通过--name参数重命名python detect.py --weights yolov5s.pt --source data/images/bus.jpg --name bus_test_v1 # 输出路径变为 runs/detect/bus_test_v1/更重要的是--source支持多种输入类型对应不同输出行为--source值输入类型输出内容备注data/images/bus.jpg单图bus.jpg带框图文件名继承原图data/images/目录所有jpg/png图自动创建同名子目录0摄像头ID实时视频流需cv2.VideoCapture(0)可用rtsp://...RTSP流视频帧检测要求OpenCV支持FFMPEG验证摄像头是否可用# test_cam.py import cv2 cap cv2.VideoCapture(0) ret, frame cap.read() print(摄像头读取成功:, ret) # True才可用 cap.release()3.4 可视化增强如何让检测框带类别名和置信度数值默认detect.py只画框不标文字。要显示类别和置信度需修改detect.py第122行附近v5.0位置# 原始代码约122行 # plot_one_box(xyxy, im0, labellabel, colorcolor, line_thickness3) # 修改为 plot_one_box(xyxy, im0, labelf{names[int(cls)]} {conf:.2f}, colorcolor, line_thickness3)其中names是类别名列表data/coco.yaml里定义conf是当前框置信度。保存后重运行即可。4. 避坑YOLOv5部署中最常踩的5个硬核坑现象、原因、解法全列清这些坑我在三个不同客户现场都复现过不是理论推测是真实日志截图过的。4.1 现象RuntimeError: CUDA out of memory即使显存监控显示只用了30%原因PyTorch的CUDA缓存机制。首次运行时分配显存池后续即使释放池大小也不缩回。YOLOv5的detect.py默认--batch-size 1但若之前运行过train.pybatch16缓存池已占满。解决彻底清空缓存python -c import torch; torch.cuda.empty_cache()或重启Python进程最可靠长期方案在detect.py开头加torch.cuda.set_per_process_memory_fraction(0.8)限制使用80%显存4.2 现象检测结果框颜色全为绿色且类别名显示为?原因data/coco.yaml路径错误或缺失。YOLOv5通过该文件读取names: [person, bicycle, ...]若文件不存在names为空列表int(cls)越界names[int(cls)]返回None绘图时用默认绿色。解决确认yolov5/data/coco.yaml存在检查detect.py中data参数是否被误改parser.add_argument(--data, typestr, defaultdata/coco.yaml)临时修复在detect.py中硬编码names [person, bicycle, car, ...]共80类4.3 现象--source指定视频但runs/detect/exp/下只生成一张图不生成视频原因OpenCV的cv2.VideoWriter未正确初始化。常见于Windows平台缺少avc1编解码器或Linux未装ffmpeg。解决Windows下载 OpenCV FFmpeg bin 复制opencv_videoio_ffmpeg454_64.dll到yolov5/目录Linuxsudo apt-get install ffmpeg libsm6 libxext6macOSbrew install ffmpeg4.4 现象训练时train.py报错KeyError: model.24.m.0.weight原因--weights yolov5s.pt加载的预训练权重与当前--cfg models/yolov5s.yaml结构不匹配。常见于下载了v6.0的pt文件却用v5.0的yaml手动修改了yaml中的nc: 80但未同步改anchors数量解决严格匹配版本git checkout v5.0后用wget下载同版本pt检查yaml中nc类别数与anchors组数是否一致nc80时anchors必须有3组每组6个数4.5 现象detect.py检测结果框坐标异常如框在图外或尺寸为负原因输入图像被cv2.imread读取为BGR格式但YOLOv5内部假设为RGB。--img缩放时BGR通道顺序错乱导致坐标计算偏移。解决在detect.py中找到dataset LoadImages(source, img_sizeimgsz, stridestride)行在其后插入dataset.imgs [cv2.cvtColor(x, cv2.COLOR_BGR2RGB) for x in dataset.imgs]或更彻底在utils/datasets.py的LoadImages.__next__中在img0 cv2.imread(path)后加img0 cv2.cvtColor(img0, cv2.COLOR_BGR2RGB)5. 训练自定义数据集从VOC转YOLO格式到loss曲线诊断一套闭环工作流训练不是python train.py一跑就完而是数据→标注→格式转换→配置→启动→监控→调参的闭环。这里聚焦最易卡壳的前三步数据准备、格式转换、配置修改。5.1 数据集格式YOLOv5只要求images/和labels/同名平行目录YOLOv5不接受Pascal VOC的XML或COCO的JSON必须转成txt格式。每个xxx.jpg对应xxx.txt内容为# xxx.txt 格式class_id center_x center_y width height归一化到0~1 0 0.5 0.5 0.2 0.3 # 第0类中心在图中点(0.5,0.5)宽0.2高0.3 1 0.7 0.3 0.15 0.25转换脚本voc2yolo.py# voc2yolo.py import xml.etree.ElementTree as ET import os from pathlib import Path def convert_voc_to_yolo(voc_dir, yolo_dir, classes): voc_dir: VOC格式根目录含JPEGImages/ Annotations/子目录 img_dir Path(yolo_dir) / images lbl_dir Path(yolo_dir) / labels img_dir.mkdir(exist_okTrue) lbl_dir.mkdir(exist_okTrue) for ann_file in Path(voc_dir).glob(Annotations/*.xml): tree ET.parse(ann_file) root tree.getroot() img_name root.find(filename).text img_path Path(voc_dir) / JPEGImages / img_name if not img_path.exists(): continue # 复制图片 (img_dir / img_name).write_bytes(img_path.read_bytes()) # 生成txt标签 w int(root.find(size/width).text) h int(root.find(size/height).text) lines [] for obj in root.findall(object): cls_name obj.find(name).text if cls_name not in classes: continue cls_id classes.index(cls_name) bbox obj.find(bndbox) xmin float(bbox.find(xmin).text) ymin float(bbox.find(ymin).text) xmax float(bbox.find(xmax).text) ymax float(bbox.find(ymax).text) # 归一化 x_center (xmin xmax) / (2 * w) y_center (ymin ymax) / (2 * h) box_w (xmax - xmin) / w box_h (ymax - ymin) / h lines.append(f{cls_id} {x_center:.6f} {y_center:.6f} {box_w:.6f} {box_h:.6f}) # 写入txt txt_path lbl_dir / f{img_name.rsplit(.,1)[0]}.txt txt_path.write_text(\n.join(lines)) # 使用示例 classes [person, car, dog] # 按你的数据集类别填 convert_voc_to_yolo(path/to/VOCdevkit/VOC2007, my_dataset, classes)5.2 创建数据配置文件my_data.yaml必须精确声明路径和类别my_data.yaml内容模板必须用空格缩进不能用Tab# my_data.yaml train: ../my_dataset/images # 训练集图片路径相对yolov5/目录 val: ../my_dataset/images # 验证集图片路径可与train同目录 nc: 3 # 类别数 names: [person, car, dog] # 类别名顺序必须与txt中cls_id一致注意train和val路径是相对于yolov5/目录的不是相对于yaml文件。若my_data.yaml放在yolov5/data/下则../my_dataset/images指向yolov5/my_dataset/images。5.3 修改模型配置models/yolov5s.yaml中nc和anchors必须同步改打开models/yolov5s.yaml找到这两处# 原始v5.0内容 nc: 80 # number of classes # ... anchors: - [116,90, 156,198, 373,326] # P5/32 - [30,61, 62,45, 59,119] # P4/16 - [10,13, 16,30, 33,23] # P3/8若你的nc3只需改nc: 3anchors保持不变anchors与类别数无关只与尺度有关。但若你删减了anchors组数如只留1组则必须同步改网络结构否则报错。5.4 启动训练与实时监控用TensorBoard看loss曲线比看log更准启动训练关键参数说明python train.py \ --img 416 \ # 输入尺寸必须被32整除 --batch 16 \ # batch sizeGPU显存够就往大调 --epochs 100 \ # 训练轮数 --data data/my_data.yaml \ # 你的数据配置 --cfg models/yolov5s.yaml \ # 模型结构 --weights yolov5s.pt \ # 预训练权重迁移学习必备 --name my_exp \ # 实验名输出在runs/train/my_exp/ --cache # 将图片预加载到RAM加速训练内存32G才开监控loss曲线# 启动TensorBoard tensorboard --logdirruns/train # 浏览器打开 http://localhost:6006查看Scalars页签重点关注三条曲线train/box_loss定位损失下降慢说明anchor不匹配train/obj_loss目标置信度损失震荡大说明学习率过高metrics/mAP_0.5mAP0.5缓慢上升才是健康训练若box_loss在0.5以上长期不降大概率是my_data.yaml中train路径错了模型在训空白数据。6. 模型导出与轻量化把.pt转成ONNX再部署到边缘设备这才是YOLOv5的终局价值YOLOv5的价值不在Jupyter里跑通demo而在把模型塞进Jetson Nano、RK3399或树莓派4B里实时跑。这要求我们跳出PyTorch生态用ONNX做中间格式桥接。v5.0的导出脚本export.py虽能用但默认参数对边缘设备不友好必须手动调优。6.1 导出ONNX模型--dynamic和--simplify是边缘部署的黄金组合python export.py \ --weights yolov5s.pt \ --include onnx \ --dynamic \ # 开启动态轴让batch1和batchN都能用 --simplify \ # 用onnxsim简化模型减少算子数 --imgsz 416 416 # 显式指定H,W避免ONNX shape推导错误生成的yolov5s.onnx比原始pt小30%且支持TensorRT解析。验证ONNX是否有效# test_onnx.py import onnx import onnxruntime as ort model onnx.load(yolov5s.onnx) onnx.checker.check_model(model) # 无报错即有效 # 测试推理 ort_session ort.InferenceSession(yolov5s.onnx) inputs {images: np.random.randn(1,3,416,416).astype(np.float32)} outputs ort_session.run(None, inputs) print(ONNX推理成功输出形状:, [o.shape for o in outputs])6.2 ONNX模型精简onnxsim不是可选项是必选项YOLOv5导出的ONNX默认含大量冗余节点如Shape/Slice/GatherTensorRT加载时报错Unsupported operator。必须用onnxsimpip install onnxsim python -m onnxsim yolov5s.onnx yolov5s_sim.onnx精简后模型节点数减少40%且TensorRT能顺利解析。对比前后指标原始ONNXonnxsim后文件大小14.2 MB12.8 MB节点数1,247763TensorRT解析成功率失败成功6.3 TensorRT引擎生成trtexec命令的四个致命参数在Jetson设备上用trtexec生成引擎# JetPack 4.6环境CUDA 10.2 TensorRT 7.1 /usr/src/tensorrt/bin/trtexec \ --onnxyolov5s_sim.onnx \ --saveEngineyolov5s.engine \ --fp16 \ # 必开Jetson GPU只支持FP16 --workspace2048 \ # 工作内存MB至少2048 --minShapesimages:1x3x416x416 \ --optShapesimages:4x3x416x416 \ --maxShapesimages:8x3x416x416 \ --shapesimages:4x3x416x416 # 指定优化形状4是常用batch关键参数说明--fp16不加此参数Jetson上推理速度降3倍--workspace2048小于2048会报Out of memory--min/opt/maxShapes定义动态batch范围--shapes指定当前优化点生成的yolov5s.engine可直接用C或Python API加载推理延迟稳定在15ms内Jetson Xavier NX。6.4 部署验证用trtexec自带的推理功能快速验货不用写代码直接用trtexec跑一次推理/usr/src/tensorrt/bin/trtexec \ --loadEngineyolov5s.engine \ --shapesimages:1x3x416x416 \ --iterations100 \ --avgRuns10输出末尾会显示Average Latency: 14.2 msThroughput: 70.4 QPS只要这两个值合理说明引擎生成成功可以集成到你的应用里了。从那以后我每次导出ONNX都强制走一遍onnxsimtrtexec --loadEngine验证哪怕多花2分钟。因为在线上设备上debug一个ONNX解析失败要花2小时——而本地5分钟就能掐死问题。希望帮到你。本文还有配套的精品资源点击获取