企业官网建设流程全解析

微软开源的 Swin Transformer 已经发布好几年了，但直到今天，它依然是很多视觉团队落地 Transformer 模型时的首选骨干网络。原因很简单：它把"全局注意力"拆成了"窗口注意力 + 移位窗口"，用近乎线性的计算量拿到了媲美 CNN 的精度和极强的下游迁移能力。但源码评测和工程治理审计这个角度却很少有人认真做——大家通常只跑一下 ImageNet 预训练权重，或者在检测框架里换掉 backbone 就完事。我这次把 microsoft/Swin-Transformer 仓库从配置管理、数据管线、模型构建到训练循环完整过了一遍源码，并针对工程落地做了选型评估。这篇东西适合两类人看：一类是准备把 Swin 引入生产环境的算法工程师，另一类是想通过经典源码提升代码功力的同学。我会把源码里真正值得抄的设计、需要改的坑、以及落地上容易踩的雷都讲清楚。

1. 项目定位与工程治理视角的框架梳理

1.1 Swin-Transformer 在视觉模型里的坐标

在动源码之前，先明确这个项目在整个视觉模型生态里的位置。Swin Transformer 的核心创新是提出了层级式 (hierarchical) 的特征金字塔结构，配合窗口自注意力 (window-based self-attention) 和移位窗口 (shifted window) 机制。和 ViT 那种全局 16x16 patch 一路算到底不同，Swin 采用类似 CNN 的下采样策略：先做 4x4 patch embedding，然后通过 Patch Merging 逐步把分辨率降为 1/8、1/16、1/32，形成多尺度特征。正是这个设计让 Swin 天然适合检测和分割这类需要多尺度信息的任务，也让它从"纯图像分类模型"变成了"通用视觉骨干"。

这一点直接决定了工程治理的难度。如果只是拿 Swin 做分类，那它和普通 ViT 没有本质区别；但如果要把它接入 Faster R-CNN、Mask R-CNN、UperNet 这类下游框架，就要考虑特征层对齐、窗口乘法在特征图上的作用方式、以及预训练权重如何与下游 head 拼接。官方仓库里同时保留了 classification、detection、segmentation 三个方向的实验配置，我这次审计以 classification 主线为主，因为这是整个仓库的地基。

1.2 "工程治理审计"到底想解决什么问题

我理解的"工程治理"不是指代码规范检查那种静态审计，而是从可维护性、可复现性、可扩展性三个维度去评估一个开源项目能不能顺畅地落到自己的业务里。以 Swin-Transformer 仓库为例，典型问题包括：配置系统和模型代码的耦合程度高不高？能不能在不改源码的情况下切换不同规格的模型？训练脚本的随机性控制是否到位？混合精度和分布式训练是否开箱即用？下游迁移时权重文件是否好对接？

带着这些问题去读源码，你会发现它不是一个"玩具项目"，而是微软团队为 ImageNet 比赛和后续多个研究复现准备的工程底座。但与此同时，它也存在若干只做了"研究够用"、没做"生产可用"的地方。比如数据增强依赖 timm 库，训练脚本里大量使用全局常量，部分配置参数散落在命令行而不是 yaml 文件里。这些在落地时都需要二次封装。我在后续章节会具体指出这些点。

2. 仓库结构与配置系统的源码拆解

2.1 目录结构全景：一个研究仓库的典型布局

拿到 microsoft/Swin-Transformer 仓库后，第一眼看到的是这样的结构：

Swin-Transformer/ ├── main.py # 分类训练入口 ├── config.py # 命令行参数定义 ├── models/ │ ├── build.py # 根据配置构建模型 │ ├── swin_transformer.py # Swin 核心实现 │ ├── swin_mlp.py # Swin-MLP 变体 │ └── vision_transformer.py ├── data/ │ ├── build.py # 构建 dataloader │ ├── dataset.py # 数据集类（ImageNet 等） │ ├── samplers.py # 分布式采样器 │ ├── imagenet.py # ImageNet 数据增强（依赖 timm） │ └── ... ├── utils.py # 工具函数 ├── engine.py # 训练/验证循环 ├── optimizers.py # 优化器与学习率调度 ├── lr_scheduler.py # 多种 LR 策略 ├── configs/ # yaml 配置目录 └── main_detection/ # 检测/分割下游实验

