timm这个库，但凡做过图像分类、目标检测或者自监督学习的同学，多少都听说过。我最早接触它的时候，它还只是某个图像模型库的附属品，没想到几年下来，它已经成了PyTorch生态里离不开的模型弹药库。项目标题就一句话“Pytorch Image Models (timm)”，但背后牵扯的东西可不少：模型 zoo、预训练权重、训练 trick、迁移学习的基础设施。这篇文章我不打算写成 API 文档，那没意思。我按自己实际用的经验，把 timm 从安装、加载模型、改头、微调到踩坑，完整过一遍，顺便把那些网上搜不到但实测很关键的细节也一并写出来。

如果你是刚入门深度学习的小白，这篇文章可以帮你少走弯路；如果你已经在用 timm，我希望里面的几个排错思路能给你启发。我尽量说人话，不堆术语，到了必须讲原理的地方也会拿生活类比帮你理解。

1. timm 到底是什么：一个镜像库的自我修养

1.1 为什么需要统一接口

先理解一个最基础的问题：图像模型那么多，为什么大家偏要用 timm？

想象一下，你要做图像分类，今天想试试 ResNet，明天想试试 EfficientNet，后天又听说某个新出的 ViT 效果不错。如果每个模型都是独立的一套代码、不同的构造函数参数、不同的预处理方式，你得花多少时间去适配？ResNet 的输入是224x224，EfficientNet 不同版本可能要求240或260，ViT 要把图像切成 patch，还得加 position embedding。这些细节单看每个模型文档都能搞定，但一旦你想批量对比十几个模型，工作量就爆炸了。

timm 做的事就是把这些模型的差异隐藏在一层统一接口后面。你只需记住几个核心函数：create_model、list_models、get_pretrained_cfg。只要知道模型名字，就能创建模型，加载预训练权重，拿到和官方一致的预处理配置。这种设计思路，跟平时我们说的“适配器模式”很像：它不关心里面是哪家模型，只要外面这套接口统一，就能大批量地玩。

另外，timm 不只是把模型堆在一起，它还做了大量模型结构上的优化，比如很多模型支持不同的features_only模式，可以输出多尺度特征图；有些模型支持可变的输入分辨率；有些模型内部融合了多种注意力机制的实现变体。这些都不是单纯把 PyTorch 官方代码搬运过来就完事，而是二次开发后的结果。所以，timm 里很多模型的实现，和官方原版在细节上会有差别，有时候反而是 timm 的版本更好用。

1.2 timm 的设计哲学：模型工厂与预训练权重仓库

你把 timm 理解成一个模型工厂，它手里有两个核心资产：一个是有序组织的模型注册表，另一个是庞大的预训练权重库。

模型注册表是什么意思？就是你给create_model('resnet50')传一个字符串，它就能自动找到对应的模型类并实例化。这个注册机制不是硬编码一个巨大的if else，而是通过装饰器和全局字典实现的。开发者可以在 timm 里注册自己的模型，也可以把自己训练的模型权重登记进去。这样 timm 就不只是一个“消费者”库，它还可以是你自己的模型管理工具。

预训练权重库更是 timm 的灵魂。目前 timm 收录的预训练权重来源非常杂，有的是官方开源，有的是第三方用更强数据或者更强训练策略训出来的，还有的是通过自监督方法预训练的。不同来源的权重，在 ImageNet 上的准确率差异可能很大，甚至同一个模型名字，不同权重的表现能差一两个点。timm 通过pretrained_cfg来管理每个权重对应的训练配置，包括输入尺寸、归一化均值方差、插值方式、是否需要特定 crop ratio。你只要加载了对应的权重，它就能帮你把预处理参数一起调好。这是非常贴心的设计，因为很多模型非官方权重和预处理不匹配，直接套用 ImageNet 标准归一化，效果会打折扣。

所以，timm 的价值不只是一个“库”，更是一套“标准化的模型使用协议”。理解这套协议，后面用起来才会顺手。

2. 装起来很简单，但版本坑要提前讲

2.1 安装方式与依赖选择

安装 timm 的常规方式有两种。如果你不需要最新特性，直接用 pip：

pip install timm

这个装的是 PyPI 上的稳定版，经过测试，稳定性和兼容性都比较好。如果你需要最新模型或者 bug 修复，可以直接从 GitHub 装：

pip install git+https://github.com/huggingface/pytorch-image-models.git

我个人建议在项目里锁定具体版本号，而不是无脑timm==latest。原因很简单：深度学习框架发展太快，timm 每隔一段时间就会改模型默认参数，甚至去掉某些旧模型。你今天写的代码没问题，过几个月再跑，可能就报了Unknown model或者权重下载失败的错。锁定版本，至少能保证可复现。

