简介这份资源面向希望上手视觉Transformer的深度学习开发者与图像分类学习者围绕CrossFormer这一引入跨尺度注意力机制的新型架构提供从模型搭建到训练评估的完整实战代码帮助解决传统ViT在多尺度特征交互上的不足。压缩包共2000个文件以1986张png图像数据为主另含7个py脚本、4个pyc缓存、1个json类别映射、1个pth预训练权重及1个txt说明整体约835.34MB可直接用于复现图像分类流程。目前已有191人学习下载。读者能获得可运行的训练脚本、类别配置与权重文件并借助图像样本理解数据组织方式适合作为课程设计、科研入门或工程落地的参考模板。1. 跨尺度注意力到底解决了什么从一张 224 的图说起图像分类做到今天ResNet 那套「一层层往下采样」的范式已经被 Transformer 啃得差不多了。但真把 ViT 拉到自己数据集上跑很多人会撞上同一个问题模型对全局结构敏感对局部细节迟钝。一张 224×224 的图patch 切完就是 196 个 token全塞进自注意力计算量随分辨率平方涨小目标、细纹理基本被平均掉。CrossFormer 的思路不是继续堆 token而是把特征图分成多个尺度让不同尺度的特征互相「看一眼」——这就是跨尺度注意力Cross-Scale Attention。它要解决的是传统视觉 Transformer 在多尺度特征交互上的短板让细节和结构能同时被照顾到。这份资源围绕 CrossFormer 做图像分类实战从数据组织、模型加载、训练评估到推理验证都有对应代码和样例图适合已经跑过至少一个分类基线、想换架构对比效果的从业者也适合需要把多尺度建模落到具体任务上的工程同学。2. 环境与数据准备把 class.json 和那批 png 理顺2.1 依赖版本与目录结构CrossFormer 官方实现依赖 PyTorch、timm 以及 einops 这类张量重排库。我一般不会一上来就装最新版而是先锁一个能跑通的组合避免 CUDA 和 torchvision 版本打架。下面这套是我在单卡 3090 上验证过的A100 或 4090 同理显存 12G 起步比较稳。# 建议用 conda 隔离避免污染已有环境 conda create -n crossformer python3.9 -y conda activate crossformer # torch 版本按自己 CUDA 驱动选这里给的是 cu118 组合 pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cu118 # CrossFormer 依赖 timm 的层实现和 einops 做维度重排 pip install timm0.9.12 einops0.7.0 pip install numpy pillow tqdm tensorboard逻辑说明torch 和 torchvision 必须版本对齐否则torchvision.ops里某些算子会报符号未定义。timm 锁 0.9.x 是因为 CrossFormer 的 block 实现引用了 timm 的DropPath和to_2tuple0.9 之后接口没大改但 1.x 有破坏性变更。einops 负责把(B, H, W, C)和(B, N, C)之间来回倒CrossFormer 的多尺度分支全靠它。参数说明python3.9是保守选择3.10 也能跑cu118对应驱动 520 以上驱动低就换 cu117。装完用python -c import torch; print(torch.cuda.is_available())确认返回 False 就先解决驱动别急着往下走。数据这块资源里给了class.json和一批 png5e4d1ee0d.png、77291b3ad.png、0367e0199.png、5a8b75712.png、8029e3396.png、d09db3735.png、ade525bad.png、14719a83e.png、898f2827c.png。class.json是类别映射通常是{0: cat, 1: dog}这种索引到名称的字典png 就是样本图。我一般按下面的结构摆dataset/ ├── train/ │ ├── class_a/ │ │ ├── 5e4d1ee0d.png │ │ └── ... │ └── class_b/ │ └── ... ├── val/ │ ├── class_a/ │ └── class_b/ └── class.jsonclass.json放在 dataset 根目录训练脚本读它来对齐ImageFolder的class_to_idx。这里有个容易翻车的点ImageFolder是按文件夹名排序生成索引的如果class.json里的顺序和文件夹字母序不一致标签就会错位。稳妥做法是训练前打印一次dataset.class_to_idx和class.json对一遍。2.2 数据增强与 DataLoader 配置图像分类的增强不用太花CrossFormer 本身对尺度敏感所以 RandomResizedCrop 是主力配合水平翻转和颜色抖动就够。下面这段是可直接抄的 Dataset 构建import json from torchvision import datasets, transforms from torch.utils.data import DataLoader # 读类别映射用于推理时把索引翻回名称 with open(dataset/class.json, r, encodingutf-8) as f: class_map json.load(f) train_tf transforms.Compose([ transforms.RandomResizedCrop(224, scale(0.6, 1.0)), # 尺度扰动喂给多尺度分支 transforms.RandomHorizontalFlip(p0.5), transforms.ColorJitter(0.2, 0.2, 0.2), 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, transformtrain_tf) val_set datasets.ImageFolder(dataset/val, transformval_tf) train_loader DataLoader(train_set, batch_size32, shuffleTrue, num_workers8, pin_memoryTrue, drop_lastTrue) val_loader DataLoader(val_set, batch_size32, shuffleFalse, num_workers8, pin_memoryTrue)逻辑说明RandomResizedCrop的scale(0.6, 1.0)是关键它让同一张图在不同 epoch 呈现不同尺度正好喂给 CrossFormer 的跨尺度分支做交互比固定 resize 更能压出模型的多尺度能力。drop_lastTrue在训练集上开避免最后一个 batch 只有一张图导致 BatchNorm 统计抖动。参数说明batch_size32是 12G 显存的保守值CrossFormer-T 在 224 分辨率下大概占 8G 左右想上 64 得看显存。num_workers8按 CPU 核数调Windows 上如果报共享内存错误就降到 0 或 2。Normalize用的是 ImageNet 统计量如果你自己的数据分布差得远可以换成数据集自身的 mean/std但多数迁移场景直接用 ImageNet 的就行。3. 模型加载与训练循环CrossFormer 怎么接进分类头3.1 从 timm 拉 CrossFormer 并改分类层CrossFormer 在 timm 里有现成实现直接create_model就能拉不用自己重写 block。关键是num_classes要改成你的类别数pretrainedTrue会下 ImageNet 权重小数据集上必须开否则收敛慢到怀疑人生。import torch import torch.nn as nn import timm device torch.device(cuda if torch.cuda.is_available() else cpu) num_classes len(train_set.classes) # 和 class.json 对齐 # CrossFormer 有 tiny/small/base/large 几档小数据集先用 tiny model timm.create_model( crossformer_tiny, # 也可换 crossformer_small pretrainedTrue, num_classesnum_classes, drop_rate0.1, # 分类头 dropout drop_path_rate0.1, # 随机深度防过拟合 ) model model.to(device) # 打印参数量心里有数 total sum(p.numel() for p in model.parameters()) print(ftotal params: {total/1e6:.2f}M)逻辑说明timm.create_model会自动把预训练权重的分类头丢掉换成num_classes对应的新 Linear 层所以不用手动改head。drop_path_rate是 CrossFormer 这种深层 Transformer 的正则化重点小数据集上 0.1 到 0.2 之间调太大欠拟合太小过拟合。参数说明crossformer_tiny参数量约 28Msmall约 50Mbase破百。类别数少于 10 且样本几千张tiny 足够上万张再考虑 small。drop_rate只作用在分类头drop_path_rate作用在每个 block 的残差分支两者别混。3.2 训练循环与学习率调度CrossFormer 对学习率比 CNN 敏感预训练权重加载后主干用小学习率微调分类头用大学习率从头学这是常见做法。下面这套带 warmup 的 cosine 调度我在多个分类任务上复用from torch.optim import AdamW from torch.optim.lr_scheduler import CosineAnnealingLR, LinearLR, SequentialLR epochs 50 base_lr 1e-4 head_lr 1e-3 # 主干和分类头分组给不同学习率 backbone_params [p for n, p in model.named_parameters() if head not in n] head_params [p for n, p in model.named_parameters() if head in n] optimizer AdamW([ {params: backbone_params, lr: base_lr}, {params: head_params, lr: head_lr}, ], weight_decay0.05) warmup LinearLR(optimizer, start_factor0.01, total_iters5) cosine CosineAnnealingLR(optimizer, T_maxepochs - 5, eta_min1e-6) scheduler SequentialLR(optimizer, schedulers[warmup, cosine], milestones[5]) criterion nn.CrossEntropyLoss(label_smoothing0.1) for epoch in range(epochs): model.train() running_loss, correct, total 0.0, 0, 0 for imgs, labels in train_loader: imgs, labels imgs.to(device), labels.to(device) optimizer.zero_grad() logits model(imgs) loss criterion(logits, labels) loss.backward() # 梯度裁剪Transformer 训练必备 torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm1.0) optimizer.step() running_loss loss.item() * imgs.size(0) correct (logits.argmax(1) labels).sum().item() total imgs.size(0) scheduler.step() train_acc correct / total print(fepoch {epoch1}/{epochs} loss {running_loss/total:.4f} acc {train_acc:.4f})逻辑说明分组学习率是微调 Transformer 的核心技巧主干已经在 ImageNet 上学到通用特征大学习率会把它们冲掉分类头是随机初始化需要快速下降。label_smoothing0.1缓解过自信对类别不平衡的小数据集尤其有用。clip_grad_norm_防梯度爆炸Transformer 深了之后不裁剪很容易 loss 变 NaN。参数说明base_lr1e-4是 tiny 档的稳妥值small 可以降到 5e-5。weight_decay0.05是 AdamW 的常用配置别用 SGD 那套 1e-4。warmup 5 个 epoch 让模型先稳住再进 cosine 退火。max_norm1.0是经验值报梯度异常时先看这个。3.3 验证与指标落盘训练完不验证等于白跑。验证阶段关掉增强用torch.no_grad()省显存同时把混淆矩阵和每类准确率存下来方便定位是哪个类拖后腿。from sklearn.metrics import classification_report, confusion_matrix import numpy as np model.eval() all_preds, all_labels [], [] with torch.no_grad(): for imgs, labels in val_loader: imgs imgs.to(device) logits model(imgs) preds logits.argmax(1).cpu().numpy() all_preds.extend(preds) all_labels.extend(labels.numpy()) all_preds np.array(all_preds) all_labels np.array(all_labels) acc (all_preds all_labels).mean() print(fval acc: {acc:.4f}) # 类别名从 class.json 翻回来报告才可读 target_names [class_map[str(i)] for i in range(num_classes)] print(classification_report(all_labels, all_preds, target_namestarget_names)) print(confusion_matrix(all_labels, all_preds))逻辑说明classification_report给出每类的 precision/recall/f1比单一 acc 信息量大得多。混淆矩阵能看出模型把哪两类搞混如果某两类互相错得厉害要么加数据要么检查标注。参数说明target_names的顺序必须和ImageFolder的class_to_idx一致否则报告里的类名会张冠李戴。class_map的 key 是字符串所以用str(i)取。4. 避坑与排查那些让 loss 不降的细节4.1 现象loss 从第一个 epoch 就 NaN原因学习率给大了或者梯度没裁剪CrossFormer 的跨尺度分支在反向时梯度范数容易冲高。解决先把base_lr降到 1e-5 跑两个 epoch 看 loss 是否正常下降确认后再往上加同时确保clip_grad_norm_在step()之前调用。如果还 NaN检查输入归一化是不是漏了像素值 0-255 直接进网络必炸。4.2 现象训练 acc 很高val acc 卡在随机水平原因过拟合或者训练集和验证集分布不一致。CrossFormer 参数量大几千张图很容易记住训练集。解决把drop_path_rate提到 0.2加weight_decay到 0.1增强里加RandomErasing。如果 val acc 一直不涨而 train acc 飙到 99%先查验证集是不是和训练集同分布别急着调模型。4.3 现象报错size mismatch for head.weight原因num_classes和预训练权重的分类头对不上或者加载权重时没设strictFalse。用timm.create_model时它会自动处理但如果你是手动load_state_dict必须加strictFalse跳过分类头。解决确认num_classes len(train_set.classes)且class.json的类别数和文件夹数一致。4.4 现象显存够但报 OOM原因batch_size看着不大但 CrossFormer 的多尺度分支会临时放大激活值峰值显存比同参数量的 CNN 高。解决开torch.cuda.amp混合精度或者把batch_size减半、梯度累积两步。混合精度写法是with torch.autocast(device_typecuda):包住前向scaler.scale(loss).backward()替换普通 backward。4.5 现象验证集准确率波动大每次跑结果差很多原因随机种子没固定或者drop_path在验证时没关。解决训练前设torch.manual_seed(42)、np.random.seed(42)验证前调model.eval()。如果还波动检查DataLoader的shuffle在验证集上是不是误开了验证必须shuffleFalse。5. 推理与进阶把模型用起来再压一压训练完的模型最终要落到推理。单张图推理的流程和验证类似但多了预处理对齐和类别名回填。下面这段可以直接拿去用from PIL import Image def predict(img_path, model, class_map, device): model.eval() img Image.open(img_path).convert(RGB) tensor val_tf(img).unsqueeze(0).to(device) # 用验证集同款预处理 with torch.no_grad(): logits model(tensor) prob torch.softmax(logits, dim1) idx prob.argmax(1).item() return class_map[str(idx)], prob[0, idx].item() # 拿资源里的样例图试一张 name, score predict(dataset/val/class_a/5e4d1ee0d.png, model, class_map, device) print(fpred: {name}, score: {score:.4f})逻辑说明推理的预处理必须和验证集完全一致Resize(256)CenterCrop(224)一步都不能少否则分布偏移会让准确率掉一截。softmax后的分数不是校准概率只用来排序别当置信度直接对外报。参数说明class_map的 key 是字符串索引str(idx)转换别漏。如果批量推理把unsqueeze(0)去掉一次喂多张但要注意显存。进阶方向有两个。一是换更大的 backbonecrossformer_small或base但前提是数据量跟上几千张图换大模型基本是负收益。二是把 CrossFormer 当特征提取器冻结主干只训分类头适合样本极少的情况这时base_lr设 0只留head_lr。验证方法上我习惯在训练结束后跑一遍 TTA测试时增强把原图和水平翻转的预测平均通常能涨 0.5 到 1 个点代价是推理时间翻倍。有个血泪经验CrossFormer 的预训练权重对输入分辨率有隐含假设224 是原生训练尺寸你硬拉到 384 而不做位置编码插值准确率会掉得莫名其妙。真要上高分辨率先确认 timm 里的img_size参数有没有跟着改。从那以后我每次换分辨率都强制先跑一遍单张推理看输出是否合理再开训练。希望帮到你。本文还有配套的精品资源点击获取