机器学习与深度学习 / 系统课时
定位线上预测与离线结果差异
定位线上预测与离线结果差异
线上接口返回的类别一旦与离线验证不一致,不要先怀疑模型“失效”。最有效的方法是固定同一份原始输入,在解码、预处理、模型版本、运行精度和类别映射五个边界逐层比对,找到第一个发生偏离的位置。
学习目标
- 能按固定顺序比对线上与离线推理链路,快速缩小故障范围。
- 能用张量差异、模型版本和类别映射证据判断差异来自哪一层。
- 能在修复后用同一输入验证 logits 与最终类别重新对齐。
先固定同一份输入
排查必须从完全相同的原始图片字节开始。若离线脚本读的是本地 JPEG,而服务收到的是客户端重新压缩、旋转或转码后的图片,后续任何数值比较都没有意义。先记录请求体哈希、解码后的宽高、色彩模式与 EXIF 方向,再进入预处理。
服务链路中最值得保留的是“边界证据”:解码后图像摘要、预处理后张量形状与数值范围、模型文件哈希或版本号、推理 dtype,以及最终使用的类别列表版本。只要这些信息可观测,问题通常能在一次复现中被定位。

用最小脚本检查边界
下面的可运行示例故意构造一张纯红图片。正确链路会得到 red,而把 RGB 错当成 BGR 后会得到 blue。真实项目可把这里的 preprocess 和 ColorCNN 替换为生产代码,但保留相同的逐层比较方式。
from io import BytesIO
import numpy as np
import torch
from PIL import Image
from torch import nn
CLASSES = ['red', 'blue']
OFFLINE_MODEL_VERSION = 'cnn-demo-v1'
SERVICE_MODEL_VERSION = 'cnn-demo-v1'
def decode(raw: bytes) -> Image.Image:
return Image.open(BytesIO(raw)).convert('RGB')
def preprocess(image: Image.Image, bgr: bool = False) -> torch.Tensor:
arr = np.array(image, dtype=np.float32) / 255.0
if bgr:
# 模拟线上 OpenCV 链路忘记从 BGR 转回 RGB。
arr = arr[..., ::-1].copy()
return torch.from_numpy(arr).permute(2, 0, 1).unsqueeze(0)
class ColorCNN(nn.Module):
def __init__(self) -> None:
super().__init__()
self.conv = nn.Conv2d(3, 2, kernel_size=1, bias=False)
with torch.no_grad():
self.conv.weight.zero_()
# 类别 0 只看红通道,类别 1 只看蓝通道。
self.conv.weight[0, 0, 0, 0] = 1.0
self.conv.weight[1, 2, 0, 0] = 1.0
def forward(self, x: torch.Tensor) -> torch.Tensor:
return self.conv(x).mean(dim=(2, 3))
def top1(logits: torch.Tensor) -> str:
return CLASSES[int(logits.argmax(dim=1).item())]
image = Image.new('RGB', (2, 2), (255, 0, 0))
buffer = BytesIO()
image.save(buffer, format='PNG')
raw = buffer.getvalue()
offline_image = decode(raw)
service_image = decode(raw)
x_offline = preprocess(offline_image)
x_service = preprocess(service_image)
x_bgr_bug = preprocess(service_image, bgr=True)
model = ColorCNN().eval()
with torch.inference_mode():
y_offline = model(x_offline)
y_service = model(x_service)
y_bgr_bug = model(x_bgr_bug)
print(f'decode_size_offline={offline_image.size} decode_size_service={service_image.size}')
print(f'input_max_diff={(x_offline - x_service).abs().max().item():.6f}')
print(f'logits_max_diff={(y_offline - y_service).abs().max().item():.6f}')
print(f'offline_top1={top1(y_offline)} service_top1={top1(y_service)}')
print(f'bgr_bug_input_max_diff={(x_offline - x_bgr_bug).abs().max().item():.6f}')
print(f'bgr_bug_top1={top1(y_bgr_bug)}')
print(f'model_version_match={OFFLINE_MODEL_VERSION == SERVICE_MODEL_VERSION}')
print(f'class_mapping_match={CLASSES == ['red', 'blue']}')预期输出
decode_size_offline=(2, 2) decode_size_service=(2, 2)
input_max_diff=0.000000
logits_max_diff=0.000000
offline_top1=red service_top1=red
bgr_bug_input_max_diff=1.000000
bgr_bug_top1=blue
model_version_match=True
class_mapping_match=True这个结果说明:正常线上链路与离线链路在输入张量和 logits 上完全一致;一旦通道顺序错误,差异在“预处理张量”这一层就已经出现,因此无需继续怀疑类别映射或模型权重。
按固定顺序收窄根因
| 检查边界 | 应比较的证据 | 常见根因 |
|---|---|---|
| 输入解码 | 原始字节哈希、宽高、RGB/RGBA、EXIF 方向 | 客户端压缩、自动旋转、透明通道处理不同、RGB/BGR 混用 |
| 预处理 | 张量 shape、dtype、数值范围、抽样像素、最大绝对差 | Resize 插值、Crop 顺序、归一化均值方差、NHWC/NCHW 不一致 |
| 模型版本 | 文件哈希、模型版本、提交号、eval() 状态 |
发布了旧权重、加载错文件、Dropout 或 BatchNorm 仍在训练模式 |
| 运行精度 | 设备、后端、FP32/FP16、logits 差值 | 半精度舍入、算子实现差异、量化参数不同 |
| 类别映射 | 类别数组内容和顺序、索引到名称的映射 | 训练与服务的 classes.json 版本不同、排序规则变化 |
定位时只追踪“第一个不一致点”。如果预处理张量已经不同,后面的 logits 与类别不同只是结果,不是新的根因;如果张量完全一致而 logits 不同,再检查模型文件、eval()、设备与精度。
处理精度差异与修复验证
FP16、量化或不同硬件后端不一定能做到逐位相等,因此不要把“非零差值”直接判定为错误。应在同一批固定样本上比较 logits 的最大绝对差,并根据模型和精度模式设置明确容差,同时观察 top-1 或 top-k 是否跨过决策边界。
修复后重新发送同一份原始图片字节,依次确认解码属性一致、预处理张量一致或处于容差内、模型版本一致、logits 差异符合预期、类别映射完全相同。只有这些证据都重新对齐,线上与离线结果一致才是可复现的修复,而不是偶然“测起来正常”。