企业官网建设流程全解析

1. 先聊聊"从入门到入狱"这个标题：YOLOv5到底学的是什么

1.1 一次目标检测任务让我决定彻底搞懂它

我最初接触到 YOLOv5 是因为一个很实际的需求：要给厂里一条流水线上的工件做数量统计和位置标定。当时团队里有人提议用传统图像处理，但零件种类一多、光照一变，阈值怎么调都崩。后来有人甩过来一句"试试 YOLOv5 吧"，我就从一个只会 pip install 的小白，硬着头皮走上了自学目标检测的路。

这篇笔记就是我从零开始跑通 YOLOv5 完整流程的记录：环境配置、官方权重推理、标注自己的数据集、训练、评估、导出模型。如果你也是刚接触深度学习、想在真实项目里用 YOLOv5 训练自己的数据集，这篇笔记应该能帮你少走不少弯路。标题里"从入门到入狱"是句调侃，意思是 YOLOv5 功能确实强大，但乱用、滥用、错用，轻则训练出一堆废模型浪费算力，重则把不合格的模型放到不该放的场景里，那真就离"出事"不远了。

1.2 "功能强大不要乱用"不是开玩笑

先说清楚 YOLOv5 能做什么。它是一个单阶段目标检测模型，核心任务就是"在图片里找到物体并框出来"，可以检测人、车、动物、缺陷、工件、农作物，几乎任何你手头有图片数据的东西。它速度快、精度高、生态成熟，网上教程一抓一大把，看起来"轻轻松松就能训练一个自己的检测器"。

但正因为门槛低，才更容易出问题。

• 有人拿它做人脸识别相关的敏感应用，不考虑合规性；
• 有人拿它训练自动抢票、作弊外挂之类的工具，这已经不只是"技术滥用"的问题了；
• 有人完全不懂数据集怎么来，爬了一堆版权不明的图片就开训，模型上线就被告；
• 还有人拿 5 张图就敢训"生产级模型"，结果误检率奇高，直接背锅。

我"入狱"这两个字不是真的指坐牢，而是想表达：如果你只学会了操作、没学会判断"什么场景能用、什么数据能训、什么后果要承担"，那翻车是迟早的事。所以这篇笔记不光是教你怎么跑通流程，也会在关键节点提醒你哪些地方别乱来。

1.3 这篇笔记覆盖什么、不覆盖什么

覆盖的内容包括：

• YOLOv5 环境搭建（CPU 和 GPU 都讲）
• 官方权重推理（图片、视频、摄像头实时检测）
• 用 labelImg 标注自己的图片数据
• 组织数据集目录结构、编写 data.yaml 配置文件
• 完整跑一次训练并理解核心训练参数
• 评估模型效果、导出 ONNX 模型
• 我在实操中遇到过的几个坑和排查思路

不覆盖的内容包括：YOLOv5 内部每一层的详细数学推导、自定义网络结构修改、分布式多机训练、模型量化部署到边缘设备的全流程。这些是进阶内容，后面我的笔记系列里可能会单独写。

2. 环境准备：先把"地基"打牢，后面才不返工

2.1 硬件与软件版本匹配是最大的坑

我第一次装 YOLOv5 环境，照着网上的教程一顿操作，结果 torch 版本和 CUDA 版本对不上，import torch 时说 CUDA unavailable，折腾了整整一个晚上。后来我总结出一条经验：先确定你机器的硬件，再倒推装什么版本的驱动、CUDA、PyTorch，顺序反了就是无限踩坑。

先看你的显卡：

• NVIDIA 显卡：建议用 GPU 训练，速度比 CPU 快几十倍不止；
• 没有 NVIDIA 显卡或者用 Mac：也能跑，但只能用小模型、小数据集做学习验证，训练 100 轮的 COCO128 都要等很久；
• 纯 CPU 环境：强烈建议先装 CPU 版 PyTorch，别去折腾 CUDA。

一个我自己试过的稳定组合是这样的：

判断 CUDA 和 PyTorch 是否匹配的最快方法：去 PyTorch 官网的 Get Started 页面，选择你的系统、安装方式、CUDA 版本，它会直接生成对应的安装命令。不要自己去网上乱找 pip 命令。