依赖方面，timm 的核心依赖是 PyTorch 和 torchvision。但请注意，timm 对 torchvision 的依赖并不是硬性的。很多基础模块它自己实现了，比如RandomResizedCropAndInterpolation、RandAugment这些数据增强能力。它通常在setup.py里声明了torch>=1.7之类的条件，但真正跑起来时，你最好用一个比较新的 PyTorch，因为 timm 的新版本会用到一些新增的 API，比如torch.nn.functional.scaled_dot_product_attention，老版本 PyTorch 根本没有这个函数。

另外，timm 还依赖huggingface_hub，因为部分预训练权重是放在 HuggingFace Hub 上的。如果你在国内网络环境不好，下载权重会卡。这个后面我会专门讲怎么处理。

2.2 版本锁定：训练结果可复现的第一步

这里要展开讲一下版本锁定的重要性。做过科研或者比赛的同学应该深有体会：模型训练不是跑通就完事，而是要反复对比实验。如果 timm 的版本升级导致某个模型结构发生了变化，比如默认激活函数从 ReLU 换成了 SiLU，那同一个训练脚本跑出来的结果就完全变了。你之前辛辛苦苦调好的参数，可能全部作废。

我踩过这样一个坑：某次比赛我用 timm 里的一个模型跑 baseline，记录下来的准确率是 89.2%。几天后再跑，同一份代码，准确率变成了 89.4%。一开始我还以为是随机种子没固定，后来查了 timm 的更新日志，发现官方把某个特定模型默认的norm_layer从 BatchNorm 换成了 LayerNorm，这导致结果有了细微变化。从那时起，我每次新建项目都会在 requirements.txt 里锁死 timm 的版本，并且在模型保存时额外存一份 timm 的版本号。

如果你实在需要升级 timm，最好先跑一遍测试集，对比关键指标变化。深度学习是实验科学，任何依赖的升级都应该当作一次潜在的干扰因素来处理，别图省事。

3. 五分钟上手：加载模型与特征提取

3.1 最常用操作：create_model 与 pretrained 权重

timm 的使用核心就是create_model。我们看一个最简单的例子：

import timm # 列出所有以 resnet 开头的模型名字 names = timm.list_models('resnet*') print(names[:10]) # 创建模型，加载预训练权重 model = timm.create_model('resnet50', pretrained=True) # 查看模型默认输入尺寸和预处理配置 cfg = model.default_cfg print(cfg['input_size'], cfg['mean'], cfg['std'])

这段代码背后发生了几件事：它根据模型名去注册表里找到ResNet类，然后实例化一个默认配置的模型；pretrained=True时，它会去下载或者从本地缓存加载预训练权重；加载完之后，default_cfg里存了和你手上权重匹配的预处理参数。这些参数在你用torchvision.transforms.Normalize时是必须用上的，不然输入数据的分布就和训练时不匹配，模型输出的 logits 就失真了。

有一点要注意，pretrained=True默认为真时，timm 会选择该模型的“最佳可用权重”，但这个“最佳”是浏览下来口碑最好的那个来源。如果你想指定某个具体权重，可以用pretrained_cfg_name或者直接在模型名后面带 tag，例如：

model = timm.create_model('resnet50.a1_in1k', pretrained=True)

这种带后缀的写法叫“权重标签”，a1_in1k表示这个权重是在 ImageNet-1k 上用某种特定的增强策略训练出来的。有时候不同标签的权重差异很大，不要只看模型名字就完事。

3.2 修改分类头：适应自己的类别数

大多数场景下，我们不是直接用 ImageNet 的 1000 类，而是换成自己的数据集。这时需要修改模型的分类头。timm 为此专门提供了参数num_classes：

model = timm.create_model('efficientnet_b0', pretrained=True, num_classes=10)

这个操作会把原模型的最后一层全连接层替换成输出 10 类的新层。看起来很简单，但里面有一个坑：部分模型在分类头之前还有特殊结构，比如池化层、dropout 层、全局平均池化等。timm 的reset_classifier方法对这些结构做了统一处理，一般来说是没问题的。不过，如果你顺便设置了drop_rate，新分类头会继承这个 dropout 配置，训练时没问题，推理时你可能会发现输出概率分布变得平滑一些，这是正常的，因为 dropout 在 eval 模式下会自动关闭。

