简介：一份围绕PoolFormer图像分类实战的资源包，适用于对Transformer轻量化架构、MetaFormer设计思路感兴趣的深度学习开发者和研究者。其核心思路是以简单pooling替换传统token mixer，在降低计算开销的同时保持较强的特征表达力，适合用于图像分类任务的快速验证与算法对比，对计算资源有限的场景尤为友好。压缩包内共2000余个文件，其中以2400余张PNG图像为主，构成训练与验证样本；另有5个Python脚本和1个模型权重文件，覆盖数据集划分、模型定义、训练、推理等关键环节，整体大小811MB。目前已有689人学习或下载。借助这份资源，读者可完整复现PoolFormer在图像分类任务上的实验结果，深入理解MetaFormer通用架构的落地细节；同时，基于附带的代码与权重，还能快速开展二次开发、消融实验或论文复现，让学习与实践更具指向性。
1. 先说结论：PoolFormer是把注意力换成池化的Transformer变体，图像分类实战可以直接照抄
提到PoolFormer，很多人的第一反应是它又堆了一个注意力机制的新模型。恰恰相反，PoolFormer把Transformer里的注意力模块整个拿掉，换成一个两行代码就能写完的3x3平均池化，在ImageNet同规模下精度反而超过了ResNet。这不是玄学，论文作者颜水成把原因归结为MetaFormer这个通用骨架：Transformer的成功更多来自整体结构，而不是某个具体的token混合器。手上的这份zip资源，是一套用PoolFormer实现图像分类任务的完整实战代码，覆盖从数据集准备、模型搭建到训练测试的完整链路。包内的截图记录了作者跑实验时的日志和曲线，先翻一遍能帮你省下不少对参数的时间。适合两类人：一类是想快速复现PoolFormer、把分类精度往上拉一截的工程师；另一类是研究视觉模型结构、想亲手对比注意力与池化差异的算法同学。
2. 架构拆解：MetaFormer通用框架与PoolFormer的极弱token混合器
2.1 MetaFormer把Transformer抽象成了哪几块
标准的Transformer Block长什么样？输入是一组token，对图像分类任务来说，就是把图片切成固定大小的patch再做线性映射，得到patch embedding序列。每个block内部有两个子层：第一个子层是token mixer，负责让不同位置的token交换信息，自注意力是最经典的实现；第二个子层是MLP，负责在每个token自身的特征空间里做非线性变换。两个子层前后各跟一个归一化，外面再套残差连接。大多数人研究Transformer时都盯着注意力看，但MetaFormer这篇论文提出了一个反直觉的观点：把token mixer当作一个黑匣子，只要它能在token之间传递信息，用注意力、用MLP、甚至用池化，都不影响整体框架的有效性。
# MetaFormer Block 骨架（PyTorch 伪代码） class MetaFormerBlock(nn.Module): def __init__(self, dim, token_mixer, mlp_ratio=4.0, norm_layer=nn.LayerNorm): super().__init__() self.norm1 = norm_layer(dim) self.token_mixer = token_mixer(dim) # Attention / MLP / Pooling 均可 self.norm2 = norm_layer(dim) self.mlp = Mlp(dim, hidden_features=int(dim * mlp_ratio)) def forward(self, x): x = x + self.token_mixer(self.norm1(x)) x = x + self.mlp(self.norm2(x)) return x这段代码是理解PoolFormer的钥匙。token_mixer在实例化时被替换成不同的算子，网络其他部分完全不用动。norm_layer用LayerNorm还是BatchNorm，在PoolFormer里有专门讨论，因为pooling没有可学习参数，归一化层的作用会被放大，这一点下文会展开。mlp_ratio控制MLP隐藏层宽度，一般取4，和ViT保持一致。残差连接用的是x + mixer(norm(x))的PreNorm顺序，和很多ViT实现相同。
把token mixer抽象成黑匣子之后，论文的第二个贡献就顺理成章了：用最简单的非参数算子pooling来实例化这个黑匣子，看看整体框架的精度上限到底受不受mixer影响。这就是PoolFormer名称的由来——Pooling加Former。
2.2 pooling为什么能当token mixer：极弱混合器反而更抗过拟合
PoolFormer里的pooling实现起来极其简单：对二维特征图做一次3x3、stride 1、padding 1的平均池化。如果输入是[B, N, C]的token序列，需要先reshape成[B, C, H, W]，池化完再reshape回去。
class Pooling(nn.Module): def __init__(self, pool_size=3, stride=1, padding=1): super().__init__() self.pool = nn.AvgPool2d(kernel_size=pool_size, stride=stride, padding=padding) def forward(self, x): B, N, C = x.shape # token 序列格式 H = W = int(N ** 0.5) x = x.transpose(1, 2).reshape(B, C, H, W) x = self.pool(x) x = x.flatten(2).transpose(1, 2) return x参数说明：pool_size取3，意味着每个token只和自己周围一圈的8个邻居做平均，感受野是3x3。stride必须为1，特征图尺寸不变才能走残差连接。padding取1是保证边界token也有完整邻域。整个模块没有任何可学习参数，梯度可以穿过平均池化反传到上一层，反向传播没有问题。
从频率角度看，平均池化等效一个低通滤波器，它会把高频的局部纹理差异抹平，因此网络更关注整体结构而非细节噪声，这在分类任务里反而带来更好的泛化。这个特性在纹理密集的场景，比如遥感森林图像分类里，体现得很明显：高频噪声被池化滤掉一层，训练更稳定。直觉上pooling太弱，不足以做复杂的token混合，但实验结果说明，只要MetaFormer框架在那里，MLP层会把特征逐步加工成判别性表示，mixer只负责让不同空间位置的信息有机会见面。这个发现直接挑战了"注意力是ViT成功核心"的说法。
关于归一化层的选择也要单独说。PoolFormer把注意力换成无参数的池化后，归一化层的作用被放大了：同一个结构用BatchNorm或LayerNorm，收敛速度和最终精度都会有可感知的差异。ViT系列默认用LayerNorm，但PoolFormer这类分阶段结构里，有的开源实现用BatchNorm，有的用LayerNorm，不同版本各不相同。只要代码里固定了一种，能让loss正常下降，没必要频繁切换；但从零训练时如果发现收敛很慢，把LayerNorm换成BatchNorm再试一次，往往有惊喜。
2.3 PoolFormer变体配置与选择
PoolFormer是分阶段设计，和PVT、Swin类似，有4个stage，每个stage由若干MetaFormerBlock组成，stage之间通过patch embedding下采样。官方提供了几个不同规模的变体，配置如下。
| 变体 | 各阶段 depth | 各阶段 channels | 定位 |
|---|---|---|---|
| PoolFormer-S12 | [2, 2, 6, 2] | [64, 128, 320, 512] | 轻量级，适合快速验证 |
| PoolFormer-S24 | [4, 4, 12, 4] | [64, 128, 320, 512] | 通用图像分类主力 |
| PoolFormer-S36 | [6, 6, 18, 6] | [64, 128, 320, 512] | 精度优先 |
| PoolFormer-M48 | [6, 14, 14, 6] | [96, 192, 384, 768] | 中等规模基线 |
表格里的数值来自论文和官方仓库，具体以你拿到的代码为准。channel从64起步、按2倍左右扩张到512，这和主流CNN的宽度设计一致，说明PoolFormer希望兼顾CNN的层级特征和Transformer式的全局建模。S12参数量最小，适合先验证环境和流程；S24的深度分布更均衡，是复现论文精度的推荐选择；显存充足、追求更高精度时用S36。M48接近ViT-B的规模和计算量，一般不作为第一选择。我一般会在正式训练前先用S12把整个pipeline跑通，确认数据集、增强、优化器都没问题，再换成S24正式开训，能省不少排查时间。
3. 复现准备：环境、数据集与zip包目录，一次对齐不容易返工
3.1 环境与依赖安装
先把zip包解压出来，建议放在一个不带中文路径和空格的目录下。很多训练脚本对路径里的中文支持不好，会报一些莫名其妙的FileNotFoundError，看起来像数据问题，其实只是路径编码问题。解压之后，环境建议单独建一个conda虚拟环境，避免和现有项目的包互相污染。
conda create -n poolformer python=3.8 -y conda activate poolformer pip install torch==1.12.0 torchvision==0.13.0 pip install timm==0.6.12 pip install tensorboardtorch锁在1.12是因为这套代码在这个版本下最稳，后面避坑章节会提到AMP和timm的版本耦合问题。如果机器是较新的Ubuntu系统，直接装更新的torch问题也不大，但timm版本要注意：timm超过0.9之后对旧模型定义的注册方式做了调整，PoolFormer的模型文件如果还是老写法，import时可能直接报错。装完环境后先跑一句命令确认版本。
python -c "import torch, timm; print(torch.__version__, timm.__version__)"3.2 数据集组织
图像分类最通用的数据组织方式是ImageFolder风格：每个类一个文件夹，文件夹名就是标签名，torchvision的datasets.ImageFolder可以直接读。如果你用的是自己的业务数据，也建议先整理成这个格式，后面换模型、换框架都省事。
data/ ├── train/ │ ├── dog/ │ │ ├── dog_001.jpg │ │ └── dog_002.jpg │ └── cat/ │ ├── cat_001.jpg │ └── cat_002.jpg └── val/ ├── dog/ │ ├── dog_val_001.jpg │ └── ... └── cat/ └── ...train和val的类名要完全一致，不能出现train里有dog、val里却没有的情况。类别顺序由文件夹名字母序决定，训练和测试必须用同一套映射关系。我不建议把数据集整个复制进项目目录，尤其是训练集上百GB时，复制一份既占磁盘又慢，用符号链接更省事。
mkdir -p data/train data/val ln -s /mnt/imagenet/train/dog data/train/dog ln -s /mnt/imagenet/val/dog data/val/dog数据路径准备好之后，先做一次加载验证，别直接开训练。用下面的脚本打印类别列表和样本数，确认与你预期一致。如果业务数据类别不均衡，这一步也能同时看到每类的样本量，类别少于50张的要么做增强要么合并，PoolFormer对尾部类别的拟合能力一般。
from torchvision import datasets, transforms train_ds = datasets.ImageFolder("data/train", transform=transforms.ToTensor()) print(train_ds.classes) print(len(train_ds), len(train_ds.classes))3.3 zip包内关键文件与目录说明
解压zip之后建议先把目录结构过一遍，再动手改代码。下面是这套资源里最常见的文件组织方式，不同版本的包可能略有出入，但核心模块都在。
| 文件/目录 | 作用 |
|---|---|
| main.py | 训练和评估入口，含参数解析、日志、checkpoint保存 |
| models/poolformer.py | PoolFormer模型定义，各变体配置与注册逻辑 |
| utils.py | 数据加载、增强、优化器、学习率调度等工具函数 |
| configs/ | 训练参数配置文件，可以直接改 |
| docs/截图.png | 配套博客的原理图和实验截图 |
models/poolformer.py是核心文件，里面的create_poolformer函数负责按变体名构建模型。如果只想做推理，可以只用这个文件；如果要改造模型结构，比如替换token mixer，也是在这个文件里动手。main.py里的参数几乎都有默认值，但数据路径、模型名、输出目录这三个每次训练前必须确认。docs下的截图是博客里的原理图和实验曲线，遇到精度对不上论文时，翻一张损失曲线对比一下，就能判断问题出在收敛还是数据。配套的CSDN博客里有更详细的图文推导，排查问题时可以把博客里画的block图和手里的代码对照着看。
4. 训练与测试：配置文件、启动命令与结果记录
4.1 配置文件里的关键参数
打开configs里的训练配置，核心参数就下面几组。用Python dict展示，实际可能是yaml或者直接写在main.py的argparse默认值里，含义都一样。
config = dict( model="poolformer_s12", # 模型变体 batch_size=128, # 单卡batch size，多卡按卡数倍增 lr=1e-3, # 初始学习率 min_lr=1e-5, # cosine退火的最低学习率 warmup_epochs=20, # 前20个epoch线性warmup weight_decay=0.05, # AdamW的权重衰减 epochs=300, # 总训练轮数 drop_path=0.1, # Stochastic Depth 概率 aa="rand-m9-mstd0.5-inc1", # RandAugment 策略 mixup=0.8, cutmix=1.0, # 数据混合增强 )lr设1e-3是ViT系模型的常用值，注意AdamW和SGD的最优学习率差一个量级，别拿CNN的0.1来套。warmup_epochs设20，是因为Transformer系结构在训练初期梯度震荡大，直接满学习率容易崩。drop_path是Stochastic Depth概率，S12用0.1，S36这种深模型一般提到0.2以上。mixup和cutmix对最终精度贡献明显，但训练代价也高，小规模数据想快速验证可以先关掉。min_lr配合cosine调度，训练后期把学习率降到很低，通常能比固定小学习率多出一个点左右的精度。
还有一个容易漏掉的细节是EMA，指数移动平均。很多分类训练脚本会维护一组模型参数的移动平均，训练结束后使用EMA权重去测试，通常能再抬零点几个点。PoolFormer官方训练里也有类似处理。如果你在main.py里看到model_ema相关代码，记得测试时加载的是ema版本而不是原始权重，两者精度差得不多，但对比baseline时不能混用。
4.2 单机多卡训练命令
训练入口是main.py，官方脚本用PyTorch的distributed.launch启动分布式训练。单机四卡命令如下。
python -m torch.distributed.launch --nproc_per_node=4 \ --master_port=29500 main.py \ --model poolformer_s24 \ --data-path ./data \ --batch-size 128 \ --lr 1e-3 \ --weight-decay 0.05 \ --warmup-epochs 20 \ --epochs 300 \ --output-dir ./output/poolformer_s24每卡128、4卡就是global batch 512。PoolFormer官方在8卡、每卡128的配置下用1e-3训练300轮，如果你的global batch明显偏小或偏大，建议按比例调整lr，否则精度会波动。master_port设一个不冲突的端口，多组训练同时跑的时候容易撞端口。
提示：多卡扩卡时，learning rate不需要严格随batch size翻倍。从4卡加到8卡，lr可以保持或乘1.5，看前几十个step的loss是否稳定再定，直接翻倍容易震荡。
如果是在自己的小数据集上微调，训练参数不要照搬ImageNet的300轮。我一般把epochs压到50到100，lr降到5e-4，warmup缩短到5个epoch，权重衰减保持0.05但drop_path降到0.05。预训练权重已经让模型处于一个比较好的初始点，大学习率很容易把学到的通用特征冲掉，这个现象在CNN上不明显，在MetaFormer这类结构上却很典型。第一次用自己的数据跑时，我会先只开20个epoch看loss下降曲线，确认能正常收敛再拉满，省得浪费一整轮训练时间。
4.3 测试与结果记录
训练结束或中途想验证当前权重，用evaluation模式跑一遍验证集。
python main.py \ --eval \ --model poolformer_s24 \ --resume ./output/poolformer_s24/best.pth \ --data-path ./data这个命令会加载best.pth，在val集上输出top-1和top-5准确率。main.py通常按epoch保存checkpoint，best.pth是验证集top-1最高的一版，last.pth是最后一轮。日志方面，tensorboard会记录每个epoch的train loss、val loss和top-1曲线。我判断训练是否正常就看两条曲线：train loss是不是平稳下降、val top-1是不是同步上升。如果train loss在降但val top-1纹丝不动，说明过拟合或增强强度不够，优先检查mixup、cutmix和drop_path这三个开关。这套流程走完，一份能复现的结果就有了，后面所有对比都拿这个做baseline。
5. 避坑笔记：PoolFormer实战中的四个高频问题
5.1 精度比论文低两三个点，先查优化器与warmup
现象：照搬配置训练完，验证集top-1比论文报告低2到3个百分点，train loss最终也没压到论文水平。
原因：最常见的是优化器选错或warmup没生效。PoolFormer基于MetaFormer框架，对AdamW的epsilon和weight_decay敏感；有人直接用SGD或Adam默认参数，收敛曲线完全不同。warmup配置给了但没生效的情况也常见，尤其是分布式训练时参数被覆盖。另外一点：复现精度要在相同数据增强下比，RandAugment和Mixup有没有开，能拉开两个点以上的差距。
解决：明确指定torch.optim.AdamW，lr设为1e-3，weight_decay设0.05，beta保持默认。warmup_epochs给到20，并确认lr真的从接近0开始线性上升。在第一个epoch的日志里打印lr，如果一开始就是满学习率，说明warmup配置没串到优化器里。这条排查完再谈其他。
5.2 加载官方预训练权重时报unexpected key
现象：用load_state_dict加载官方release的pth时，报missing key或unexpected key，最常见的是position embedding、cls_token以及分类头维度不一致。
原因：官方预训练权重是ImageNet 224输入，position embedding的shape是固定的；你自己的模型如果改了输入分辨率，或者分类类别数不是1000，权重自然对不齐。
解决：先排除分类头，再加载backbone部分。常见做法是按key名过滤掉head或fc前缀，position embedding单独拿出来做插值。
def load_pretrained(model, ckpt_path): state = torch.load(ckpt_path, map_location="cpu") if "state_dict" in state: state = state["state_dict"] new_state = {} for k, v in state.items(): if k.startswith("head") or k.startswith("fc"): continue new_state[k] = v missing, unexpected = model.load_state_dict(new_state, strict=False) if len(unexpected) > 0: print("ignored keys:", unexpected[:10]) return model跳过head/fc之后，剩余的key一般都能对上。如果position embedding的shape不匹配，会显示在missing里，需要从state里取出来用torch.nn.functional.interpolate插值到目标size。注意插值后要重新写成state_dict的key格式，别覆盖错位置。
5.3 混合精度训练loss变NaN
现象：开启AMP后训练到中后期loss突然变成NaN，或者前几个step就直接NaN，关掉AMP就正常。
原因：PoolFormer这种归一化加池化的结构，在fp16下容易出现梯度上溢；timm旧版优化器在AMP下对权重衰减的数值精度处理也有兼容问题，低学习率加上fp16会放大这个问题。学习率偏大时更容易爆。
解决：优先把AMP切到bfloat16，A100等新卡上稳定很多。如果只有fp16，把weight_decay临时降到0.02试一版，排除数值问题；还不行就关AMP。注意PoolFormer内部如果用了BatchNorm，BN在fp16下也容易出问题，虽然torch的autocast会自动处理前向，但需要把整个模型放进autocast作用域，别只在loss backward时开。
5.4 小数据集上过拟合、收敛慢
现象：自己只有几千张图，从零训练PoolFormer，验证集精度一直上不去，train loss却早就压到很低。
原因：池化token mixer没有可学习参数，特征表达完全靠MLP硬拟合，数据量不够时很容易把高频噪声学进去；从零训练时通道数较少的浅层收敛也慢。和多数图像分类算法一样，PoolFormer在小数据上也没有免死金牌。
解决：不要从零训，尽量加载ImageNet预训练权重做微调。如果任务图像和ImageNet域差距大，先用RandAugment、Mixup、CutMix全开的情况下跑一个中间模型，再在这个模型基础上继续微调。小数据集上把warmup拉长到30个epoch、lr降到3e-4，比默认参数稳定得多。还有一种思路是直接换PoolFormer-S12，参数量小，过拟合风险低。
6. 验证与进阶：把PoolFormer迁移到自己的数据集上
6.1 先跑通单图推理，作为一切改动的基准
迁移到自己的数据之前，先用一张验证集图片跑一次完整推理。这一步要确认三件事：图像预处理与训练一致、权重加载正确、分类头输出能对应上类名。预处理是最容易翻车的，训练时用的timm数据管线，推理时也要同一套，否则精度莫名掉一截。
from PIL import Image import torch from timm.data import create_model, create_transform model = create_model("poolformer_s24", pretrained=True, num_classes=1000) model.eval() transform = create_transform(224, is_training=False) img = transform(Image.open("test.jpg")).unsqueeze(0) with torch.no_grad(): logits = model(img) print(logits.argmax(dim=-1).item())create_transform里is_training=False就是推理预处理，包括resize到256、中心裁剪224、归一化。换成自己的数据时，把num_classes改掉，加载微调后的权重即可。
6.2 换掉token mixer，验证MetaFormer上界
进阶玩法就是把mixer抽象落到代码：保持其余结构不动，把Pooling替换成Identity或一圈简单注意力，就能在同一个数据上对比极弱混合器、无混合器和强混合器的差距。
# 在 poolformer.py 里替换 mixer 为 Identity class IdentityMixer(nn.Module): def forward(self, x): return x这个实验对理解MetaFormer很有价值。我做过的对照组显示：在中等规模数据上，Identity和Pooling的差距很小，说明MLP本身已经在做空间信息的部分重组；注意力在小数据上过拟合更明显，需要更强的增强才能稳住。
6.3 导出ONNX做部署验证
如果想把这个分类模型端到端部署，导出ONNX并按静态shape验证一遍就够了。PoolFormer中间有多次reshape，动态batch导出时要指定好维度。
torch.onnx.export(model, dummy, "poolformer.onnx", input_names=["input"], output_names=["logits"], opset_version=12, dynamic_axes={"input": {0: "batch"}})dummy是1x3x224x224的随机张量。导出后用onnxruntime跑一次推理，对比torch输出，误差在1e-4以内就算合格。
这几年我换过不少最新的图像分类模型，PoolFormer是少数让我重新审视"模型结构里到底什么是关键"的一个。从那以后，每次换新骨架我都会把token mixer单独提出来做一次控制变量实验，先跑单图推理、再跑小轮训练、最后才上全量数据，这套流程基本没翻过车。希望帮到你。
本文还有配套的精品资源，点击获取