2.2 使用 conda 创建独立环境

我强烈建议用 conda 创建一个独立的虚拟环境，不要直接装在系统 Python 里。原因是 YOLOv5 的依赖项跟其他项目经常冲突，独立环境出问题了直接删掉重来，不污染系统。

# 创建环境 conda create -n yolov5 python=3.9 -y # 激活环境 conda activate yolov5 # 安装 PyTorch（以 CUDA 11.8 为例） pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 # 验证 PyTorch 是否能用 GPU python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

如果输出2.x.x+cu118 True，说明 GPU 版本可用。如果显示False，先别急着往下走，检查驱动版本和 CUDA 是否装对。

2.3 拉取 YOLOv5 源码并安装依赖

YOLOv5 的代码托管在 GitHub 上，使用 git 拉取：

git clone https://github.com/ultralytics/yolov5 cd yolov5 pip install -r requirements.txt

这里有个细节：requirements.txt里安装的依赖包含torch和torchvision。如果你之前已经手动装了 GPU 版 PyTorch，建议在安装 requirements 时加一个--no-deps参数跳过重装，或者直接注释掉 requirements 里的 torch 那几行，否则 pip 可能会把 GPU 版覆盖成 CPU 版。这是我踩过的第二个坑，安装完发现 torch 变成 CPU 版了。

验证环境是否正常：

python detect.py --source data/images/bus.jpg --weights yolov5s.pt

如果能在runs/detect/exp下看到带框的 bus 图片，说明整个环境已经通了。注意第一次运行会自动下载yolov5s.pt权重文件，大概 14MB 左右，如果下载慢可以考虑手动下载放到项目根目录。

3. 第一天实战：用官方权重跑通检测流程

3.1 官方权重怎么选

YOLOv5 官方提供了 n/s/m/l/x 五个尺度的预训练权重，全部是在 COCO 数据集上训练好的，能检测 80 类常见物体（人、汽车、猫、狗、杯子、椅子等）。

第一次跑通流程，建议用yolov5s.pt，速度、精度、显存占用都适中。我自己的经验是：不要一上来就追求 x 模型，先用 s 把全流程跑通，后面再换大模型提升精度，这样排查问题会容易很多。

3.2 detect.py 参数逐个拆解

detect.py是 YOLOv5 的推理脚本，核心参数如下：

python detect.py \ --weights yolov5s.pt \ # 权重文件路径 --source data/images/bus.jpg \ # 输入图片 --conf-thres 0.25 \ # 置信度阈值，低于该值的目标会被过滤 --iou-thres 0.45 \ # NMS 的 IoU 阈值，控制重叠框的合并 --img 640 \ # 推理尺寸 --device 0 \ # GPU 设备号，CPU 用 --device cpu --save-txt \ # 同时保存 txt 标注文件 --classes 0 2 \ # 只检测指定类别（COCO 的类别索引）

参数含义不难理解，但有两个容易被忽略的点：

• --conf-thres设太低（比如 0.1）会产生大量误检框，设太高（比如 0.8）会漏检。实际项目中应该先在测试集上跑一遍，观察置信度分布再定阈值。
• --img影响检测精度和速度的平衡。输入尺寸越大，小目标越容易检到，但推理越慢。一般 640 是默认值，如果小目标很多，可以试试 1280，显存要相应加大。

--source参数非常灵活，支持图片、目录、视频、摄像头、网络流等各种输入。传 URL 时要用引号包住：

python detect.py --weights yolov5s.pt --source "https://ultralytics.com/images/zidane.jpg"

3.3 从单张图片到视频流

跑通单张图片后，可以试试视频和摄像头：

# 视频文件 python detect.py --weights yolov5s.pt --source test.mp4 # 摄像头（0 表示默认摄像头） python detect.py --weights yolov5s.pt --source 0

视频检测的本质是逐帧推理，CPU 上跑 640 尺寸的视频帧率会很低，大概只有几帧每秒。GPU 上跑会好很多，但也到不了实时。如果要做实时摄像头检测，建议用yolov5n或yolov5s加上--half参数开启 FP16 推理。

