Transformers 中的 BEiT 模型BERT 式掩码图像建模预训练视觉 Transformer 的架构、配置与实战指南【免费下载链接】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/transformersBEiTBidirectional Encoder representation from Image Transformers是首个让视觉 TransformerViT的自监督预训练效果全面超越有监督预训练的代表性工作。本文以 Hugging Face Transformers 仓库中的 BEiT 模型文档 为核心骨架结合 modeling_beit.py、configuration_beit.py 等源码实现系统讲解 BEiT 的掩码图像建模原理、完整配置参数、图像预处理、四类下游任务模型以及 SDPA 注意力加速帮助你直接上手调用预训练权重完成图像分类、语义分割与掩码图像建模等任务。BEiT 模型概览把 BERT 的自监督范式搬到视觉领域BEiT 由 Hangbo Bao、Li Dong 和 Furu Wei 在论文BEiT: BERT Pre-Training of Image Transformers中提出论文于 2021 年 6 月 15 日发布在 Hugging Face Papers 上并于 2021 年 8 月 4 日合入本仓库。它的核心贡献在于受 NLP 领域 BERT 的启发BEiT 提出了**掩码图像建模Masked Image Modeling, MIM**任务来预训练视觉 Transformer这也是第一个让 ViT 的自监督预训练在效果上超过有监督预训练的方法。与 原始 ViT 论文 直接预测图像类别标签不同BEiT 的预训练目标是根据被掩码的图像块patch预测来自 OpenAI DALL-E 模型 码本codebook的视觉 token。论文摘要中的关键表述如下我们引入了自监督视觉表示模型 BEiT。遵循 NLP 领域 BERT 的思路我们提出掩码图像建模任务来预训练视觉 Transformer。具体地每张图像在预训练中有两个视图图像块如 16×16 像素与视觉 token即离散 token。我们先将原始图像token 化为视觉 token然后随机掩码部分图像块并送入骨干 Transformer预训练目标是基于被破坏的图像块恢复原始视觉 token。预训练完成后通过在预训练编码器上追加任务层直接在下游任务上微调模型参数。图像分类与语义分割的实验表明我们的模型取得了具有竞争力的结果例如 base 尺寸的 BEiT 在 ImageNet-1K 上达到 83.2% 的 top-1 准确率明显超过相同设置下从零训练的 DeiT81.8%large 尺寸的 BEiT 仅使用 ImageNet-1K 就达到 86.3%甚至超过了在 ImageNet-22K 上有监督预训练的 ViT-L85.2%。两视图预训练图像块 视觉 token从论文摘要和仓库源码都可以还原出 BEiT 预训练的完整流程它包含两条并行信息流图像块视图将原图切成 16×16 像素的 patchbase 配置下 224×224 输入会产生 196 个 patch由 BeitPatchEmbeddings 用nn.Conv2d(num_channels, hidden_size, kernel_sizepatch_size, stridepatch_size)一次性完成投影输出形状为(batch_size, seq_length, hidden_size)的序列特征视觉 token 视图借助 DALL-E 的离散图像 tokenizerVQ-VAE把图像编码为离散的视觉 token作为预训练阶段需要恢复的监督信号。训练时随机掩码一部分 patch将其替换为可学习的 mask token见 BeitEmbeddings.forward 中bool_masked_pos与mask_token的替换逻辑把被破坏的 patch 序列喂给骨干 Transformer最后用语言建模头在掩码位置预测对应的视觉 token。注意由于预测的是 VQ-VAE 视觉 token 而非 RGB 像素值BEiT 的掩码图像建模实现与AutoModelForMaskedImageModeling不兼容需要使用BeitForMaskedImageModeling直接调用这一点在 modeling_beit.py 的类文档中有明确说明。架构与源码实现基于 ViT 骨架的模块化组装BEiT 在架构上就是一个常规的视觉 Transformer区别仅在于预训练方式。仓库采用模块化modular方式组织代码modular_beit.py 是源文件它直接复用了ViTPatchEmbeddings、ViTEmbeddings、ViTAttention、ViTMLP、ViTLayer、ViTPreTrainedModel等 ViT 组件仅替换了BeitRelativePositionBias等 BEiT 特有模块modeling_beit.py 则是自动生成的实际模型实现文件文件头部有由 modular 文件生成请勿手动编辑的警告。前向流程与关键模块BeitModelmodeling_beit.py的完整前向链路如下BeitEmbeddingspatch 投影 → 可选掩码替换 → 拼接[CLS]token → 可选添加绝对位置编码 → dropout每个BeitLayer对应 timm 实现的 BlockPre-LayerNorm → 多头自注意力 → layer scalelambda_1→ DropPath 残差 → Post-LayerNorm → MLP → layer scalelambda_2→ DropPath 残差末端layernorm与BeitPooler汇聚出序列输出与池化输出。值得一提的实现细节Layer scale 初始化BeitLayer中的lambda_1/lambda_2以config.layer_scale_init_value默认 0.1初始化modeling_beit.pyDropPath随机深度BeitDropPath按层线性递增 dropout 率drop_path_rate * i / (num_hidden_layers - 1)CLS 与均值池化BeitPooler 在use_mean_poolingTrue时对 patch token剔除[CLS]做 LayerNorm 后的均值池化否则取[CLS]token 的最终隐藏状态输出结构BeitModelOutputWithPoolingmodeling_beit.py在标准BaseModelOutputWithPooling基础上明确了pooler_output的语义均值池化或 CLS并支持hidden_states/attentions的逐层输出。T5 式相对位置偏置BEiT 使用受 T5 模型启发的相对位置嵌入预训练时作者在多个自注意力层之间共享相对位置偏置use_shared_relative_position_bias微调时每一层的相对位置偏置用预训练得到的共享偏置初始化。BeitRelativePositionBias 实现了完整的相对位置索引生成与偏置表插值逻辑支持任意窗口尺寸输入分辨率变化时通过双线性插值扩展偏置表。源码中_keys_to_ignore_on_load_unexpected [r.*relative_position_index.*]modeling_beit.py表明相对位置索引是运行时动态生成的缓存张量不属于需要加载的模型权重。使用要点如果想从零预训练BEiT必须将BeitConfig的use_relative_position_bias每层独立偏置或use_shared_relative_position_bias跨层共享偏置设置为True否则模型中不会包含位置嵌入。日常加载官方预训练权重做微调时权重自带相对位置偏置无需额外配置。BeitConfig完整配置参数详解BeitConfig定义在 configuration_beit.py 中继承自PreTrainedConfig与BackboneConfigMixin。下表整理了当前仓库中全部配置项及其默认值配置项默认值说明vocab_size8192视觉 token 码本大小即掩码图像建模头的输出维度hidden_size768隐藏层维度base 尺寸num_hidden_layers12Transformer 层数num_attention_heads12注意力头数intermediate_size3072MLP 中间层维度hidden_actgelu激活函数hidden_dropout_prob0.0隐藏层 dropoutattention_probs_dropout_prob0.0注意力 dropoutinitializer_range0.02权重初始化范围layer_norm_eps1e-12LayerNorm epsilonimage_size224输入图像分辨率可传int或(h, w)元组patch_size16patch 尺寸num_channels3输入通道数use_mask_tokenFalse是否为掩码图像建模启用可学习 mask tokenuse_absolute_position_embeddingsFalse是否使用绝对位置编码use_relative_position_biasFalse是否在注意力层中使用 T5 式相对位置偏置use_shared_relative_position_biasFalse是否跨层共享同一份相对位置偏置layer_scale_init_value0.1layer scale 初始化值≤0 时禁用drop_path_rate0.1随机深度最大丢弃率use_mean_poolingTrue分类头之前对 patch token 均值池化否则用 CLSpool_scales(1, 2, 3, 6)语义分割 PSP 模块的池化尺度use_auxiliary_headTrue训练时是否使用辅助分割头auxiliary_loss_weight0.4辅助头交叉熵损失的权重auxiliary_channels256辅助头通道数auxiliary_num_convs1辅助头卷积层数auxiliary_concat_inputFalse分类层前是否拼接辅助头输入semantic_loss_ignore_index255语义分割损失的忽略索引add_fpnFalse作为骨干网时是否附加 FPN仅BeitBackbone使用reshape_hidden_statesTrue骨干输出是否重排为 4D 特征图从源码可以看到两个联动校验规则configuration_beit.pyadd_fpnTrue时out_indices必须恰好为 4 个整数base 架构建议[3, 5, 7, 11]out_indices也可用旧参数名segmentation_indices传入并自动转换。stage_names由[stem] [stage1...stage12]组成供骨干输出对齐使用。初始化一个 BEiT 配置与随机权重模型的标准写法 from transformers import BeitConfig, BeitModel # 初始化 beit-base-patch16-224-pt22k 风格的配置 configuration BeitConfig() # 从配置初始化随机权重模型 model BeitModel(configuration) # 访问模型配置 configuration model.config图像预处理BeitImageProcessor 与 BeitImageProcessorPil由于 BEiT 模型要求每张输入图像具有相同分辨率必须使用图像处理器完成 resize或 rescale与归一化。仓库提供两个后端实现BeitImageProcessor基于 Torchvision 后端的处理器BeitImageProcessorPil基于 PIL 的处理器二者共享BeitImageProcessorKwargs。它们的默认预处理参数完全一致image_processing_beit.py参数默认值resampleBICUBICimage_mean/image_stdImageNet 标准均值/标准差size224×224crop_size224×224do_resizeTruedo_center_cropFalsedo_rescaleTruedo_normalizeTruedo_reduce_labelsFalsepreprocess方法除了处理普通图像外还支持传入segmentation_maps分割标签图会以do_normalizeFalse, do_rescaleFalse独立处理避免归一化破坏类别标签的整数语义并转为int64张量image_processing_beit.py。do_reduce_labels用于 ADE20k 这类以 0 表示背景、但背景不参与类别计数的数据集——开启后所有标签值减 1背景被替换为 255忽略索引。post_process_semantic_segmentation则把BeitForSemanticSegmentation的原始 logits 转换为逐像素的分割图支持target_sizes尺寸还原与return_segmentation_scores概率输出。下游任务四类模型 骨干网络BeitForImageClassification图像分类BeitForImageClassification 在BeitModel带池化层之上接一个线性分类头。分类头输入是 patch token 均值池化或 CLS后的pooler_outputnum_labels 1时计算 MSE 回归损失否则计算交叉熵损失。推断示例 from transformers import AutoImageProcessor, BeitForImageClassification from PIL import Image image_processor AutoImageProcessor.from_pretrained(microsoft/beit-base-patch16-224) model BeitForImageClassification.from_pretrained(microsoft/beit-base-patch16-224) inputs image_processor(imagesimage, return_tensorspt) outputs model(**inputs) logits outputs.logitsBeitForMaskedImageModeling掩码图像建模BeitForMaskedImageModeling 在骨干之上叠加 LayerNorm 与lm_headnn.Linear(hidden_size, vocab_size)预测被掩码 patch 的视觉 token。它通过bool_masked_pos形状(batch_size, num_patches)1 表示被掩码指定掩码位置仅在掩码位置计算交叉熵损失 from transformers import AutoImageProcessor, BeitForMaskedImageModeling import torch from PIL import Image image_processor AutoImageProcessor.from_pretrained(microsoft/beit-base-patch16-224-pt22k) model BeitForMaskedImageModeling.from_pretrained(microsoft/beit-base-patch16-224-pt22k) num_patches (model.config.image_size // model.config.patch_size) ** 2 pixel_values image_processor(imagesimage, return_tensorspt).pixel_values # 生成 (1, num_patches) 的随机布尔掩码 bool_masked_pos torch.randint(low0, high2, size(1, num_patches)).bool() outputs model(pixel_values, bool_masked_posbool_masked_pos) loss, logits outputs.loss, outputs.logits list(logits.shape) [1, 196, 8192]输出 logits 形状[1, 196, 8192]对应 196 个 patch 与 8192 的码本大小与vocab_size配置严格对应。预训练或继续预训练时用labels视觉 token ID监督掩码位置即可。BeitForSemanticSegmentation语义分割BeitForSemanticSegmentation 是 BEiT 在密集预测任务上的完整实现结构上由三部分构成FPN 颈部BeitFPNNeck把out_indices选出的 4 层特征图映射为 4 级金字塔2 倍上采样 / 4 倍上采样 / 恒等 / 2 倍下采样见 modeling_beit.py解码头BeitUperHeadUPerNet 风格的 PSP 模块pool_scales金字塔池化 FPN 融合最后用 1×1 卷积输出num_labels通道modeling_beit.py辅助头BeitFCNHeadFCN 风格的辅助监督其通道数、卷积层数、权重等由auxiliary_channels/auxiliary_num_convs/auxiliary_loss_weight控制。该模型强制要求config.out_indices为恰好 4 个整数base 架构用[3, 5, 7, 11]否则直接抛出ValueError。推断时 logits 形状为(batch_size, num_labels, height, width) from transformers import AutoImageProcessor, BeitForSemanticSegmentation from PIL import Image image_processor AutoImageProcessor.from_pretrained(microsoft/beit-base-finetuned-ade-640-640) model BeitForSemanticSegmentation.from_pretrained(microsoft/beit-base-finetuned-ade-640-640) inputs image_processor(imagesimage, return_tensorspt) outputs model(**inputs) logits outputs.logits # (batch_size, num_labels, height, width)BeitBackbone供 DETR / MaskFormer 等框架使用BeitBackbone 将 BEiT 作为通用骨干网络暴露给 DETR、MaskFormer 等检测/分割框架支持通过out_features/out_indices选择输出层reshape_hidden_states控制输出 4D 特征图或 3D 序列add_fpnTrue时附加 FPN。可结合AutoBackbone使用 from transformers import AutoImageProcessor, AutoBackbone processor AutoImageProcessor.from_pretrained(microsoft/beit-base-patch16-224) model AutoBackbone.from_pretrained( ... microsoft/beit-base-patch16-224, out_features[stage1, stage2, stage3, stage4] ... ) outputs model(**processor(image, return_tensorspt)) list(outputs.feature_maps[-1].shape) [1, 768, 14, 14]检查点命名与可用权重理解检查点命名规则有助于正确选择预训练权重。BEiT 每个检查点的名字都同时反映了预训练/微调时使用的 patch 分辨率与图像分辨率microsoft/beit-base-patch16-224base 尺寸架构patch 分辨率 16×16微调分辨率 224×224microsoft/beit-base-patch16-224-pt22k在 ImageNet-22k 上预训练仅预训练microsoft/beit-large-patch16-224-pt22k-ft22k在 ImageNet-22k 预训练并在 ImageNet-22k 上微调microsoft/beit-base-finetuned-ade-640-640在 ADE20k 上微调至 640×640 的语义分割权重。可用检查点分三类① 仅在 ImageNet-22k约 1400 万张图像、2.2 万类上预训练② 在 ImageNet-22k 上进一步微调③ 在 ImageNet-1kILSVRC 2012约 130 万张图像、1000 类上微调。仓库测试 test_modeling_beit.py 的 slow 用例覆盖了上述全部检查点类型可作为挑选权重的参考依据。注意力加速Scaled Dot Product AttentionSDPA当前仓库的 BEiT 实现已全面接入 PyTorch 原生 SDPA。源码层面BeitPreTrainedModel声明了_supports_sdpa True与_supports_flash_attn Falsemodeling_beit.pyBeitAttention通过ALL_ATTENTION_FUNCTIONS.get_interface(config._attn_implementation, eager_attention_forward)按配置分发到 eager 或 SDPA 实现modeling_beit.py。当 PyTorch 版本 ≥ 2.1.1 且硬件可用时SDPA 默认启用也可以显式指定attn_implementationsdpafrom transformers import BeitForImageClassification model BeitForImageClassification.from_pretrained( microsoft/beit-base-patch16-224, attn_implementationsdpa, device_mapauto )官方英文文档记录了在 NVIDIA GeForce RTX 2060-8GB、PyTorch 2.5.1、Ubuntu 20.04 环境下、float16精度 microsoft/beit-base-patch16-224的本地基准结果详见 英文版 BEiT 文档训练场景50 步、batch2、图像 1048×640每 batch 耗时从 eager 的 0.984s 降至 SDPA 的 0.746s加速约 31.98%峰值显存从 6738.9MB 降至 4319.9MB节省约 56%。推理场景各 batch 下的对比图像 batch 数Eager (s/iter)SDPA (s/iter)加速比显存节省10.0120.0111.05×0.24%40.0130.0111.18×3.23%160.0450.0351.30×10.08%320.0880.0661.33×17.04%可见 batch 越大、分辨率越高SDPA 的收益越明显。文档同时建议为获得最佳加速效果请以半精度加载模型torch.float16或torch.bfloat16。测试套件中还包含test_sdpa_can_compile_dynamictest_modeling_beit.py这类对 SDPA 与torch.compile组合的回归验证。上手资源与验证途径图像分类BeitForImageClassification有配套的官方示例脚本 run_image_classification.py可参照 图像分类任务指南 完成自定义数据集微调将ViTImageProcessor/ViTForImageClassification替换为对应的 BEiT 类即可语义分割参见 语义分割任务指南模型对比BEiT 在 ImageNet-1K 与 CIFAR-100 微调后性能优于同为 ViT 架构的 原始 ViT 与数据高效的 DeiT测试验证单元测试 test_modeling_beit.py 覆盖BeitModel、四个任务模型与骨干网络的梯度、前向输出与 pipeline 集成test_image_processing_beit.py 覆盖图像预处理与分割后处理可通过它们校验自己的使用方式是否正确。总而言之BEiT 用 BERT 的掩码思想统一了视觉表示学习而本仓库则将其落地为开箱即用的工程实现完整的配置体系、双后端图像处理器、四类任务头加骨干网络以及默认启用的 SDPA 加速。无论是复现论文、微调下游任务还是将其作为检测分割框架的骨干都可以基于上文内容直接开始。【免费下载链接】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），仅供参考