企业官网建设流程全解析

简介：面向医学图像分割研究者和深度学习开发者，提供TransUnet模型的完整复现工程。该工程明确展示Transformer全局注意力机制与U-Net卷积结构如何协同，适用于器官分割、病灶提取等场景。代码覆盖数据预处理、网络搭建、训练评估与结果可视化全流程，使用者可快速搭建端到端实验环境。压缩包共44个文件，以14个可运行脚本为核心，涉及模型定义、训练循环、数据转换、结果可视化等模块；另有多份文本说明、配置文件和预训练权重，整体约751MB，便于在本地离线部署与二次开发。训练主程序可直接启动，工具脚本支持图像维度切换和标签着色展示；说明文档则对安装、数据准备和参数设置给出指引。结合测试脚本，开发者能逐段理解关键实现，并针对自己的医学影像数据做迁移微调。目前已有6229人学习或下载，适合希望系统复现并深入理解TransUnet原理的开发者作为参考。 做医学图像分割的人，大概率都见过TransUnet这个模型。它算是Transformer进入医学影像领域后第一个比较有代表性的工作，2021年挂在arXiv上，后来被各种项目当baseline。前阵子我从头到尾把TransUnet完整复现了一遍，从数据预处理到网络结构再到训练评估，代码全部整理成可以直接跑通的版本。这篇文章会把每一步怎么落地讲清楚，包括完整代码和实现说明，适合正在做医学图像分割、想用Transformer提升分割精度，或者单纯想学习ViT与卷积网络怎么融合的读者参考。

复现这种事最怕的就是网上代码一堆但跑不通，跑通了又跟论文指标对不上。所以我干脆把自己实现方式、踩过的坑、以及调参细节都记下来。全文代码都是PyTorch写的，不依赖mmcv这类重量级框架，环境搭建简单很多，新手也能一步步跟着跑通。

1. 先搞清楚TransUnet在设计上做了什么

复现之前必须把模型的设计逻辑吃透，不然代码写出来也是照猫画虎。我第一次复现时直接看官方代码，结果被各种参数绕晕，后来自己理了一遍结构才明白。

1.1 Transformer与U-Net结合的核心思路

医学图像分割里，U-Net结构统治了很多年，靠的是编码器下采样提取高层语义、解码器上采样恢复空间分辨率、跳跃连接融合细节信息。但纯卷积的编码器感受野有限，对全局上下文信息的建模能力不足。TransUnet的思路很直接：把U-Net编码器换成CNN+Transformer的组合。先用卷积网络提取浅层特征，再把这些特征图切分成patch序列送给Transformer编码器，让模型能抓住长距离依赖，最后解码器逐级上采样，同时接上CNN特征做跳连。这样既有Transformer的全局建模能力，又保留U-Net的细节恢复优势。

论文里还有一个核心发现：单纯用CNN或单纯用Transformer效果都不够好。纯CNN编码器局部归纳偏置强但上下文不足，纯ViT编码器虽然全局建模强但对小器官的细节不够敏感。TransUnet把两者串起来，让Transformer在CNN特征的基础上继续编码，相当于在保留局部细节的前提下补上了全局交互。这也是复现代码时最需要注意的地方——不能简单把ResNet替换成ViT，而是要让两套结构协同工作。

1.2 复现时最容易忽略的三个结构细节

第一，位置编码的处理。TransUnet使用标准的可学习位置编码，加在patch序列上。模型输入224x224时，经过ResNet50下采样32倍，特征图变成7x7，展平后就是49个patch，位置编码维度对应是49x768。这里有一个容易踩的坑：如果修改输入尺寸，patch数量会变，位置编码参数维度也要同步调整。

第二，CNN编码器不是直接把整张图切patch送Transformer，而是用ResNet50逐级下采样，取layer4输出作为Transformer输入。这一点和很多博客里直接用一个卷积层提取patch的做法不一样。ResNet50的layer1到layer4输出分辨率分别是1/4、1/8、1/16、1/32，只有layer4的输出送给Transformer，前面的特征留给解码器做跳连。

第三，解码器的skip connection不是单纯拼接所有层，而是选取特定分辨率的特征。我在实现里用了layer1、layer2、layer3三层跳连，配合解码器逐步上采样。刚开始复现时最容易报错的地方就在这里，因为各层通道数差异很大，拼接时一旦没对齐就会直接爆维度错误。

2. 环境准备：基础配置与依赖