这里有个体验上的小建议：第一次跑视频时，输出结果会保存在runs/detect/expN目录里，每张图片/每帧都不会覆盖之前的输出结果，这是 YOLOv5 的一个细节设计——每次运行自动新建 exp 目录，方便对比不同参数的效果。

4. 从"会用"到"懂用"：YOLOv5 结构和原理速览

4.1 网络骨架、颈部、检测头的关系

这个部分我不打算堆公式，但完全不懂原理去调参，跟摸黑走夜路没区别。YOLOv5 的网络结构可以理解成三个部分：Backbone（骨干网络）、Neck（颈部）、Head（检测头）。

• Backbone（CSPDarknet）负责提取图像特征。图片输入后会经过一系列卷积和下采样，从原始像素变成多尺度的特征图，越往后特征图越小但语义信息越丰富；
• Neck（PANet）负责把不同尺度的特征融合。小物体需要浅层的细节信息，大物体需要深层的语义信息，PANet 通过自顶向下和自底向上的路径把两者结合起来；
• Head负责输出最终结果，包括每个预测框的位置、尺寸、类别概率和置信度。

YOLOv5 的输出有三个尺度，对应检测大、中、小三种目标。如果你用export.py导出模型后再用 Netron 查看 ONNX 图，能看到三个输出头，这就是为什么 YOLOv5 对小目标有一定检测能力的原因。

4.2 三种尺寸模型的选择逻辑

很多新手会问：训练自己的数据集，到底选哪个规模？我的建议是：

1. 如果数据集比较小（几百张到一两千张），优先用 s 或 n。模型参数量越大，过拟合的风险越高；
2. 如果数据集充分（5000 张以上）且目标多是中小物体，可以上 m 或 l；
3. 先跑通一次完整训练，用 s 模型看 loss 能不能收敛、验证集的指标大概什么水平，再决定要不要换更大的模型。

用 x 模型跑小数据集，结果往往不如 s 模型，这就是典型的"功能强大不要乱用"——不是所有场景都需要大模型。

4.3 Mosaic 数据增强为什么在训练里至关重要

训练 YOLOv5 时默认开启 Mosaic 增强，原理是把 4 张训练图片随机缩放后拼成一张新图片，等于用一张图同时让模型看到更多目标、不同尺度、不同背景。这能显著提升小目标检测能力，也让模型对遮挡更鲁棒。

但 Mosaic 也不是没缺点。如果数据集本身分布不均匀（比如某类目标特别多），拼图可能会让模型学到错误的类别关联。我在一个项目中就发现，Mosaic 增强导致模型把"座椅"和"人"绑定了，后来在hyp.scratch-low.yaml里把mosaic从 1.0 降到 0.5 才改善。

4.4 训练时"数据被喂了几遍"是什么意思

初学时会经常看到"epoch"这个词，它指的是整个训练集被完整遍历的次数。比如你有 100 张训练图片，batch size 设为 16，那么一个 epoch 就是把这 100 张图片分 7 批（100/16，向上取整）喂给模型。

注意，epoch和batch是两个经常被混淆的概念：

• epoch：完整过一遍数据集；
• batch size：一次喂给模型多少张图；
• iterations/step：一个 epoch 内更新的次数（等于训练集图片数/batch size，向上取整）。

YOLOv5 的日志里显示的 Epoch、GPU_mem、box_loss、obj_loss、cls_loss 等指标，前 50 个 epoch 主要看 loss 是否在下降，后面再看验证集的 mAP 是否上升。一次训练几百轮，等于数据被喂了几百遍，模型会逐渐记住数据里的特征模式。

5. 训练自己的数据集：绕不开的脏活累活

5.1 数据采集与标注工具选择

自己训练前先要搞清楚：你的数据从哪里来？这个环节最容易被忽略，但数据质量直接决定模型上限。

数据采集的原则：

