YOLOv5 的安装、训练与部署我一口气盘清楚了搞目标检测的开发者哪怕没亲手用过 YOLOv5也大概率在 GitHub 上见过那个醒目的仓库。它不算官方正统的 YOLO 续作但凭一套开箱即用、训练部署一条龙的体验愣是成了工业界和学术界使用频率最高的检测框架之一。这篇文章我不打算复读官方 README而是从一个实际跑过多个项目、踩过不少坑的开发者视角把 yolov5 安装使用从头到尾捋一遍环境怎么选、依赖怎么装、训练推理怎么写、出了报错怎么排查。读完你应该能直接照着手里的场景开干。我自己最早接触 YOLOv5 是在某个人脸检测 demo 上当时团队里其实还在用老一代检测库切到 YOLOv5 之后最大的感受是安装足够友好工程结构清晰模型导出的链路也顺畅得不像刚出来两年的项目。后来帮几个朋友搭过环境发现大家踩的坑高度集中基本都是环境版本冲突、目录没捋清、显存申爆这老三样。把这些经验提前写出来能帮你少折腾很多时间。1. 安装前的环境判断与工具选型1.1 Python、CUDA 与 PyTorch 版本怎么搭配先聊环境这是 90% 安装问题的源头。YOLOv5 官方仓库的 requirements.txt 给了依赖清单但那份清单只解决了“能跑”的问题解决不了“跑得顺”的问题。核心要锁定的三个变量是 Python、CUDA、PyTorch 的版本关系。个人踩坑后的结论是如果从零开始装优先选 Python 3.8 或 3.10别用 3.7部分新版依赖已经开始放弃 3.7也别追新到 3.12 以上packaging 和 torch 的轮子兼容性还得看运气。CUDA 和 PyTorch 的对应关系更敏感比如 PyTorch 2.0 之后对 CUDA 版本的要求有明显变化装错的话检测不到 GPU或者训练时直接 Illegal instruction 崩掉。配环境最快的路径不是自己编译而是先想清楚机器的显卡型号和驱动版本。用 nvidia-smi 看 CUDA 驱动支持的版本号再决定装哪个 PyTorch 轮子。驱动支持 12.x 的就装 cu121 或 cu118 的 torch驱动只支持 11.x 的老老实实找 cu113 或 cu116 的老轮子。很多人死在“官网最新版 PyTorch 默认下载的是 cu121但我机器驱动只有 11.4”跑起来不报错但训练慢得离谱其实就是 CUDA 根本没吃上。提示安装前先确认显卡显存。训练至少 6GB 显存起步跑小模型推理倒是宽容得多。显存不够的时候可以从数据集、batch size、模型尺度三个方向做减法后面会展开。1.2 选择 Conda 还是原生 venv安装 Python 依赖时我强烈建议用一个隔离环境。直接在系统 Python 里装 torch 不是不行但等到你同时维护两个项目、一个要 torch 1.x 一个要 torch 2.x 的时候就知道虚拟环境有多香。Conda 和 venv 之间选哪个个人体会选 Conda。原因很朴素——torch 这类巨型依赖背后的数值计算库OpenBLAS、MKL版本有讲究Conda 在解决依赖冲突上比 pip 强势而且 conda 装 cudatoolkit 可以做到不污染全局驱动。公司里那位搞模型压缩的同事就吃过 pip 乱装 cudatoolkit 的亏他后来老老实实回归 conda。新建环境示例conda create -n yolov5 python3.8 -y conda activate yolov5这个环境名字可以随便起但建议起得和你手里的项目相关比如yolo-custom这样多项目并行时一眼就能认出哪个环境在哪个工程下。2. 安装 YOLOv5 的过程与细节2.1 仓库克隆与目录结构认识YOLOv5 的安装不是pip install yolov5这么简单官方推荐的方式是下载仓库然后把仓库根目录当作工作区。原因很简单它的train.py、detect.py、export.py都依赖内部的相对路径直接 pip 装一个包反而丢失了这种目录的透明性。我习惯这样操作git clone https://github.com/ultralytics/yolov5 cd yolov5 pip install -r requirements.txt第 3 步是很多人跳过又出问题的地方。官方 requirements.txt 里包含 torch、torchvision、opencv-python、numpy 等一堆依赖。不关心版本的话直接装即可但我建议先手动装 torch再走 requirements.txt。顺序反了pip 会把 torch 当作未满足的依赖顺手装成 CPU 版本等你用torch.cuda.is_available()检查时就得返工。装完依赖可以顺手验证一遍import torch print(torch.__version__) print(torch.cuda.is_available())如果是 True恭喜基本盘稳了。如果 False大概率是 torch 版本和 CUDA 不对付重新走一遍 cu118 那类带版本标签的安装最省心。2.2 requirements.txt 里容易被忽略的依赖requirements.txt 里有一项pycocotools在 Windows 上装这个经常出大问题因为它需要编译 C 扩展。Linux 一般没事Windows 用户常常得手动装 Visual Studio Build Tools 或者用pip install pycocotools-windows替代。还有一个是torchvision版本必须和 torch 严格匹配否则会报类似的错误torchvision is not compatible with torch xx. 如果手动装了 torch建议用如下方式锁定 torchvisionpip install torchvision --index-url https://download.pytorch.org/whl/cu118这样 torchvision 和 torch 会按照同一套构建配置对齐规避版本配不上带来的隐性 bug。2.3 数据目录要不要放仓库里我见过不少新手顺手把数据集往 yolov5 仓库内部一丢就开始训练实际这样体验很糟。因为训练过程中datasets目录会慢慢生成缓存文件.cache、labels 等混在源码里既不好做版本管理也会让 clone 下来的仓库越来越臃肿。我个人的建议是单独建一个数据根目录例如/data/datasets然后用绝对路径或者相对路径指过去。YOLOv5 的官方数据配置是 yaml 文件里写path字段根本没必要把数据硬塞进仓库。后续多项目复用、模型蒸馏、数据增广切分都会方便不少。3. 安装完成后的模型测试3.1 用下载好的预训练权重跑一次推理装好依赖后第一件事不是急着拿自己的数据集开练而是先用官方权重跑一遍全流程确认框架层面没毛病。YOLOv5 提供了一组预训练权重可以直接拿来预测图片。第一次运行detect.py时它会在启动时检查权重是否本地存在不存在就自动从云盘下载过程有点慢但省心。命令python detect.py --weights yolov5s.pt --source data/images/bus.jpg --conf-thres 0.4跑完你会看到终端输出保存路径默认是runs/detect/exp里面画着检测框和置信度。如果这一步顺利说明安装链路基本贯通。很多新手在这个节点容易晕看到data/images/bus.jpg不知道文件在哪。实际上仓库里带了这两张示例图就是给你做 smoke test 用的。我自己测试时还喜欢顺手换一张自己的照片进去试试传一张普通街拍图跑一下稍微结合--iou-thres 0.5看下误检能对模型的脾气有个直观印象。3.2 常见报错No module named torchvision的排查每次在群里答疑最多的问题就是这个。明明装了一堆包import 时却报找不到 torchvision。原因无非三种记得不牢固确实没装。装到了别的虚拟环境conda 激活错了。装了但 pip 版本乱了Windows 上混装 conda 和 pip 很容易出现这个问题。排查路径很直接先pip list看 torchvision 在不在再看which python确认当前用的是哪个解释器。做深度学习项目环境隔离这件事再怎么强调都不过分凡是环境问题九成都是环境自己先乱掉的。4. 核心实操用 YOLOv5 训练自己的检测模型4.1 数据集标注与 YOLO 格式整理训练自己的模型数据格式是第一个拦路虎。YOLOv5 要求的数据格式是每个图片对应一个同名 txt 文件内容每行是class_id x_center y_center width height四个坐标值都是归一化到 0-1 的小数。手动生成太痛苦建议使用标注工具做好标注后自写脚本转换。常用的开源工具包括 LabelImg 和 AnyLabeling前者流传广、安装简单后者 UI 和交互更现代还能支持辅助标注模型。无论哪个导出格式一般都不是 YOLO 原生格式可能会导出成 COCO JSON 或者 Pascal VOC XML。我自己习惯的转换策略是VOC 或 COCO 统一转成标准化数据帧比如 pandas因为中途做数据清洗、类别过滤或重命名会很方便。再从数据帧导出为 YOLO txt 格式。划分 train/val 数据集时保证每一类的实例数量大致均衡避免某一类在验证集中缺失。4.2 image size 与 batch size 怎么调训练命令常见是python train.py --data dataset.yaml --weights yolov5s.pt --img 640 --batch 16 --epochs 100这个命令人人都能写但参数怎么定才是门道。--img是输入边长YOLOv5 内部会按比例缩放并 pad 到固定尺寸。先用 640 是稳妥的模型默认锚框都在这个尺度上做过统计。如果你后面想检测小目标可以试试 1280但显存和时间成本也会涨一大截。--batch的选择需要结合显存动态调整。假设你有 8GB 显存--img 640 --batch 16通常能跑 yolov5s但如果你拿的是 yolov5x显存可能直接炸。稳妥的做法是把 batch 往下调到 4到 2直到刚好不 OOM。可调参数还有更细的--multi-scale、--cos-lr、--label-smoothing新手阶段不要一把梭全开。先把基础流程跑通再把锦上添花的开关逐个加上这样出问题时定位才知道去哪找。4.3 训练中断怎么续传训练到一半断电、显存 OOM 是常态。YOLOv5 在每轮 epoch 结束时会自动保存last.pt和best.pt在runs/train/exp/weights/下。恢复训练只需要python train.py --data dataset.yaml --weights runs/train/exp/weights/last.pt --resume这里有个容易迷惑的点--resume加不加--weights都行。如果加了它会从指定权重文件所在路径推断上次训练的 log 路径如果不加要确保当前命令里有--project那种指向原来目录的参数否则会新开一个 exp 目录。我自己有个小习惯每周清理一次runs/train只保留best.pt和关键截图的 exp把last.pt留下但不上传 git因为last.pt体积不小且每隔几轮就换一版频繁同步到网盘的体验太痛。5. 推理阶段的进阶场景5.1 按摄像头输入实时检测推理环境的构建比训练轻量很多CPU 也能跑但体验差距明显。如果想做摄像头实时检测命令可以写成python detect.py --weights best.pt --source 0 --conf-thres 0.4 --view-img--source 0指的是本地第 0 号摄像头设备。输出窗口会弹出实时画面。这个模式下建议加--device 0指定 GPU或--device cpu取决于你机器上有几块卡。如果有多卡但没指定默认跑第 0 块遇到和第 1 块卡绑定的数据流时会出现传输瓶颈。实时场景下比较实用的是调--max-det限制最大检测数量防止画面里突然涌入大量目标时检测逻辑过载。默认是 1000但实际业务往往用不到那么多。5.2 导出为 ONNX 与 TensorRT训练完模型不等于完事部署才是真考验。YOLOv5 官方提供的export.py可以直接导出多种格式python export.py --weights best.pt --include onnx engineONNX 适合跨平台部署TensorRT 则是 NVIDIA 显卡上的性能最优解导出完通常还得做一次推理一致性验证。我自己一般先导 ONNX 跑一遍动态尺寸接口再用 TensorRT 做静态 batch 的加速推理耗时能比原 PyTorch 模式降低一个量级。有一个坑值得提导出的 ONNX 模型如果要动态输入尺寸detect.py里默认的--img可不适用需要在导出时制定--dynamic参数。否则按固定尺寸导出的模型你不小心送进一张 960x540 的图脚本可能会因为分辨率对不上直接报错。5.3 C 侧调用 ONNX 的配置方案如果要把模型集成到 C 项目里常见做法是 ONNXRuntime 搭配 OpenCV。部署到嵌入式设备或服务端中断场景时内存和时间开销都比 Python 侧稳定不少。基本步骤是加载 ONNX session将输入图按模型要求的 letterbox 尺寸预处理执行推理后解码输出 tensor转换为检测框后处理非极大值抑制剔除重叠框。这一步的坑往往集中在预处理方式上。YOLOv5 在训练时把 RGB 图像做了 0-1 缩放即除以 255如果你在 C 侧忘了这步直接把 0-255 的像素值送进模型推理结果会飘到完全不可用置信度普遍跌到 0.1 以下。多个资深工程师查了半天问题最后发现是归一化给漏了这一点务必小心。6. 常见问题速查表与避坑技巧问题现象可能原因解决办法torch.cuda.is_available() 为 Falsetorch 是 CPU 版本或 CUDA 版本不匹配卸载 torch按机器驱动对应 cu118/cu121 重新安装训练时显示 Unknown image format数据集路径写错或图片格式特殊检查 yaml 文件和实际目录结构避免中文路径RuntimeError: CUDA out of memorybatch 或模型尺寸太大降低 batch、img或换更小的模型如 yolov5sdetect.py 显示 weights not found权重路径写错换成绝对路径或确认下载完成推理时置信度一直很高但不准训练数据标注有误用可视化工具叠加标注框核对轮换标注人员复核导出 ONNX 失败torch 版本过旧升级 torch 至官方 README 指定版本范围看完这个表你再遇到同类问题起码心里有数。很多时候问题不是模型本身而是设备和环境上的细节。7. 最后的经验补充分享YOLOv5 这个框架教会我一个道理好的工程项目会把复杂的原理包装成清晰的操作接口。装上就能跑跑起来能训练训练完能导出这条链路本身就是这类工具最大的价值。但我在实际项目中体会最深的还是数据的质量和标注的一致性。同样的网络结构干净的数据和杂乱的数据最后 mAP 能差出一大截。如果你现在就准备上手我的建议是先不要急着追求高精度。用一个小数据集把安装、训练、导出、推理这整条流水线都走过一遍把每个环节的输入输出摸清楚再去调模型参数和扩数据。路是一步步铺的安装只是第一块砖。那几份测试用的预训练权重我至今留着不是为了跑分而是遇到环境问题时可以快速回归一下框架本身有没有坏这个习惯帮你省下的时间绝对远超你想象的量。