对接过目标检测的人都知道YOLO 系列在工程里的地位不用多说。我最近在 Ubuntu 22.04 上重新搭了一套 YOLOv5 环境原本以为照着 README 走就行结果还是被各种小细节卡了几轮。这篇是系列的第一篇先把环境准备、官方推理流程和最容易踩的坑讲清楚目标很简单让你拿到一台装了 Ubuntu 22.04 的机器敲完命令就能看到检测框。如果后面要继续训练自己的数据集也会在这一篇基础上往下走。1. 先搞清楚为什么是 Ubuntu 22.04 和 YOLOv51.1 YOLOv5 能做什么不能做什么YOLOv5 是一个目标检测模型它的核心任务是从图像或视频里找出哪里有物体、是什么物体、框在什么位置。官方仓库默认带的是 COCO 数据集上训练的权重能识别人、车、猫、狗、杯子、飞机等 80 类常见物体。换句话说你拿到手就能直接用来做检测不需要先训练自己的模型。但要说清楚一个边界YOLOv5 本身解决的是检测问题不是分类也不是分割。如果你想要的是这张图里有没有猫这样的单图分类或者把前景物体精细抠出来这样的分割任务YOLOv5 不直接做这个。它给你的是一组带类别标签的矩形框。这和它的网络结构直接相关yolov5 把目标检测拆解成回归任务——预测每个候选框的中心点、宽高、置信度和类别概率。理解这一点很关键因为之后的很多参数调整比如 confidence threshold、NMS IOU threshold都是围绕这个回归结果来的。1.2 Ubuntu 22.04 在目标检测场景下的优势我选择 Ubuntu 22.04 而不是其他版本不是因为它最新而是因为它和 PyTorch、CUDA 的兼容性曲线比较平缓。Ubuntu 22.04 自带的是 Python 3.10这个版本在 PyTorch 1.12 到 2.x 范围内都能得到很好的支持。老一点的 Ubuntu 18.04 自带 Python 3.6装新版 PyTorch 经常会碰到版本要求不满足的问题太新的系统又可能遇到 NVIDIA 驱动还没适配的情况。所以 22.04 是个稳妥选择。另外Ubuntu 22.04 的软件源里有比较新的 GCC、OpenCV 依赖装编译类软件时不容易出现缺一个底层库的问题。对于只是做推理、不想自己重新编译 Darknet 或 TensorRT 的人来说这能省掉很多系统层面的麻烦。如果你用的是 WSL2 里装的 Ubuntu 22.04同样适用只是后面在显卡调用上会多几步检查。1.3 这一篇到底要带你完成什么作为系列第一篇我给这篇定下的目标是三个在你的 Ubuntu 22.04 上装好 YOLOv5 官方代码和运行环境成功跑通官方的图片检测命令看到输出结果知道遇到常见报错时排查思路是什么。模型训练、数据标注、自己数据集的格式转换这些后面会单独展开。第一篇不碰训练是因为训练涉及的东西太多了数据集划分、anchors、超参数、训练策略任何一个环节出问题都会让人瞬间失去耐心。先把推理跑通建立了对输入输出格式的直觉再进入训练阶段会顺畅很多。2. 环境准备阶段容易被忽略的细节2.1 硬件检查先看你有没有明显短板在动手之前先花两分钟检查一下机器。虽然这话听起来像废话但我在不同机器上翻车翻多了发现硬件差异带来的体验差别比任何参数都明显。打开终端执行lscpu | grep -E Model name|CPU\(s\) free -h | head -n 2 nvidia-sminvidia-smi如果提示 command not found说明显卡驱动还没装好或者机器根本没有 NVIDIA 显卡。这决定了你接下来能不能用 GPU 推理。YOLOv5 官方 README 写的安装步骤其实默认你已经有 CUDA 环境但实际很多人的机器是一张核显或者 NVIDIA 显卡驱动还没装。内存方面官方给的建议是 8GB 以上。实测 8GB 跑 CPU 推理、batch size 为 1 是够用的但如果同时开浏览器、编辑器、看文档很容易爆。磁盘建议留至少 20GB 空闲因为 YOLOv5 的库、虚拟环境、权重文件、数据集加在一起会慢慢吃掉不少空间。2.2 基础软件安装Python、pip、gitUbuntu 22.04 默认自带 Python 3.10一般够用了。但系统自带的 pip 可能不是最新版本需要处理一下sudo apt update sudo apt install -y python3-pip git python3-venv python3 -m pip install --upgrade pip一句话说明为什么要装python3-venvYOLOv5 的依赖版本和系统其他软件包容易冲突尤其是 OpenCV、numpy 这类库直接用系统级 pip 安装很可能把环境搞乱。用虚拟环境把 YOLOv5 的依赖隔离起来出问题了删了重建就行代价最低。pip 的下载源也建议提前换一下。国外源连接不稳定会影响依赖安装速度换国内镜像源之后安装时间可以从十几分钟缩短到几分钟。确保系统代理或者网络策略允许的情况下可以这样配置pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple这里有个容易踩的细节Ubuntu 22.04 的python3指向的是 Python 3.10但有些教程会直接让你用pip install而系统里同时存在pip和pip3。为了保持一致性后面所有安装命令我都是基于虚拟环境内的pip这样不会出现明明装了库却 import 不到的问题。2.3 显卡驱动、CUDA 与 PyTorch 的取舍先用nvidia-smi看看显卡状态。如果你能看到类似这样的输出----------------------------------------------------------------------------- | NVIDIA-SMI 525.125.06 Driver Version: 525.125.06 CUDA Version: 12.0 | -----------------------------------------------------------------------------说明驱动没问题而且驱动支持的最高 CUDA 版本是 12.0。这里要特别说明一个常见误解nvidia-smi显示的 CUDA Version 不是你系统里已经装好的 CUDA Toolkit它只代表当前驱动能兼容的最高 CUDA 版本。跑 PyTorch 只要安装预编译的 PyTorch 包里面自带了需要的 CUDA 运行时库不需要单独安装完整 CUDA Toolkit。所以正确的做法是先看nvidia-smi显示的最高 CUDA 版本然后去 PyTorch 官网选一个不超过这个版本的预编译安装命令。比如驱动最高支持 CUDA 12.0你就可以安装支持 CUDA 11.8 或 12.1 的 PyTorch 版本。如果你没有 NVIDIA 显卡先不用灰心后面会讲到怎么用 CPU 把流程跑通。只是速度会慢很多做个功能验证、跑跑官方示例还是没问题的。3. 拉取代码、安装依赖、跑通官方推理3.1 从 GitHub 拉取 YOLOv5 仓库这一步最简单也最容易因为网络问题中断。在终端执行cd ~ git clone https://github.com/ultralytics/yolov5 cd yolov5如果 git clone 速度很慢或者中途报错可以试试用镜像仓库地址或者用git clone --depth 1只拉取最新一次提交减少文件体积git clone --depth 1 https://github.com/ultralytics/yolov5--depth 1会丢掉历史提交记录对普通使用没有任何影响。这个操作值得养成习惯yolov5 仓库的历史记录不少全量拉取没太大必要。克隆完成后先看一眼目录结构ls -la你会看到detect.py、train.py、val.py、data、models、utils这些核心文件和目录。detect.py就是做推理用的主脚本后续所有检测命令都围绕它展开。3.2 用虚拟环境隔离依赖我建议在yolov5目录下创建一个虚拟环境而不是直接往系统 Python 里装cd ~/yolov5 python3 -m venv venv source venv/bin/activate激活之后终端提示符前面会出现(venv)前缀看到这个前缀再执行下面的命令才能确保依赖都装进了虚拟环境里。为什么要这样做因为 YOLOv5 的requirements.txt里锁定的部分依赖版本和系统里已有的版本可能冲突。比如系统里已经有 numpy 1.24而 YOLOv5 某个依赖要求 numpy 必须小于特定版本直接在系统环境装很容易报ERROR: pips dependency resolver的冲突提示。虚拟环境就是一个隔离沙箱随便折腾。3.3 安装 requirements.txt——别急着直接执行很多人拿到requirements.txt就立刻跑pip install -r requirements.txt我也这么干过然后在 torch 下载环节等了几十分钟最后还可能因为版本不匹配出问题。所以建议先打开文件看一眼cat requirements.txt里面的核心依赖无非是 torch、torchvision、opencv、matplotlib、numpy 这些。这里有个细节requirements.txt里给出的 torch 版本往往是最新的稳定版不一定和你本地驱动最匹配。所以我的习惯是先单独安装 torch 和 torchvision再安装其余依赖。如果使用 GPU先去 PyTorch 官网复制当前机器驱动能支持的安装命令比如pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118这里cu118表示 CUDA 11.8 的预编译版本。确认安装成功之后再回来安装其余依赖pip install -r requirements.txt如果 CPU 环境直接执行pip install torch torchvision就可以了不用加 index-url。3.4 下载权重、运行第一次检测官方仓库的detect.py默认会从 PyTorch hub 自动下载权重文件。如果你直接运行python detect.py --weights yolov5s.pt --source data/images/bus.jpg它会先尝试下载yolov5s.pt大约 14MB。网络正常情况下几秒到几十秒就完成了。下载好的权重会保存在当前目录。如果下载失败最常见的原因是网络无法访问外网或者访问不稳定。可以手动用镜像地址下载权重文件放到当前目录。下载完成后重新运行上面的命令。第一次跑的时候脚本会加载模型、执行推理然后在屏幕上打印类似这样的信息image 1/1 /home/user/yolov5/data/images/bus.jpg: 640x640 4 persons, 1 bus, 1 tie Speed: 18.3ms pre-process, 213.4ms inference, 4.2ms NMS per image at shape (1, 3, 640, 640)看到4 persons, 1 bus, 1 tie就说明检测成功了。如果最后几个词是类似0 persons的结果也不要慌可能在前面某个环节出问题后面会讲排查思路。3.5 输出目录和检测结果怎么看运行完成后默认会在runs/detect目录下生成结果。第一次运行目录是runs/detect/exp第二次是runs/detect/exp2以此类推。ls runs/detect/exp/你会看到bus.jpg和labels目录。图片是可视化结果检测框、类别标签、置信度都画在上面。labels目录里是 YOLO 格式的标签文件每行表示一个目标对应的是class x_center y_center width height这个格式后续在训练自己的数据集、验证标注文件时都会用到。打开标签文件第一列的数字是类别索引比如 COCO 数据集里0代表 person5代表 bus后面的值是归一化坐标。对第一次接触 YOLO 格式的人来说这个文件可能看不出什么但它其实就是模型学到的检测框的标准答案表示方式。4. 从官方示例过渡到自己的数据4.1 检测自己图片或视频时最常用的几个参数官方样例图片是为了验证环境真正用起来一定要换成自己的数据源。最常用的三个命令模式# 单张图片 python detect.py --weights yolov5s.pt --source /path/to/your/image.jpg # 整个文件夹 python detect.py --weights yolov5s.pt --source /path/to/folder # 视频文件 python detect.py --weights yolov5s.pt --source /path/to/video.mp4--source参数很灵活它支持图片、视频、文件夹、摄像头设备号甚至流媒体地址。我日常在项目里用得最多的是文件夹模式把一批图片丢进一个目录让脚本批量处理输出自动存入新的 exp 目录。摄像头模式也值得提一下python detect.py --weights yolov5s.pt --source 00表示默认摄像头。在 Ubuntu 22.04 上如果系统有多个视频设备可能需要改成1或2。有时候摄像头权限没给够会报错说无法打开设备可以先用lsusb和/dev/video*检查设备是否存在。4.2 imgsz、conf-thres、iou-thres 到底是干什么的推理结果里会有一个 640x640 的提示。这个就是--imgsz参数决定的推理尺寸默认是 640。为什么不直接把原始图片丢给模型因为 YOLOv5 的输入是一个固定大小的张量网络结构里设计了 SPPF 和 PANet输入分辨率需要能整除下采样倍数。把不同尺寸的图片统一缩放到 640x640模型才能批量处理而且这也能提高对小尺寸输入的计算效率。--conf-thres是置信度阈值默认 0.25。意思是只有当模型认为某个目标是这一类的概率大于 25% 时才输出这个框。把这个值调低比如 0.1会看到更多低置信度的检测框误检也会变多调高到 0.5框会更少但更准确。实际调参时我一般先用 0.25 跑一遍看整体效果再根据误报漏报情况微调。--iou-thres是 NMS 的 IoU 阈值默认 0.45。它的作用是去掉重叠的检测框。比如同一辆车可能被输出 10 个相近的框NMS 会把这些重叠度大于阈值的框合并成一个。阈值太小会导致重叠物体被误删阈值太大又可能出现一个物体有多个框。下面这些参数在第一次使用时会给你更多掌控感python detect.py --weights yolov5s.pt --source data/images/bus.jpg --conf-thres 0.3 --iou-thres 0.5 --imgsz 6404.3 输出管理别让 exp 目录越堆越多每次跑detect.py脚本都会自动创建新的exp目录用多了之后runs/detect下面可能堆了几十个文件夹。这时候手动去翻很麻烦。两个解决思路用--project参数指定输出根目录比如--project ~/my_detections用--name参数给当前任务起名字比如--name car_test。这样输出路径会变成~/my_detections/car_test很好找。再配合--exist-ok重复跑同一个名字的任务时会直接覆盖不会无限累加。python detect.py --weights yolov5s.pt --source ~/test_imgs --project ~/my_detections --name first_round这个习惯我一开始没有后面做批量实验的时候才发现几十个 exp 目录摆在那里想对比不同参数的结果非常痛苦。早一点规划输出路径后面能省很多力气。5. 实测排错新手最容易卡住的几个点5.1 依赖没装全还是装错版本最典型的报错是ModuleNotFoundError: No module named torch这个基本就是没有激活虚拟环境或者激活之后忘了先安装依赖。先检查which python which pip如果python路径指向/usr/bin/python而不是虚拟环境里的路径说明虚拟环境没激活。重新执行source venv/bin/activate。另一个更隐蔽的问题是RuntimeError: Couldnt load custom C ops。这通常是因为 PyTorch 与系统上的 libstdc 版本不兼容或者 PyTorch 被装成了 CPU 版本但你想用 GPU。遇到这种错误我建议直接把当前虚拟环境里的 torch 卸载重新从 PyTorch 官网的安装命令安装不要用 pip 自动解析因为自动解析很容易把 torch 降级。5.2 torch 命令能 import 但 cuda 不可用跑推理时如果很慢GPU 完全没占用可以检查一下python -c import torch; print(torch.__version__); print(torch.cuda.is_available())如果输出False说明 PyTorch 没有使用 GPU。常见原因是安装的 PyTorch 是 CPU 版本或者是 CUDA 版本但与驱动不匹配。这时候重新执行一次适用于当前驱动版本的安装命令比如pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118不要只更新 torchtorchvision也需要和 torch 版本配套否则可能出现torchvision导入时报torchvision::_roi_align之类的算子不匹配错误。5.3 CPU 推理太慢能不能先做点优化没有独立显卡的时候CPU 推理慢是正常的。但有几个小技巧可以让流程顺畅一些把图片尺寸调小--imgsz 320可以让推理时间大幅下降代价是检测精度下降用更小的模型yolov5n.pt是 nano 版本只有 4MBCPU 上比yolov5s.pt快不少固定线程数环境变量OMP_NUM_THREADS8有时候能让推理更快些建议实际试一下。python detect.py --weights yolov5n.pt --source data/images/bus.jpg --imgsz 320这种组合在 CPU 上做验证、跑 Demo 是够用的真要部署到生产环境还是得想办法上 GPU 或者用加速工具。这只是权宜之计明白这点就行。5.4 权重下载慢或者失败怎么办权重下载失败不一定代表网络完全不通。有时候是 pypi 源没问题但 GitHub Releases 或 PyTorch hub 的连接有问题。手动下载权重放到当前目录最直接把yolov5s.pt下载到~/yolov5/下脚本检测到文件存在时就不会重复下载。如果运行时提示类似KeyError或加载权重错误多半是权重文件被截断或下载不完整重新下载一份覆盖就可以。如果你用的是自定义模型名比如某个best.pt也放在当前目录下然后python detect.py --weights best.pt --source data/images/bus.jpg文件路径一定要和权重文件名称一致不然脚本会尝试从网上找名字对应的权重然后给你一个 404 或者连接失败。6. 在进入训练阶段前最好先搞明白这几件事6.1 官方模型的能力边界现在能跑通推理只能说明环境没问题。要继续往下走必须先理解官方预训练权重是在 COCO 数据集上训练的识别的类别是那 80 类。如果你要检测的东西不在这 80 类里比如工业零件、特定农作物、某个特殊交通标志官方权重基本帮不上忙。这就要进入训练自己的数据集的阶段。这也是为什么我建议先把推理流程吃透再训练。上面的每一步置信度阈值、IOU 阈值、图片尺寸、权重格式都会在模型训练和验证阶段反复用到。例如训练的时候--imgsz和推理时的--imgsz最好一致否则模型输入尺寸和推理尺寸差异过大会影响精度。6.2 数据标注和 YOLO 格式会是你绕不开的门槛YOLOv5 训练时用到的标签格式刚才跑推理时已经在labels目录见过了就是那个class x_center y_center width height文本。自己训练时你需要把每张图片对应的标注文件也做成这种格式。市面上有很多标注工具比如 LabelImg、Labelme都能导出成 YOLO 格式。这里提前说一个很多人第一次都会犯的错标注框的坐标必须是归一化到 0~1 之间的。比如一张 1280x720 的图某个框的 x_center 是 640归一化之后就是 0.5。如果是像素坐标训练时会直接报错或者产生毫无意义的 loss。所以第一篇里看到输出的标签文件时最好顺手算一下坐标范围对后续理解训练数据格式有很大帮助。6.3 为什么我建议先做一次最小可行性训练当你把环境完全跑通后下一步我不建议直接上几千张图开始训练。最好是先准备 30~50 张图标注成像样的数据集然后跑一次完整的训练流程。目的不是为了得到高精度模型而是为了验证数据管线图片路径、标注格式、数据增强、训练循环、验证指标。这一套流程跑通了之后再加数据、调超参数才有基础。否则数据问题上千行报错信息你会连错误出在标注还是代码里都分不清。这个思路其实和这篇的目标一致——先让链路通起来再让结果好起来。对我来说这一步做完之后整个 YOLOv5 的入口就算是真正打开了一条缝。第一篇文章停在推理和排错这里刚好合适后面的数据集制作、训练策略调整、模型导出和部署我们下一篇再继续。如果你在跑通推理的过程中遇到什么奇怪的问题欢迎在评论区留下报错信息我会从遇到的问题里挑有代表性的展开讲。