• 尽量在真实部署场景中采集，模拟场景训出来的模型到真实场景往往精度暴跌；
• 覆盖尽量多的情况：不同光照、不同角度、不同距离、不同遮挡、不同背景；
• 每个类别至少 1000 张以上（简单场景可以少一点，复杂场景建议更多），太少的话模型很容易过拟合；
• 类别不要一开始就搞很多，建议先做 1 到 3 类的试点项目，跑通后再扩展。

标注工具推荐两个：

我平时主要用 labelImg。安装简单，标注完保存为 YOLO 格式，会自动生成与图片同名的.txt文件。

pip install labelImg labelImg # 打开后记得把保存格式切换为 YOLO

标注 BTW 几个操作技巧：

• 先设置默认保存目录（自动保存），否则标完 50 张忘了保存就白干了；
• 打开"自动保存"和"单类模式"可以大幅加快单类别目标的标注速度；
• 框尽量紧贴目标边缘，但不要把关键特征切掉。

5.2 数据集目录结构与 data.yaml 配置

YOLOv5 训练要求的数据集目录结构如下：

dataset/ ├── images/ │ ├── train/ # 训练集图片 │ └── val/ # 验证集图片 ├── labels/ │ ├── train/ # 训练集标签（txt） │ └── val/ # 验证集标签（txt） └── data.yaml # 数据集配置文件

注意：图片和标注文件的文件名必须一一对应。比如0001.jpg对应0001.txt，拼错一个都会导致训练时报"no labels found"。

我一般按照 8:2 或者 9:1 的比例划分训练集和验证集。测试集可以另外留一份，但 YOLOv5 官方的流程通常只用 train 和 val。

data.yaml 的内容：

# 数据集根目录 path: /home/user/dataset train: images/train val: images/val # 类别数量 nc: 2 # 类别名称，顺序与标注文件里的 class_id 一一对应 names: 0: cat 1: dog

这里有一个很容易踩的坑：class_id 必须从 0 开始连续编号。如果你在标注时只有 3 个类别，但 class_id 是 1、2、3，训练会直接报错。标注文件 txt 的每一行格式是：

class_id x_center y_center width height

后面四个值都是归一化坐标，即像素坐标除以图片宽高，取值范围 0 到 1。labelImg 会自动帮你算好，所以正常标注生成的文件不需要手改。

5.3 train.py 参数详解与一次完整训练

训练命令长这样：

python train.py \ --data data.yaml \ --weights yolov5s.pt \ --epochs 100 \ --batch-size 16 \ --img 640 \ --device 0 \ --name my_custom_model

参数背后的逻辑：

• --weights yolov5s.pt：基于官方预训练权重做迁移学习。千万不要用--weights ''从零开始训练，除非你有海量数据和充足算力，否则收敛极慢、精度还低；
• --epochs 100：训练多少轮。100 轮是一个比较合理的起点，如果你的数据量很小，50 轮可能就够了；数据量大或者任务复杂，可以到 200 轮、300 轮；
• --batch-size 16：显存不够就调小到 8 或 4，显存够用可以调大到 32 甚至 64。batch-size 越大，训练越稳定，但不要超过显卡显存上限；
• --img 640：训练时图片缩放的目标尺寸。训练图片会先按比例缩放到短边 640，再做 padding 补到 640×640；
• --cache：把图片缓存到内存中，加快数据读取，如果你的内存足够（比如 32GB 以上），建议加上。

完整训练一次，控制台日志里会有这些信息：

Epoch gpu_mem box obj cls labels img_size 1/100 6.21G 0.0893 0.0205 0.0013 52 640 2/100 6.21G 0.0714 0.0182 0.0011 48 640

重点关注box（框损失）、obj（目标损失）、cls（分类损失）的变化趋势。正常情况下，这些值应该随着 epoch 增加而波动下降。如果 loss 不降反升，或者震荡特别剧烈，说明学习率太高、batch-size 太小或者数据有问题。

训练结束后，结果存放在runs/train/name/目录下，包括：

• weights/best.pt：验证集上 mAP 最高的权重，部署时首选；
• weights/last.pt：最后一轮的权重，一般用于续训；
• results.png：loss、mAP、PR 曲线等训练过程图像；
• confusion_matrix.png：混淆矩阵，查看类别的互相混淆情况；
• train_batch*.jpg：训练时的 batch 数据增强预览图，能直观看到数据增强效果。

