计算机视觉 / 系统课时

排查推理结果异常

排查推理结果异常

当检测框缺失、类别错乱、框位置偏移或置信度异常时,不能只反复调阈值。本课建立一条可复现的排查链路,从权重、类别、预处理、后处理到坐标还原逐层验证,最终定位真正出错的环节。

学习目标

  • 能按固定顺序定位推理异常所在层级
  • 能验证权重类别、输入张量和坐标还原是否一致
  • 能用对照实验判断阈值调整是否合理

先判断异常属于哪一层

推理结果异常通常来自五个位置:加载了错误权重、类别映射不一致、图像预处理与训练不一致、置信度或 NMS 阈值不合适、坐标没有从缩放图正确还原到原图。先根据现象缩小范围,再做验证,效率远高于同时修改多个参数。

现象 优先检查
所有图片都没有框 权重、输入尺寸、归一化、置信度阈值
有框但类别名称错误 names 顺序、数据集 YAML、部署端类别表
框整体偏移或尺寸不对 Letterbox 填充、坐标缩放、原图宽高顺序
重复框很多 IoU 阈值、NMS 是否执行、类别无关 NMS 配置
离线正常、服务异常 BGR/RGB、张量维度、FP16、前后处理差异

推理异常分层排查流程

固定输入并建立基线

选择一张长期不变、人工确认过标注的测试图片,固定权重、输入尺寸和阈值。每次只改一个变量,并把检测图片与标签同时保存,避免凭肉眼比较不同批次结果。

bash
# 固定权重、图片、尺寸和阈值,建立可重复的基线
python detect.py \
  --weights runs/train/exp/weights/best.pt \
  --source data/images/bus.jpg \
  --imgsz 640 \
  --conf-thres 0.25 \
  --iou-thres 0.45 \
  --save-txt \
  --save-conf \
  --project runs/diagnose \
  --name baseline \
  --exist-ok

预期结果

text
runs/diagnose/baseline/
├── bus.jpg
└── labels/
    └── bus.txt

实际日志中的推理耗时和保存路径可能不同,但目录中应同时出现可视化图片与对应标签文件。若标签文件为空,先检查权重和预处理;若标签正确而图片框错误,重点检查绘制与坐标还原。

核对权重与类别映射

权重必须来自预期训练任务,类别数量和顺序必须与推理端使用的名称表一致。不要只看文件名,应直接读取权重中的 model.names。仅对可信的本地权重执行下面的检查,因为 torch.load 会反序列化文件内容。

python
import torch

weights_path = "runs/train/exp/weights/best.pt"

# 新旧 PyTorch 对 weights_only 参数的支持不同,兼容两种加载方式
try:
    checkpoint = torch.load(
        weights_path, map_location="cpu", weights_only=False
    )
except TypeError:
    checkpoint = torch.load(weights_path, map_location="cpu")

model = checkpoint.get("ema") or checkpoint["model"]
names = model.names
items = sorted(names.items()) if isinstance(names, dict) else list(enumerate(names))

print(f"num_classes={len(items)}")
for class_id, class_name in items:
    print(f"{class_id}: {class_name}")

预期输出

text
num_classes=<N>
0: <CLASS_0>
1: <CLASS_1>
...

将输出与数据集 YAML 中的 names、服务端类别数组以及前端展示文案逐项对照。数量相同但顺序不同,也会造成“框正确、名称错误”。

检查图像预处理

YOLOv5 常见输入流程是读取 BGR 图像、执行 Letterbox、转换为 RGB、从 HWC 变为 CHW、转为连续数组,再归一化到 0~1。部署代码漏掉任一步,都可能让模型输出明显退化。

python
import cv2
import numpy as np
from utils.augmentations import letterbox

image = cv2.imread("data/images/bus.jpg")
if image is None:
    raise FileNotFoundError("未找到测试图片")

# 固定 auto=False,确保输出尺寸可直接与部署端对照
resized, ratio, pad = letterbox(image, new_shape=640, auto=False)

# BGR 转 RGB、HWC 转 CHW,并归一化到 0~1
tensor = resized[:, :, ::-1].transpose(2, 0, 1)
tensor = np.ascontiguousarray(tensor, dtype=np.float32) / 255.0

print(f"shape={tensor.shape}")
print(f"range=({tensor.min():.3f}, {tensor.max():.3f})")
print(f"ratio={ratio}, pad={pad}")

预期输出

text
shape=(3, 640, 640)
range=(<MIN_0_TO_1>, <MAX_0_TO_1>)
ratio=(<RATIO_X>, <RATIO_Y>), pad=(<PAD_X>, <PAD_Y>)

如果形状不是 CHW、数值仍在 0~255、颜色通道未转换,先修复预处理。训练与推理的 Letterbox 参数也应一致,尤其要关注 auto、目标尺寸和步长约束。

验证后处理与坐标还原

模型输出的框坐标基于 Letterbox 后的图像,绘制到原图前必须去掉填充并按缩放比例还原。推荐复用 YOLOv5 自带的 non_max_suppression 和 scale_boxes,不要在多个服务中各写一套近似实现。

排查时同时记录三组数据:NMS 前候选框数量、NMS 后框数量、还原后的最终坐标。若 NMS 前已有正确候选而最终框消失,问题在阈值或 NMS;若数值正确但绘制偏移,问题在坐标还原或宽高顺序。

最后再调整阈值

conf-thres 过高会漏检,过低会引入大量低质量框;iou-thres 过低容易过度抑制相邻目标,过高则可能保留重复框。先确认权重、类别、预处理和坐标链路正确,再用同一验证集做单变量对照。

建议依次测试 conf-thres 为 0.15、0.25、0.40,并保留同一 iou-thres。比较的不只是“看起来更好”,还应记录漏检数、误检数和重复框数量,选择符合业务成本的阈值。

本课总结

  • 推理异常应按权重、类别、预处理、后处理和坐标还原的顺序逐层定位
  • 固定测试输入并一次只改一个变量,才能形成可靠的对照结论
  • 阈值只负责取舍已有预测,不能修复错误的类别映射或图像处理链路

下一课预告

下一课将为数据集、训练配置、代码提交和模型权重建立统一版本关系,使每个线上模型都能追溯、复现并安全回滚。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查推理结果异常

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通