如果你不想加载预训练权重，想从头随机初始化模型，直接设pretrained=False就行。这种情况下，模型内部的 BatchNorm 统计量也是随机的，需要足够的训练轮次才能稳定。对于小数据集，强烈建议使用预训练权重做迁移学习，因为从零训练一个小网络很容易过拟合，而且收敛慢得多。

3.3 提取中间层特征：不止输出最后一层

图像检索、风格迁移、跨模态特征对齐这些任务，经常需要拿到模型中间层的特征图，而不是最后的分类向量。timm 提供了features_only选项和自定义 hook 两种方式。

先看features_only：

model = timm.create_model('resnet50', pretrained=True, features_only=True, out_indices=[2, 3, 4]) x = torch.randn(1, 3, 224, 224) features = model(x) print(len(features)) # 3 for f in features: print(f.shape)

out_indices里的数字对应不同的 stage，具体含义不同模型不同，一般从浅到深，数字越大特征图分辨率越小、通道数越多。这个功能在做目标检测的 Neck 特征融合时特别有用，比如你用 YOLO 系列框架时，想要骨干网络输出 P3、P4、P5 特征图，直接用 timm 的features_only就能拿到，省得自己写 forward hook。

如果你只想要某一个中间模块的输出，也可以手动注册 forward hook：

activation = {} def hook_fn(module, input, output): activation['value'] = output model = timm.create_model('resnet50', pretrained=True) model.layer4.register_forward_hook(hook_fn) x = torch.randn(1, 3, 224, 224) model(x) print(activation['value'].shape)

这种方案更灵活，适合调试。但要注意，如果你后续修改了模型结构，hook 所在的模块可能不存在了。所以在做结构修改时，尽量把 hook 挂在通用的 stage 模块上，而不是具体到某些可能被删除的层。

4. 迁移学习实战：把预训练模型用出效果

4.1 数据预处理与增强的匹配

迁移学习的第一步不是创建模型，而是把数据处理好。很多人直接拿 torchvision 的Resize、Normalize一套，也没细想。但 timm 里的很多模型，尤其是 EfficientNet 系列和 ViT 系列，对输入尺寸和 crop 比例非常敏感。

以efficientnet_b0为例，官方推荐的输入尺寸是 224x224，但它在训练时用的 RandomResizedCrop 的比例范围是 0.08 到 1.0，而验证时用的是按比例缩放后中心裁剪。这些细节在default_cfg的crop_pct和interpolation字段里都有。你加载模型后，应该直接用这些配置来构建验证集 transform：

from timm.data import resolve_data_config from timm.data.transforms_factory import create_transform cfg = resolve_data_config(model=model, verbose=True) train_tfms = create_transform(**cfg, is_training=True) val_tfms = create_transform(**cfg, is_training=False)

create_transform会根据模型配置自动生成合适的数据增强 pipeline，包括随机裁剪、翻转、RandAugment、Mixup、CutMix 等。这些增强策略都是 timm 官方训练时用过的，和我们手里的预训练权重匹配度很高。如果自己临时换一套增强，比如直接用了 AutoAugment 或者粗粒度的增强，可能导致训练不稳定。

这里有一个经验：迁移学习初期，先用 timm 默认增强，后面模型收敛了再逐步加强增强策略，可以有效避免一开始就震荡。别把比赛里的 heavy augmentation 一上来就怼在小数据集上，容易把预训练特征破坏掉。

4.2 分层学习率与解冻策略

很多迁移学习教程会告诉你：把冻结的 backbone 训一轮，然后解冻全部层再训。但这只是一种粗放策略。timm 模型内部结构复杂，不同层对应不同抽象层次的特征，前面层学到的是通用边缘、纹理，后面层学到的是和 ImageNet 类别相关的抽象特征。对于自己的数据集，如果和 ImageNet 差异较大，比如医学图像、卫星图像，那么后面层需要更大程度地调整，前面层可以少调甚至不动。

一个比较稳的策略是分层设置不同的学习率。具体做法是：将模型参数按名称分组成 backbone 参数和 head 参数。对 backbone 设置较低的学习率，比如 1e-4，对 head 设置较高的学习率，比如 1e-3。还可以进一步将 backbone 划分为多个阶段，每个阶段的学习率乘以一个衰减系数，使得靠近输入的层学习率更低。

param_groups = [ {'params': model.features.parameters(), 'lr': 1e-4}, {'params': model.classifier.parameters(), 'lr': 1e-3}, ] optimizer = torch.optim.AdamW(param_groups, weight_decay=0.01)

