简介面向图像分割入门与进阶人群这份资源以VOC和Cityscapes数据集为依托完整演示了基于PyTorch训练DeepLabv3语义分割模型的流程覆盖数据预处理、ASPP模块与解码器构建、优化器与学习率配置、IoU评估及模型微调等核心环节适合希望从零跑通项目并理解多尺度特征融合原理的读者。压缩包共43个文件其中23个Python脚本按datasets、network、utils、metrics等模块组织覆盖数据加载、网络定义、损失函数、训练评估与预测17张可视化图片直观展示输入图像、目标掩码与预测结果2个txt文件提供依赖环境说明1个md为项目说明文档整体大小2.13MB结构清晰、便于检索复用。目前已有493人下载学习通过源码与样例输出对照研读可快速掌握DeepLabv3的实际训练技巧并能够迁移到自动驾驶、医学影像等真实分割任务中。1. 跨数据集训练DeepLabv3为什么跑通的人说简单跑崩的人说不值语义分割入门绕不开DeepLabv3而最劝退的环节不是模型结构是把VOC和Cityscapes两套数据集喂进同一个训练流程。很多人拿到基于Pytorch在VOCCityscapes上训练DeepLabv3的项目源码时以为跑通训练循环就万事大吉实际上一开始就折在数据加载、标签冲突和验证指标这三道坎上。这篇文章会沿着一条完整可复现的路径走一遍模型选型为什么落在DeepLabv3两套数据集的标签体系怎么统一训练参数哪些是必调的以及跨数据集训练时最容易翻车的地方在哪。适合已经在用Pytorch写过分类或检测模型、现在想进入分割方向的人也适合做道路场景、遥感或工业质检时需要在自有数据集上重新训练分割模型的从业者。2. DeepLabv3的原理与PyTorch生态选型从空洞卷积到ASPP别再用错backbone2.1 空洞卷积与ASPP增大感受野且不丢分辨率的关键DeepLabv3的核心价值在于它用空洞卷积解决了一个基础矛盾分割任务既需要足够大的感受野来理解全局上下文又需要保留边界细节所需的原始分辨率。普通卷积通过下采样扩大感受野但每一层pooling都会损失空间信息到最后特征图的尺寸太小上采样回来边界已经糊了。空洞卷积的做法是在卷积核内部插入空洞同样大小的卷积核可以覆盖更大的区域特征图分辨率保持不变。ASPP模块是DeepLabv3里最值得理解的部分它把同一张特征图并行送入四个不同空洞率的空洞卷积分支再加上一个全局平均池化分支。四个分支的感受野从小到大分别捕捉不同尺度的物体上下文最后concat起来相当于让网络同时看到“一个轮胎”和“一整条街”。Decoder层则是把ASPP输出上采样四倍后与backbone的浅层特征拼接这样最终预测既保留深度语义又能拿回锐利的边缘。这套设计在实际训练中有一个直接影响backbone的最后一个stage stride为16还是8直接决定显存占用和分割精度。最常见做法是output_stride16因为8虽然精度略高但特征图更大显存消耗高出不少对Cityscapes这种高分辨率图像来说尤其吃紧。我一般会先在16上跑通再考虑8做精细调优。2.2 为什么选PyTorch实现生态、权重与分布式训练的取舍Pytorch在分割方向做得比较顺手的地方主要有三个。第一是模型定义直观一个forward函数从头写到尾断点调试时能看到每一层张量的形状变化不像静态图那样需要先构图再执行。第二是torchvision里直接提供了deeplabv3_resnet101和deeplabv3_resnet50的预训练权重省去了自己从零预训练backbone的时间。第三是分布式训练和混合精度的支持比较成熟单机多卡用DistributedDataParallel是分割项目里的常规操作。从工程角度看DeepLabv3的PyTorch实现还有一个隐藏优势这不只是一个模型文件而是一条完整的数据流。自己做数据增强、自定义Dataset、切换验证集都只需要改一个Python文件不必动C或编译环节。对于标题里这种“VOCCityscapes跨数据集训练”场景灵活性恰恰是最重要的因为两套数据集的标注格式、类别数量、图像尺寸都不同你需要在Dataset层做统一处理而不是靠改配置参数硬凑。值得提醒的是不要在拿到源码后急着替换backbone。ResNet101在VOC和Cityscapes上的表现已经被大量实验验证过虽然MobilenetV3或HRNet更轻或更强但换backbone会连带改变ASPP输入通道数、预训练权重的加载逻辑和显存预算前期调试成本会明显上升。先把ResNet101这条路线走通再谈替换是更稳妥的路径。2.3 加载预训练权重的正确姿势与常见误用在Pytorch里加载DeepLabv3的预训练权重常见做法是直接使用torchvision模型接口但有一个细节很多人会忽略模型结构里包含一个aux_classifier辅助分类头训练时会计算辅助损失而推理时并不需要它。如果直接加载别人训练好的完整权重再用自己的代码做验证需要确认权重字典里的key与模型完全对齐否则会报missing key或unexpected key的错误。我一般会这样处理先实例化模型然后加载权重最后对aux_classifier做特殊处理。训练阶段保留它让辅助损失帮助backbone更好地收敛验证和推理阶段则把模型切到eval模式并且不再计算辅助输出。代码示例如下。import torch import torchvision def build_model(num_classes21, output_stride16, load_pretrainedTrue): # 使用torchvision自带的DeepLabv3-ResNet101结构 model torchvision.models.segmentation.deeplabv3_resnet101( weightsCOCO_WITH_VOC_LABELS_V1 if load_pretrained else None, num_classesnum_classes, aux_lossTrue # 训练时启用辅助分类头 ) if load_pretrained: # 预训练权重基于VOC标注体系如果换成Cityscapes需要自行微调类别层 print(Pretrained weights loaded) return model这段代码里的关键参数是aux_loss和weights。aux_loss决定是否保留辅助分类头训练时推荐为True因为它能提供额外的梯度信号让backbone中浅层也得到有效监督但如果你的显存非常紧张可以关掉它来省一部分计算量。weights参数指定预训练权重来源这里用的是基于COCO数据集聚类的分割预训练模型类别数按项目需求设置。还有一个更容易踩的坑Cityscapes有19个训练类别VOC是21类20类物体加1个背景。直接用同一个模型在两类数据集上交替训练时最后一层卷积的权重维度必须能同时容纳两类标签。常见做法有两个一是把模型的输出通道数固定为21Cityscapes的标签在预处理阶段做映射合并到VOC体系里二是各自维护一个独立的分类头交替训练时切换。第一种简单但Cityscapes很多类别在VOC里没有对应关系会损失信息第二种更严谨但工程复杂度高。我在模拟项目X里用的是方案一配合一个类别映射字典效果足够稳定。3. 在VOCCityscapes上准备数据目录结构、标签映射与Class Weight计算3.1 两套数据集的目录规范与标注格式差异拿到VOC和Cityscapes原始数据后第一步不是写Dataset类而是把目录结构和标注格式彻底搞清楚。VOC的目录常见为VOCdevkit/VOC2012下面有JPEGImages存放原图SegmentationClass存放PNG格式的彩色索引图SegmentationObject存放实例分割掩码。用PIL打开SegmentationClass时得到的是单通道索引图像素值范围0到20其中0表示背景255表示边缘标注中的void区域。Cityscapes的结构则完全不同原始数据分为leftImg8bit和gtFine两个目录每个目录下再按城市名分成train/val/test。gtFine中的标注是polygon格式的JSON文件需要用官方工具转换成PNG的label图转换后像素值直接对应官方定义的33类ID其中训练时只使用19类剩余类别都归为ignore。如果不做转换直接用原始JSON当maskDataset类根本没法做torch.Tensor转换这也是很多人在加载Cityscapes时报错的原因。两类数据放一起训练时我习惯先建立一个统一的根目录分别软链或拷贝到data/voc和data/cityscapes下然后各自写一个data loading函数返回统一格式的图像和标签。不要试图把两套数据的文件全部摊平到同一个目录因为文件名规则不同摊平之后调试和可视化都很难受。# 建立统一的数据目录结构 # 目录约定data/voc/JPEGImages, data/voc/SegmentationClass # data/cityscapes/leftImg8bit, data/cityscapes/gtFine # 用软链接避免重复拷贝物理磁盘占用更小 mkdir -p data ln -s /your_path/VOCdevkit/VOC2012/JPEGImages data/voc_images ln -s /your_path/VOCdevkit/VOC2012/SegmentationClass data/voc_masks ln -s /your_path/leftImg8bit data/cityscapes_images ln -s /your_path/gtFine data/cityscapes_masks这段脚本只是建立目录软链真正的作用是让后续的Dataset类只读一个固定的相对路径避免在不同机器上迁移时反复修改绝对路径。注意ln -s的源路径必须是绝对路径否则在训练脚本的工作目录与数据目录不一致时会变成断链读不到文件。3.2 用Pytorch的Dataset类统一两个数据源不两套数据集的Dataset统一的核心是返回的image和mask必须通道数一致、尺寸处理逻辑一致、标签语义一致。VOC图像是三通道RGBCityscapes的leftImg8bit也是RGB图像侧天然对齐但mask侧一个像素值代表VOC的21类一个代表Cityscapes的19类必须在读取时做映射而不是在模型里做映射。我常用的做法是给每个数据集单独写一个Builder函数返回同一个CustomDataset类的实例这个类的构造函数接收一个label_map字典用来把原始像素值映射到统一标签空间。这样做的好处是后续训练代码完全不用关心数据来自哪个数据集只需要迭代遍历。import os from PIL import Image import torch from torch.utils.data import Dataset import numpy as np class SegDataset(Dataset): def __init__(self, image_dir, mask_dir, label_mapNone, transformsNone): # label_map: 原始标签到统一标签的映射字典None表示原样使用 self.image_dir image_dir self.mask_dir mask_dir self.label_map label_map if label_map is not None else {} self.transforms transforms self.image_ids [f.split(.)[0] for f in os.listdir(image_dir) if f.endswith(.jpg) or f.endswith(.png)] def __len__(self): return len(self.image_ids) def __getitem__(self, idx): image_id self.image_ids[idx] image Image.open(os.path.join(self.image_dir, image_id .jpg)).convert(RGB) mask Image.open(os.path.join(self.mask_dir, image_id .png)) mask np.array(mask, dtypenp.int64) if self.label_map: # 直接遍历映射字典做标签替换避免对整个数组做循环 for src, dst in self.label_map.items(): mask[mask src] dst if self.transforms is not None: image, mask self.transforms(image, mask) # 图像归一化到[-1,1]区间Pytorch预训练模型默认输入范围 image torch.from_numpy(np.array(image, dtypenp.float32) / 127.5 - 1.0).permute(2, 0, 1) mask torch.from_numpy(mask).long() return image, mask这段代码的核心是label_map替换逻辑。注意这里用的是遍历字典逐值替换而不是np.where或布尔索引因为像素值需要被替换的目标值可能发生重叠顺序遍历可以保证最终结果正确。transforms参数接受一个自定义的可调用对象同步处理image和mask后面讲数据增强时还会用到。有个性能细节值得注意如果mask尺寸是2048x1024遍历字典做替换需要扫描整个数组多次。Cityscapes的图比较大我一般会在预处理阶段用向量化方式做一次映射而不是在构建Dataset时逐个替换。更好的做法是在官方转换工具输出PNG时就把标签映射到位这样训练时完全不干预。3.3 计算类别频率与Loss权重小类别不丢的关键跨数据集训练最容易出现的问题是小类别被淹没。VOC里的瓶子、椅子Cityscapes里的摩托车、自行车这些类别在整张图中占的比例极小CrossEntropyLoss在默认情况下会一视同仁地计算每个像素的损失比例悬殊时网络会把小类别直接忽略掉。解决办法是在训练前统计训练集的类别频率用逆频率或平方根逆频率作为类别权重。统计类别频率不需要遍历全部图像可以用torch.nn.functional.one_hot在整个训练集上做累计更快的做法是直接读取mask时用np.bincount统计。数据量大的时候逐张读一遍也不慢VOC约一万张图Cityscapes训练集约三千张单机几秒到几十秒就能完成统计。import numpy as np from collections import Counter def compute_class_weights(mask_paths, num_classes, ignore_label255): # mask_paths: 所有训练集mask文件的路径列表 count np.zeros(num_classes, dtypenp.float64) for mask_path in mask_paths: mask np.array(Image.open(mask_path), dtypenp.int64) mask mask[mask ! ignore_label] # 剔除void像素 if mask.size 0: continue # bincount的minlength保证输出长度固定 hist np.bincount(mask, minlengthnum_classes)[:num_classes] count hist # 对频率为0的类别做保底处理 count[count 0] 1.0 # 使用平方根逆频率比纯逆频率更平滑 weights 1.0 / np.sqrt(count) weights weights / weights.sum() * num_classes return torch.from_numpy(weights).float()这段代码的关键点是ignore_label的处理。255这个像素值在任何数据集里都不参与训练统计时必须提前剔除否则会把几千上万个void像素当成背景类导致背景类的权重被压得极低。平方根逆频率比纯逆频率温和不会让低频率类别的权重过大而干扰收敛这是我在多个项目里对比后的经验建议直接用。4. 训练DeepLabv3的Minimal Pipeline模型、优化器、学习率与四个必调参数4.1 训练主循环与验证逻辑的最小实现跨数据集训练的代码结构其实很常规训练主循环、验证循环、模型保存三块就够。难点集中在数据集切换和评价指标计算上。以下代码是一个单机多卡可用的最小框架核心思路是交替或混合遍历两个数据集的DataLoader验证时分别计算各自的mIoU。import torch from torch.utils.data import DataLoader import torch.nn as nn def train_one_epoch(model, dataloader, optimizer, criterion, device, lr_schedulerNone): model.train() total_loss 0 for images, masks in dataloader: images, masks images.to(device), masks.to(device) optimizer.zero_grad() # 模型输出是dict包含out和aux outputs model(images) loss criterion(outputs[out], masks) if aux in outputs: # 辅助损失权重一般设为0.4主损失为1.0 loss 0.4 * criterion(outputs[aux], masks) loss.backward() optimizer.step() if lr_scheduler is not None: lr_scheduler.step() total_loss loss.item() * images.size(0) return total_loss / len(dataloader.dataset)这段代码里model的输出是一个字典key为out和aux这是torchvision分割模型的统一接口。criterion使用CrossEntropyLoss时要注意ignore_index参数必须设为255否则void区域会参与loss计算导致mIoU虚高或波动。辅助损失的权重0.4是经验值一般不需要频繁调整但如果你发现总loss下降很慢可以试着把它调大再调小对比。验证环节的核心是按数据集分别统计mIoU因为VOC和Cityscapes的类别数不同混在一起统计没有任何实际意义。我建议在验证代码里维护一个per-class的IoU累计列表每个epoch结束后分别打印两个数据集的mIoU这样能第一时间发现某个数据集退化了。def validate(model, dataloader, num_classes, device): model.eval() # 存储每个类别的TP, FP, FN总和 tp torch.zeros(num_classes, devicedevice) fp torch.zeros(num_classes, devicedevice) fn torch.zeros(num_classes, devicedevice) with torch.no_grad(): for images, masks in dataloader: images, masks images.to(device), masks.to(device) outputs model(images)[out] preds outputs.argmax(dim1) for cls in range(num_classes): pred_mask (preds cls) true_mask (masks cls) tp[cls] (pred_mask true_mask).sum().item() fp[cls] (pred_mask ~true_mask).sum().item() fn[cls] (~pred_mask true_mask).sum().item() iou_per_class tp / (tp fp fn 1e-7) # 加eps防止除0 mIoU iou_per_class.mean().item() return mIoU, iou_per_class.cpu().numpy()这段验证代码的计算逻辑完全绕开了sklearn等第三方库直接在GPU上做逐类别的IoU统计速度快且便于后续接入TensorBoard。需要注意这里假设masks里没有255像素因为train阶段已经过滤了void像素。如果你直接把原始Cityscapes mask喂进去255会被当成一个类别参与计算验证结果会异常高。4.2 学习率策略与数据增强Poly策略为什么是标配DeepLabv3的训练一般使用Poly学习率衰减而不是StepLR按epoch固定衰减。原因是分割任务的收敛曲线比分类任务更平滑用StepLR会在衰减边界产生mIoU的明显抖动而Poly策略让学习率随迭代次数连续下降在训练后期自动进入精细调优阶段。Poly公式是lr乘以(1 - iter/total_iter)的0.9次方具体实现可以直接写进自定义的LambdaLR函数。数据增强对分割任务的影响比分类更大常见的组合包括随机缩放、随机裁剪、水平翻转和颜色抖动。有一个细节常被忽略缩放和裁剪必须同步作用于image和mask并且mask不能用插值只能用最邻近采样否则标签像素值会被插值算法弄出新数值训练直接报废。Pytorch的torchvision.transforms里没有同时处理image和mask的现成模块所以通常需要写一个自定义transform函数。class RandomScaleCrop: def __init__(self, scale_range(0.5, 2.0), crop_size513, ignore_label255): self.scale_range scale_range self.crop_size crop_size self.ignore_label ignore_label def __call__(self, image, mask): # 对于Cityscapes这种大图先随机缩放再裁剪到固定尺寸 scale np.random.uniform(*self.scale_range) new_w int(image.width * scale) new_h int(image.height * scale) image image.resize((new_w, new_h)) mask mask.resize((new_w, new_h), Image.NEAREST) # 必须用最邻近 # 随机裁剪到固定尺寸 if new_w self.crop_size and new_h self.crop_size: x np.random.randint(0, new_w - self.crop_size) y np.random.randint(0, new_h - self.crop_size) image image.crop((x, y, x self.crop_size, y self.crop_size)) mask mask.crop((x, y, x self.crop_size, y self.crop_size)) else: # 如果缩放后小于裁剪尺寸做padding pad_w max(0, self.crop_size - new_w) pad_h max(0, self.crop_size - new_h) image ImageOps.expand(image, border(0, 0, pad_w, pad_h), fill0) mask ImageOps.expand(mask, border(0, 0, pad_w, pad_h), fillself.ignore_label) return image, mask这段增强代码里最关键的是mask的resize用Image.NEAREST这是新手最容易踩的坑。如果用了默认的BICUBIC插值mask中原本的整数标签会被插值成小数某些值会错成相邻类别的整数训练出的模型在类别边界上会有一圈“幽灵预测”。padding时fill值也必须设为ignore_label而不是0否则填充区域会被当成背景类学习输出会出现无意义的黑色边带。4.3 用配置文件管理实验参数不玄学的办法训练分割模型的第二个玄学来源是超参数失控。batch_size、crop_size、base_lr、weight_decay、epoch数相互耦合如果不记录每次实验的配置根本分不清mIoU提升是来自学习率调整还是数据增强改动带来的。我习惯把训练参数写进一个YAML配置文件代码里统一读取然后在save模型时把配置一并存为json这样每个权重文件都自带参数指纹。# config.yaml 训练参数配置 model: name: deeplabv3_resnet101 num_classes: 21 output_stride: 16 dataset: voc_root: data/voc cityscapes_root: data/cityscapes crop_size: 513 scale_range: [0.5, 2.0] train: base_lr: 0.007 weight_decay: 0.0001 momentum: 0.9 batch_size: 16 epochs: 50 use_aux_loss: true这份配置里的base_lr设为0.007是DeepLabv3论文中在VOC上的常用初始学习率配合Poly衰减使用。如果你的机器batch_size只有8可以用linear scaling rule粗略折算但不要机械照搬分割模型的BN统计量对batch_size更敏感batch太小建议用SyncBN否则GPU数量多时BN统计会失真。开始训练后我在每个epoch结束都打印以下六个指标VOC mIoU、Cityscapes mIoU、总损失、当前学习率、单step耗时、显存占用峰值。这六个指标能让实验对比有据可依而不是靠感觉调参。配置文件和日志记录是长线项目中回报率最高的习惯没有之一。5. DeepLabv3跨数据集踩坑实录现象、原因与解决5.1 图像通道与mask标签不匹配PyTorch报错后找不到方向现象训练第一个epoch时报错RuntimeError: Expected input image as a Tensor with 3 dims but got 4 dims或者loss直接为nan。原因VOC的mask用PIL读取少数时候会得到四通道RGBA图或者某些PNG带有alpha通道导致通道数变成4与图像导出的形状对不上。Cityscapes的gtFine如果没做转换直接读原始JSON是dict类型根本进不了数据流。解决在所有数据读取代码里强制检查通道数统一用convert(RGB)和np.asarray做类型转换Cityscapes数据在预处理阶段就完成polygon到PNG的转换不要指望训练代码去兼容原始JSON格式。另外在Dataset类里加一个assert条件确保image.shape[0]3且mask.ndim2能直接把问题拦截在数据加载层。5.2 两套数据集的标签ID冲突掩码变成了乱码现象训练loss正常下降但输出的分割图是花斑状物体边缘完全错乱验证mIoU不超过5。原因VOC的1号标签对应aeroplaneCityscapes的1号标签对应ego vehicle。如果你在构建统一Dataset时没有做映射网络会同时学习两套标签含义同一个输出通道既想表示飞机又想表示车辆最终谁都学不像。解决建立一个显式的标签映射字典在Dataset里把Cityscapes的19类映射到VOC体系的ID。例如将Cityscapes的车、行人、骑车人类别对应到VOC的car、person、bicycle等但要保持语义严格对齐找不到对应关系的类别直接置为255忽略掉。语义不对齐的强制映射只会让模型更困惑不如直接忽略。5.3 验证集mIoU虚高void像素混入统计现象训练到后期验证mIoU突然跳到90以上但肉眼查看分割结果却满是漏检。原因验证代码把mask中的255当作普通类别参与统计。255像素在整张图中占比很大当模型预测周围类别时这些像素很容易被算成背景正确把IoU分母撑大。解决在验证循环中先排除void像素统计时只计算标签位于0到num_classes-1之间的像素。同时在计算IOU前检查每个类别的样本量样本量为0的类别单独标记不参与最终的mIoU平均。这一步做完之后验证mIoU会大幅下降但才是真实水平。5.4 显存爆掉OOM不是batch_size一个人的锅现象在Cityscapes上训练时batch_size设为16直接OOM调到4才能跑但VOC上batch_size16完全没问题。原因Cityscapes原始分辨率2048x1024即便随机缩放到0.5单张图也远超VOC的500x375。crop_size和batch_size共同决定显存消耗BCrop尺寸从513改成769显存占用会成倍上升。解决先固定crop_size513再调batch_size作为显存预算变量如果batch_size低于8但GPU数量多考虑开启SyncBN仍然不够时启用梯度累计等价于放大batch_size而不增加单step显存。我一般的方法是先定crop_size再算最大batch_size最后用梯度累计倍数凑够等效batch_size。5.5 预训练权重与类别数不匹配最后一层加载失败现象加载torchvision预训练权重时报错size mismatch for classifier.4.weight。原因torchvision的deeplabv3_resnet101预训练权重最后分类层输出21类如果你的num_classes不是21就必然报这个错误。解决加载权重时先去掉模型中的分类层键加载完backbone和ASPP部分后再对classifier层做随机初始化。Cityscapes训练时也建议保留VOC预训练权重因为它的backbone已经学会通用特征即使最后几层重新初始化收敛速度也远快于从零开始。6. 验证分割结果的三个维度与一个进阶技巧从mIoU到Boundary-aware评估模型训练完怎么判断“能不能投入使用”mIoU是学术界排序的标准但工程上只看mIoU会踩坑因为它对边界错误不敏感对大面积物体的偏好明显高于小物体。我一般会同时看三个维度per-class IoU、边界召回率、以及类不平衡下的像素准确率分布。per-class IoU能直接指出哪些类别拖后腿边界召回率则可以判断墙体与墙体的粘连问题。整个方向值不值得投入最终要看这几个数字是否满足业务场景的容忍底线。进阶技巧是给loss加一个edge-aware term。做法很简单在训练时用Canny算子从mask中提取边界像素图然后把CrossEntropyLoss在这部分像素上的权重从1提到2到3。这一改动不需要修改模型结构只调整loss计算方式但能明显改善分割结果的边界完整度。需要注意Canny提取的边界要经过膨胀处理否则边界像素太少权重提升对loss的影响微乎其微。我在模拟项目X上试过这个技巧让Cityscapes验证集的边界F1从61提升到65代价仅仅是训练时间多出不到5%。最后说一个习惯每次实验结束我会把模型权重、YAML配置、训练日志和验证结果打包成一个带时间戳的文件夹命名格式是日期backbonenum_classesmIoU。这个习惯在两次评测间隔一个月的时候救过我很多次否则你根本不知道手上这份权重是调了哪个参数跑出来的。对比和复现是实验的核心希望这篇笔记能帮你把跨数据集训练的路走通一遍少踩几个坑也希望你在自己的数据上跑出比这份方案更好的结果。本文还有配套的精品资源点击获取