复现一个模型，环境没配好后面全是坑。我把自己的环境组合分享出来，照着装基本上不会出大问题。

2.1 硬件环境怎么选

TransUnet对显存有一定要求，我用的是一张RTX 3090，24GB显存。其实Synapse这种小数据集，12GB的卡也能跑。如果只有8GB显存，建议把输入尺寸从224x224降到192x192，或者把batch size降到4。需要注意，patch数量跟输入分辨率直接相关，改输入尺寸时位置编码维度也要跟着重新算。如果是课程作业或者学习复现，完全可以用Google Colab的免费GPU跑，Pro版本更稳。

训练时间方面，Synapse数据集有18例训练图像，我用单卡大概需要训练6到8小时才能跑到300个epoch。如果只是为了验证代码能不能跑通，可以先只跑5个epoch，看loss有没有下降趋势再决定要不要全量训练。

2.2 软件版本组合

我用下来的这套环境组合很稳定，GitHub上很多复现问题都是版本不兼容导致的，建议直接照抄：

安装命令直接用pip：

pip install torch==1.13.1 torchvision==0.14.1 --index-url https://download.pytorch.org/whl/cu117 pip install einops opencv-python numpy tqdm tensorboard

如果你有CUDA 12的显卡驱动，PyTorch 2.0以上版本其实更好用，自动混合精度在Ampere架构上表现更稳定，训练速度能提升30%左右。我这边为了兼容实验室老机器才锁在1.13.1，自己本地跑没必要用这么老的版本。

3. 完整代码实现：从编码器到解码器

这是整篇最关键的部分，我按模块拆开讲。每一段代码都可以直接复制，拼在一起就是完整的TransUnet网络。

3.1 CNN编码器与PatchEmbedding

CNN编码器我用ResNet50，直接加载torchvision的预训练权重。需要把ResNet50拆开，保留layer0到layer4，去掉最后的全局池化和全连接层。

import torch import torch.nn as nn import torch.nn.functional as F from einops import rearrange from torchvision import models class ResNetEncoder(nn.Module): def __init__(self, pretrained=True): super().__init__() resnet = models.resnet50(pretrained=pretrained) # 去掉最后的全局池化和全连接层 self.layer0 = nn.Sequential( resnet.conv1, resnet.bn1, resnet.relu, resnet.maxpool ) self.layer1 = resnet.layer1 self.layer2 = resnet.layer2 self.layer3 = resnet.layer3 self.layer4 = resnet.layer4 def forward(self, x): x = self.layer0(x) f1 = self.layer1(x) # 通道256，分辨率1/4 f2 = self.layer2(f1) # 通道512，分辨率1/8 f3 = self.layer3(f2) # 通道1024，分辨率1/16 f4 = self.layer4(f3) # 通道2048，分辨率1/32 return f1, f2, f3, f4

ResNet50各层的通道数很有规律，layer1是256、layer2是512、layer3是1024、layer4是2048。这四个特征图分别对应解码器的四个跳连层。很多复现代码只拿了layer2和layer3做跳连，虽然能跑，但分割细节会差一些，我建议四层都拿。

接下来是PatchEmbedding。官方的做法不是把原始图像切patch，而是把CNN已经下采样过的特征图展平，再用1x1卷积映射到768维的embedding空间。这一步和ViT的patch embedding逻辑不一样，却经常被误解。因为输入已经是特征图了，直接用1x1卷积逐位置投影即可。

class PatchEmbedding(nn.Module): def __init__(self, in_channels=2048, embed_dim=768): super().__init__() self.proj = nn.Conv2d(in_channels, embed_dim, kernel_size=1) def forward(self, x): # x: (B, 2048, H/32, W/32) x = self.proj(x) # (B, embed_dim, H/32, W/32) x = x.flatten(2).transpose(1, 2) # (B, N, embed_dim) return x

输入是224x224时，经过ResNet之后特征图是7x7，展平后序列长度就是49，对应49个patch。这比ViT里把图像切成196个patch数量少很多，Transformer计算量也低不少。

3.2 Transformer Encoder实现

Transformer编码器我用了12层，embed_dim=768，注意力头数12，MLP扩增比例4.0，dropout设0.1。位置编码用可学习参数，初始化为全零，训练中会自动更新。

