Transformers 中的 PPLCNetV4 骨干网络：配置详解、结构解析与图像特征提取实践

Transformers 中的 PPLCNetV4 骨干网络：配置详解、结构解析与图像特征提取实践

【免费下载链接】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

PPLCNetV4 是飞桨（PaddlePaddle）PP-LCNet 系列的新一代轻量级卷积骨干网络，当前以纯 Backbone（骨干网络）形态集成进 🤗 Transformers（model_type = "pp_lcnet_v4"），未附带任何分类头与官方预训练分类权重。本文基于仓库内的模型文档页与同名源码模块展开，系统讲解其定位、PPLCNetV4Config全部配置项、网络结构源码原理、特征图输出方式，并给出可直接运行的前向推理示例，帮助你在图像分类、检测、分割等下游任务中把 PPLCNetV4 当特征提取器使用。

模型定位：仅作为骨干网络提供

在阅读源码与使用该模型前，先明确两个事实（均来自官方模型文档）：

1. PPLCNetV4 在 Transformers 中只提供 backbone 网络，即不存在PPLCNetV4ForImageClassification之类的带分类头的版本；
2. 目前没有官方发布的预训练图像分类 checkpoint，源码中的 checkpoint 标注为PaddlePaddle/Not_yet_released（见 configuration_pp_lcnet_v4.py）。

因此实际使用方式是：直接PPLCNetV4Backbone(config)以随机初始化创建网络，或用它作为更大视觉模型的骨干部分，再自行接上任务头做训练。该模型由 PaddlePaddle 团队于2026-05-19贡献到 Transformers。

从代码组织看，本模型位于独立的src/transformers/models/pp_lcnet_v4/目录，其中：

• configuration_pp_lcnet_v4.py —— 配置类PPLCNetV4Config；
• modeling_pp_lcnet_v4.py —— 骨干网络PPLCNetV4Backbone及其内部子模块；
• modular_pp_lcnet_v4.py —— modular 源文件，展示它与既有 PP-LCNet、HGNetV2 代码的复用关系。

在 Transformers 的模型家族里，PPLCNetV4 与 PP-LCNet、PP-LCNetV3 同属一条轻量骨干网络演进线：从 modular_pp_lcnet_v4.py 可以看到，PPLCNetV4Config直接派生自PPLCNetConfig，PPLCNetV4ConvLayer继承自 HGNetV2 的HGNetV2ConvLayer，SE 模块继承自 PP-LCNet 的PPLCNetSqueezeExcitationModule——这表明 V4 是在前代基础上做架构升级与模块复用，而不是从零实现。

快速上手：创建一个 PPLCNetV4 骨干网络并提取特征

以下示例直接取自 modeling_pp_lcnet_v4.py 的 docstring，可在无预训练权重的情况下直接运行：

from transformers import PPLCNetV4Config, PPLCNetV4Backbone import torch # 使用默认配置（scale=1.0、stem_type="large"） config = PPLCNetV4Config() model = PPLCNetV4Backbone(config) # 输入为图像张量：batch_size=1, 3 通道, 224x224 pixel_values = torch.randn(1, 3, 224, 224) with torch.no_grad(): outputs = model(pixel_values) # outputs 是 BackboneOutput，feature_maps 为多尺度特征图 feature_maps = outputs.feature_maps print(list(feature_maps[-1].shape))

关键输入输出约定（源码可证，见 modeling_pp_lcnet_v4.py 与 modeling_pp_lcnet_v4.py）：

• 主要输入名称为pixel_values，输入模态声明为("image",)，即只接受图像张量；
• 模型不含注意力机制（has_attentions = False），前向返回BackboneOutput，包含feature_maps与hidden_states两类输出；
• feature_maps中只包含用户指定的 stage（默认配置下包含stem与stage1–stage4五级输出），feature_maps[-1]即最后一个 stage（默认 stage4）的输出，其通道数为 384（scale=1.0 时）；
• 模型声明支持梯度检查点（supports_gradient_checkpointing = True），并可在全图编译下运行（_can_compile_fullgraph = True）。

