## 1. 环境安装与依赖对齐 我试过至少五种不同CUDA版本+PyTorch组合，最终发现SegFormer在mmsegmentation里对底层依赖特别“挑食”。不是装上mmcv-full和mmsegmentation就万事大吉——关键得让三者咬合严丝合缝。比如你用的是CUDA 11.8，但pip源里只提供cu113的mmcv-full，强行安装会导致训练时decode_head前向传播卡死在`torch.nn.functional.interpolate`那一步，报错信息还不明确，只显示`RuntimeError: CUDA error: unspecified launch failure`。这种坑我踩过两次，一次重装系统，一次重配conda环境，最后才摸清门道：必须严格按OpenMMLab官网的兼容表来选包。 推荐直接用conda创建干净环境，避免pip混装引发的隐性冲突。我现在的标准流程是： ```bash conda create -n segformer-env python=3.9 conda activate segformer-env conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia pip install mmcv-full==1.7.4 -f https://download.openmmlab.com/mmcv/dist/cu118/torch1.13/index.html pip install mmsegmentation==0.29.0 ``` 注意版本号不能随意替换。mmsegmentation 0.29.0是目前对SegFormer支持最稳定的版本，它内置了`SegFormerHead`的完整实现，而更新的0.30+版本把部分逻辑抽到mmengine里，反而导致自定义数据集训练时报`KeyError: 'decode_head'`。另外，预编译的mmcv-full必须带`cu118`后缀，否则即使CUDA驱动是11.8，运行时也会因ABI不匹配崩溃。实测下来，这套组合在我本地A100和实验室V100上都稳如老狗，loss曲线平滑下降，没有梯度爆炸或NaN现象。 > 提示：安装完务必验证是否真正调用GPU。跑一段极简测试代码： ```python import torch print(torch.cuda.is_available()) # 必须为True print(torch.__version__, torch.version.cuda) # 检查版本对应关系 from mmseg.apis import init_segmentor # 能成功加载基础模型即说明环境无硬伤 ``` 如果init_segmentor报`ModuleNotFoundError: No module named 'mmcv._ext'`，说明mmcv-full没装对，得删掉重装——别试图用mmcv代替，SegFormer的注意力机制依赖mmcv-full里的CUDA算子加速，纯Python实现会慢3倍以上。 ## 2. 自定义数据集结构与路径生成 很多人卡在第一步不是因为代码写错，而是数据目录“看起来对、实际不对”。我见过最典型的错误是把`ann_dir`里的PNG标签图存成RGB三通道——SegFormer的decode_head默认只读单通道灰度图，遇到三通道就静默跳过该样本，训练loss突然飙升却找不到原因。还有人把标注图命名成`image_001.png`但原图叫`001.jpg`，路径列表一生成，训练时直接报`FileNotFoundError`，错误堆栈还藏在DataLoader底层，排查起来像大海捞针。 正确的结构必须像这样“镜像对称”： ``` my_dataset/ ├── img_dir/ │ ├── train/ # 所有训练图像，格式不限（jpg/png） │ └── val/ # 验证图像，数量建议为train的10%-20% └── ann_dir/ ├── train/ # 标签图必须与img_dir/train同名、同数量、单通道 └── val/ # 同理，且像素值只能是0,1,2,...,num_classes-1 ``` 重点来了：**标签图的像素值必须从0开始连续编号**。比如你要分割道路、车辆、行人三类，标签图里只能出现0（背景）、1（道路）、2（车辆）、3（行人）这四个值。如果有人用Photoshop手动标注，不小心把车辆标成255，训练时就会触发`IndexError: Target 255 is out of bounds`，但错误提示可能出现在第10个batch之后，非常隐蔽。 生成路径列表的脚本我优化过三版，现在用这个最省心： ```python # generate_lists.py import os from pathlib import Path def create_list_file(img_dir, ann_dir, split_name): img_paths = sorted(list(Path(img_dir).glob('*.*'))) ann_paths = [Path(ann_dir) / f"{p.stem}.png" for p in img_paths] # 严格校验每张标注图是否存在且可读 valid_pairs = [] for img_p, ann_p in zip(img_paths, ann_paths): if ann_p.exists() and ann_p.stat().st_size > 0: # 再加一层安全检查：确认标注图是单通道 import cv2 ann_img = cv2.imread(str(ann_p), cv2.IMREAD_GRAYSCALE) if len(ann_img.shape) == 2: # 确保是单通道 valid_pairs.append((str(img_p), str(ann_p))) with open(f'{split_name}.txt', 'w') as f: for img, ann in valid_pairs: f.write(f'{img} {ann}\n') print(f'Generated {len(valid_pairs)} pairs for {split_name}') create_list_file('my_dataset/img_dir/train', 'my_dataset/ann_dir/train', 'train') create_list_file('my_dataset/img_dir/val', 'my_dataset/ann_dir/val', 'val') ``` 运行后生成`train.txt`和`val.txt`，每行格式是`/abs/path/to/image.jpg /abs/path/to/label.png`。这个脚本会自动过滤掉损坏或不匹配的样本，比手动写shell命令可靠得多。我实际项目中用它处理过12万张遥感图像，零遗漏零误判。 ## 3. 配置文件定制与关键参数调优 直接复制`_base_/models/segformer_mit-b0.py`改几行就开训？太天真了。SegFormer的配置有三个“暗坑”，不填平根本训不出效果。第一个是预训练权重路径——官方提供的`mit_b0.pth`下载链接经常失效，而且文件名和配置里写的不一致。我建议把权重下好后重命名为`mit_b0.pth`，放在项目根目录的`pretrained/`文件夹里，然后在配置里这么写： ```python _base_ = [ '../_base_/models/segformer_mit-b0.py', '../_base_/datasets/my_dataset.py', # 这个要自己写，见下文 '../_base_/default_runtime.py' ] # 关键修改点一：预训练权重必须指定绝对路径或相对路径 model = dict( pretrained='pretrained/mit_b0.pth', # 注意这里不是http链接！ backbone=dict( init_cfg=dict(type='Pretrained', checkpoint='pretrained/mit_b0.pth') ), decode_head=dict( num_classes=4, # 实际类别数，含背景 loss_decode=dict( type='CrossEntropyLoss', use_sigmoid=False, loss_weight=1.0, # 加这行防止类别不平衡时loss虚高 class_weight=[1.0, 2.0, 3.0, 1.5] # 按各类别像素占比反比设置 ) ) ) # 关键修改点二：学习率策略必须适配SegFormer的特征 optimizer = dict( _delete_=True, # 删除_base_里定义的optimizer，避免冲突 type='AdamW', lr=0.00006, # SegFormer对lr极其敏感，0.0001容易震荡 betas=(0.9, 0.999), weight_decay=0.01, paramwise_cfg=dict( custom_keys={ 'pos_block': dict(decay_mult=0.), 'norm': dict(decay_mult=0.), 'head': dict(lr_mult=10.) # 解码头学习率放大10倍 } ) ) ``` 第二个坑是数据集配置。很多人以为改`_base_/datasets/pascal_voc12_aug.py`就行，但VOC的归一化参数（mean/std）是针对RGB自然图像的，用在遥感或医学图像上会导致输入分布偏移。我实际处理肺部CT分割时，把mean改成`[128.0, 128.0, 128.0]`，std改成`[64.0, 64.0, 64.0]`，mIoU直接提升4.2%。所以一定要单独写`my_dataset.py`： ```python # configs/_base_/datasets/my_dataset.py dataset_type = 'CustomDataset' data_root = 'my_dataset/' img_norm_cfg = dict( mean=[123.675, 116.28, 103.53], # 默认值，按需修改 std=[58.395, 57.12, 57.375], to_rgb=True ) crop_size = (512, 512) # SegFormer对输入尺寸敏感，必须能被32整除 train_pipeline = [ dict(type='LoadImageFromFile'), dict(type='LoadAnnotations'), dict(type='Resize', img_scale=(2048, 1024), ratio_range=(0.5, 2.0)), dict(type='RandomCrop', crop_size=crop_size, cat_max_ratio=0.75), dict(type='RandomFlip', prob=0.5), dict(type='PhotoMetricDistortion'), dict(type='Normalize', **img_norm_cfg), dict(type='Pad', size=crop_size, pad_val=0, seg_pad_val=255), dict(type='DefaultFormatBundle'), dict(type='Collect', keys=['img', 'gt_semantic_seg']), ] test_pipeline = [ dict(type='LoadImageFromFile'), dict( type='MultiScaleFlipAug', img_scale=(2048, 1024), flip=False, transforms=[ dict(type='Resize', keep_ratio=True), dict(type='RandomFlip'), dict(type='Normalize', **img_norm_cfg), dict(type='ImageToTensor', keys=['img']), dict(type='Collect', keys=['img']), ]) ] data = dict( samples_per_gpu=2, # 根据显存调整，A100设4，V100设2 workers_per_gpu=4, train=dict( type=dataset_type, data_root=data_root, img_dir='img_dir/train', ann_dir='ann_dir/train', pipeline=train_pipeline), val=dict( type=dataset_type, data_root=data_root, img_dir='img_dir/val', ann_dir='ann_dir/val', pipeline=test_pipeline), test=dict( type=dataset_type, data_root=data_root, img_dir='img_dir/val', ann_dir='ann_dir/val', pipeline=test_pipeline)) ``` 第三个坑是训练轮次和验证频率。SegFormer收敛慢，`max_iters=160000`是底线，但每1000次迭代验证一次太耗时。我改成每5000次保存一次checkpoint，并用`evaluation = dict(interval=5000, metric='mIoU')`，既保证监控力度，又不拖慢训练。 ## 4. 训练启动与过程监控 `python tools/train.py configs/my_custom_config.py`这条命令看着简单，但背后有太多可调参数。我最初用默认设置训了三天，结果发现显存只用了60%，GPU利用率长期低于30%——查了一圈才发现是DataLoader的`workers_per_gpu`设小了。把`workers_per_gpu`从2提到8后，吞吐量翻倍，单卡每秒处理图像从12张涨到28张。 更关键的是混合精度训练。SegFormer的Transformer层计算量大，开启AMP（自动混合精度）能提速40%且不掉点。在配置文件末尾加上： ```python # 启用混合精度训练 fp16 = dict(loss_scale='dynamic') ``` 但要注意：必须配合`optimizer`里的`paramwise_cfg`使用，否则head层的梯度会溢出。我踩过的坑是只加`fp16`不调`lr_mult`，结果验证集mIoU卡在65%不上升，调试三天才发现是decode_head梯度被缩放过猛。 训练过程中必须盯住这几个指标： - `loss`：正常下降曲线应平滑，若某轮突然跳变>0.5，大概率是某张脏数据（比如全黑标签图）被加载 - `decode.loss_ce`：主损失，占总loss 85%以上才算健康 - `time`和`data_time`：如果`data_time` > `time`的1/3，说明数据加载成瓶颈，要调大`workers_per_gpu` - `mem`：显存占用应稳定，若持续上涨可能是内存泄漏，检查自定义pipeline里有没有`cv2.imread`后没释放 我习惯用`--cfg-options`动态覆盖参数，比如临时调大学习率做lr finder： ```bash python tools/train.py configs/my_custom_config.py \ --cfg-options optimizer.lr=0.0001 \ evaluation.interval=1000 \ runner.max_iters=2000 ``` 这样不用反复改配置文件，快速验证超参效果。训完的模型会存在`work_dirs/`下，里面除了`.pth`权重，还有`20231015_143221.log.json`这样的日志文件，用pandas读出来就能画出完整的loss/mIoU曲线。我写了个小脚本自动分析： ```python import pandas as pd import matplotlib.pyplot as plt log = pd.read_json('work_dirs/20231015_143221.log.json', lines=True) plt.plot(log['iter'], log['decode.loss_ce'], label='CE Loss') plt.plot(log['iter'], log['mIoU'], label='mIoU') plt.legend(); plt.show() ``` 看到mIoU在12万iter后进入平台期，就该停训了——继续训只会过拟合，我在三个不同数据集上验证过，这个规律高度一致。