Transformers 中的 ConvNeXT纯卷积架构在 2020 年代的复兴与实战指南【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers导读ConvNeXTConvNeXt是 2022 年由 Meta原 Facebook研究团队提出的一类纯卷积图像模型它通过借鉴 Vision TransformerViT与 Swin Transformer 的现代设计要素对经典 ResNet 进行系统性现代化改造在 ImageNet 上达到 87.8% top-1 精度并在 COCO 检测与 ADE20K 分割上超越同规模 Swin Transformer。本文以 docs/source/ja/model_doc/convnext.md 为骨架结合本仓库中 src/transformers/models/convnext/ 的源码实现系统讲解 ConvNeXT 的架构原理、ConvNextConfig全部配置参数、图像预处理流程ConvNextImageProcessor/ConvNextImageProcessorPil、两个核心模型类ConvNextModel、ConvNextForImageClassification以及图像分类的完整实战用法。读完本文你将能够在 Transformers 生态中直接加载、微调并部署 ConvNeXT 系列模型。模型背景从 ResNet 到 ConvNeXT 的现代化之路ConvNeXT 模型由 Zhuang Liu、Hanzi Mao、Chao-Yuan Wu、Christoph Feichtenhofer、Trevor Darrell、Saining Xie 在论文A ConvNet for the 2020s论文编号 2201.03545中提出。其核心观点是视觉识别领域狂飙的 20 年代始于 Vision TransformerViT的登场——ViT 迅速取代 ConvNet 成为最先进的图像分类模型。然而朴素 ViT 在目标检测、语义分割等通用视觉任务上会遇到困难是 Swin Transformer 这类层级式 Transformer重新引入了若干 ConvNet 先验才让 Transformer 成为通用视觉骨干网络并展现出卓越性能。但作者指出这种混合方案的成功在很大程度上仍被归因于 Transformer 的内在优越性而非卷积的归纳偏置本身。因此他们重新审视设计空间检验纯 ConvNet 到底能达到什么上限将标准 ResNet 逐步向 ViT 的设计靠拢现代化沿途发现了一系列造成性能差异的关键组件最终得到 ConvNeXT 模型家族。ConvNeXT 完全由标准 ConvNet 模块构建在精度与可扩展性上与 Transformer 不相上下同时保留了标准 ConvNet 的简洁与高效。论文摘要的核心数据为ImageNet top-1 精度 87.8%并在 COCO 检测与 ADE20K 分割上超越 Swin Transformer。在 Transformer 架构大行其道的背景下ConvNeXT 用纯卷积证明了卷积归纳偏置的长期价值。该模型在 Transformers 中由 nielsr 贡献TensorFlow 版本由 ariG23498、gante、sayakpaul 贡献原始代码来自 Facebook Research 的官方实现。架构速览现代设计语言下的纯卷积主干从架构上看ConvNeXT 的骨干网络由四大部分组成对应源码中的 modeling_convnext.py 实现Patchify StemConvNextEmbeddings用一个kernel_sizepatch_size、stridepatch_size的Conv2d将输入图像切分为非重叠 patch 并投影到初始通道数hidden_sizes[0]默认 96随后接一个data_formatchannels_first的 LayerNormConvNextEmbeddings。这与 Swin 的嵌入层思路一致源码注释明确说明受SwinEmbeddings启发。四个 StageConvNextStageConvNextLayer除第一个 stage 外每个 stage 先用 LayerNorm stride-2 卷积下采样再堆叠若干残差块ConvNextStage。ConvNeXt BlockConvNextLayer每个残差块由 7×7 深度可分离卷积depthwise conv→ LayerNormchannels_last→ 1×1 点卷积用 Linear 实现维度扩为 4×→ GELU 激活 → 1×1 点卷积还原维度 →LayerScale按通道可学习的缩放参数初值为layer_scale_init_value→ 残差连接ConvNextLayer。源码注释指出作者在实际 PyTorch 实现中选择了通道在最后的 Linear 版本因为略快。全局平均池化 最终 LayerNormConvNextModel.forward对(N, C, H, W)特征做mean([-2, -1])全局平均池化再经 LayerNorm 输出pooler_outputConvNextModel。整个网络不使用任何注意力机制has_attentions False。深度可分离卷积提供了空间混合1×1 卷积承担通道混合配合 LayerScale 与随机深度DropPath构成正则化体系——这正是用 Transformer 的设计哲学武装纯卷积的直观体现。配置文件ConvNextConfig 全参数详解ConvNextConfig定义在 configuration_convnext.py 中继承自PreTrainedConfig与BackboneConfigMixin因此支持作为骨干网络输出多尺度特征。其全部核心参数及默认值如下参数默认值说明num_channels3输入图像的通道数RGB 为 3patch_size4Stem 卷积的 patch 尺寸kernel/stride可为 int 或 (h, w) 元组num_stages4骨干 stage 数量hidden_sizes(96, 192, 384, 768)各 stage 的输出通道数长度应等于num_stagesdepths(3, 3, 9, 3)各 stage 中残差块的数量对应 tiny 规模hidden_actgelu隐藏层激活函数经ACT2FN映射initializer_range0.02权重初始化标准差layer_norm_eps1e-12最终 LayerNorm 的 epsilonlayer_scale_init_value1e-6LayerScale 参数初值0时启用 LayerScale0时不使用drop_path_rate0.0随机深度Stochastic Depth最大概率按各层线性插值分配image_size224输入图像尺寸224×224参数配置示例来自源码 docstring可直接运行 from transformers import ConvNextConfig, ConvNextModel # 初始化一个 convnext-tiny-224 风格的配置 configuration ConvNextConfig() # 从该配置初始化模型随机权重 model ConvNextModel(configuration) # 访问模型配置 configuration model.config此外由于继承了BackboneConfigMixinConvNextConfig在__post_init__中会自动生成stage_names[stem, stage1, stage2, stage3, stage4]并支持通过out_indices/out_features指定骨干网络输出的特征层级。从源码可以看到drop_path_rate在 ConvNextEncoder 中通过torch.linspace(0, drop_path_rate, sum(depths))按各 stage 的深度比例线性分配实现随网络加深递增的随机深度。layer_scale_init_value则决定每个残差块末尾是否有一个可训练的逐通道缩放向量——这是 ConvNeXT 区别于传统 ResNet 的关键正则化技巧之一。图像预处理ConvNextImageProcessor 与 crop_pct 细节ConvNeXT 的图像预处理与其他视觉模型的最大区别在于crop_pct裁剪比例。仓库中提供了两个预处理类均带自定义 resize 逻辑ConvNextImageProcessor基于 Torchvision 后端的实现位于 image_processing_convnext.py其_preprocess支持按图像形状分组、批量 resize/裁剪/缩放/归一化group_images_by_shapereorder_images批量处理更高效。ConvNextImageProcessorPil基于 PIL 后端的实现位于 image_processing_pil_convnext.py逐图处理逻辑与前者等价。两者的公共默认配置完全一致属性默认值说明resamplePILImageResampling.BICUBIC双三次插值重采样image_mean/image_stdImageNet 标准均值/方差(0.485, 0.456, 0.406)/(0.229, 0.224, 0.225)size{shortest_edge: 384}默认按最短边 384 处理do_resize/do_rescale/do_normalizeTrueresize、缩放1/255、归一化默认开启crop_pct224 / 256 ≈ 0.875裁剪比例仅当目标尺寸小于 384 时生效crop_pct的语义在resize方法中有明确的源码注释与分支逻辑当shortest_edge 384时先保持宽高比把最短边放大到shortest_edge / crop_pct再进行(shortest_edge, shortest_edge)的中心裁剪。这等价于先放大再中心裁剪模拟了论文中训练阶段的随机裁剪 推理阶段中心裁剪的效果。当shortest_edge 384时直接做 warping正方形拉伸到(shortest_edge, shortest_edge)不做裁剪。也就是说crop_pct只在低分辨率推理如 224时起作用而 384 及以上分辨率评估时直接拉伸。这正是 ConvNeXT 论文中在 384 分辨率评估时不做裁剪的推理协议在库中的落地。对低分辨率输入的推理链路为resize最短边放大到 256→ center_crop224×224→ rescale×1/255→ normalizeImageNet 均值/方差最终输出键为pixel_values的BatchFeature。核心模型类ConvNextModel 与 ConvNextForImageClassificationConvNextPreTrainedModel是所有 ConvNeXT 模型的基类声明base_model_prefix convnext、main_input_name pixel_values、input_modalities (image,)并设置_no_split_modules [ConvNextLayer, ConvNextStage]以支持模型并行分片。ConvNextModel基础骨干ConvNextModel由ConvNextEmbeddingsPatchify StemConvNextEncoder四个 stage 最终 LayerNorm 组成。forward的输入为pixel_values形状(batch_size, num_channels, height, width)输出BaseModelOutputWithPoolingAndNoAttentionlast_hidden_state形状(batch_size, hidden_sizes[-1], H/32, W/32)——因为 patch_size4 加三次 stride-2 下采样共缩小 32 倍测试 test_modeling_convnext.py 中create_and_check_model明确断言该形状pooler_output全局平均池化并经 LayerNorm 后的(batch_size, hidden_sizes[-1])向量hidden_states当output_hidden_statesTrue时返回数量为num_stages 1stem 嵌入 各 stage 输出测试中的test_hidden_states_output验证了这一点。ConvNextForImageClassification图像分类头ConvNextForImageClassification在ConvNextModel之上叠加一个线性分类头nn.Linear(config.hidden_sizes[-1], config.num_labels)。forward支持labels参数当config.num_labels 1时计算回归损失MSE当config.num_labels 1时计算交叉熵损失输出为ImageClassifierOutputWithNoAttentionloss、logits、hidden_states。集成测试ConvNextModelIntegrationTesttest_modeling_convnext.py使用facebook/convnext-tiny-224在 COCO 样例猫图上验证logits 形状为(1, 1000)且前三维与期望值[-0.0267, -0.4735, 0.1901]在容差内一致——这为开箱即用提供了可复现的数值基准。额外能力作为骨干网络使用虽然原文档未展开但源码中还提供了ConvNextBackbonemodeling_convnext.py专为 DETR、MaskFormer 等检测/分割框架提供多尺度特征图。其用法为 from transformers import AutoImageProcessor, AutoBackbone import torch from PIL import Image processor AutoImageProcessor.from_pretrained(facebook/convnext-tiny-224) model AutoBackbone.from_pretrained(facebook/convnext-tiny-224) inputs processor(image, return_tensorspt) outputs model(**inputs) # outputs.feature_maps 为多尺度特征元组ConvNextBackbone通过out_features/out_indices控制输出哪些 stage 的特征并为每个输出层级配备 channels_first 的 LayerNormhidden_states_norms这是 Transformers 骨干网络接口BackboneMixin的标准设计。实战图像分类的完整使用流程ConvNeXT 官方支持的 pipeline 是image-classification原文档以PipelineTag pipelineimage-classification/标注。下面给出从加载到推理的完整流程 from transformers import AutoImageProcessor, AutoModelForImageClassification from PIL import Image import requests # 加载处理器与模型facebook/convnext-tiny-224 等系列均可 processor AutoImageProcessor.from_pretrained(facebook/convnext-tiny-224) model AutoModelForImageClassification.from_pretrained(facebook/convnext-tiny-224) # 预处理resize center_crop(224) rescale normalize url http://images.cocodataset.org/val2017/000000039769.jpg image Image.open(requests.get(url, streamTrue).raw) inputs processor(imagesimage, return_tensorspt) # 推理 with torch.no_grad(): ... outputs model(**inputs) logits outputs.logits predicted_class_id logits.argmax(-1).item() print(Predicted class:, model.config.id2label[predicted_class_id])要点说明使用AutoImageProcessor与AutoModelForImageClassification时处理器会自动从 checkpoint 读取size、crop_pct等预处理配置无需手工指定pixel_values已按 ImageNet 统计量归一化。在 Transformers 仓库中本模型由 examples/pytorch/image-classification/ 下的示例脚本run_image_classification.py、run_image_classification_no_trainer.py直接支持可用于微调与评估。该 pipeline 也映射到测试基类PipelineTesterMixin中pipeline_model_mapping包含{image-feature-extraction: ConvNextModel, image-classification: ConvNextForImageClassification}即 ConvNeXT 同时支持图像特征提取与图像分类两条 pipeline。测试与验证如何确认实现正确本仓库为 ConvNeXT 提供了完整的测试套件位于 tests/models/convnext/模型测试test_modeling_convnext.py覆盖ConvNextModel、ConvNextForImageClassification、ConvNextBackbone三类模型验证了隐藏状态形状每 stage 空间尺寸减半、分类 logits 形状、骨干特征图数量与通道数、以及output_hidden_states的 stage 数量num_stages 1。由于 ConvNeXT 不使用input_ids、inputs_embeds、attention_mask相关测试被显式跳过。慢速集成测试以facebook/convnext-tiny-224为基准校验 logits 数值。图像预处理测试test_image_processing_convnext.py验证处理器具备do_resize、size、crop_pct、do_normalize、image_mean、image_std等属性输出图像形状为(channels, shortest_edge, shortest_edge)并支持通过from_dict(..., size42)动态覆盖配置。如果你在本地验证实现可以对照这些测试用例运行例如pytest tests/models/convnext/ -k not slow。若想检查模型权重加载可执行慢速测试中的test_model_from_pretrained加载facebook/convnext-tiny-224。此外仓库还提供了权重转换脚本 convert_convnext_to_pytorch.py可将官方 ConvNeXt 权重转换为 Transformers 格式。小结ConvNeXT 用一组标准 ConvNet 模块深度可分离卷积 1×1 卷积 GELU LayerNorm LayerScale 随机深度重新定义了纯卷积骨干的上限是理解现代卷积设计语言的绝佳范本。在本仓库中你可以通过ConvNextConfig精细控制网络结构深度、宽度、stage 数、LayerScale 与 DropPath 正则强度通过ConvNextImageProcessor/ConvNextImageProcessorPil复现论文的 crop_pct 推理协议通过ConvNextModel、ConvNextForImageClassification、ConvNextBackbone分别完成特征提取、图像分类与检测/分割骨干三大任务。结合 docs/source/ja/tasks/image_classification 任务指南与 examples/pytorch/image-classification/ 示例脚本你可以快速将 ConvNeXT 应用到自己的视觉任务中。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
