Swin-UNet复现实战：从环境搭建到成功运行的完整避坑指南

1. 环境准备：从零搭建Swin-UNet开发环境

第一次复现Swin-UNet时，我花了整整两天时间在环境配置上。后来发现，其实只要按步骤操作，半小时就能搞定。下面是我总结的Windows+Pycharm黄金组合配置方案：

首先确保你的电脑已经安装好Python 3.7-3.10版本（推荐3.8）。我实测过3.10也能正常运行，但保险起见建议用3.8。打开Pycharm后，先别急着创建项目，我们要先解决几个关键问题：

• CUDA版本选择：如果你有NVIDIA显卡，建议安装CUDA 11.3配合cuDNN 8.2.1。这个组合在Windows下最稳定。可以用nvidia-smi命令查看显卡支持的CUDA版本。
• 虚拟环境创建：在Pycharm终端执行：

  conda create -n swinunet python=3.8 conda activate swinunet

  我强烈建议用conda而不是venv，因为后面安装PyTorch时会少很多麻烦。

安装核心依赖时有个小技巧：先装PyTorch再装其他包。用这个命令能避免90%的版本冲突：

pip install torch==1.12.1+cu113 torchvision==0.13.1+cu113 --extra-index-url https://download.pytorch.org/whl/cu113

注意：如果下载速度慢，可以添加清华镜像源。但记得安装完成后切换回默认源，避免后续包版本混乱。

2. 源码获取与项目初始化

论文作者HuCaoFighting在GitHub上维护的代码库相当友好，但有几个隐藏细节需要注意：

1. 下载源码时，不要直接点"Download ZIP"。这样会丢失git信息，建议用：

   git clone https://github.com/HuCaoFighting/Swin-Unet.git

2. 下载预训练模型时，记得选择swin_tiny版本。大模型在Windows下容易爆显存，我第一次跑就因为这个卡了半天。

项目结构有个关键点：configs文件夹里的yaml文件决定了整个模型的架构。新手最容易犯的错误是直接修改这个文件，正确做法是复制一份再改：

cp configs/swin_tiny_patch4_window7_224.yaml configs/my_config.yaml

数据集准备阶段有个坑：Synapse数据集需要手动创建train_npz和test_vol_h5两个子目录。我建议这样组织目录结构：

data/ └── Synapse/ ├── train_npz/ ├── test_vol_h5/ └── lists/ └── lists_Synapse/

3. 典型报错与解决方案实录

3.1 路径相关错误

Windows下第一个拦路虎肯定是路径问题。报错信息里出现"\"和"/"混用时，用这个万能修复方案：

# 在train.py开头添加 import os os.environ['PATH'] = os.pathsep.join([ os.environ['PATH'], os.path.dirname(os.path.abspath(__file__)) ])

路径配置要特别注意三点：

1. 所有路径建议用os.path.join()拼接
2. 配置文件里的路径要用相对路径
3. 数据集路径最后一定要加斜杠，比如'../data/Synapse/'

3.2 参数配置错误

最让人头疼的是这个报错：

KeyError: 'Transformer/encoderblock_0/MultiHeadDotProductAttention_1/query\\kernel'

解决方法其实很简单：在train.py中找到预训练模型加载部分，添加：

state_dict = {k.replace('\\', '/'): v for k, v in state_dict.items()}

类别数错误也很常见。当看到n_class报错时，记住：

• Synapse数据集用9类
• ACDC数据集用4类 修改位置通常在train.py第58行附近。

3.3 内存相关优化

在8GB显存的笔记本上跑模型，这几个参数必须调：

batch_size: 4 # 默认8会爆显存 num_workers: 0 # Windows下必须设为0 window_size: 7 # 可以尝试减小到5

如果还是显存不足，在swin_unet.py里开启梯度检查点：

self.encoder.use_checkpoint = True

4. 训练技巧与性能调优

成功运行只是第一步，要让模型真正work还需要一些技巧：

1. 学习率策略：初始学习率设为3e-4，用余弦退火调度。我在train.py里加了这段代码：

   scheduler = torch.optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=100)

2. 数据增强：医疗图像需要特殊处理。修改dataset.py中的transform：

   transform = Compose([ RandomRotate90(), RandomFlip(), GaussianNoise(p=0.5), AdjustContrast(gamma=0.8) ])

3. 早停机制：添加这个回调能避免过拟合：

   early_stop = EarlyStopping( patience=10, delta=0.001, path='checkpoint.pt' )

训练过程中建议用TensorBoard监控：

tensorboard --logdir=./model_output --port=6006

5. 模型验证与结果可视化

跑通训练后，验证阶段还有几个注意点：

1. 测试时要用--phase test参数：

   python train.py --cfg configs/my_config.yaml --phase test

2. 可视化推荐用matplotlib而不是OpenCV：

   plt.imshow(output[0, 1:].permute(1, 2, 0)) # 显示第一个类别

3. 指标计算要注意：Synapse数据集用Dice系数，ACDC用Hausdorff距离

最后分享一个实用技巧：把常用命令写成run.bat批处理文件：

@echo off set PYTHONPATH=. python train.py --cfg configs/my_config.yaml --output_dir ./output

记得第一次成功运行时，我盯着训练日志看了好久。虽然过程曲折，但解决问题的成就感是无价的。现在每次复现新模型，我都会先建个bug_log.md文件记录报错和解决方案，这个习惯帮我节省了大量时间。