yolov5下载与常见报错解决：从requirements.txt到SPPF的detect排错实录

1. 为什么你的 yolov5 一跑 detect.py 就报错很多人第一次接触目标检测都是从 yolov5 开始的。它把训练、推理、导出整条链路都封装得比较顺手克隆下来装个依赖就能跑detect.py看效果。但真正动手时卡住新手的往往不是模型原理而是下载和运行阶段的一堆报错requirements.txt装到一半失败、SPPF找不到、Upsample属性缺失、张量尺寸对不上。这些错误日志看起来吓人其实大部分是版本没对齐导致的。这篇就聚焦 yolov5 本地部署全流程从克隆仓库、安装requirements.txt依赖到运行detect.py推理把 SPPF 模块缺失、版本冲突这些高频报错逐一复现并给出可复制的修复动作。适合刚拿到 yolov5 源码、准备跑通第一张检测图的人。我会把每个报错的日志、原因、解决步骤都写清楚你照着对照表定位就行。过程中如果涉及模型下载或接口调用我会顺带说下怎么用 TaoToken 这类平台做辅助验证但核心还是本地环境排错。先说清楚一个前提yolov5 有多个版本分支5.0、6.0、6.1、7.0 之间的models/common.py差异不小。你下载的代码版本、权重文件版本、PyTorch 版本三者只要有一个不匹配detect.py就会在加载模型或前向推理时抛异常。所以排错的第一步永远是确认自己用的是哪个版本。2. 下载源码与 requirements.txt 依赖安装2.1 选对分支再克隆yolov5 官方仓库在 GitHub 上默认分支是 master但 master 会持续更新。如果你跟着某篇老教程做教程用的是 5.0 版本而你直接克隆了最新版后面权重和代码就对不上。稳妥做法是显式指定 tag 或分支git clone -b v5.0 https://github.com/ultralytics/yolov5.git yolov5-5.0 cd yolov5-5.0如果你网络环境拉 GitHub 慢也可以直接下载对应版本的 zip 包解压。解压后目录结构大致是这样data放超参数 yaml 和测试图片models放网络结构配置和common.pyutils放 loss、metrics、plots 等工具函数weights放权重根目录下detect.py、train.py、test.py、requirements.txt各司其职。训练自己的数据集时建议把数据集放在项目同级目录而不是塞进data里面避免路径混乱。2.2 安装 requirements.txt 的正确姿势进入项目目录后先建一个独立虚拟环境别直接往系统 Python 里装python -m venv venv # Windows venv\Scripts\activate # Linux / macOS source venv/bin/activate然后安装依赖pip install -r requirements.txtrequirements.txt里核心依赖包括matplotlib3.2.2、numpy1.18.5、opencv-python4.1.2、Pillow、PyYAML5.3.1、scipy1.4.1、torch1.7.0、torchvision0.8.1、tqdm4.41.0日志相关有tensorboard2.4.1绘图有seaborn0.11.0、pandas导出相关有thop、pycocotools2.0。注意torch和torchvision是版本绑定的pip自动解析时可能给你装一个和 CUDA 不匹配的版本。如果你有 NVIDIA 显卡并想用 GPU 推理建议先单独装对应 CUDA 版本的 PyTorch再装其余依赖pip install torch1.8.1cu111 torchvision0.9.1cu111 -f https://download.pytorch.org/whl/torch_stable.html pip install -r requirements.txt装完后验证一下python -c import torch; print(torch.__version__, torch.cuda.is_available())输出类似1.8.1 True就说明 GPU 可用。如果显示False要么是没装 CUDA 版要么是驱动问题先解决这个再往下走否则后面detect.py会默认走 CPU速度慢很多。2.3 权重文件别下错版本detect.py默认会去下载yolov5s.pt。如果你用的是 5.0 代码却让它自动下载了 6.1 的权重加载时就会报 SPPF 相关的错。所以权重最好手动下载对应版本放到项目根目录或weights目录下。5.0 对应的yolov5s.pt和 6.x 的权重结构不同不能混用。下载后可以用torch.load简单验证import torch ckpt torch.load(yolov5s.pt, map_locationcpu) print(type(ckpt), list(ckpt.keys())[:5] if isinstance(ckpt, dict) else model)能正常打印出字典键说明权重文件没损坏。3. 运行 detect.py 与三类高频报错复现3.1 SPPF 模块缺失AttributeError: Cant get attribute SPPF这是 5.0 版本最经典的报错完整日志类似AttributeError: Cant get attribute SPPF on module models.common from ...\yolov5-5.0\models\common.py原因很直接你用的是 5.0 代码但加载的权重是 6.x 版本6.x 的common.py里新增了SPPF类而 5.0 的common.py没有。解决办法有两个推荐第一个。方案一把 6.x 的SPPF类复制到你的models/common.py里。在文件合适位置加入import warnings class SPPF(nn.Module): # Spatial Pyramid Pooling - Fast (SPPF) layer for YOLOv5 by Glenn Jocher def __init__(self, c1, c2, k5): super().__init__() c_ c1 // 2 self.cv1 Conv(c1, c_, 1, 1) self.cv2 Conv(c_ * 4, c2, 1, 1) self.m nn.MaxPool2d(kernel_sizek, stride1, paddingk // 2) def forward(self, x): x self.cv1(x) with warnings.catch_warnings(): warnings.simplefilter(ignore) y1 self.m(x) y2 self.m(y1) return self.cv2(torch.cat([x, y1, y2, self.m(y2)], 1))方案二换成 5.0 对应的权重文件从源头避免类缺失。如果你只是想快速跑通方案二更省事如果你想顺便理解 SPPF 结构方案一更值得做。3.2 Upsample 报错object has no attribute recompute_scale_factor日志AttributeError: Upsample object has no attribute recompute_scale_factor这是 PyTorch 版本升级后nn.Upsample接口变化导致的。旧代码里Upsample初始化时传了recompute_scale_factor参数新版本 PyTorch 已经移除。打开models/common.py找到Upsample相关调用把recompute_scale_factor参数删掉即可。通常在第 150 行附近类似# 修改前 nn.Upsample(scale_factorscale_factor, modenearest, recompute_scale_factorTrue) # 修改后 nn.Upsample(scale_factorscale_factor, modenearest)改完保存重新运行detect.py。这个报错和 SPPF 不同它跟权重版本无关纯粹是 PyTorch 版本和代码写法不兼容。3.3 RuntimeError张量尺寸不匹配日志RuntimeError: The size of tensor a (60) must match the size of tensor b (56) at non-singleton dimension 3这个报错通常出现在特征图相加或拼接时两个张量空间尺寸不一致。根因还是模型版本不匹配你加载的yolov5s.pt和当前代码的网络结构对不上导致某一层输出的特征图大小差了几个像素。解决办法是下载与代码版本严格对应的权重文件替换掉原来的yolov5s.pt。替换后建议清一下缓存rm -rf ~/.cache/torch/hub/checkpointsWindows 下对应C:\Users\你的用户名\.cache\torch\hub\checkpoints。然后重新运行让程序加载你放好的权重。3.4 报错对照速查表报错关键词典型日志片段根因修复动作SPPFCant get attribute SPPF5.0 代码加载 6.x 权重补 SPPF 类或换 5.0 权重Upsampleno attribute recompute_scale_factorPyTorch 版本升级删除该参数RuntimeErrorsize of tensor a (60) must match b (56)权重与代码版本不匹配替换对应版本权重requirementsCould not find a version依赖版本冲突或源问题单独装 torch 再装其余4. 验证请求与成功结果确认修完报错后用一张测试图跑通推理。项目data/images下自带示例图直接执行python detect.py --weights yolov5s.pt --source data/images --img-size 640 --conf-thres 0.25参数说明--weights指定权重路径--source可以是图片、视频目录或0摄像头--img-size是推理分辨率--conf-thres是置信度阈值。运行后终端会打印每张图的检测结果类似image 1/2 .../bus.jpg: 640x480 4 persons, 1 bus, Done. (0.021s) Results saved to runs/detect/exp看到Results saved to就说明推理成功结果图在runs/detect/exp目录下。打开图片能看到检测框和类别标签。如果终端报No module named utils说明你不在项目根目录运行cd回 yolov5 根目录再执行即可。如果你想把推理结果接到自己的服务里可以用 Python 调用import torch model torch.hub.load(., custom, pathyolov5s.pt, sourcelocal) results model(data/images/bus.jpg) results.print() results.save()sourcelocal表示用本地代码而不是从 GitHub 拉避免网络问题。跑通这一步说明你的环境、代码、权重三者已经对齐。5. 本篇常见错排查清单除了上面三类还有几个坑值得单独说。第一个是pip install -r requirements.txt时pycocotools编译失败Windows 上尤其常见可以先用pip install pycocotools-windows替代或者直接注释掉这行因为只做推理不训练的话用不到它。第二个是opencv-python和opencv-python-headless冲突两个都装会导致cv2导入异常用pip list | grep opencv检查并卸载多余的那个。第三个是 CUDA out of memory--img-size调太大或 batch 太大都会触发推理时把--img-size降到 416 或 320 试试。第四个是AssertionError: No weights found检查--weights路径是否正确相对路径是相对于你执行命令的目录不是脚本所在目录。第五个是中文路径问题Windows 下项目路径含中文可能导致torch.load失败把项目挪到纯英文路径下即可。如果你在排错过程中需要快速验证某个模型接口是否可用可以用 TaoToken 的模型对话功能做一次简单请求确认网络和鉴权没问题再回到本地继续调。它的 API 地址是https://taotoken.net/api接入文档在https://taotoken.net/docAPI Keys 在https://taotoken.net/api-keys管理。注意这些只是辅助验证yolov5 的本地推理不依赖它。6. 排错之后把环境固化成可复现配置跑通一次不代表下次还能跑通建议把当前环境导出成requirements-lock.txtpip freeze requirements-lock.txt这样下次换机器或重装时直接pip install -r requirements-lock.txt就能复现完全一致的版本组合避免torch自动升级带来的 Upsample 类报错。另外把权重文件、代码版本、PyTorch 版本记在一个 README 里团队协作时能省掉大量沟通成本。如果你后续要做长期编码或 Agent 类任务需要频繁调用模型接口可以了解下 TaoToken 的 Coding Plan地址是https://taotoken.net/coding-plan适合把模型能力接进日常开发流。模型对话入口在https://taotoken.net/model-chat控制台在https://taotoken.net/console。这些链接都带了来源标记方便你回查。最后提醒一句yolov5 的报错九成来自版本不对齐遇到异常先别急着改代码先确认代码分支、权重版本、PyTorch 版本三者是否匹配。把这三个对齐detect.py基本都能顺利跑出结果。