企业官网建设流程全解析

简介：这份文档面向具备一定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 python=3.8 conda activate yolov5_env

Python 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.x+cu113 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.txt

requirements.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'。稳妥做法是克隆时指定 tag：git 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 上大概 30FPS，CPU 上可能只有 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} 第{i+1}行格式错误: {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} 第{i+1}行坐标越界: {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，重点关注mAP@0.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/exp，v6.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、mAP@0.5、mAP@0.5:0.95。如果mAP@0.5高但mAP@0.5:0.95低，说明框的位置不够准，考虑增加训练轮数或调--img到 640。如果某个类别P很低，检查那个类别的标注是不是漏标或错标。

验证通过后，导出模型给部署用。YOLOv5 支持导出 ONNX、TorchScript、CoreML 等格式：

# 导出 ONNX，opset 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 数字不部署。希望帮到你。

本文还有配套的精品资源，点击获取