不过，model.features和model.classifier并不是所有模型都有的属性。timm 中不同模型的命名规则不同，有的叫backbone、head，有的叫stages、fc。这时候可以通过get_parameter_count或者直接遍历named_parameters，根据层名里的关键字来分组。比如名称包含blocks、layer的是骨干部分，包含classifier、head、fc的是头部。

解冻策略上，我建议不要一步到位。先冻结全部 backbone，只训练新 head，跑一个小 epoch 看看 loss 是否下降。如果 loss 能正常下降，说明数据和预训练特征间没有严重冲突。然后解冻最后一个 stage，再训练几个 epoch，观察验证集指标。如果提升明显，再解冻更多层。这种渐进解冻的方式，比一次性全解冻更容易稳定收敛，也便于定位是哪个阶段造成了过拟合。

4.3 混合精度与 EMA：让训练更稳更快

timm 官方训练代码里大量使用了混合精度训练和指数移动平均（EMA）。这两个技术也是我训练模型时默认开启的。

混合精度训练，简单说就是在前向传播和反向传播中使用 FP16，但在优化器更新时用 FP32 保存权重副本。这样能减少显存占用，也能加快计算，尤其是 T4/V100/A100 这类支持 Tensor Core 的显卡上收益明显。PyTorch 自带的实现：

from torch.cuda.amp import autocast, GradScaler scaler = GradScaler() for images, labels in dataloader: images, labels = images.cuda(), labels.cuda() with autocast(): outputs = model(images) loss = criterion(outputs, labels) scaler.scale(loss).backward() scaler.step(optimizer) scaler.update()

注意，使用混合精度时，BatchNorm 层的统计量可能会受影响。建议在训练初期不开启混合精度，等模型 warmup 完成后再开启，或者使用 grad scaler 的动态损失缩放来解决梯度下溢的问题。timm 里很多模型设计时就考虑了 FP16 的稳定性，但如果你自定义了模型结构，FP16 可能出现 NaN loss，这时需要检查是否有未转为半精度的层，或者暂时关闭 AMP。

EMA 是对模型参数做滑动平均。它的思想是：训练后期，参数在最优解附近震荡，滑动平均能够平滑这些震荡，得到更加鲁棒的模型。实现比较简单：

ema_model = timm.utils.ModelEmaV2(model, decay=0.9998)

每个 step 更新完模型参数后，调用ema_model.update(model)即可。验证和推理时，使用ema_model而不是原始模型。这个技巧在分类和目标检测任务里非常稳定地提升最终指标，一般能涨 0.2~0.5 个点，而且几乎不消耗额外时间。所以，别轻视这些小 trick，它们才是模型效果的隐形推手。

5. 踩坑实录：那些文档里没写的教训

5.1 训练与推理模式不一致导致的“神秘涨点”

有段时间我训练一个分类模型，训练集表现不错，但验证集总是不对劲。刚开始以为过拟合，后来发现是模型在训练时用了model.train()，但在验证时忘记切换model.eval()。BatchNorm 的 running_mean 和 running_var 如果一直不更新，模型输出的分布就会不稳定。更隐蔽的是，某些模型在train模式下带有随机的 Dropout，如果验证时没有切换回 eval，每次推理结果都不同。

timm 模型的default_cfg里其实定义了很多和推理相关的参数，比如interpolation、crop_pct，这些只影响数据预处理，不影响模型内部状态。建议在代码里写一个统一的validate()函数，每次验证前强制设置model.eval()和torch.no_grad()。这不算高级技巧，但确实能减少 80% 的“灵异事件”。

5.2 不同权重来源的归一化参数差异

前面提到权重标签，这里具体说说归一化。ImageNet 的标准归一化均值是[0.485, 0.456, 0.406]，标准差是[0.229, 0.224, 0.225]。大多数预训练权重都是这样。但 timm 里有些来自自有数据集训练的模型，比如某些用 Instagram 数据训练的模型，归一化参数可能不同。

如果你加载了一个权重，但没有使用它的default_cfg里的归一化参数，而是继续用 ImageNet 的标准均值方差，那么输入数据的分布就会偏移，模型的激活值可能异常大或异常小，最终准确率掉一两个点是常有的事。我见过有人用 EfficientNetV2 的预训练权重，却用 ImageNet 的归一化，结果在猫狗分类上只有 80% 的准确率；改成default_cfg对应的归一化后，直接跳到 90% 以上。所以，不要凭经验猜，一定要用resolve_data_config来构建 transform。

5.3 自定义模型注册：timm 也可以承载自己的网络

timm 不是一个封闭的库。如果你自己设计了一个网络，也可以用 timm 的注册机制把它纳入管理，方便统一使用各种训练配置和预训练权重逻辑。这样做的收益在于：你的自定义模型可以像 timm 原生模型一样被create_model创建，也能和 timm 的调度器、优化器 wrapper 配合。

