3. 模型加载与权重验证：YOLO模型文件损坏、路径错误、类别文件不匹配的排查

模型加载失败，是YOLO实战中最常见的“开场白”。

我见过太多同学，代码写得漂漂亮亮，结果一运行就报错。然后开始怀疑人生，怀疑OpenCV版本，甚至怀疑自己是不是不适合学这个。

其实说白了，90%的加载问题都出在三个地方：文件坏了、路径错了、类别文件对不上。今天我们就把这几个坑一个一个填平。

3.1 模型文件损坏：你下载的.weights可能是个“空壳”

为什么会这样？

网络断点续传出错、硬盘空间不足、甚至Git LFS没正确拉取，都会导致你拿到的权重文件不完整。我遇到过最离谱的一次，是同事从百度网盘下载的模型，解压时没报错，但加载到一半就崩了——文件尾部被截断了。

怎么排查？我个人的习惯是三步走：

1. 校验文件哈希值：官方发布的模型通常会提供MD5或SHA256值。下载后用命令行比对一下，这是最靠谱的方法。
2. 检查文件头部：YOLO的.weights文件前几个字节是固定的版本号。用十六进制编辑器看一眼，如果开头不是预期的值，直接重下。
3. 分段加载测试：写个小脚本，只加载网络结构不加载权重，看会不会报错。如果结构能加载但权重不行，那基本就是文件坏了。

import cv2

# 第一步：只加载网络结构，验证cfg文件没问题
net = cv2.dnn.readNetFromDarknet('yolov4.cfg', '')
print("网络结构加载成功")

# 第二步：加载权重，如果这里崩了，大概率是权重文件问题
try:
    net = cv2.dnn.readNetFromDarknet('yolov4.cfg', 'yolov4.weights')
    print("权重加载成功")
except Exception as e:
    print(f"加载失败：{e}")
    # 常见错误：OpenCV(4.5.5) Error: Parsing error in layer ... 
    # 这种就是权重文件损坏或版本不匹配

3.2 路径错误：路径 vs 相对路径的“罗生门”

路径问题，说白了就是程序找不到文件。

你以为你写对了，但Python的工作目录可能跟你想象的不一样。尤其是用IDE（PyCharm、VS Code）运行时，工作目录默认是项目根目录，而不是脚本所在目录。

这里有个我常用的调试模板：

import os
import sys

# 获取当前脚本的路径
script_dir = os.path.dirname(os.path.abspath(__file__))

# 拼接模型文件路径
weights_path = os.path.join(script_dir, 'models', 'yolov4.weights')
cfg_path = os.path.join(script_dir, 'models', 'yolov4.cfg')

# 检查文件是否存在
if not os.path.exists(weights_path):
    print(f"❌ 权重文件不存在：{weights_path}")
    sys.exit(1)
if not os.path.exists(cfg_path):
    print(f"❌ 配置文件不存在：{cfg_path}")
    sys.exit(1)

# 再加载
net = cv2.dnn.readNetFromDarknet(cfg_path, weights_path)

路径错误的典型表现：

• FileNotFoundError：文件没找到，最直接。
• error: (-215:Assertion failed) !ssize.empty()：OpenCV内部断言失败，其实也是文件没读到。
• 程序不报错但检测结果全为空：路径指向了一个旧模型或错误模型。

3.3 类别文件不匹配：你的模型认识80类，但你的代码只给了20类

这个问题隐蔽性很高。

模型加载成功了，检测也能跑，但输出的类别编号跟你的类别文件对不上。比如模型输出的是“人”，你这边显示的是“自行车”。

为什么会这样？因为YOLO模型输出的只是类别索引（0, 1, 2...），真正显示成文字是靠你提供的coco.names文件。如果这个文件跟模型训练时用的不一致，那结果就是张冠李戴。

我曾经踩过一个坑：从网上下了一个自称“COCO 80类”的模型，但它的类别文件里只有79行。结果每次检测到“狗”，显示的都是“猫”。排查了半天，最后发现是类别文件少了一行“dog”。

验证类别文件的方法：

# 加载类别文件
with open('coco.names', 'r') as f:
    classes = [line.strip() for line in f.readlines()]

print(f"类别数量：{len(classes)}")
print(f"前10个类别：{classes[:10]}")

# 检查常见类别是否存在
expected = ['person', 'bicycle', 'car', 'motorbike', 'aeroplane', 'bus', 'train', 'truck', 'boat']
for cls in expected:
    if cls not in classes:
        print(f"⚠️ 缺少类别：{cls}")

3.4 一张图看懂排查流程

下面这张图是我自己总结的排查路线，每次遇到加载问题我就按这个走一遍，基本都能解决。

3.5 常见错误速查表

我把平时遇到最多的错误整理成了表格，方便你快速定位：

3.6 我的“三板斧”调试习惯

最后分享几个我个人的调试习惯，希望能帮你少走弯路：

• 每次换模型都重新校验：不要因为上次能用就跳过检查。环境变了、文件被覆盖了，这些事我见得太多了。
• 日志打印要详细：加载成功或失败，都要打印出文件路径、大小、类别数量。这样出问题时有据可查。
• 准备一个“最小测试用例”：一张图片、一个模型、一段最简单的加载代码。每次调试都先用这个跑通，再往上加功能。