这个布局很典型：研究项目通常把"模型定义"和"训练脚本"分开，把"配置"和"代码"通过 argparse 连接起来。好处是换模型、换数据集时不需要动 Python 代码，坏处是如果配置项太多，config.py 会膨胀成一个"参数沼泽"。Swin 仓库没有用 Hydra 或 OmegaConf 这类高级配置库，而是用 yaml + argparse 的组合。实际用下来，对于单模型仓库这已经足够了。

2.2 配置系统审计：yaml 与 argparse 的双层结构

Swin-Transformer 的配置逻辑是这样工作的：main.py接受一个--cfg参数指向 yaml 文件，然后config.py中定义的get_config()函数会读取这个 yaml 并把它与命令行参数合并。如果用户在命令行额外指定了某个参数，它会覆盖 yaml 里的值。

# config.py 的核心结构 def get_config(): parser = argparse.ArgumentParser('Swin Transformer training and evaluation script', add_help=False) parser.add_argument('--cfg', type=str, required=True, metavar="FILE", help='path to config file') parser.add_argument('--batch-size', type=int, help='total batch size') parser.add_argument('--lr', type=float, help='initial learning rate') # ... 省略大量参数 _C = Config() args = parser.parse_args() _C.merge_from_file(args.cfg) # 先从 yaml 加载 _C.merge_from_list(opts) # 再用命令行覆盖 return _C

从工程治理角度看，这套设计有一个明显优点：模型结构相关的超参数（如SWIN.EMBED_DIM、SWIN.DEPTHS、SWIN.WINDOW_SIZE）全部收敛在 yaml 文件里，和训练超参数（如TRAIN.LR_SCHEDULER）分开管理。这比把模型参数硬编码在代码里要规范得多。

但也有两个值得注意的问题。第一，仓库里不同 yaml 之间大量重复字段，比如MODEL.TYPE、DATA.DATASET在每个文件里都出现，维护时如果只改一个文件很容易漏改其他文件。第二，config.py里用_C.merge_from_list(opts)时需要在命令行手动写MODEL.SWIN.WINDOW_SIZE 7这种点分键，语法不够友好。我落地时通常会把外层再包一层简单的load_config函数，统一默认值，避免散落在各处的硬编码。

2.3 模型构建的工厂模式：尽量少改业务代码

models/build.py是连接配置和模型类的桥梁。它的核心逻辑是根据config.MODEL.TYPE来选择模型类：

def build_model(config): model_type = config.MODEL.TYPE if model_type == 'swin': model = SwinTransformer( img_size=config.DATA.IMG_SIZE, patch_size=config.MODEL.SWIN.PATCH_SIZE, in_chans=config.MODEL.SWIN.IN_CHANS, num_classes=config.MODEL.NUM_CLASSES, embed_dim=config.MODEL.SWIN.EMBED_DIM, depths=config.MODEL.SWIN.DEPTHS, num_heads=config.MODEL.SWIN.NUM_HEADS, window_size=config.MODEL.SWIN.WINDOW_SIZE, mlp_ratio=config.MODEL.SWIN.MLP_RATIO, qkv_bias=config.MODEL.SWIN.QKV_BIAS, qk_scale=config.MODEL.SWIN.QK_SCALE, drop_rate=config.MODEL.DROP_RATE, drop_path_rate=config.MODEL.DROP_PATH_RATE, ape=config.MODEL.SWIN.APE, patch_norm=config.MODEL.SWIN.PATCH_NORM, use_checkpoint=config.TRAIN.USE_CHECKPOINT, fused_window_process=config.MODEL.SWIN.FUSED_WINDOW_PROCESS, ) elif model_type == 'swin_mlp': ...

这种"工厂 + 配置"的写法在开源视觉仓库里几乎是标配了。好处是后续加新的 model_type 只需在 build.py 增加分支，不会污染已有模型代码。另外注意fused_window_process这个参数，它控制是否把 window_partition/window_reverse 用 CUDA 扩展加速。我在推理时实测过，开启 fused 操作可以让移位窗口的耗时降低 5%-10%，后面会在部署章节详细讲。