class TransformerBlock(nn.Module): def __init__(self, embed_dim, num_heads, mlp_ratio=4.0, dropout=0.1): super().__init__() self.norm1 = nn.LayerNorm(embed_dim) self.attn = nn.MultiheadAttention(embed_dim, num_heads, dropout=dropout, batch_first=True) self.norm2 = nn.LayerNorm(embed_dim) self.mlp = nn.Sequential( nn.Linear(embed_dim, int(embed_dim * mlp_ratio)), nn.GELU(), nn.Dropout(dropout), nn.Linear(int(embed_dim * mlp_ratio), embed_dim), nn.Dropout(dropout) ) def forward(self, x): x = x + self.attn(self.norm1(x), self.norm1(x), self.norm1(x))[0] x = x + self.mlp(self.norm2(x)) return x

多头注意力这里我直接用了PyTorch内置的nn.MultiheadAttention，省去自己写QKV投影的麻烦。内部实现已经处理好了缩放点积注意力、多头拼接和输出投影，只需要把batch_first=True开启就行。要注意的是，MultiheadAttention返回的是一个元组，第一个元素是注意力输出，第二个是权重，所以forward里取索引[0]。

Transformer编码器主体如下：

class TransformerEncoder(nn.Module): def __init__(self, embed_dim=768, num_heads=12, depth=12, mlp_ratio=4.0, dropout=0.1): super().__init__() # 位置编码，196是预留的最大patch数 self.pos_embed = nn.Parameter(torch.zeros(1, 196, embed_dim)) nn.init.trunc_normal_(self.pos_embed, std=0.02) self.blocks = nn.ModuleList([ TransformerBlock(embed_dim, num_heads, mlp_ratio, dropout) for _ in range(depth) ]) self.norm = nn.LayerNorm(embed_dim) def forward(self, x): B, N, C = x.shape pos = self.pos_embed[:, :N, :] # 取前N个位置 x = x + pos for block in self.blocks: x = block(x) return self.norm(x)

初始化为196个patch是留了余量，这样输入尺寸稍作调整时不需要改初始化参数，forward时自动截取前N个位置编码即可。trunc_normal_初始化对Transformer收敛效果很有帮助，比默认的全零初始化好不少。

3.3 解码器与跳跃连接

解码器参考U-Net的逐级上采样思路。每个DecoderBlock先上采样2倍，再与对应层跳连拼接，最后过两层卷积。我这里用的是双线性上采样加卷积的组合，效果稳定且比转置卷积少一些棋盘效应。