5.4 超参数调整的逻辑：先别急着动

YOLOv5 的超参数配置在data/hyps/hyp.scratch-low.yaml里，包含lr0（初始学习率）、lrf（最终学习率因子）、momentum、weight_decay、warmup_epochs、mosaic、hsv_h等一堆参数。

新手最容易犯的错是一开始就乱调超参数。我的建议是：

1. 第一次训练全部用默认参数，目的是验证数据、代码流程没有 bug；
2. 如果 loss 收敛但 mAP 不够高，优先从数据层面改进（增加数据量、标注质量、类别均衡），而不是调超参；
3. 如果模型过拟合（训练 loss 很低但验证 mAP 上不去），再考虑调整weight_decay、dropout、mosaic、mixup等正则化相关参数；
4. 如果训练震荡不稳，再把lr0调小一半试试。

我曾经遇到过一次极端情况：某个类别只有 20 张图，另一个类别有 2000 张图，训练出来那个少样本类别 mAP 只有 0.05。后来加了数据增强和类别权重才勉强到 0.4。这让我深刻体会到：超参数是锦上添花，数据分布才是决定模型上限的根本。

6. 训练完成之后：验证、导出与部署

6.1 test.py 或 val.py 的指标怎么看

训练结束后，YOLOv5 会自动在验证集上评估一次，日志里会显示：

Class Images Instances P R mAP50 mAP50-95 all 200 300 0.923 0.887 0.934 0.712

这几个指标的含义：

• P（Precision，精确率）：模型检测出的框中，真正是目标的比例。P 高说明误检少；
• R（Recall，召回率）：真实目标中，被模型检测出来的比例。R 高说明漏检少；
• mAP50：IoU 阈值为 0.5 时的平均精度，最常用的粗粒度指标；
• mAP50-95：IoU 阈值从 0.5 到 0.95 的平均精度，要求框的定位更精确。

实际项目里，P 和 R 要根据业务场景权衡。比如质检场景宁可误检也不能漏检，就把置信度阈值调低；而安防告警场景希望减少误报，就把阈值调高。

如果对验证集上的表现不满意，可以回到训练阶段，但不要指望靠调参数起死回生。先去看confusion_matrix.png，查清楚是类别混淆、漏检还是定位不准，再有针对性地改数据。

6.2 导出 ONNX 并部署到自己的程序里

训练好的best.pt是 PyTorch 格式，实际部署时往往需要转成 ONNX 或者 TensorRT 等格式。导出 ONNX 的命令：

python export.py --weights runs/train/my_custom_model/weights/best.pt --include onnx

导出的.onnx文件可以用 ONNX Runtime 加载，在 Python 里部署：

import onnxruntime as ort import cv2 import numpy as np sess = ort.InferenceSession("best.onnx") input_name = sess.get_inputs()[0].name output_names = [o.name for o in sess.get_outputs()] img = cv2.imread("test.jpg") img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB) img = cv2.resize(img, (640, 640)) img = img.astype(np.float32) / 255.0 img = np.transpose(img, (2, 0, 1))[None] outputs = sess.run(output_names, {input_name: img})

导出后要做一个重要验证：ONNX 模型的推理结果要和 PyTorch 模型保持一致。因为导出过程中可能有算子兼容问题，导致结果对不上。用同一张测试图分别跑.pt和.onnx，对比检测框坐标和置信度，误差在合理范围内才算部署成功。

如果要在 Jetson Nano 或者手机这类边缘设备上跑，可以进一步导出 TensorRT 的 engine 文件，速度比 ONNX 快不少。这是另外一个话题，后面有机会单独写。

7. 我在实操中踩过的坑（附完整排查思路）

7.1 CUDA out of memory：不是无脑调小 batch

训练时报错RuntimeError: CUDA out of memory，这是新手最常遇到的错误。很多人第一反应是把 batch-size 减半，然后接着跑，但这只是治标。

我的排查顺序是这样的：