3. 核心源码深度解析：从 Patch Embedding 到移位窗口

3.1 Patch Embedding 与 Patch Merging 的工程实现

Swin 的 Patch Embedding 并不是简单地把图像切成 patch 再拉平，而是用一层Conv2d同时完成"切块"和"线性投影"两个操作。具体来说，patch_size=4时，输入(B, 3, H, W)通过一个 stride=4、kernel=4 的卷积变成(B, embed_dim, H/4, W/4)，然后展平成(B, H/4 * W/4, embed_dim)。这里有个容易被忽略的细节：patch_norm=True时，这个 Patch Embedding 是一个Sequential(Conv2d, LayerNorm)，LayerNorm 作用在通道维度上。源码里这一层的实现非常紧凑：

self.proj = nn.Conv2d(in_chans, embed_dim, kernel_size=patch_size, stride=patch_size) if patch_norm: self.norm = nn.LayerNorm(embed_dim) else: self.norm = None def forward(self, x): B, C, H, W = x.shape x = self.proj(x).flatten(2).transpose(1, 2) # (B, H*W, C) if self.norm is not None: x = self.norm(x) return x

工程上值得学习的一点是：用卷积实现 patch 化在 GPU 上效率非常高，比直接用F.unfold再 reshape 的速度快得多。这个小技巧在 ViT 系列的代码里其实并不通用，很多实现反而绕了远路。

Patch Merging 的思路更直接，把 2x2 邻域的特征在通道维上拼接，然后通过 Linear 把 4C 压缩成 2C，其实就是一种"空间下采样 + 通道升维"操作。源码里还做了一个LayerNorm(channels)放在 Linear 之前。这里要提醒一句：Patch Merging 的输出顺序是(B, H/2, W/2, 2C)，后面接的通常是LayerNorm(2C)，所以代码里每次都先x = x.view(B, H, W, C)，再 merge，再展平。如果自己实现时搞混了维度顺序，很容易出现"结果不对但又不报错"的 bug。

3.2 Window Attention 的实现细节与性能关键点

Window Attention 是 Swin 的核心，它把特征图按window_size * window_size划分成互不重叠的窗口，只在窗口内部计算自注意力。源码里的关键函数是window_partition和window_reverse：