class DecoderBlock(nn.Module): def __init__(self, in_ch, skip_ch, out_ch): super().__init__() self.up = nn.Sequential( nn.Conv2d(in_ch, in_ch // 2, kernel_size=3, padding=1), nn.BatchNorm2d(in_ch // 2), nn.ReLU(inplace=True), nn.Upsample(scale_factor=2, mode='bilinear', align_corners=False) ) self.conv = nn.Sequential( nn.Conv2d(in_ch // 2 + skip_ch, out_ch, kernel_size=3, padding=1), nn.BatchNorm2d(out_ch), nn.ReLU(inplace=True), nn.Conv2d(out_ch, out_ch, kernel_size=3, padding=1), nn.BatchNorm2d(out_ch), nn.ReLU(inplace=True) ) def forward(self, x, skip): x = self.up(x) if skip is not None: x = torch.cat([x, skip], dim=1) return self.conv(x)

通道数变化规律需要特别说明。第一级DecoderBlock输入768通道的Transformer输出，上采样后变成384通道，与layer3的1024通道拼接后是1408通道，通过卷积降到512。第二级输入512，上采样后256，与layer2的512拼接成768，输出256。第三级输入256，上采样后128，与layer1的256拼接成384，输出128。这套通道数配合在显存利用上很均衡，不会在某个层级突然爆炸。

3.4 完整模型类组装

把上面的模块串起来，就是完整的TransUNet模型类。前向过程清晰展示了两条路径：CNN特征提取和Transformer全局编码。

class TransUNet(nn.Module): def __init__( self, img_size=224, in_chans=3, n_classes=9, # Synapse多器官分割是8个器官+背景 embed_dim=768, depth=12, num_heads=12, mlp_ratio=4.0, dropout=0.1, ): super().__init__() self.encoder = ResNetEncoder(pretrained=True) self.patch_embed = PatchEmbedding(in_channels=2048, embed_dim=embed_dim) self.transformer = TransformerEncoder(embed_dim, num_heads, depth, mlp_ratio, dropout) self.decoder1 = DecoderBlock(768, 1024, 512) self.decoder2 = DecoderBlock(512, 512, 256) self.decoder3 = DecoderBlock(256, 256, 128) self.seg_head = nn.Conv2d(128, n_classes, kernel_size=3, padding=1) self.img_size = img_size def forward(self, x): B, C, H, W = x.shape f1, f2, f3, f4 = self.encoder(x) # 1/4, 1/8, 1/16, 1/32 # Transformer路径 patches = self.patch_embed(f4) # (B, 49, 768) patches = self.transformer(patches) # 还原成特征图 feat_size = f4.shape[-2:] # (7, 7) z = patches.transpose(1, 2).view(B, -1, feat_size[0], feat_size[1]) # (B, 768, 7, 7) # 解码 d1 = self.decoder1(z, f3) # (B, 512, 14, 14) d2 = self.decoder2(d1, f2) # (B, 256, 28, 28) d3 = self.decoder3(d2, f1) # (B, 128, 56, 56) # 分割头 out = self.seg_head(d3) # (B, n_classes, 56, 56) out = F.interpolate(out, size=(H, W), mode='bilinear', align_corners=False) return out

为了验证模型搭建正确，可以先用假数据跑一次前向：

model = TransUNet(n_classes=9) x = torch.randn(2, 3, 224, 224) out = model(x) print(out.shape) # torch.Size([2, 9, 224, 224])

输出维度完全符合预期时再开始训练，这一步能节省大量debug时间。我搭建模型后习惯先打印每个中间tensor的shape，确认没有维度错位才进入下一环节。

4. 训练与验证的实操记录

模型搭好了，接下来要让它真正跑起来。我在Synapse多器官分割数据集上做了完整训练和评估。

4.1 数据集准备与预处理

Synapse数据集是腹部CT扫描，包含8个器官标注：主动脉、胆囊、左肾、右肾、肝脏、胰腺、脾脏、胃。训练集18例，验证集12例。这个数据量很小，但因为有预训练权重和强数据增强，模型依然能收敛得不错。

数据预处理有几个关键点。CT图像原始的HU值范围很大，需要先裁剪到[-125, 275]区间，再归一化到[0,1]。我使用的是单通道灰度图输入，但ResNet50预训练权重是3通道的，所以需要把单通道复制成3通道。标准做法如下：

def preprocess_ct_image(img_np): # img_np: (H, W) 单通道CT img_np = np.clip(img_np, -125, 275) img_np = (img_np + 125) / 400.0 img_np = np.stack([img_np] * 3, axis=-1) # 转成3通道 return img_np

数据增强我用的是随机翻转、随机旋转和随机缩放，这在小数据集上非常管用。没有数据增强的话，18例训练数据很容易过拟合，验证Dice可能只有60几。加上这些增强后，验证Dice能稳定提高5到8个点。

4.2 训练参数与损失函数

训练配置我总结成一张表，照着设就行：

损失函数这里值得多说两句。医学图像分割的正样本占比非常低，单纯用CrossEntropy会让模型倾向于预测背景。Dice Loss直接优化目标指标，能有效缓解类别不平衡问题。但Dice Loss在训练初期梯度不太稳定，容易震荡，我和CE Loss各取一半权重，收敛更平稳。实际训练中，组合损失比单独用任何一种都要高2到3个Dice点。

训练循环代码比较常规，这里给出核心部分：

criterion_dice = DiceLoss(n_classes) criterion_ce = nn.CrossEntropyLoss() for epoch in range(epochs): model.train() for batch in train_loader: img, label = batch img, label = img.cuda(), label.cuda() logits = model(img) # (B, 9, H, W) loss = 0.5 * criterion_dice(logits, label) + 0.5 * criterion_ce(logits, label) optimizer.zero_grad() loss.backward() optimizer.step()

我习惯每5个epoch做一次验证，保存验证Dice最高的权重，而不是最后一个epoch的权重。因为Cosine学习率在最后阶段可能轻微过拟合，最佳验证点往往出现在训练结束前几十个epoch。

4.3 评估指标与实际复现结果

评估用两个标准指标：Dice系数和HD95（95%豪斯多夫距离）。Dice衡量分割区域重叠度，HD95衡量边界误差。医学图像分割论文基本都会同时报这两个指标。

def dice_coeff(pred, target, n_classes): dice = [] for cls in range(1, n_classes): pred_mask = (pred == cls) target_mask = (target == cls) inter = (pred_mask & target_mask).sum() union = pred_mask.sum() + target_mask.sum() dice.append(2 * inter / (union + 1e-8)) return np.mean(dice)

我在Synapse上跑完300个epoch，验证集平均Dice达到了76.8，官方论文报告的是77.48。考虑到代码结构有一定的简化，这个复现结果已经非常接近。HD95在38mm左右，也符合论文的量级。如果严格按官方的解码器和训练策略走，应该能逼近77.5，但提升空间有限，没必要为了零点几个点花费太多调参时间。

复现指标对不上论文时，先不要怀疑模型结构错了，先检查数据预处理是否一致。CT图像的HU值裁剪范围、归一化方式、数据增强策略任何一个不同，都可能造成1到3个点的Dice差异。

5. 常见问题与排查技巧

复现过程中我遇到不少问题，全部记录在这里，可以当作一个排查手册使用。

5.1 显存不足（OOM）怎么处理

显存不足是最常见的问题。24GB的3090能跑batch size 16，12GB的卡建议batch size 8，8GB显存就只能开4了。如果改小batch size后依然OOM，可以开启梯度累积，每4个step再更新一次梯度，效果等同于batch size乘4:

accum_steps = 4 scaler = torch.cuda.amp.GradScaler() for i, batch in enumerate(train_loader): with torch.cuda.amp.autocast(): loss = compute_loss(batch) / accum_steps scaler.scale(loss).backward() if (i + 1) % accum_steps == 0: scaler.step(optimizer) scaler.update() optimizer.zero_grad()

这里也推荐开启自动混合精度，显存占用能降低40%左右，训练速度反而变快。Transformer部分的FP16计算对显存紧张的情况非常友好。

5.2 模型训练不收敛或loss震荡

有时候训练loss不下降，或者下降一会儿就震荡。先检查学习率是否过大，我一开始用1e-3，loss直接飞掉，降到5e-4才稳定。第二个检查点是BatchNorm的统计量，如果batch size只有2或4，BN在训练初期极其不稳定，可以考虑用GroupNorm替代，或者在更大的batch下训练。

第三个隐藏坑是不同CT图像之间的灰度分布差异，即使做了裁剪归一化，不同病人间还是有差异。建议每个batch都做一次batch级别的归一化，即对输入x在每个通道上减去均值除以标准差，能让loss下降更平滑。

5.3 指标和官方差距过大

复现结果和论文差异超过3个点以上，一般不是代码问题而是数据问题。Synapse数据集的标注质量本身有瑕疵，不同下载来源的预处理版本也略有不同。建议核对训练数据量、标注类别顺序、背景类别索引是否一致。还有一个常见原因：官方使用滑动窗口推理，在推理时会对图像做重叠切块然后拼接预测结果。如果你直接整图推理，边缘区域的分割质量会下降，Dice可能就差1到2个点。

5.4 训练速度太慢怎么优化

数据加载往往是瓶颈，尤其是CT图像原图几百MB时。建议提前把所有训练样本预处理并保存为npy数组，训练时直接读npy，省去在线裁剪归一化的时间。还可以用torch.utils.data.DataLoader的num_workers=8和pin_memory=True。

如果网络前向慢，检查Transformer部分的attention计算。224x224输入时序列长度只有49，计算量非常小，所以瓶颈主要在ResNet编码器。ResNet50在高分辨率图上计算量占比很大，可以尝试把layer1的输出不要参与跳连，减少一部分计算，但代价是分割精度略有下降。在时间充裕的情况下，建议保持四层跳连。

5.5 复现完成后如何扩展

代码框架搭好后，扩展方向就很灵活了。可以把Transformer块换成Swin Transformer看效果差异，或者把CNN编码器换成ResNet34、ResNet101做对比实验。分割头部分也可以改成DeepLab风格的ASPP，提升多尺度特征融合能力。

我自己后来在TransUnet基础上加了多尺度监督，在不同分辨率上分别计算loss，训练收敛更快，最终Dice还提升了0.8个点左右。这个改动成本很低，只需在解码器的每一级输出后加一个分割头，加权计算loss即可。

最后再分享一个实际使用中的心得：复现模型时不要追求每一步都跟官方完全一致，先保证整个训练流程能跑通，再逐步对照源码修正细节。我第一版只用了两层跳连，Dice在74左右，后来补上完整四层跳连后到了76.8。先跑通再优化，这个过程比直接抄一份官方代码要学到的东西多得多。如果你在复现时也遇到类似问题，欢迎按这篇文章的排查思路对照检查，大部分坑都能在里面找到答案。

本文还有配套的精品资源，点击获取