从零跑通 CLAN 域适应：GTA5 到 Cityscapes 语义分割完整实战指南-育师

从零跑通 CLAN 域适应：GTA5 到 Cityscapes 语义分割完整实战指南

【免费下载链接】CLAN( TPAMI2022 / CVPR2019 Oral ) Taking A Closer Look at Domain Shift: Category-level Adversaries for Semantics Consistent Domain Adaptation项目地址: https://gitcode.com/gh_mirrors/cl/CLAN

CLAN（Category-level Adversaries）是一个做「语义一致域适应」的经典 PyTorch 项目，出自 CVPR 2019 Oral 与 TPAMI 2022 两篇论文。域适应说白了，就是把游戏画面（GTA5）上学到的语义分割能力，迁移到真实街景（Cityscapes）上——目标域一张标注都不用。本文带你走一条「环境→数据→训练→mIoU」的最短链路，照着做即可出结果。

CLAN 域适应是什么：先搞清能力边界

在动手前花两分钟定位这个项目，能帮你避开一半的期望落差。

它解决什么问题

普通语义分割模型换一套数据就"懵了"，CLAN 的核心贡献是用「类别级判别器（Category-level Discriminator）」逐类地对抗，让特征分布按类别对齐，而不是全局硬拉。配合一个"权重失配损失"防止特征空间退化，迁移后的语义一致性显著更好。

它能做什么、不能做什么

能：GTA5 → Cityscapes、SYNTHIA → Cityscapes 这两条仿真到真实（sim2real）的语义分割域适应链路，输出 Cityscapes 标准 19 类结果。
不能：它不是即插即用的通用工具箱。源域和目标域的数据规格、列表文件（dataset/gta5_list/train.txt等）都是写死约定，换数据集要改代码；且单卡显存要求 11G 起步，默认 batch size 为 1。

搞清楚边界后，我们进入流水线。先搭环境。

第 1 步：一键装好环境与代码

环境很简单，官方口径是 Python 3.6 + PyTorch 1.0.0，属于老配置，别用新版 torch 硬套。

git clone https://gitcode.com/gh_mirrors/cl/CLAN && cd CLAN conda create -n clan_env python=3.6 && conda activate clan_env pip install torch==1.0.0 torchvision pillow numpy matplotlib imageio

⚠️ 还有一个容易漏的件：ImageNet 预训练权重（DeepLab-ResNet），训练脚本启动时直接从./model/目录读取（RESTORE_FROM指向model/DeepLab_resnet_pretrained_init-f81d91e8.pth），没有它训练第一步就会崩。记得按这个文件名放好，否则改一下脚本里的RESTORE_FROM变量。

代码和环境都就位，下面解决数据这个大头。

第 2 步：数据集怎么摆对位置

需要三个数据集：GTA5（源域）、Cityscapes（目标域，需申请授权）、SYNTHIA（可选替代源域）。下载后按下面的目录结构摆进项目根目录，脚本里的路径变量（如DATA_DIRECTORY = './data/GTA5'）都是相对它写的：

├── data/ │ ├── Cityscapes/ │ │ ├── gtFine/ # 真值标注 │ │ └── leftImg8bit/ # 街景原图 │ ├── GTA5/ │ │ ├── images/ │ │ └── labels/ │ └── SYNTHIA/ │ └── RAND_CITYSCAPES/

摆好图之后，还要把图片列表文件和内容对上：dataset/cityscapes_list/train.txt、dataset/gta5_list/train.txt、dataset/synthia_list/train.txt里写的是相对路径（如aachen/aachen_000000_000019_leftImg8bit.png），如果你的数据目录名不同，要么统一目录名，要么批量改列表。Cityscapes 的 19 类映射规则在dataset/cityscapes_list/info.json里，一般无需动它。

数据齐了，最后一条命令链就能出 mIoU。

第 3 步：训练到出 mIoU 的完整链路

这一条线分三个脚本，按顺序跑即可。

训练（默认源域 GTA5、目标域 Cityscapes，共 10 万 iter，每 2000 iter 存一个 checkpoint 到 snapshots 目录）：

CUDA_VISIBLE_DEVICES=0 python CLAN_train.py --snapshot-dir ./snapshots/GTA2Cityscapes

训练过程中会滚动打印 loss_seg / loss_adv / loss_weight，同时写入 snapshots 目录的loss.txt，可以直接盯它判断是否收敛。

评估（拿某个 checkpoint 在 Cityscapes val 集上跑推理）：

python CLAN_evaluate.py --restore-from ./snapshots/GTA2Cityscapes/GTA5_100000.pth --save ./result/GTA2Cityscapes_100000

算 mIoU（把预测结果和 gtFine 真值对齐求交并比）：

python CLAN_iou.py ./data/Cityscapes/gtFine/val result/GTA2Cityscapes_100000

💡 一个实用技巧：表现最好的 checkpoint 往往不是最后一个。CLAN_evaluate_bulk.py和CLAN_iou_bulk.py可以批量评测 snapshots 下所有模型，结果自动汇总成 Excel 表，适合训练完做横向对比挑最优。

想看"它学到了什么"，仓库gifs/目录下有 GTA5 风格街景被分割成彩色 mask 的动图示例，直观感受域适应效果。

跑通全流程后，如果你打算魔改网络，花十分钟看一眼模块地图会省很多事。

进阶：核心模块地图，G 和 D 到底在哪

代码量不大，值得花 10 分钟扫一遍，重点就四个文件：

model/CLAN_G.py：生成器网络，Res_Deeplab类。ResNet-101 骨干 + 两个解耦的 DeepLabV2 头（对应 pred_source1/2），"解耦"正是 CLAN 对抗训练的载体。
model/CLAN_D.py：类别级判别器FCDiscriminator，注意它的输入是逐类别的 softmax 概率而非普通特征——这就是"category-level"的落点。
utils/loss.py：损失函数，含加权 BCE（WeightedBCEWithLogitsLoss），即训练里"自适应对抗损失"的实现，预热期后启用。
CLAN_train.py主体：训练主循环，G 和 D 交替更新、damping 衰减、warmup + 多项式学习率调度都在这一个文件里，读它就能看懂全流程。

数据加载逻辑在dataset/下的三个数据集类里，改数据协议时从这里入手。

高频踩坑与对策

最后集中回答跑不通时最常见的几类报错。

CUDA OOM / 显存不足：官方要求显存 ≥11G。显存小卡可把--input-size-source、--input-size-target调低（如640,360），NUM_WORKERS也可降到 2。
启动即报找不到权重文件：就是上面说的 ImageNet 预训练权重没放进model/，文件名要对上RESTORE_FROM。
FileNotFoundError 报某个 png：列表文件和实际目录对不上，先检查data/下的层级名是否完全一致，再核对*_list/*.txt第一行的前缀。
mIoU 比预期低：先确认评估用的是 val 列表（cityscapes_list/val.txt）且真值目录传的是gtFine/val；再试试 bulk 评测换几个 checkpoint 对比。
新环境装不上 torch 1.0.0：这是 2019 年的依赖组合，最稳的方案就是 Python 3.6 + 官方老版 torch 原样复刻，而不是升级到新版 PyTorch 后逐个修兼容问题。