注册方式：

import timm import torch.nn as nn from timm.models import register_model @register_model class MyNet(nn.Module): def __init__(self, num_classes=1000, **kwargs): super().__init__() self.features = nn.Sequential(...) self.classifier = nn.Linear(128, num_classes) def forward(self, x): x = self.features(x) return self.classifier(x) # 创建时默认需提供 pretrained_cfg timm.models.MyNet.default_cfg = {'input_size': (3, 224, 224)}

注册之后，timm.list_models()里就会出现mynet。你也可以给MyNet定义一个default_cfg，这样在create_model时能自动匹配预处理配置。这个过程并不复杂，但能让你的网络融入整个 timm 生态，比如直接用 timm 里的学习率调度器、裁剪策略等等。

实际上，很多开源项目就是这么做的。它们把自己的骨干网络注册进 timm，然后通过create_model('自己的网络名', pretrained=True)来加载权重。这样既方便别人复现，也避免了自己造一套重复的模型管理代码。

5.4 常见报错速查表

我把平时群里问得最多的几个问题整理成了一张速查表，基本都是针对 timm 的：

还有一个小技巧，timm 在加载预训练权重时，会先映射到 CPU 再加载到 GPU，如果你遇到共享内存不足的报错，可以把map_location='cpu'显式传参。虽然在timm.create_model内部已经处理了，但如果你自定义加载权重时，这一点容易忽略。

另外，当你想把 timm 模型导出为 ONNX 时，要注意某些模型使用了动态操作，比如基于输入尺寸的分支。需要固定输入大小后，再使用torch.onnx.export设置动态轴。我一般会先跑一个 dummy input 验证导出图的输出 shape 是否符合预期。

6. 如何在项目里真正用好 timm

6.1 把 timm 当作标准库而非临时工具

很多人只是需要某个模型时才想起 timm，用完就丢。我建议是把 timm 作为自己项目的基础依赖，构建一套基于 timm 的模型管理基础设施。比如在项目里写一个models.py，统一封装模型创建和权重加载逻辑，再写一个config.py，集中管理所有模型的预处理参数和训练超参。这样当你需要对比不同模型时，只需改配置，不用改代码。

timm 还提供了很多辅助工具，比如timm.scheduler里的学习率调度器（CosineLRScheduler、OneCycleScheduler），timm.optim里的优化器（LAMB、LARS），以及timm.data里的数据增强工厂。这些模块质量很高，比你自己写轮子靠谱。我自己现在训练时，几乎不再手动写 step 型学习率调度，直接用 CosineLRScheduler 加 warmup，省事又稳。

6.2 从 timm 源码里能学到什么

最后说点进阶的。timm 的源码是非常好的学习材料，尤其是那些模型实现。如果你想深入理解 CNN 结构如何设计、注意力如何集成、不同 stage 之间通道数如何变化，直接阅读timm/models/resnet.py或者timm/models/vision_transformer.py，都比看论文更生动。

比如 Vision Transformer 的 patch embedding 实现，就是对输入做一个卷积，再用 reshape 和 permute 得到 token 序列。这个思路简洁优雅。timm 里还有大量分布式训练辅助代码，比如ModelEmaV2、CheckpointSaver，这些都能直接抄到自己的训练脚本里。我之前自己写训练框架时，很多组件就是参考 timm 改的，省了很多测试时间。

所以，timm 对你的价值，不只是“能不能调模型”，更是“怎么把训练这件事做得更系统”。这话听起来有点虚，但当你真的把它的源码吃透一部分后，对深度学习工程化的理解会提升一个层次。

聊到最后，我想说点个人体会。timm 这个库的更新频率很高，有时候今天写的代码，过两周就有新版本，某些行为会变。我现在养成的习惯是：每次新建环境时，固定好所有依赖版本，把模型权重下载后放到本地目录，用TORCH_HOME环境变量防止它默认下载。权重下载这种事，看似小事，但真在比赛最后关头碰到下载失败，心态会崩。所以，提前做好离线准备，是每一个想认真做实验的人绕不开的一步。

如果你刚开始接触 timm，不用纠结把所有模型都看一遍，先把自己任务最相关的 5 个模型搞清楚，跑通一个完整的微调流程，再慢慢扩展。模型这东西，不在多，在于你能把它的训练配置和预处理吃透。等你能熟练掌握create_model、resolve_data_config和自定义注册之后，你会发现 timm 已经长在你的工程流程里了。