pvt_v2_b3 是 PVTv2（Pyramid Vision Transformer v2）b3 规格的轻量级分层 Transformer 视觉 backbone 预训练权重，常用于语义分割、目标检测等任务的特征提取。新手首次接入时最常踩的坑集中在三类：输入图片尺寸、归一化参数、out_indices 配置。本文整理 8 个高频问题，并给出可对照的排查清单，帮你快速定位报错。

pvt_v2_b3 仓库速览：先认识这 4 个文件

关键结构参数（摘自 config.json）：

• 4 个 stage：stage1~stage4，隐藏通道数依次是 64 / 128 / 320 / 512
• 步长strides：[4, 2, 2, 2]，累计下采样倍数为32
• out_features：["stage1","stage2","stage3","stage4"]，out_indices：[0,1,2,3]（见 config.json）
• torch_dtype: float32，即权重默认按 FP32 加载（config.json）

下面 8 个坑，建议从上到下逐条自查。

坑 1：输入图片尺寸不是 32 的倍数

⚠️最高频报错。PVTv2 的总下采样倍数为 4×2×2×2 = 32，最后一个 stage 在特征重组（reshape_last_stage）时要求特征图整除。因此输入的高度和宽度都应是32 的倍数。

• ✅ 推荐尺寸：224×224、256×256、384×384、512×512（预处理器默认 224×224，见 preprocessor_config.json）
• ❌ 常见踩坑：225×225、321×321 这类"看起来差不多"的尺寸，会在最后阶段报 shape/reshape 不匹配的错误

自查方法：确认H % 32 == 0且W % 32 == 0。

坑 2：忘了归一化，或归一化参数不对

预处理器做了三件事（见 preprocessor_config.json）：

1. do_rescale：像素除以 255（rescale_factor ≈ 0.00392，即 1/255）
2. do_normalize：减均值、除标准差，用的是ImageNet 统计量
   • 均值：[0.485, 0.456, 0.406]
   • 标准差：[0.229, 0.224, 0.225]
   • 参数来源：preprocessor_config.json
3. do_resize：缩放到 224×224

这类错误不会报错，但模型输出会完全随机。如果你绕过官方 ImageProcessor 手写预处理，请严格照抄上面这组参数。

坑 3：out_indices 与下游代码解包数量不匹配

out_indices决定模型输出哪几个 stage的特征，默认[0,1,2,3]输出全部 4 个（config.json）。

典型踩法：

• 你改成了out_indices=[2, 3]只输出 2 个特征，但下游代码仍按 4 个变量解包，报"not enough values to unpack"
• 或者按位置取特征时搞混了"索引 0~3"与"stage1~stage4"的对应关系

自查方法：out_indices的长度 = 模型实际输出的特征数量，务必与下游解包/取用的数量一一对应；拿不准时保持默认 4 个，再在下游按需选取。

坑 4：搞错每个 stage 特征图的分辨率和通道

以默认 224×224 输入为例，四个 stage 的输出如下：

自查方法：写下游 head（分割头、检测头）时，核对自己用的 stage 索引对应的分辨率和通道数是否匹配，尤其注意 stage3 的通道是 320 而不是常见的 256/384。

坑 5：把 backbone 权重直接当训练好的分类器用

该权重的architectures为PvtV2ForImageClassification，id2label是LABEL_0~LABEL_999的占位标签（config.json），说明它本质是通用视觉 backbone 预训练权重，并非面向你的数据集微调好的分类器。

• 做分割 / 检测 / 深度估计：把它当 backbone，接上对应任务的 head 再训练
• 做分类：直接推理会在你的新类别上输出随机结果，需要微调分类头

坑 6：批量推理时混入不同尺寸或通道顺序错误

• 同一个 batch 内的图片必须尺寸一致，否则会拼接失败
• 手写张量输入时注意通道顺序：ImageProcessor 期望的数值数组是H×W×C（通道在后）的 uint8 图像；如果你传的是 H×C×W 的张量而没有走标准预处理流程，图像会被"转置"理解，结果静默出错

自查方法：优先使用仓库自带的PvtImageProcessor（preprocessor_config.json），少写自定义预处理逻辑。

坑 7：resize 插值模式与预期不符

预处理默认resample: 2，即双三次插值（bicubic）（preprocessor_config.json）。

• 如果你自己先用最近邻/双线性把图缩到 224，再送入会do_resize的处理器，会被二次缩放
• 小目标、文字类图像对插值方式敏感，换插值模式可能带来可感知的精度差异

自查方法：只保留一处 resize，确认整条链路只缩放一次。

坑 8：dtype 与设备不匹配

该权重是float32（config.json），model.safetensors 体积也不小。

• 强行以 FP16 加载但没做转换，可能得到乱码输出或数值异常
• 模型与输入张量一个在 GPU 一个在 CPU，会直接报 device mismatch

自查方法：加载后确认model.device与输入张量设备一致；显存不足时再做统一的半精度转换，而不是半信半疑地"只降一半"。

8 个坑速查表：出问题时先看这里

按这张清单从上到下排查，绝大多数 pvt_v2_b3 的接入问题都能在 10 分钟内定位到根因。