简介：这份资源面向希望将CrossFormer落地到图像分类任务的开发者与研究者，提供了一套可直接运行的实战工程。CrossFormer通过跨尺度注意力机制强化不同尺度特征间的信息交互，弥补传统视觉Transformer在多尺度建模上的短板，适合具备一定深度学习基础、想快速复现并验证该架构效果的中高级读者。压缩包共2000个文件，以1986张png图像数据为主，另含7个py脚本、4个pyc缓存、1个json类别映射、1个pth权重与1个txt说明，整体约835.34MB，覆盖数据、代码与模型权重。目前已有191人学习下载。借助其中的训练脚本、类别配置与预训练权重，读者可完成数据加载、模型训练、评估与推理全流程，并对照排错思路理解跨尺度注意力的实现细节，为迁移到自动驾驶、医疗影像等场景提供参考。
1. CrossFormer 实战：图像分类任务从选型到跑通
如果你最近在找一个能替换 ViT、Swin Transformer 的骨干网络来做图像分类，CrossFormer 大概率已经出现在你的候选列表里了。它最核心的设计是跨尺度注意力（Cross-Scale Attention），把不同尺度的特征图当成 token 来做注意力计算，而不是像 Swin 那样只在固定窗口内做自注意力。这意味着它在处理多尺度目标——比如森林遥感图像里大小不一的树冠、医学影像里不同尺寸的病灶——时，天然比固定窗口的方案更有优势。我第一次在森林图像分类任务上用它替换 Swin-T，同等参数量下 top-1 涨了约 1.8 个百分点，推理速度基本持平。这篇笔记就按我实际落地的路径，从环境搭建、数据组织、模型改造、训练调参到踩坑排查，把 CrossFormer 做图像分类这件事讲透。适合已经跑过至少一个 Transformer 分类模型、想换骨干或做多尺度场景优化的从业者。
2. CrossFormer 做图像分类：结构拆解与选型判断
2.1 跨尺度注意力到底解决了什么问题
标准 ViT 把图像切成固定大小的 patch，整张图从头到尾只有一个尺度。Swin 引入了层级结构，但注意力仍然限制在固定窗口内，窗口之间靠 shift 操作来交换信息。CrossFormer 的做法更直接：它把特征图按不同尺度分组，每组内部的 token 做自注意力，同时用一个跨尺度注意力模块让不同尺度的 token 之间也能交互。
具体来说，CrossFormer 的每个 stage 会输出多个尺度的特征图，比如 stage 1 输出 H/4 × W/4 和 H/8 × W/8 两个尺度。跨尺度注意力模块把这两个尺度的 token 拼接后做注意力，再拆回去。这样做的代价是显存占用比 Swin 高一些，但换来的是模型能同时关注局部细节和全局结构。
对于图像分类任务，这个特性在两类场景下收益最明显：一是目标尺度差异大的数据集（遥感、病理、森林图像），二是需要同时利用纹理和形状信息的数据集（细粒度分类）。如果你的数据集里目标尺度比较统一，比如标准的 ImageNet 风格，CrossFormer 的优势不会特别突出，用 Swin 或 ConvNeXt 可能更划算。
2.2 分类任务的模型改造点
CrossFormer 官方实现主要是为检测和分割设计的，直接拿来做分类需要改三个地方。
第一，分类头。原版输出的是多尺度特征图，分类任务只需要最后一个 stage 的全局池化特征。常见做法是在最后一个 stage 后接一个 LayerNorm + 全局平均池化 + Linear。
第二，输入尺寸。CrossFormer 对输入尺寸有要求，因为每个 stage 要做 patch merge，尺寸需要能被 4、8、16、32 整除。做分类时我一般把输入固定为 224×224 或 256×256，避免动态尺寸带来的 reshape 报错。
第三，位置编码。原版用的是可学习的位置编码，分类任务如果输入尺寸和预训练不一致，需要做插值。我一般直接用 224×224 从头训，或者用 256×256 加载预训练权重后插值。
下面是一个最小可跑的模型改造代码：
import torch import torch.nn as nn from crossformer import CrossFormer # 假设已安装官方实现 class CrossFormerClassifier(nn.Module): def __init__(self, num_classes=10, img_size=224, drop_path_rate=0.1): super().__init__() # 加载骨干，注意 embed_dim 和 depths 按需选 self.backbone = CrossFormer( img_size=img_size, in_chans=3, embed_dim=96, depths=[2, 2, 6, 2], num_heads=[3, 6, 12, 24], group_size=[7, 7, 7, 7], drop_path_rate=drop_path_rate, ) # 取最后一个 stage 的输出维度 self.norm = nn.LayerNorm(96 * 8) # 最后一层通道数需按实际配置确认 self.head = nn.Linear(96 * 8, num_classes) def forward(self, x): # backbone 返回多尺度特征列表，取最后一个 feats = self.backbone(x) x = feats[-1] # [B, C, H, W] x = x.mean(dim=[-2, -1]) # 全局平均池化 x = self.norm(x) return self.head(x)逻辑说明：CrossFormer的forward返回一个列表，每个元素是一个 stage 的输出特征图。分类任务只取最后一个 stage，做全局平均池化后接线性层。embed_dim和depths是控制模型大小的关键参数，embed_dim=96, depths=[2,2,6,2]对应的是 Tiny 级别，参数量约 28M。drop_path_rate在分类任务上建议设 0.1 到 0.2，防止过拟合。
参数说明：group_size控制每个尺度分组的大小，默认 7 在 224 输入下工作良好。如果输入改成 256，group_size 可以保持 7 不变，但需要确认 patch merge 后的尺寸能被整除。num_heads要和embed_dim匹配，一般保持每个 head 的维度在 32 左右。
2.3 和 Swin、ConvNeXt 的选型对比
| 模型 | 参数量 (Tiny) | ImageNet top-1 | 多尺度能力 | 显存占用 | 适合场景 |
|---|---|---|---|---|---|
| CrossFormer-T | 28M | 81.5% | 强 | 较高 | 多尺度目标、遥感、病理 |
| Swin-T | 28M | 81.3% | 中 | 中 | 通用分类、检测 |
| ConvNeXt-T | 28M | 82.1% | 弱 | 低 | 通用分类、边缘部署 |
从表里能看出来，CrossFormer 在同等参数量下精度和 Swin 接近，但多尺度能力更强。代价是显存占用比 Swin 高约 15% 到 20%，因为跨尺度注意力需要同时保留多个尺度的 token。如果你的显卡显存紧张，或者任务对多尺度不敏感，ConvNeXt 是更稳的选择。我一般会在项目初期用 Swin-T 跑一个 baseline，如果发现多尺度目标漏检或误分类严重，再换 CrossFormer 做对比。
3. 数据准备与训练配置：从文件夹到 DataLoader
3.1 图像分类数据集的目录组织
CrossFormer 做分类对数据格式没有特殊要求，标准的 ImageFolder 结构就行。我一般按下面这样组织：
dataset/ ├── train/ │ ├── class_0/ │ │ ├── img_001.jpg │ │ └── ... │ ├── class_1/ │ └── ... ├── val/ │ ├── class_0/ │ └── ...如果拿到的是原始数据，比如森林图像分类常见的多光谱 TIFF，需要先转成 RGB JPG 或 PNG。转的时候注意波段选择，一般取红、绿、近红外合成假彩色，或者直接取前三个波段。我踩过的坑是直接用多光谱 4 波段喂给模型，第一层卷积的in_chans没改，直接报错。
数据增强方面，分类任务我一般用 RandAugment + Mixup + CutMix。CrossFormer 对强增强的容忍度比 ViT 好，因为跨尺度注意力本身有一定的正则效果。但 CutMix 的 alpha 不要设太大，0.2 到 0.4 比较稳，太大容易欠拟合。
3.2 训练脚本的核心参数
下面是一个基于 PyTorch 的最小训练循环，关键参数都标了注释：
import torch from torch.utils.data import DataLoader from torchvision import datasets, transforms from timm.data import Mixup from timm.loss import SoftTargetCrossEntropy # 数据增强 train_tf = transforms.Compose([ transforms.RandomResizedCrop(224, scale=(0.6, 1.0)), transforms.RandomHorizontalFlip(), transforms.RandAugment(num_ops=2, magnitude=9), transforms.ToTensor(), transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]), ]) val_tf = transforms.Compose([ transforms.Resize(256), transforms.CenterCrop(224), transforms.ToTensor(), transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]), ]) train_set = datasets.ImageFolder('dataset/train', transform=train_tf) val_set = datasets.ImageFolder('dataset/val', transform=val_tf) train_loader = DataLoader(train_set, batch_size=64, shuffle=True, num_workers=8, pin_memory=True, drop_last=True) val_loader = DataLoader(val_set, batch_size=64, shuffle=False, num_workers=8, pin_memory=True) # Mixup + CutMix mixup_fn = Mixup( mixup_alpha=0.8, cutmix_alpha=0.4, cutmix_minmax=None, prob=0.5, switch_prob=0.5, mode='batch', label_smoothing=0.1, num_classes=len(train_set.classes) ) # 优化器：AdamW + 余弦退火 model = CrossFormerClassifier(num_classes=len(train_set.classes)).cuda() optimizer = torch.optim.AdamW(model.parameters(), lr=1e-3, weight_decay=0.05) scheduler = torch.optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=100) criterion = SoftTargetCrossEntropy() for epoch in range(100): model.train() for imgs, labels in train_loader: imgs, labels = imgs.cuda(), labels.cuda() imgs, labels = mixup_fn(imgs, labels) optimizer.zero_grad() outputs = model(imgs) loss = criterion(outputs, labels) loss.backward() torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=5.0) optimizer.step() scheduler.step() # 验证略逻辑说明：Mixup和CutMix通过timm的Mixup类组合使用，prob=0.5表示每个 batch 有 50% 概率做混合。SoftTargetCrossEntropy是配合混合标签的损失函数。梯度裁剪max_norm=5.0在 CrossFormer 上比较重要，因为跨尺度注意力的梯度偶尔会爆，不裁剪的话 loss 容易飞。
参数说明：lr=1e-3是 AdamW 的常见起点，如果 batch size 小于 64，可以降到 5e-4。weight_decay=0.05是 Transformer 类模型的常用值，比 CNN 的 1e-4 大很多，因为注意力层更容易过拟合。T_max=100要和总 epoch 数一致，余弦退火才能完整走完一个周期。
3.3 学习率预热和分层衰减
CrossFormer 的骨干如果加载了预训练权重，分类头是随机初始化的，直接上大学习率会把预训练特征打乱。我一般加 5 到 10 个 epoch 的线性预热，让分类头先跟上。另外，骨干和分类头用不同的学习率，骨干用小 10 倍的学习率，分类头用正常学习率。
# 分层学习率 backbone_params = list(model.backbone.parameters()) head_params = list(model.head.parameters()) + list(model.norm.parameters()) optimizer = torch.optim.AdamW([ {'params': backbone_params, 'lr': 1e-4}, {'params': head_params, 'lr': 1e-3}, ], weight_decay=0.05) # 预热 warmup_epochs = 10 def warmup_lr(epoch): if epoch < warmup_epochs: return (epoch + 1) / warmup_epochs return 1.0 scheduler = torch.optim.lr_scheduler.LambdaLR( optimizer, lr_lambda=lambda e: warmup_lr(e) * (0.5 * (1 + math.cos(math.pi * e / 100))) )这样做的效果是训练初期 loss 下降更稳，验证集精度在前 20 个 epoch 就能超过从头训的最终精度。如果显存够，batch size 尽量往 128 以上拉，CrossFormer 对 batch size 的敏感度比 Swin 低，大 batch 下精度更稳。
4. 避坑与排查：CrossFormer 分类任务的血泪经验
4.1 输入尺寸不整除导致 reshape 报错
现象：训练启动后报RuntimeError: shape '[-1, 56, 56]' is invalid for input of size ...，或者 patch merge 时维度对不上。
原因：CrossFormer 每个 stage 要做 patch merge，输入尺寸必须能被 4、8、16、32 依次整除。比如输入 225×225，stage 1 输出 56.25，取整后 stage 2 就对不上。
解决：固定输入为 224×224 或 256×256。如果必须用其他尺寸，改成 32 的倍数，比如 288×288。另外检查img_size参数是否和实际输入一致，不一致时位置编码插值也会出问题。
4.2 显存溢出但 batch size 已经很小
现象：batch size 降到 16 还是 OOM，但换成 Swin-T 同样 batch size 能跑。
原因：CrossFormer 的跨尺度注意力会同时保留多个尺度的 token，显存占用和输入尺寸的平方成正比，而且比 Swin 多一个尺度的缓存。224 输入下，CrossFormer-T 的显存占用约等于 Swin-T 的 1.2 倍。
解决：优先用混合精度训练（AMP），能省 30% 到 40% 显存。如果还不够，把group_size从 7 降到 5，减少每个尺度的 token 数。再不行就换 CrossFormer 的更小配置，比如embed_dim=64, depths=[2,2,4,2]。
from torch.cuda.amp import autocast, GradScaler scaler = GradScaler() for imgs, labels in train_loader: with autocast(): outputs = model(imgs) loss = criterion(outputs, labels) scaler.scale(loss).backward() scaler.step(optimizer) scaler.update()4.3 预训练权重加载后精度反而下降
现象：加载官方预训练权重后，验证集精度比从头训还低，或者前几个 epoch loss 震荡严重。
原因：官方预训练权重是在 ImageNet 上训的，输入尺寸和你的任务可能不一致，位置编码插值后引入了噪声。另外，分类头是随机初始化的，直接加载骨干权重后，分类头的梯度会反向传播到骨干，破坏预训练特征。
解决：加载权重后先冻结骨干，只训分类头 5 个 epoch，然后再解冻全部微调。或者用分层学习率，骨干学习率设为分类头的 1/10。如果输入尺寸和预训练不一致，位置编码插值后先跑一个 epoch 的预热，学习率从 1e-5 开始。
4.4 验证集精度波动大，同一模型两次训练差 2 个点
现象：同样的配置跑两次，验证集 top-1 差 1.5 到 2 个百分点，找不到稳定复现的规律。
原因：CrossFormer 的跨尺度注意力对随机种子比较敏感，尤其是drop_path_rate和 Mixup 的随机性叠加后，不同种子的初始化差异会被放大。另外，如果验证集样本量小于 5000，本身统计波动就有 1 个点左右。
解决：固定随机种子，包括torch.manual_seed、numpy.random.seed、random.seed，并设置torch.backends.cudnn.deterministic = True。如果验证集小，用 5 折交叉验证取平均，不要只看单次结果。drop_path_rate设 0.1 比 0.2 更稳，波动能控制在 0.5 个点以内。
4.5 训练后期 loss 突然飞掉
现象：训练到 60 到 80 epoch 时，loss 从 0.5 突然跳到 3.0 以上，验证集精度断崖下跌。
原因：余弦退火后期学习率虽然小了，但 CrossFormer 的跨尺度注意力在深层容易积累梯度，加上 Mixup 的软标签在后期可能和模型预测冲突，导致梯度爆炸。
解决：加梯度裁剪，max_norm=5.0是安全值。另外在最后 20 个 epoch 关掉 Mixup 和 CutMix，用硬标签微调，loss 会稳很多。如果已经飞了，从最近一个验证集精度最高的 checkpoint 恢复，把学习率再降一半继续跑。
5. 进阶技巧：用特征图可视化验证 CrossFormer 的多尺度能力
训练跑通之后，怎么确认 CrossFormer 真的在利用多尺度信息，而不是只靠最后一个 stage 的全局特征？我一般会做两件事：一是可视化跨尺度注意力图，二是用不同尺度的输入做推理对比。
先看注意力图。CrossFormer 的跨尺度注意力模块会输出每个尺度 token 的注意力权重，把这些权重 reshape 回特征图尺寸，叠加到原图上，就能看到模型在关注哪些区域。下面是一个最小可视化脚本：
import matplotlib.pyplot as plt import torch.nn.functional as F def visualize_attention(model, img_tensor, layer_idx=-1): """img_tensor: [1, 3, 224, 224]""" model.eval() # 注册 hook 抓取跨尺度注意力权重 attn_maps = [] def hook(module, input, output): attn_maps.append(output.detach().cpu()) # 假设 backbone 的跨尺度注意力模块可访问 handle = model.backbone.layers[layer_idx].register_forward_hook(hook) with torch.no_grad(): _ = model(img_tensor.cuda()) handle.remove() # 取第一个注意力头，reshape 回空间尺寸 attn = attn_maps[0][0, 0] # [N, N] side = int(attn.shape[0] ** 0.5) attn = attn.reshape(side, side) attn = F.interpolate(attn[None, None], size=(224, 224), mode='bilinear', align_corners=False)[0, 0] plt.imshow(attn.numpy(), cmap='jet', alpha=0.5) plt.imshow(img_tensor[0].permute(1, 2, 0).numpy()) plt.axis('off') plt.show()逻辑说明：通过 forward hook 抓取指定层的输出，取第一个注意力头的权重矩阵，reshape 成空间图后插值回原图尺寸，叠加显示。如果注意力集中在目标区域，说明跨尺度模块在工作；如果注意力分散在全图，可能是group_size设得太大，或者预训练权重没加载好。
参数说明：layer_idx=-1表示最后一个 stage，也可以设 0 看浅层注意力。side的计算依赖 token 数，如果 token 数不是完全平方数，需要先 pad 或裁剪。实际用的时候，建议对同一张图分别用 224 和 288 输入跑一次，对比注意力区域是否随尺度变化。如果两个尺度下注意力区域基本一致，说明模型没有真正利用多尺度信息，可能需要检查跨尺度注意力的实现是否正确。
另一个验证方法是消融实验：把跨尺度注意力模块替换成普通的自注意力，保持其他配置不变，跑同样的训练。如果精度下降超过 1 个点，说明多尺度确实在起作用；如果基本持平，说明你的数据集对多尺度不敏感，换回 Swin 或 ConvNeXt 更划算。
我自己的习惯是，每次换骨干网络都先跑一个 10 epoch 的小实验，看 loss 曲线和验证集精度趋势，再决定要不要投入完整训练。CrossFormer 在小实验阶段就能看出多尺度能力的差异，如果 10 epoch 内验证集精度比 Swin 低，后面也很难追回来。希望帮到你。
本文还有配套的精品资源，点击获取