1. 先用nvidia-smi看显存占用情况。如果是其他进程占用了显存，先 kill 或者换卡，这个最常见；
2. 如果自己的训练就爆显存了，优先把--img从 640 降到 512 或 416，这个比调 batch-size 更有效，因为显存占用和输入尺寸是平方关系；
3. batch-size 从 16 降到 8、4；
4. 添加--cache-images可能会导致内存不足，如果内存吃紧就不要加；
5. 实在不行，可以考虑梯度累积，但这需要改代码逻辑，不太适合新手。

7.2 训练 loss 不下降，问题不在网络，在数据

有次我训练一个识别果品的模型，50 个 epoch 过去了，box_loss 一直在 0.1 附近横盘，val mAP 永远都是 0。

排查过程是这样的：

• 先看训练日志，发现 labels 数量为 0，训练时一个目标框都没读进去。问题出在我把标签文件夹路径写错了，data.yaml 里 val 配到了空目录；
• 修好路径后重新训练，loss 还是降不下去。用runs/train/exp/train_batch0.jpg查看训练图像，发现标注框和目标位置完全对不上——原来是 labelImg 保存时图片路径变了，标注文件和图片不是同一张。

最终我发现，训练时--data指向的路径用的是相对路径，而我在不同目录下执行命令，导致图片找不到，部分训练图片实际上没有对应的有效标签。后来我把所有的路径都改成绝对路径，并把一张张图片和标签重新对照了一遍，损失曲线才恢复正常。

所以如果你的 loss 不降，第一件事永远都是：打开train_batch0.jpg看标注对不对、是不是漏读标签了。别怀疑模型结构，90% 的概率是你数据流程有问题。

7.3 精度高但检测错位：小目标丢失与Anchor聚类

另一个头疼的问题是，mAP 看起来不错，但实际用起来小目标经常丢。举个例子，检测远处的人，在 640 输入尺寸下一张 1920×1080 的图里人可能只有 30×60 像素，模型很难抓住。

我的处理方案是：

• 把推理尺寸从 640 提高到 1280，效果立竿见影，但显存和速度代价不小；
• 使用切片推理--slide-overlap，把大图切成小块重叠推理，再拼接结果；
• 检查数据集中小目标的比例。如果小目标太少，模型学不到对应尺度的特征，可以考虑做过采样复制，或者专门用小目标样本微调一个 epoch。

YOLOv5 默认的 Anchor 是基于 COCO 数据集计算的，不一定适合你的目标尺寸分布。训练前可以用工具计算自己数据集的 Anchor 并配置到模型里，但这一步其实在 YOLOv5 里默认开启自动锚框计算，一般不用手动干预。只有在目标尺寸分布和常规相差特别大时才需要关注。

8. 写在最后：能力越大，责任越大

回到标题那个"入狱"梗。YOLOv5 本身是一把工具，就像一把刀，可以切菜也可以伤人。学习它的过程里，我觉得最重要的不是学会多少参数、调通多少模型，而是建立起对技术的判断力和边界感。

具体来说，我给自己定了三条规矩：

1. 数据必须有明确来源和授权。不爬不明来源的图片，不把他人版权数据偷偷拿来训练商业模型；
2. 应用场景要负责任。涉及人脸、隐私、公共安全等敏感场景，先跟相关人员确认合规性，不要一个人闷头开发完就上线；
3. 明确知道模型的边界。模型不是万能的，误检漏检在所难免。在需求沟通和方案设计时，把模型的适用条件和失败可能性说清楚，比什么都重要。

这篇笔记是"自学笔记"系列的第一篇，挺长的，能看到这里说明你真的想学会，看不下去也很正常，实操一次比读十遍都管用。下一步你可以拿一个 100 张图片的小数据集，跟着完整流程走一遍，遇到问题再回来对照笔记排查。

我个人在实际操作中最想再强调一次的是：第一次训练，老老实实用默认参数，目标是跑通流程，不是追求精度。等全流程走通了，你再回去看那些 mAP 指标、超参数调优的文章，会有完全不同的体会。YOLOv5 入门不难，难的是把每个环节做得扎实。数据、标注、训练、验证、部署，每一步都值得你反复打磨。