由于没有官方预训练权重，不要对默认初始化的模型直接调用from_pretrained；如需导入权重，需等待官方 checkpoint 发布后使用对应仓库 ID。

PPLCNetV4Config 配置参数详解

PPLCNetV4Config继承BackboneConfigMixin与PreTrainedConfig（见 configuration_pp_lcnet_v4.py），其全部公开字段及默认值如下表所示，这些内容在配置类的 docstring 中逐条说明，并能在代码字段声明中一一对应：

提示：配置类还透传 backbone 通用的out_features/out_indices参数（由BackboneConfigMixin提供），用于指定骨干网络输出哪些 stage 的特征图，将在下文“多尺度特征输出”小节展开。

block_configs 的默认四阶段结构

当block_configs为None时，__post_init__会写入默认配置（见 configuration_pp_lcnet_v4.py）。默认网络共4 个卷积 stage，各阶段 block 构成如下：

• Stage 1（注释中称 blocks2）：1 个 block，[3, 96, 96, 1, True]——3×3 卷积、96→96 通道、stride 1、带 SE；
• Stage 2（blocks3）：2 个 block，均为[3, 96, 96, 1, False]——不带 SE；
• Stage 3（blocks4）：7 个 block，首个为[3, 96, 192, [2, 1], False]（跨步[2, 1]承担下采样），随后 6 个 block 在 192 通道上交替开关 SE（True/False交替共 3 次开、3 次关）；
• Stage 4（blocks5）：3 个 block，首个为[3, 192, 384, [2, 1], False]完成最后一次下采样与升维，后两个 block 为[3, 384, 384, 1, True/False]。

配置对象在__post_init__中会自动派生以下派生字段：

• depths = [len(blocks) for blocks in block_configs]，默认即[1, 2, 7, 3]，表示每个 stage 的 block 数量；
• stage_names = ["stem"] + ["stage1", ..., "stage4"]，共 5 个命名输出级；
• stage_out_channels = [blocks[-1][2] for blocks in block_configs]，默认[96, 96, 192, 384]，即各 stage 的输出通道数。

若用户自定义block_configs，则必须满足架构校验规则（validate_architecture，见 configuration_pp_lcnet_v4.py）：

• block_configs长度必须等于 4（否则抛出ValueError）；
• stem_type只能是"large"或"small"。

如何使用 scale 与 stem_type 组合出不同规格

scale负责在整条主干上等比缩放各 stage 的通道数（在PPLCNetV4Backbone.__init__中，num_features按int(block[-1][2] * config.scale)计算，见 modeling_pp_lcnet_v4.py），stem_type负责切换主干入口的轻量程度。二者组合即可在不改动源码的情况下生成不同 FLOPs/参数量的变体，例如：

# 轻量变体：通道数减半 + 小型 stem（适合移动端） small_config = PPLCNetV4Config(scale=0.5, stem_type="small") small_model = PPLCNetV4Backbone(small_config) # 全尺寸变体 large_config = PPLCNetV4Config(scale=1.0, stem_type="large") large_model = PPLCNetV4Backbone(large_config)

值得注意的是，即使指定了scale，stem_channels不会被自动缩放（两者相互独立），这也为用户精细调控计算瓶颈提供了灵活性。

网络结构源码拆解

从源码结构看，PPLCNetV4 骨干网络自底向上由以下几个模块堆叠而成（实现全部位于 modeling_pp_lcnet_v4.py）。

1. ConvLayer：基础卷积单元（Conv + BN + 激活 + 可选 LAB）

PPLCNetV4ConvLayer是贯穿全网的原子卷积模块（modeling_pp_lcnet_v4.py），内部依次为：

