全卷积网络行人分割实战：Penn-Fudan 数据管线与训练避坑

简介面向图像分割入门者与行人检测实践者的全卷积网络FCN项目资料围绕 Penn-Fudan Database 展开可用于理解端到端像素级预测、上采样与跳跃连接等关键机制并完成从掩模加载、训练到预测的完整流程。压缩包共 533 个文件约 184.68MB主要为 png 图像与分割掩模、txt 说明及训练日志、py 训练脚本辅以 npy 指标结果、xml 标注和模型权重记录目录较完整便于复现实验与对照调试。已有 507 人学习下载适合课程作业、毕业设计或分割任务入门参考。资料保留多组训练参数与评估结果可帮助读者观察不同轮次、学习率和优化器设置下的表现差异并据此整理实验记录、排查训练问题逐步搭建自己的行人分割基线。1. 170 张图跑全卷积网络Penn-Fudan 行人分割的第一脚油门第一次把全卷积网络FCN接到 Penn-Fudan 这个数据集上时我盯着验证集 0.03 的 mIoU 看了十分钟。查了半天以为是学习率玄学最后发现是掩码被我读成了调色板索引前景像素全被当成背景喂进去了。这个数据集小得可怜——170 张街景图、345 个行人实例标注是逐像素的实例掩码任务是把人从画面里抠出来。它适合的人群很明确想入门语义分割、又不想被几十 G 大 dataset 劝退的开发者想快速验证一个 backbone 或损失函数改动的实验党以及需要在教学场景里跑通「数据读取-训练-推理-可视化」全链路的人。局限也得先说清楚它只有前景/背景两类样本量撑不起泛化能力别指望训完就能拿去分割别的物体。2. 项目骨架与技术选型FCN 主干、数据组织与依赖分层2.1 为什么是 FCN把分割拆成逐像素二分类全卷积网络这个名字听着唬人核心动作只有一句话把分类网络末尾的全连接层换成卷积层让输出从「一个类别向量」变成「一张 H×W 的分数图」。传统 CNN 做分割的笨办法是滑窗每个像素位置裁一块 patch 送进网络判断中心点属于谁170 张图能跑但推理时间和窗口大小成正比实际没法用。FCN 直接对整图做一次前向主干下采样 32 倍末端的 1×1 卷积把通道数压到类别数最后用双线性插值把这张 1/32 的 score map 拉回原图尺寸逐像素取 argmax 就是分割结果。在这个项目里类别数取 2索引 0 是背景索引 1 是行人。这个选择决定了后面几乎所有代码的形状——损失函数用交叉熵而不是 BCE虽然二分类两者等价但保留 num_classes 维度方便日后扩类评估指标算前景 IoU 而不是全图准确率背景占比太高全猜背景也能有 90% 准确率这是典型的自欺欺人。主干常见做法是 ResNet50torchvision 里fcn_resnet50已经把 backbone、分类头、上采样三部分拼好了改一个卷积层的输出通道就能接自己的数据。我一般不会一上来就换更深的 backbone170 张图训 ViT 那种参数量过拟合是必然的玄学调参救不回来。FCN 原论文里还有 FCN-16s、FCN-8s 的 skip 结构把浅层的高分辨率特征和深层的语义特征相加。torchvision 的实现没有做这个融合就是纯粹的单尺度 32 倍上采样边缘会比较糊。如果你后面发现行人轮廓锯齿严重可以先从这个点下手改而不是急着加数据。2.2 目录结构数据、代码、产物三块分开项目目录不需要复杂但边界要清楚。我习惯按下面这样摆好处是换数据集时只动data/换实验时只动runs/pedestrian-fcn/ ├── data/ │ ├── PennFudanPed/ │ │ ├── PNGImages/ # 原始 RGB 图170 张 │ │ ├── PedMasks/ # 实例掩码与图片同名 │ │ └── Annotation/ # 原始标注训练时不读 │ └── splits/ │ ├── train.txt # 一行一个文件名不带扩展名 │ └── val.txt ├── src/ │ ├── dataset.py # Dataset 与 collate_fn │ ├── model.py # 模型组装与改头 │ ├── engine.py # 训练/验证循环 │ ├── metrics.py # IoU、Dice │ └── transforms.py # 同步增强 ├── tools/ │ ├── train.py │ ├── predict.py │ └── visualize.py ├── configs/ │ └── fcn_r50.yaml └── runs/ # 权重、日志、预测可视化两个细节值得强调。第一PNGImages和PedMasks里的文件必须严格同名只差扩展名Dataset 里如果用两次sorted(os.listdir())再按下标取一旦某个目录多一个隐藏文件比如.DS_Store图与掩码就整体错位一位这种 bug 不会报错只会让 loss 曲线难看。稳妥写法是先取图片列表再把后缀替换成掩码路径。第二划分文件用 txt 存文件名而不是随机random_split随机种子忘了固定、或者中途改了数据集长度训练集和验证集会悄悄重叠指标虚高。2.3 依赖与环境版本对齐比装最新版重要组件建议版本说明Python3.9 / 3.103.11 以上部分 torchvision 轮子不稳PyTorch2.0 及以上需要torchvision.models.segmentation的 weights 枚举torchvision与 torch 同源版本错配是最常见的 ImportError 来源Pillow9.x 及以上读调色板 PNG 掩码numpy1.24 及以上掩码转数组opencv-python可选只用于可视化叠加训练不需要安装时直接按官方命令装配套的 torch torchvision不要分别pip install torch和pip install torchvision让 pip 自己解析它经常给你配出一个二进制不兼容的组合报错信息还指向莫名其妙的_C模块。判断环境是否真的可用跑一行就够python -c import torch, torchvision; print(torch.__version__, torchvision.__version__); \ from torchvision.models.segmentation import fcn_resnet50; print(ok)输出版本号并打印ok说明算子库和模型定义都在。如果这一步就挂了后面所有调试都是白费力气。3. 数据管线拆解从调色板 PNG 到训练张量3.1 数据集类文件名对齐与实例 id 的处理Penn-Fudan 的掩码不是 0/1 二值图而是每个行人一个独立 id 的实例图背景是 0第一个行人是 1第二个是 2依此类推。语义分割只需要「是不是人」所以要把所有非零 id 压平成 1。这一步的写法直接决定了你会不会踩到我开头说的那个坑。import os import numpy as np import torch from PIL import Image from torch.utils.data import Dataset class PedestrianSegDataset(Dataset): def __init__(self, root, split_file, transformsNone): self.root root self.transforms transforms # 只从划分文件读图片名避免两个目录 listdir 顺序不一致导致错位 with open(split_file, r, encodingutf-8) as f: self.names [line.strip() for line in f if line.strip()] def __len__(self): return len(self.names) def __getitem__(self, idx): name self.names[idx] img_path os.path.join(self.root, PNGImages, name .png) mask_path os.path.join(self.root, PedMasks, name _mask.png) img Image.open(img_path).convert(RGB) # 掩码必须按调色板索引读不能 convert(RGB)否则 id 全被映射成颜色 raw np.array(Image.open(mask_path)) obj_ids np.unique(raw) obj_ids obj_ids[obj_ids ! 0] # 去掉背景 # 广播比较得到 (N, H, W) 的布尔实例栈再沿实例维归并 inst raw obj_ids[:, None, None] seg np.zeros(raw.shape, dtypenp.uint8) seg[inst.any(axis0)] 1 # 前景统一成 1 seg torch.as_tensor(seg, dtypetorch.long) img, seg self.transforms(img, seg) if self.transforms else (img, seg) return img, seg逻辑上分三段。第一段解决「读哪张」划分文件里只存文件名主干图片路径拼.png掩码路径拼_mask.png两边强绑定杜绝错位。第二段解决「读成什么」Image.open(mask_path)之后绝对不能convert(RGB)那样调色板索引会被转成真实颜色值np.unique出来是一堆 100 多 200 多的数字前景判定全乱。第三段解决「压成几类」obj_ids[:, None, None]把一维 id 数组扩成(N,1,1)和(H,W)广播后得到每个实例的布尔图any(axis0)沿实例维归并相邻或重叠的行人也被合并成一个前景区域——语义分割本来就不区分个体这正是想要的效果。参数上split_file传的是划分 txt 的绝对或相对路径root指向PennFudanPed目录。返回的seg是long类型、形状(H, W)值域{0,1}这是nn.CrossEntropyLoss期望的标签格式它内部会做(N,C,H,W)与(N,H,W)的匹配。如果你把seg存成float损失函数不会报错但会按回归处理训练直接跑飞。3.2 同步增强图像和掩码必须走同一套几何变换分割任务的数据增强和分类任务最大的区别是翻转、裁剪、缩放这类几何变换图像和掩码必须用完全相同的参数执行。torchvision 的transforms对图像和标签是两个独立调用RandomHorizontalFlip各自抛一次硬币就会出错位。import random import torchvision.transforms.functional as TF class SyncTransform: def __init__(self, size(256, 512), hflip_prob0.5): self.size size self.hflip_prob hflip_prob def __call__(self, img, mask): # 先用双线性把图像缩到统一尺寸 img TF.resize(img, self.size, interpolationTF.InterpolationMode.BILINEAR) # 掩码只能用最近邻双线性会插出 0.5 这种非法类别值 mask TF.resize( mask.unsqueeze(0).float(), self.size, interpolationTF.InterpolationMode.NEAREST ).squeeze(0).long() if random.random() self.hflip_prob: img TF.hflip(img) mask TF.hflip(mask) img TF.to_tensor(img) # 归一到 [0,1]HWC - CHW img TF.normalize(img, mean[0.485, 0.456, 0.406], std[0.229, 0.224, 0.225]) return img, mask三个参数值得逐个说清。size定为(256, 512)是权衡结果Penn-Fudan 原图长宽比差异大统一到接近 2:1 能保留行人的纵向细节同时让 batch 能拼起来如果你的显存够可以放到(512, 1024)小目标召回会明显改善。掩码的interpolation必须是NEAREST双线性插值会在前景和背景交界处产生小数转成long后可能落到 2、3 这种不存在的类别上训练时报 Target out of bounds 或者静默学出噪声。归一化用 ImageNet 的均值和方差是因为主干加载的是 ImageNet 预训练权重输入分布对齐了冻结主干时特征才有意义。TF.resize对 PIL Image 和 Tensor 都支持但to_tensor必须在 resize 之后——先转张量再 resizePIL 的尺寸信息就丢了得手动传 size代码容易写乱。这套同步变换我只保留翻转和缩放颜色抖动、Cutout 这类只在图像上做的增强可以加但不要动掩码否则标签和像素的对应关系就断了。3.3 collate_fn为什么分割任务也要自己拼 batch单张图的尺寸归一之后理论上default_collate就能拼。但真实项目里我仍然会写一个显式的collate_fn原因有两个一是推理阶段需要把原始尺寸带出来方便把预测结果 resize 回原图做可视化二是后续如果要接多尺度训练或者实例级任务返回结构会变早留好扩展位比后期重构省事。def collate_fn(batch): imgs, masks, sizes [], [], [] for img, mask in batch: imgs.append(img) masks.append(mask) sizes.append(torch.as_tensor(mask.shape)) # 记录 (H, W)推理时还原用 return torch.stack(imgs, 0), torch.stack(masks, 0), torch.stack(sizes, 0)torch.stack要求同 batch 内形状一致所以上游的SyncTransform必须把尺寸固定死这是它存在的另一个理由。sizes返回形状(B, 2)可视化脚本里拿它做F.interpolate的目标尺寸。如果你的数据里有极端长宽比、不想统一缩放那就得改成 padding 到 batch 内最大尺寸同时返回每张图的真实尺寸逻辑会复杂一档170 张图的场景没必要。DataLoader 侧我一般这样配batch_size4256×512 下 8G 显存够用num_workers4shuffleTrue只给训练集pin_memoryTrue在 GPU 上能省一点拷贝时间。验证集不要 shuffle否则可视化对不上文件名排查问题时很痛苦。4. 模型与训练循环改头、损失与指标4.1 组装 fcn_resnet50换分类头与冻结策略torchvision 的fcn_resnet50默认输出 21 类VOC 的类别数拿来即用会对不上我们的 2 类。改的地方只有一个卷积层但位置要找准。import torch import torch.nn as nn from torchvision.models.segmentation import fcn_resnet50, FCN_ResNet50_Weights def build_model(num_classes2, freeze_backboneTrue): model fcn_resnet50(weightsFCN_ResNet50_Weights.DEFAULT) # classifier 是 Sequential最后一项是 1x1 卷积输出通道即类别数 in_ch model.classifier[4].in_channels model.classifier[4] nn.Conv2d(in_ch, num_classes, kernel_size1) if freeze_backbone: for p in model.backbone.parameters(): p.requires_grad False # 关键冻结参数不等于冻结 BN 统计量这里把主干 BN 切到 eval for m in model.backbone.modules(): if isinstance(m, nn.BatchNorm2d): m.eval() return modelmodel.classifier的结构是Conv3x3 - BN - ReLU - Dropout - Conv1x1索引 4 才是那个决定类别数的 1×1 卷积改成新卷积后in_channels沿用原来的 2048//4512输出换成 2。这一步不初始化权重也能训PyTorch 默认用 Kaiming 初始化但如果你想更稳可以手动nn.init.normal_(model.classifier[4].weight, 0, 0.01)。冻结主干的意图是ResNet50 有 2000 多万参数170 张图微调全部参数必然过拟合只训分类头约 100 万参数收敛快且不容易崩。但requires_gradFalse只挡住梯度挡不住 BatchNorm 在train()模式下继续更新 running_mean 和 running_var主干统计量会被小数据集带偏。所以那段m.eval()是必须的——这个坑我在别的项目里翻过车训练 loss 一路下降验证集 mIoU 抖得像心电图查了两天才定位到 BN。前向时注意返回结构不是 Tensor 而是OrderedDictout model(imgs) # dict: {out: Tensor(B,2,H,W), aux: ...} logits out[out]取错 key 会直接KeyError或者在别的模型上拿到的out本身就是 Tensor代码复制来复制去就混了。我习惯在engine.py里包一层forward_logits(model, x)把这种差异挡在训练循环外面。4.2 训练循环损失、优化器与学习率二分类语义分割的标准配置是交叉熵 AdamW学习率 1e-3 只给分类头如果要解冻主干则主干用 1e-4靠参数组分开放。import torch.nn.functional as F def train_one_epoch(model, loader, optimizer, device, epoch): model.train() for m in model.backbone.modules(): # 每轮重新压住主干 BN if isinstance(m, nn.BatchNorm2d): m.eval() total_loss 0.0 for step, (imgs, masks, _) in enumerate(loader): imgs, masks imgs.to(device), masks.to(device) logits model(imgs)[out] # (B, 2, H, W) loss F.cross_entropy(logits, masks) # masks 为 (B, H, W) 的 long optimizer.zero_grad(set_to_noneTrue) loss.backward() optimizer.step() total_loss loss.item() return total_loss / len(loader)cross_entropy内部自动做 softmax所以logits不要提前过激活函数重复 softmax 会让梯度变得极小表现为 loss 降得很慢、看起来像学习率设小了。masks的 dtype 必须是long形状(B,H,W)与logits的(B,C,H,W)在通道维上对齐多余或缺失的维度都会报形状错误。优化器这样配head_params [p for n, p in model.named_parameters() if p.requires_grad] optimizer torch.optim.AdamW(head_params, lr1e-3, weight_decay1e-4) scheduler torch.optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max30)weight_decay1e-4对小数据集有实打实的正则作用别省。T_max设成总 epoch 数余弦退火在最后几个 epoch 把学习率压到接近 0收敛曲线会平滑很多。batch_size4、30 个 epoch、单卡170 张图大约 20 分钟能跑完这个速度足够你一天试十几种改动。4.3 评估IoU 只算前景别被准确率骗了前面提过行人只占画面很小一块全预测背景的模型能有 90% 以上的像素准确率但 mIoU 是 0。所以评估函数只算前景类的 IoU必要时补一个 Dice。torch.no_grad() def evaluate(model, loader, device, threshold0.5): model.eval() inter, union 0.0, 0.0 for imgs, masks, _ in loader: imgs imgs.to(device) prob torch.softmax(model(imgs)[out], dim1)[:, 1] # 前景概率 pred (prob threshold).long() masks masks.to(device) inter ((pred 1) (masks 1)).sum().item() union ((pred 1) | (masks 1)).sum().item() return inter / max(union, 1e-6)threshold默认 0.5但小数据集上模型往往偏保守前景概率普遍偏低0.35~0.45 有时能多拿两三个点 IoU这个值要在验证集上扫一遍别用测试集调。union加了1e-6防止验证集里恰好没有行人的 batch 造成除零。如果想同时看召回情况把inter/union换成 Dice2*inter / (pred.sum()masks.sum())数值上通常比 IoU 高十来个点报告指标时标清楚是哪个别混着比较。评估阶段一定要model.eval()且包torch.no_grad()。前者关掉 Dropout、切到 BN 的 running 统计量后者省显存。忘了eval()的话同一个模型两次评估能得到差好几个点的结果你会误以为是随机种子的问题。5. 避坑与排查五个把我按在地上摩擦的现场5.1 现象loss 稳定下降mIoU 一直在 0.02 附近原因几乎可以断定是掩码读取错了。Image.open(mask_path)得到的是调色板模式P 模式如果中间convert(RGB)了np.unique出来是一堆颜色值obj_ids ! 0的筛选逻辑虽然还能跑但前景像素几乎全部漏掉模型学到的就是「全预测背景」。解决读掩码时只做np.array()不做任何 convert拿一张图打印np.unique(raw)应该看到[0, 1, 2, ...]这样的连续整数看到三位数就是错了。5.2 现象训练集指标很好验证集一塌糊涂且两次运行差异巨大先查划分是否重叠。用 txt 存划分、中途又改过数据集目录时训练集和验证集的文件名可能有交集更隐蔽的情况是用random_split但没固定 seed每次启动划分都不一样。解决启动时打印两个集合的文件名列表长度和交集大小交集必须为 0。另外确认评估前调了model.eval()这个漏掉的表现和划分重叠很像都是指标不稳。5.3 现象训练到一半报 Target x is out of bounds掩码 resize 用了双线性或默认插值插值产生了 0.5、1.3 这类值转long后可能变成 2超出num_classes2的范围。解决掩码的所有几何变换统一用InterpolationMode.NEAREST如果已经用了最近邻还报错检查是不是某张图的标注里存在大 id比如 255 的忽略区域在 Dataset 里显式把大于 1 的值 clip 到 1。5.4 现象冻结主干后显存还是炸或者训练速度没变快requires_gradFalse只省下梯度和优化器状态主干的前向激活值照样占显存。256×512 输入下 ResNet50 的激活不小batch_size 开 16 必然 OOM。解决把batch_size降到 4~8或者用torch.utils.checkpoint对 backbone 做梯度检查点冻结时意义不大。另外确认你没有在 DataLoader 里num_workers0且 transform 里写了重活CPU 拖慢会让人误以为是 GPU 的问题。5.5 现象推理脚本里模型输出全是 0但训练时明明正常三个原因按概率排序忘了model.eval()忘了torch.no_grad()导致显存堆积预处理和训练不一致——最常见的是推理时漏了 ImageNet 归一化或者to_tensor之后又乘了一次 255。解决把训练和推理的 transform 抽成同一个类只在训练分支加随机翻转其余完全共用推理前打印输入张量的min/max/mean和训练时打印的值对比对不上就一定是预处理的问题。6. 二次开发把二分类 FCN 改成多类别、换主干并验证真要做二次开发第一个改动通常是从「行人/背景」扩到多类别。改动点比想象中少num_classes从 2 改成 NDataset 里把实例 id 归并改成保留语义 id损失函数不用动。真正容易出错的是标签映射——Penn-Fudan 只有行人扩类意味着你要接别的数据集两套 id 体系必须重映射到统一索引否则会出现「人」和「车」共用一个 id 的情况训练 loss 正常但混淆矩阵一团糟。我一般会在configs/下放一个label_map.yamlDataset 读它做映射比散落在代码里的 if-else 好维护。第二个改动是换主干。torchvision 里fcn_resnet50换成fcn_mobilenet_v3_large只需要改构造函数但classifier的索引位置会变MobileNet 版本的分类头只有两层照抄classifier[4]会 IndexError。稳妥做法是先打印model.classifier看结构再定位最后一个 1×1 卷积import torch.nn as nn for i, layer in enumerate(model.classifier): if isinstance(layer, nn.Conv2d) and layer.kernel_size (1, 1): model.classifier[i] nn.Conv2d(layer.in_channels, num_classes, 1)第三个改动是导出部署。分割模型导出 ONNX 时torchvision 的 FCN 返回 dicttorch.onnx.export不认得包一层只返回 Tensor 的 wrapper同时把动态尺寸打开dynamic_axes指定 H、W 维否则推理时换分辨率就报错。导出后务必用同一张图对比 PyTorch 和 ONNX Runtime 的输出最大绝对误差超过 1e-3 就说明插值算子对不上多半是align_corners参数在两边的默认值不同。改造方向改动文件需要重训常见翻车点扩多类别dataset.py、configs是标签 id 未统一映射换轻量主干model.py是分类头索引写死导出 ONNXtools/export.py否返回 dict、动态轴未开换损失DiceCEengine.py是Dice 在空 mask 上除零验证方法我固定走三步先在小样本20 张上过拟合训练 loss 能压到 0.05 以下说明数据管线和模型连通性没问题再全量训练 30 epoch看验证 IoU 是否单调最后拿三张最难的图远景、遮挡、逆光肉眼比对预测和标签。这三步走完改动是否真的有效基本就有答案了比盯着 loss 曲线猜靠谱得多。那次掩码读错之后我每次接入新数据集都强制先跑一遍「打印一张图的 mask 唯一值 可视化叠图」确认像素对齐才动手写训练脚本。希望这些能帮你少走两晚弯路。本文还有配套的精品资源点击获取