Detectron2 中的 DeepLabV3 / DeepLabV3+ 语义分割实战指南：Cityscapes 训练、评估与源码解析-北京尧图网络

Detectron2 中的 DeepLabV3 / DeepLabV3 语义分割实战指南Cityscapes 训练、评估与源码解析【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2本指南围绕 projects/DeepLab/README.md 展开系统讲解如何在 Detectron2 项目中复现并应用 DeepLabV3 与 DeepLabV3 语义分割模型涵盖环境安装、8 卡分布式训练、模型评估、Cityscapes 官方结果复现以及从配置到源码的逐层剖析。读完本文你将掌握基于 ResNet-103-DC5 主干、ASPP 空洞卷积、深度可分离卷积与 poly 学习率调度在 Detectron2 中训练语义分割模型的完整链路并能独立修改配置迁移到自己的分割数据集。一、项目定位Detectron2 中的 DeepLab 实现Detectron2 官方仓库以projects/目录承载研究级模型实现DeepLab 正是其中之一。projects/DeepLab在 Detectron2 的建模框架内完整实现了 DeepLabV3 与 DeepLabV3 两种语义分割架构其核心组件分布在语义分割头定义DeepLabV3Head与DeepLabV3PlusHeadDeepLab 专用 ResNet 主干DeepLabStem与build_resnet_deeplab_backbone损失函数DeepLabCEhard pixel mining 交叉熵学习率调度与求解器构建WarmupPolyLR配置扩展add_deeplab_config训练/评估入口Trainer从入口模块 deeplab/init.py 可以看到该包对外暴露的接口即为上述add_deeplab_config、build_lr_scheduler、build_resnet_deeplab_backbone、DeepLabV3Head和DeepLabV3PlusHead是接入 Detectron2 训练管线的最小组合。二、环境安装DeepLab 项目运行在 Detectron2 之上因此首先需要安装 Detectron2 本体官方安装说明见 INSTALL.mdLinux 下编译 C/CUDA 扩展的细节可参考 detectron2/layers/csrc/README.md。# 安装 detectron2以源码方式编译DeepLab 依赖其 CUDA 扩展如 SyncBN python -m pip install -e .安装完成后无需额外安装独立包——projects/DeepLab下的 Python 代码通过detectron2.projects.deeplab命名空间被导入见 train_net.py 中的from detectron2.projects.deeplab import add_deeplab_config, build_lr_scheduler因此工作区根目录必须保持为 detectron2 仓库根目录以保证包路径可解析。三、模型训练8 卡分布式启动命令README 给出的训练命令如下进入项目目录后直接以配置文件启动cd /path/to/detectron2/projects/DeepLab python train_net.py --config-file configs/Cityscapes-SemanticSegmentation/deeplab_v3_plus_R_103_os16_mg124_poly_90k_bs16.yaml --num-gpus 8对该命令逐段拆解--config-file指定完整配置文件此处为 deeplab_v3_plus_R_103_os16_mg124_poly_90k_bs16.yaml。文件名各段含义R_103R-103 主干即改进型 ResNet-101、os16encoder 输出 stride 为 16、mg124res5 multi-grid 为 [1, 2, 4]、polypoly 学习率、90k90,000 次迭代、bs16batch size 16。--num-gpus 8使用 8 块 GPU 做分布式数据并行训练配合--num-machines、--machine-rank、--dist-url可扩展到多机。3.1 训练入口的内部逻辑train_net.py 的setup()函数展示了配置装配顺序这对自定义配置至关重要cfg get_cfg() add_deeplab_config(cfg) # 注入 DeepLab 专用配置项ASPP、stem、poly 等 cfg.merge_from_file(args.config_file) cfg.merge_from_list(args.opts) # 支持命令行覆盖 cfg.freeze() default_setup(cfg, args)即先调用add_deeplab_config注册 DeepLab 新增的配置字段否则cfg不认识ASPP_DILATIONS等键再合并 YAML 文件与命令行覆盖项。main()在非 eval 模式下创建Trainer并调用trainer.train()launch()负责根据num_gpus自动拉起多进程训练。3.2 训练数据增强管线与 Detectron2 通用检测/分割任务不同语义分割训练需要裁剪类别面积约束的增强组合。Trainer.build_train_loader针对SemanticSegmentor架构调用了自定义的build_sem_seg_train_augtrain_net.pyT.ResizeShortestEdge按INPUT.MIN_SIZE_TRAIN(512, 768, 1024, 1280, 1536, 1792, 2048) 中随机 choice缩放到边限制最大边MAX_SIZE_TRAIN4096T.RandomCrop_CategoryAreaConstraint若INPUT.CROP.ENABLEDTrue执行absolute模式的 (512, 1024) 随机裁剪并约束裁剪区域内单一类别占比不超过SINGLE_CATEGORY_MAX_AREA1.0见 deeplab/config.py 的注释反复重试裁剪直到没有任何一个 GT 类别在裁剪区域中占比超过该阈值避免大类别主导训练T.RandomFlip随机水平翻转。四、模型评估评估与训练共用同一入口只需追加--eval-only并指定权重路径cd /path/to/detectron2/projects/DeepLab python train_net.py --config-file configs/Cityscapes-SemanticSegmentation/deeplab_v3_plus_R_103_os16_mg124_poly_90k_bs16.yaml --eval-only MODEL.WEIGHTS /path/to/model_checkpoint--eval-only使main()走评估分支构建模型 → 通过DetectionCheckpointer加载MODEL.WEIGHTS→ 调用Trainer.test(cfg, model)train_net.py。评估器由Trainer.build_evaluator按数据集的evaluator_type元数据自动选择train_net.pysem_seg→SemSegEvaluator通用语义分割评估输出到OUTPUT_DIR/inferencecityscapes_sem_seg→CityscapesSemSegEvaluatorCityscapes 官方评估脚本对 19 类细粒度标注计算 mIoU忽略 ignore 区域。推理时分割头输出的 logits 通过双线性插值上采样common_stride倍回到原图分辨率见下文forward分析因此--eval-only命令中的MODEL.WEIGHTS指向任何通过DetectionCheckpointer序列化的 checkpoint 即可。五、Cityscapes 语义分割结果复现表README 中给出了使用 ImageNet 预训练初始化的 Cityscapes 模型基准结果全部以 1024×2048 输出分辨率在 Cityscapes val 集上评估方法主干输出分辨率mIoUmodel id下载DeepLabV3R101-DC51024×204876.7--DeepLabV3R103-DC51024×204878.528041665model / metricsDeepLabV3R101-DC51024×204878.1--DeepLabV3R103-DC51024×204880.028054032model / metrics其中 model id 对应训练实验目录名下载链接指向dl.fbaipublicfiles.com的模型权重与metrics.json训练日志weights 与 metrics 文件在运行时可通过DetectionCheckpointer加载或直接查看评估曲线。需要说明R103并非标准的 ResNet-103而是将 ResNet-101 的第一个 7×7 卷积替换为 3 个 3×3 卷积感受野不变、参数量略增、非线性增强的变体该修改在多数语义分割论文中被采用并在 ImageNet 上使用 PyTorch examples 的默认配方预训练DC5表示在res5阶段使用空洞dilated卷积使特征图 stride 由 32 降为 16os16从而保留更高分辨率的空间信息上述 mIoU 数据直接取自 README 表格属于官方发布结果在实际复现时受随机种子、GPU 型号与数值精度影响可能产生小幅浮动。六、配置深度解析从 Base 到模型专属配置6.1 基础配置 Base-DeepLabV3-OS16-Semantic.yaml该文件继承自仓库级基础配置 configs/Base-RCNN-DilatedC5.yaml提供 PIXEL_MEAN/STD、SyncBN 等通用项并声明了语义分割的默认骨架MODEL: META_ARCHITECTURE: SemanticSegmentor BACKBONE: FREEZE_AT: 0 SEM_SEG_HEAD: NAME: DeepLabV3Head IN_FEATURES: [res5] ASPP_CHANNELS: 256 ASPP_DILATIONS: [6, 12, 18] ASPP_DROPOUT: 0.1 CONVS_DIM: 256 COMMON_STRIDE: 16 NUM_CLASSES: 19 LOSS_TYPE: hard_pixel_mining DATASETS: TRAIN: (cityscapes_fine_sem_seg_train,) TEST: (cityscapes_fine_sem_seg_val,) SOLVER: BASE_LR: 0.01 MAX_ITER: 90000 LR_SCHEDULER_NAME: WarmupPolyLR IMS_PER_BATCH: 16 INPUT: MIN_SIZE_TRAIN: (512, 768, 1024, 1280, 1536, 1792, 2048) MIN_SIZE_TRAIN_SAMPLING: choice MIN_SIZE_TEST: 1024 MAX_SIZE_TRAIN: 4096 MAX_SIZE_TEST: 2048 CROP: ENABLED: True TYPE: absolute SIZE: (512, 1024) SINGLE_CATEGORY_MAX_AREA: 1.0 DATALOADER: NUM_WORKERS: 10关键参数说明配置项默认值作用MODEL.SEM_SEG_HEAD.ASPP_CHANNELS256ASPP 各分支输出通道数MODEL.SEM_SEG_HEAD.ASPP_DILATIONS[6, 12, 18]ASPP 中三个空洞卷积的 dilation 系数MODEL.SEM_SEG_HEAD.ASPP_DROPOUT0.1ASPP 输出上的 dropout 比例MODEL.SEM_SEG_HEAD.COMMON_STRIDE16输出相对于输入的下采样倍数os16MODEL.SEM_SEG_HEAD.NUM_CLASSES19Cityscapes 细粒度类别数MODEL.SEM_SEG_HEAD.LOSS_TYPEhard_pixel_mining损失类型可选cross_entropy或hard_pixel_miningSOLVER.LR_SCHEDULER_NAMEWarmupPolyLRpoly 学习率调度器DeepLab 特有INPUT.CROP.SINGLE_CATEGORY_MAX_AREA1.0单类别在裁剪区域的最大面积占比约束6.2 DeepLabV3 专属配置 deeplab_v3_plus_R_103_os16_mg124_poly_90k_bs16.yaml_BASE_: Base-DeepLabV3-OS16-Semantic.yaml MODEL: WEIGHTS: detectron2://DeepLab/R-103.pkl PIXEL_MEAN: [123.675, 116.280, 103.530] PIXEL_STD: [58.395, 57.120, 57.375] BACKBONE: NAME: build_resnet_deeplab_backbone RESNETS: DEPTH: 101 NORM: SyncBN OUT_FEATURES: [res2, res5] RES5_MULTI_GRID: [1, 2, 4] STEM_TYPE: deeplab STEM_OUT_CHANNELS: 128 STRIDE_IN_1X1: False SEM_SEG_HEAD: NAME: DeepLabV3PlusHead IN_FEATURES: [res2, res5] PROJECT_FEATURES: [res2] PROJECT_CHANNELS: [48] NORM: SyncBN COMMON_STRIDE: 4 INPUT: FORMAT: RGB与 DeepLabV3 配置deeplab_v3_R_103_os16_mg124_poly_90k_bs16.yaml相比V3 的关键差异多级特征输入OUT_FEATURES: [res2, res5]低层res2stride 4提供高分辨率细节高层res5输入 ASPP 提供语义信息Decoder 通道投影PROJECT_FEATURES: [res2]、PROJECT_CHANNELS: [48]将 res2 通过 1×1 卷积压缩到 48 通道再与上采样后的 ASPP 输出拼接COMMON_STRIDE 降为 4DeepLabV3 的 encoder-decoder 结构输出 stride 从 16 降到 4直接输出 4 倍下采样的 logits在推理时仅需上采样 4 倍即可回到原图DeepLab StemSTEM_TYPE: deeplab、STEM_OUT_CHANNELS: 128将标准 7×7 stride 2 卷积替换为 3 个 3×3 卷积stride 2/1/1输出通道扩展到 128STRIDE_IN_1X1: False在 res5 空洞阶段下采样发生在 3×3 卷积而非 1×1 卷积这是空洞分割标准的stride_in_1x1False设定。6.3 add_deeplab_config新配置项从哪来DeepLab 使用的许多配置项ASPP_*、POLY_LR_*、PROJECT_*、STEM_TYPE、RES5_MULTI_GRID等并非 Detectron2 内置而是由 deeplab/config.py 中的add_deeplab_config动态注入cfg.SOLVER.POLY_LR_POWER 0.9 # poly 学习率指数 cfg.SOLVER.POLY_LR_CONSTANT_ENDING 0.0 # 尾部恒定学习率0 表示关闭 cfg.MODEL.SEM_SEG_HEAD.LOSS_TYPE hard_pixel_mining cfg.MODEL.SEM_SEG_HEAD.PROJECT_FEATURES [res2] cfg.MODEL.SEM_SEG_HEAD.PROJECT_CHANNELS [48] cfg.MODEL.SEM_SEG_HEAD.ASPP_CHANNELS 256 cfg.MODEL.SEM_SEG_HEAD.ASPP_DILATIONS [6, 12, 18] cfg.MODEL.SEM_SEG_HEAD.ASPP_DROPOUT 0.1 cfg.MODEL.SEM_SEG_HEAD.USE_DEPTHWISE_SEPARABLE_CONV False cfg.MODEL.RESNETS.RES4_DILATION 1 cfg.MODEL.RESNETS.RES5_MULTI_GRID [1, 2, 4] cfg.MODEL.RESNETS.STEM_TYPE deeplab这是接入任何 Detectron2 训练脚本如tools/plain_train_net.py前必须调用的注册步骤——漏掉它会导致cfg.merge_from_file因未知字段而报错。七、源码级原理剖析7.1 DeepLabV3 分割头decoder 逐级融合DeepLabV3PlusHead 注册于SEM_SEG_HEADS_REGISTRY其核心layers()方法自高到低分辨率反向遍历in_features代码注释为 Reverse feature maps into top-down order对每个特征f先做project_convres2 为 1×1 投影到 48 通道res5 为 ASPP 模块将上一级低分辨率输出y双线性上采样到当前特征分辨率与投影特征拼接拼接结果经fuse_conv融合——默认是两层 3×3 卷积semantic_seg.py若开启USE_DEPTHWISE_SEPARABLE_CONV则按 Panoptic-DeepLab 的建议用单个 5×5 深度可分离卷积替代两层 3×3 卷积两者感受野相同见代码注释最后predictor1×1 卷积输出num_classes通道的 logits。forward()中训练与推理行为分离semantic_seg.py训练时返回(None, {loss_sem_seg: ...})推理时对 logits 做scale_factorcommon_stride的双线性上采样后返回(C×H×W logits, {})。from_config中还隐藏一个细节当开启裁剪训练INPUT.CROP.ENABLED时若裁剪尺寸不能被 encoder stride 整除会直接抛出ValueError同时 ASPP 的 image pooling 分支会使用train_h // encoder_stride作为全局平均池化的 kernel size这解释了为何 Cityscapes 配置固定裁剪为 (512, 1024) 且 stride 为 16/4。7.2 DeepLabV3 分割头单特征 ASPPDeepLabV3Head 结构更简洁断言len(in_features) 1取单一高层特征默认res5→ ASPP → 1×1 predictor → 上采样common_stride16倍。它没有 decoder 与低层特征融合因此CONVS_DIM256直接作为 ASPP 输出通道并被 predictor 消费。7.3 DeepLabCEhard pixel mining 损失LOSS_TYPE: hard_pixel_mining对应 loss.py 中的DeepLabCE其实现逻辑为先用reductionnone的交叉熵计算每个像素的损失取前top_k_percent_pixels默认 0.2即最难的 20%像素的损失做torch.topk对这批最难像素的损失求均值作为最终 loss。该策略来自 TensorFlow DeepLab 框架与 DeeperLab 论文作用是让训练聚焦于难分类像素如物体边缘、小目标两个分割头在构造损失时均调用DeepLabCE(ignore_labelself.ignore_value, top_k_percent_pixels0.2)。若希望使用标准交叉熵只需将LOSS_TYPE改为cross_entropy。7.4 DeepLabStem改进的 ResNet 主干resnet.py 中的DeepLabStem将标准BasicStem的 7×7 stride 2 卷积替换为3×3(stride 2) → 3×3 → 3×3三段结构每段后接 ReLU最后接 3×3 stride 2 max-pool输出 128 通道。build_resnet_deeplab_backbone通过STEM_TYPE在basic/deeplab间切换并支持RES5_MULTI_GRID在 res5 阶段以dilation_per_block [dilation * mg for mg in res5_multi_grid]逐 block 设置空洞率即 [1, 2, 4] × 2 2/4/8实现 multi-grid 空洞卷积。res4_dilation1、res5_dilation2的组合配合OUT_FEATURES: [res2, res5]正是os16res5 输出 stride 16的由来。7.5 WarmupPolyLRpoly 学习率调度DeepLab 训练不使用 Detectron2 默认的多步衰减而是 lr_scheduler.py 中的WarmupPolyLR其学习率公式为lr base_lr × warmup_factor × (1 - iter / max_iters)^powerpower 0.9POLY_LR_POWER学习率随迭代平滑衰减到 0前warmup_iters轮执行线性 warmup默认因子 0.001若设置POLY_LR_CONSTANT_ENDING 0当衰减值低于该阈值时学习率恒定保持为base_lr × constant_ending避免尾部衰减过慢。调度器由 build_solver.py 的build_lr_scheduler根据SOLVER.LR_SCHEDULER_NAME WarmupPolyLR路由创建并被Trainer.build_lr_scheduler接入 Detectron2 训练循环。八、扩展到自定义数据集若要在自己的分割数据集上使用本实现需调整以下配置均可用--opts命令行覆盖无需改代码数据集注册参考 detectron2/data/datasets/builtin.py 与 cityscapes.py 注册xxx_sem_seg_train/xxx_sem_seg_val并在 DATASETS 中替换TRAIN/TEST类别数MODEL.SEM_SEG_HEAD.NUM_CLASSES改为实际类别数背景计入则 1忽略值MODEL.SEM_SEG_HEAD.IGNORE_VALUE默认 -1数据集中若有 ignore 区域需对应设置裁剪与增强INPUT.CROP.SIZE必须能被COMMON_STRIDE整除DeepLabV3 为 16、DeepLabV3 为 4否则from_config会抛ValueError预训练MODEL.WEIGHTS可替换为 detectron2:// 的 ImageNet 权重或其他 checkpointDetectionCheckpointer会自动做兼容加载。九、引用 DeepLab若在研究中使用了本实现请按如下 BibTeX 引用原始论文DeepLabv3Encoder-Decoder with Atrous Separable Convolution for Semantic Image SegmentationECCV 2018inproceedings{deeplabv3plus2018, title{Encoder-Decoder with Atrous Separable Convolution for Semantic Image Segmentation}, author{Liang-Chieh Chen and Yukun Zhu and George Papandreou and Florian Schroff and Hartwig Adam}, booktitle{ECCV}, year{2018} }DeepLabv3Rethinking atrous convolution for semantic image segmentationarticle{deeplabv32018, title{Rethinking atrous convolution for semantic image segmentation}, author{Chen, Liang-Chieh and Papandreou, George and Schroff, Florian and Adam, Hartwig}, journal{arXiv:1706.05587}, year{2017} }十、小结projects/DeepLab在 Detectron2 框架内提供了开箱即用的 DeepLabV3/V3 语义分割方案通过add_deeplab_config注入 ASPP、DeepLabStem、multi-grid、poly 学习率等专属配置通过train_net.py一键完成分布式训练与 Cityscapes 评估并在 Cityscapes val 上以 R103-DC5 主干取得 DeepLabV3 78.5 mIoU、DeepLabV3 80.0 mIoU 的官方结果。结合本文的配置拆解与源码剖析你可以快速复现官方实验或将这套 encoder-decoder 空洞卷积 hard pixel mining 的组合迁移到自定义语义分割任务中。【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Detectron2 中的 DeepLabV3 / DeepLabV3+ 语义分割实战指南：Cityscapes 训练、评估与源码解析

相关推荐

Angular Core 运行时错误机制解析：从 errors.api.md 读懂 RuntimeError 与错误码体系

Rust 编译器错误 E0670 深度解析：Rust 2015 中禁止使用 `async fn` 及迁移方案

Selenium Ruby 绑定维护指南：为 Chromium DevTools Protocol 添加新版本支持并发布 selenium-devtools Gem

更多资讯

打造带长期记忆的 AI Agent：Zep 记忆后端 + AutoGen 编排 + Ollama/Qwen 3 本地模型实战（Zep Memory Assistant）

Spring @Async异步编程实战：线程池、事务与异常处理全解析

CANN/GE CreateVector函数API文档

Spring Boot构建食品安全管理系统的技术实践

Reflex Build 应用通用设置指南：名称、ID、可见性、复用导出与删除

daisyUI Status 组件完全指南：用纯 CSS 圆点优雅展示元素在线状态

今日更新

CopilotKit Vue Demo 与 React Demo 的 Parity 实现指南：路由、运行时端点与交互语义的全框架对齐

Harbor RBAC 实战：db_auth 模式下非管理员用户管理项目成员的完整验证与权限模型解析

STM32平衡车纯平衡程序从拆包到参数整定的完整调试指南

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？