• nn.Conv2d（默认bias=False，padding 自动取(kernel_size-1)//2以保持空间尺寸）；
• nn.BatchNorm2d；
• 激活函数（由ACT2FN[activation]解析，None时为nn.Identity()）；
• 当同时满足“指定了激活”且use_learnable_affine_block=True时，追加一个 Learnable Affine Block，否则为恒等映射。

2. Learnable Affine Block（LAB）

PPLCNetV4LearnableAffineBlock（modeling_pp_lcnet_v4.py）是 V4 引入的可学习参数模块：out = scale * hidden_state + bias，其中scale初始为 1.0、bias初始为 0.0，二者均可训练。它让网络在既定计算之后具备额外的一阶仿射校正能力，默认关闭，可在配置中通过use_learnable_affine_block=True全局开启。

3. Squeeze-and-Excitation 模块（SE）

SE 模块的作用是实现通道级注意力、自适应特征重标定（docstring 描述见 modeling_pp_lcnet_v4.py）。其前向流程为：

1. 对特征图做全局自适应平均池化得到通道描述向量；
2. 经过两级 1×1 卷积：第一级将通道压缩为channel // reduction并接ReLU，第二级恢复为channel并接Hardsigmoid得到 0~1 的通道门控；
3. 将门控与原特征做逐通道乘法（residual * gate）完成重标定。

在默认 stage 配置中，SE 被有节奏地穿插（如 stage1、stage3 的第 2/4/6 个 block），以在轻量与表达力之间取得平衡。

4. Stem：两种入口结构

• LargeStem（stem_type="large"，复用 HGNetV2 的HGNetV2Embeddings实现，modeling_pp_lcnet_v4.py）结构较复杂：先用 3×3 卷积把 3 通道提为stem_channels[1]（48），随后并行走两条路径——一路通过 2×2/2×2 卷积（stem2a→stem2b）并做 pad，另一路走MaxPool2d，两路结果在通道维拼接后再经stem3（3×3）与stem4（1×1）卷积，最终输出stem_channels[2]（96）通道。该 stem 在前向入口还校验输入通道数是否与config.num_channels一致。
• SmallStem（stem_type="small"，modeling_pp_lcnet_v4.py）则是极简的两段式结构：两个 stride=2 的 3×3 卷积（不带激活），中间插入一次 GELU 激活，直接在两次 2× 下采样中完成 3→48→96 的通道扩张，开销显著更低。

5. DepthwiseSeparableConvLayer：核心可分离卷积块

主干中的每个 block 都落在PPLCNetV4DepthwiseSeparableConvLayer（modeling_pp_lcnet_v4.py）上，其前向流程为：

1. token 卷积：深度可分离卷积（groups=in_channels）处理空间信息。当stride == 1且in_channels == out_channels时使用独立的nn.Conv2d（代码以use_rep_dw标记，对应重参数化友好的设计）；否则退化为“普通 ConvLayer + depthwise groups”的写法；
2. 可选 SE：当 block 配置中use_squeeze_excitation=True时插入 SE 模块做通道重标定；
3. channel 卷积：记录残差后，先用 1×1 卷积把通道扩为 2 倍，经GELU激活，再用 1×1 卷积压回目标通道数——结构近似轻量的通道级 MLP；
4. 残差连接：仅当in_channels == out_channels且stride == 1时执行residual + hidden_state（下采样/升维 block 不做恒等相加）。

PPLCNetV4Block按block_configs[stage_index]把多个这样的层串成一个 stage（modeling_pp_lcnet_v4.py），PPLCNetV4Encoder则由 LargeStem/SmallStem + 4 个PPLCNetV4Block组成并输出BaseModelOutputWithNoAttention（modeling_pp_lcnet_v4.py）。

以 Backbone 身份接入：多尺度特征图输出

PPLCNetV4Backbone继承BackboneMixin与PPLCNetV4PreTrainedModel（modeling_pp_lcnet_v4.py），它的职责是把 Encoder 的中间 stage 输出转成便于下游消费的特征金字塔。

前向逻辑（modeling_pp_lcnet_v4.py）清晰展示了多尺度特征收集过程：