def window_partition(x, window_size): B, H, W, C = x.shape x = x.view(B, H // window_size, window_size, W // window_size, window_size, C) windows = x.permute(0, 1, 3, 2, 4, 5).contiguous().view(-1, window_size, window_size, C) return windows def window_reverse(windows, window_size, H, W): B = int(windows.shape[0] / (H * W / window_size / window_size)) x = windows.view(B, H // window_size, W // window_size, window_size, window_size, -1) x = x.permute(0, 1, 3, 2, 4, 5).contiguous().view(B, H, W, -1) return x

注意window_partition必须在(B, H, W, C)的布局下操作，所以 attention 之前要把(B, N, C)重新 reshape 成(B, H, W, C)。这一步在源码里非常频繁，也是很多二次开发同学最容易出错的地方——原始特征如果是(B, N, C)布局，直接 reshape 成(B, H, W, C)时，序列顺序和空间位置的对应关系必须搞清楚。

真正让 Window Attention 在工程上有价值的是它的显存效率。全局注意力在H=W=224、window_size=7时的复杂度约为局部注意力的几十倍，而精度只差 1-2 个点。这也是 Swin 能在消费级显卡上训练的底气。源码里 attention 函数的实现如下：

def forward(self, x, mask=None): B_, N, C = x.shape qkv = self.qkv(x).reshape(B_, N, 3, self.num_heads, C // self.num_heads).permute(2, 0, 3, 1, 4) q, k, v = qkv[0], qkv[1], qkv[2] q = q * self.scale attn = (q @ k.transpose(-2, -1)) attn = attn + self.relative_position_bias_table # 实际是查表后相加 if mask is not None: attn = attn.view(B_ // num_windows, num_windows, num_heads, N, N) + mask.unsqueeze(1).unsqueeze(0) attn = attn.view(-1, num_heads, N, N) attn = softmax(attn) attn = self.attn_drop(attn) x = (attn @ v).transpose(1, 2).reshape(B_, N, C) x = self.proj(x) x = self.proj_drop(x) return x

这里 mask 的处理是关键：在 shifted window 模式下，窗口中的 token 可能来自特征图中的非相邻区域，为了让注意力只在"空间相邻"的 token 之间计算，需要按窗口的移位方向生成 mask。源码中mask的 shape 是(num_windows, window_size*window_size, window_size*window_size)，在compute_mask函数里通过H // window_size的网格坐标差值生成。整个过程非常 tricky，我第一次读的时候花了大半天才理清。

3.3 相对位置编码：用一个查表操作替代学习 embedding

Swin 没有采用 ViT 的绝对位置编码，而是学习了一个相对位置偏置表 (relative_position_bias_table)。表格形状是(2*window_size-1) * (2*window_size-1), num_heads，也就是 window_size=7 时有 13x13=169 个位置对，每个 head 一个偏置值。在 attention 计算流程中，会通过get_relative_position_index生成每个位置对的坐标差索引，然后用这个索引去查表。

这个设计背后有个工程优势：相对位置偏置天然具有平移等变性，也就是说位置偏移相同的一对 token 共享同一个偏置，这使得模型在小窗口上训练后，对更大分辨率图像的推理也具备一定泛化能力。实测中，Swin 可以从 224 分辨率直接迁移到 384 或 512 分辨率，相对位置表不需要重新训练，这在部署时非常方便。

不过要注意：把relative_position_index和relative_position_bias_table以 buffer 方式注册到模型里后，导出 ONNX 或者转 TensorRT 时会遇到"动态 shape 下索引表尺寸不匹配"的问题。这块我在部署章节会给出具体解决办法。

3.4 完整前向传播链路：Stage、Block 与整体流程的串联

Swin 的前向流程可以概括为四层循环：先 Patch Embedding，然后依次经过 4 个 Stage，每个 Stage 内包含若干 BasicLayer，每个 BasicLayer 内包含两个带不同窗口配置的 SwinTransformerBlock。基础 block 的计算顺序是：LayerNorm -> Window Attention -> 残差 -> LayerNorm -> MLP -> 残差，同时会有 drop path 和随机深度 (stochastic depth) 的叠加。

有经验的读者会发现，SwinTransformerBlock 在 forward 里之所以要区分shift_size > 0和shift_size == 0两种分支，就是为了在同一个 block 中实现 Cycle Shift。官方代码在 shifted 分支会先torch.roll把特征图按(-shift_size, -shift_size)滚动，再重新 partition，然后加上 mask 做 window attention，最后window_reverse后再 roll 回来。这一串操作的数值正确性很好验证，但速度会有额外开销。所以官方同时提供了CUDA fused window process扩展来合并这些操作。我在训练 Swin-B 的时候开过 fused，单 step 耗时大约能降 7% 左右，建议有条件就开。

4. 训练系统工程治理审计与复现性评估

4.1 训练循环与学习率策略的源码审计

官方训练脚本用的是标准的 "warmup + cosine decay" 学习率策略，入口在lr_scheduler.py。它支持 cosine、linear、step 等多种调度器，默认情况下使用 cosine。整个训练过程中还有一个容易被忽略的细节：当get_num_layer和get_layer_id被启用时，Swin 会对浅层和深层分别设置不同的学习率，也就是 layer-wise lr decay。这个机制在实际调参时很有用，尤其是下游迁移场景。

从工程治理角度，官方训练循环的最大问题在于"过于集中"。engine.py里train_one_epoch函数包含了混合精度、梯度累积、EMA（可选）、日志输出等多个关注点，代码行数不短。对于想在生产环境二次开发的团队，我建议直接参考它的写法，但把训练循环拆成 "Trainer" 类来管理，否则后期加个 warmup 阶段的梯度裁剪或者异常检测，会把 engine.py 改得越来越难维护。

复现性方面，官方在main.py设置了随机种子，同时把torch.backends.cudnn.benchmark打开。这里有个矛盾点：benchmark=True会提升速度但可能引入轻微的非确定性，严格复现时建议在推理和评测阶段把它关掉。我在训练时有几次在不同机器上结果差 0.1 个点，排查到最后发现就是 cudnn benchmark 和 CPU 线程数的差异。

4.2 数据管线与 ImageNet 增强链路

Swin 的数据增强大部分来自 timm，包括 RandomResizedCrop、RandomHorizontalFlip、ColorJitter、RandAugment、Mixup、Cutmix 和 RepeatedAugmentation。这些在data/imagenet.py里组装，源码里有一长串 args 控制 aug 强度，比如AUG.RANDAUGMENT_N、AUG.MIXUP、AUG.CUTMIX等。这个设计的好处是方便复现论文结果，坏处是每个增强参数都暴露在 yaml 里，对不熟悉 timm 的开发者不友好。

落地时我通常会做两处改动：第一，把训练增强和验证增强拆成两个独立 pipeline，因为生产环境经常需要自定义预处理；第二，把data/dataset.py里的 ImageFolder 依赖替换成自己的数据集类，官方实现的硬编码路径和 class index 映射在私有数据集上不太够用。

还有一个容易踩坑的点：samplers.py里的DistributedSampler和RepeatAugSampler。RepeatAugSampler 是 Swin 官方为了在 1024 batch size 等大 batch 场景下避免重复样本导致精度下降而引入的。它的逻辑是"对每个样本重复多次再做采样"，代码本身没问题，但如果你并行训练时开了num_replicas或rank参数不对，会出现训练集样本被重复采样的隐患。建议只在 batch size 大于 512 时开启。

4.3 混合精度、Checkpoint 与容错机制

官方通过torch.cuda.amp实现了混合精度训练，amp_autocast和GradScaler的使用是标准写法。Swin 因为大量用到 LayerNorm 和 Softmax，这些算子在 FP16 下存在精度风险，所以源码中部分算子会被 autocast 抬高到 FP32。在做 FP16 推理时，LayerNorm 的方差计算容易在低精度下产生偏差，我实测 Swin-L 转半精度在 ImageNet 验证集上会掉 0.1-0.3 个点，视觉上不容易发现但统计上明显。

Checkpoint 方面，官方只保存了model、optimizer、lr_scheduler和epoch，没有做模型结构哈希和数据集指纹校验。这意味着你换 GPU 数量或者改 batch size 后继续训练，只能靠人工确认训练状态是否对齐。对于生产环境，我强烈建议额外保存一个 json 记录 config、随机种子、数据版本、git commit hash。我以前在一个检测项目里就吃过亏：pretrain 权重和实际训练配置差了 2 个 layer 的初始化，结果模型不收敛，排查了两天才发现是 checkpoint 和 config 不匹配。

5. 落地选型指南：Swin vs 其他骨干，以及场景适配

5.1 参数与精度的横向对比：哪些场景选 Swin-T，哪些选 Swin-B

按官方报告数据（ImageNet-1K，224 分辨率，单 crop），几个常用档位的表现大致如下：

选型时我的经验是：云端训练、离线场景优先 Swin-B，它相比 Swin-S 的显存成本高不了太多但精度更稳；移动端或实时性场景选 Swin-T，配合蒸馏或量化后精度仍然可用；如果预算充足且任务复杂，可以考虑用 ImageNet-22K 预训练的 Swin-L，它在检测、分割上的增益往往比分类更明显。

不过要注意：Swin 的 FLOPs 并不等于实际推理延迟。窗口注意力在 CPU 上不如 CNN 高效，在 GPU 上又要看是否启用了 fused window、TensorRT 是否针对roll + partition做了优化。所以做 latency benchmark 时必须用真实推理环境测，不能只看 FLOPs 表。

5.2 与 ViT、ConvNeXt、Focal Transformer 的核心取舍

把 Swin 和几个主流骨干放在一起看，会更清楚它的优势边界。ViT 在超大预训练数据下精度上限更高，但在中小数据上收敛慢、需要大量 trick；ConvNeXt 通过纯 CNN 结构复刻了 Swin 的训练配方，推理生态更成熟，但架构表达能力在超大规模数据上有争议；Focal Transformer 在 Swin 基础上引入了 fine-to-coarse 注意力，精度确实更高，但实现复杂度也上去了，社区成熟度不够。

工程落地上我一般这样判断：如果团队主要做检测/分割，且希望用统一的 backbone 承载多个任务，Swin 依然是首选，因为它的多尺度设计已经被下游框架反复验证过。如果只是做纯分类或者 CLIP 类图像塔，ViT 和 ConvNeXt 也可以考虑，有一张 ViT-B 的精度可能还略胜 Swin-B。如果业务有严格的延迟预算，我建议先测 ConvNeXt-T，它的卷积实现更容易被量化到 TensorRT 里。

5.3 预训练权重迁移与下游任务对接经验

Swin 官方权重在 ImageNet 上很稳，但迁移到自己的数据集时，需要注意最后 classification head 不一致的问题。官方实现里num_classes是硬编码在模型构造函数里的，加载预训练权重时一般会通过strict=False加载，并在代码里过滤掉head相关 key。我用来加载检测预训练权重时，直接复用mmdetection的load_checkpoint就行，它已经处理好了 prefix 的问题。

如果你用的是自己的训练框架，我建议把官方权重先 pad 到统一 dict，再按model.backbone.加前缀。Swin 的 block 命名和 detector 里的backbone.layers不一定一致，这一步很容易出错。另外，Swin 的relative_position_index和relative_position_bias_table是 buffer，它们在 load_state_dict 时必须存在。如果框架自动把 buffer 当成可训练参数过滤掉，就会报 KeyError。遇到这个问题，检查load_state_dict(..., strict=False)的输出，确认缺失的 key 列表里只有head相关参数，才算加载正确。

6. 常见问题与避坑记录：实战中的排查思路

6.1 显存不足：window_size、patch_size 与 batch size 的联动调整

Swin 在训练时经常遇到显存不够，第一个排查方向是window_size。它在窗口内部计算注意力，窗口越大显存开销越高，但感受野也更大。官方在 224 分辨率下默认window_size=7，如果你把输入分辨率提到 384，就必须同步把window_size调大到 12 或干脆保持 7 但接受性能下降——注意，window_size必须能被H / patch_size整除，否则会直接报错。第二个排查方向是BATCH_SIZE和梯度累积。Swin 在 batch size 较小的情况下 BN 统计不稳定，但它的所有归一化都是 LayerNorm，所以 batch size 可以很小而不影响精度，这是我比较推荐的做法：用小 batch + grad accumulation 来适配大模型，而不是盲目减分辨率。第三个方向是开启use_checkpoint=True，梯度检查点会在反向传播时重新计算中间激活，显存能省 40% 左右，代价是训练时间增加约 20%。

6.2 训练不收敛或精度低于论文：数据增强与学习率的匹配问题

我在复现 Swin-B 时遇到过精度比论文低 1% 的情况，排除了代码 bug 之后，最后锁定在两个地方：一是增强配置里AUG.MIXUP、AUG.CUTMIX开关是否和官方一致，mixup 概率开太高会在小数据集上明显掉点；二是lr和weight_decay是否匹配，Swin 官方的大模型通常用lr=1e-3、weight_decay=0.05，但你如果用 AdamW 且设置了不同 weight decay，很容易导致正则过强、收敛缓慢。另外如果你只用了单卡而 batch size 只有官方一半，最好把 lr 也相应调低，否则梯度噪声会毁掉整个训练曲线。

还要注意 warmup epoch 数。官方在大数据集上通常 warmup 20 个 epoch 左右，但小数据集上 warmup 过长反而会让模型前期学得太慢。我的经验是在私有数据集上 warmup 3-5 个 epoch 就够，重点观察 loss 是否能在前 100 个 iteration 里充分下降。如果 loss 一直降不下来，先检查数据标签有没有错位，再考虑改学习率。

6.3 推理性能瓶颈：fused window process 与 TensorRT 导出

Swin 在推理时的最大瓶颈集中在window_partition/window_reverse和torch.roll这类"数据搬移"操作上。在纯 PyTorch 环境里，建议显式开启fused_window_process=True，并确认你编译了对应的 CUDA extension。如果完全用 Python 实现，每个窗口的 4 次 reshape + transpose 会产生大量内存拷贝，GPU 利用率会明显下降。

往 TensorRT 或 ONNX 导出时，relative_position_index这个 buffer 是动态 shape 的大坑。建议导出前把relative_position_index转成常量或直接用torch.arange计算相对位置索引，避免 ONNX 在动态分辨率下报 shape 不匹配。还有一个更省事的方案：转 ONNX 时固定输入分辨率，尺寸变了就重新导出。对于生产环境来说，这不是一个"优雅"的方案，但确实最省心。

6.4 下游检测/分割的衔接问题：特征层命名与 UperNet 等框架

在 mmdetection 里用 Swin 做 backbone 时，最常见的问题有两个：第一，out_indices对应哪几个 stage。Swin 的features输出是一个包含 4 个 stage 特征的 tuple，对应分辨率分别是 1/4、1/8、1/16、1/32。mmdet 一般只需要后面三个，所以要设out_indices=(1, 2, 3)而不是默认值。第二，mask 和 roll 操作在 FPN 的forward里能否正确处理多尺度输入。Swin 的窗口机制天然依赖输入尺寸可以被window_size * patch_size整除，如果检测时输入尺寸不是 32 的倍数，结果可能直接崩或者精度严重下降。实操时我会把检测端的输入统一 resize 到 800x800、1280x1280 这类规范尺寸，保证H、W能被 32 整除。

分割任务里，如果用 UperNet 或 Segformer 风格框架接 Swin，还需要注意 LayerNorm 在permute后的维度问题。Swin 在 forward 里经常在(B, H, W, C)和(B, N, C)之间切换，如果下游 head 对通道顺序有严格要求，接收特征前要先permute(0, 3, 1, 2)。这个细节经常出现在自定义 loss 或者可视化脚本里，表现形式是一堆看似莫名其妙的维度报错。

7. 我的最终选型建议与工程化改造要点

如果让我一句话总结 Swin-Transformer 这个项目的工程价值，我会说：它是"研究代码"里最接近"生产代码"的那一档，但离真正的生产标准还有一段距离。它把模型结构、训练策略、下游任务验证都集成得比较完整，能够让你在几小时内从零跑出一个可复现的 ImageNet 结果；但它的配置管理、数据管线封装、推理导出支持等方面仍然停留在研究阶段，落地时需要做一轮"瘦身 + 加固"。

针对不同团队，我给出三个档次的改造建议。第一种是只做微调实验的团队：直接用官方仓库跑通，把权重导出到自己的框架，不需要深度改造。第二种是面向业务落地的团队：把 config 系统升级为统一的配置结构，把训练循环拆成 Trainer 类，增加数据版本和实验日志的记录，同时为推理单独封装一个model_export子模块，固定用 ONNX 或 TensorRT API 导出。第三种是在 Swin 基础上做架构创新的团队：建议先在官方代码上跑通小规模 ablation，再基于它的 block 结构开发新模型，这样能最大程度复用已经被验证过的 training recipe。

我在实际项目中最后选定的方案是：训练阶段用官方 Swin-B，稍作修改支持了 EMA 和梯度裁剪，部署阶段用 TensorRT 的 FP16 推理，配合fused_window_process扩展。整个流程下来，在检测任务上相对 ResNet-50 backbone 的 mAP 提升大约在 3-4 个点，同时推理延迟只在可接受范围内增加的 30% 左右。这算是一个比较稳妥的取舍。

最后再分享一个容易被忽视的经验：Swin 对输入分辨率非常敏感，训练时用 224 的模型，直接推理 512 的图可能会掉精度；但如果先用 384 分辨率微调几个 epoch，精度往往能进一步上升。所以如果你想在业务里用高分辨率输入，别省这一步微调。我的建议是从 224 拉高到 384 时，学习率调低 2-3 倍，warmup 用 1 个 epoch 就够，几轮就能看到明显提升。这个技巧在我的多个项目里都非常有效。