1. 先调用self.encoder(pixel_values)得到每级 hidden state；
2. 遍历self.stage_names（stem+stage1…stage4），只把出现在self.out_features中的 stage 输出收进feature_maps元组；
3. 返回BackboneOutput(feature_maps=..., hidden_states=...)。

因此，下游任务（例如把某几个 stage 的特征图喂给 FPN/检测头）应通过out_features或out_indices显式指定需要的层级。仓库测试就采用了“挑选部分 stage”的典型用法（见 test_modeling_pp_lcnet_v4.py），其构造参数为：

out_features=["stage2", "stage3", "stage4"], out_indices=[2, 3, 4], stem_channels=(3, 16, 16), # 测试用缩小版 stem block_configs=[...], # 测试用缩小版 block 配置

也就是说：stem 的输出（含浅层空间细节）与 stage3/4 的深层语义特征可以按需自由组合，这正是检测、分割类模型常需要的多尺度能力。模型本身不做分类/回归，也没有注意力输出，与同样位于tests/models下并引用 PPLCNetV4 的下游检测模型（可通过搜索pp_lcnet_v4/PPLCNetV4在 tests/models 内查证）的搭配方式是一致的：backbone 只负责产出特征图，任务逻辑交给外部 head。

验证与测试：仓库如何保障其可用性

PPLCNetV4 与 Transformers 中其他 backbone 共用一套成熟测试基础设施：

• test_modeling_pp_lcnet_v4.py 继承BackboneTesterMixin（通用骨干网络测试套件，定义于 test_backbone_common.py）与ConfigTester（通用配置测试，定义于 test_configuration_common.py），同时自行定义PPLCNetV4ModelTester负责生成缩小版但结构完整的模型与输入（batch=3、128×128、3 通道）。
• 注册信息同样完整：pp_lcnet_v4 -> PPLCNetV4Config出现在 auto_mappings.py，pp_lcnet_v4 -> PPLCNetV4Backbone出现在 modeling_auto.py，意味着它可以通过 Auto API 按model_type被动态解析（前提是官方 checkpoint 可用）。
• 模型代码本身由 modular 源文件 modular_pp_lcnet_v4.py 自动生成，文件头部有 CI 强制检查的生成声明，改动需落在 modular 源上——这也解释了为何 PPLCNetV4 能大量复用pp_lcnet/hgnet_v2中已被验证的模块实现。

如果你想在本地跑通验证，可对默认配置运行一次前向（上一节的代码示例即可），或用测试的缩小配置（stem_channels=(3, 16, 16)+ 自定义block_configs）观察各 stage 特征图尺寸随 stride 的下采样规律。需要注意：由于缺少官方权重，当前所有运行结果均为随机初始化行为，仅能验证网络结构与数据流是否正确。

小结

PPLCNetV4 在 Transformers 中的角色非常纯粹——一个可插拔、可配置、可多尺度输出的卷积骨干网络。把它与 PP-LCNet/PP-LCNetV3 放在一起看，可以观察到轻量 CNN 设计的连续演进：可分离卷积 + SE 通道注意力 + GELU 通道 MLP 构成主干，可选的 LAB 增强表达力，scale与stem_type提供规格弹性，而out_features/out_indices让它在目标检测与语义分割中可以直接充当 FPN 等结构的特征提取器。掌握PPLCNetV4Config的默认结构与各项参数语义后，你便可以在不触碰源码的前提下按需构造适配自身算力与任务的骨干网络。

进一步阅读仓库内相关资料：

• 模型文档页：docs/source/en/model_doc/pp_lcnet_v4.md
• 同系列文档：PP-LCNet、PP-LCNetV3
• 配置实现：configuration_pp_lcnet_v4.py
• 模型实现：modeling_pp_lcnet_v4.py
• Modular 源文件：modular_pp_lcnet_v4.py
• 测试套件：test_modeling_pp_lcnet_v4.py

【免费下载链接】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