BEiT-3 图像文本检索微调与评估实战指南基于 COCO 与 Flickr30k 的完整流程【免费下载链接】unilmLarge-scale Self-supervised Pre-training Across Tasks, Languages, and Modalities项目地址: https://gitcode.com/GitHub_Trending/un/unilm导读本文是 BEiT-3Image as a Foreign Language在图像文本检索Image-Text Retrieval任务上的完整实战指南面向希望在 COCO 与 Flickr30k 两个经典跨模态检索基准上复现、微调与评估 BEiT-3 模型的开发者。读完本文你将掌握检索数据集的下载与目录组织方式、基于 Karpathy split 生成索引文件的脚本化流程、base/large 两档模型的多卡微调命令与关键超参数语义、以及单卡评估微调模型并解读 TRK / IRK 指标的方法。文中所有命令均以 get_started_for_retrieval.md 为骨架并辅以 datasets.py、run_beit3_finetuning.py、modeling_finetune.py 等源码级证据进行原理展开。一、检索任务与 BEiT-3 适配概览BEiT-3 采用 Magneto 架构 解耦 Multiway Transformer 作为骨干在统一的 backbone 上处理视觉与语言模态详见 README.md。对于需要深度融合的视觉语言任务官方建议使用BEiT3-base/BEiT3-large而对于图像文本检索或纯视觉任务使用经过图像文本对比学习Image-Text ContrastiveITC中间微调的BEiT3-base-itc与BEiT3-large-itc检查点通常效果更好README.md。检索微调正是从这两个 ITC 检查点出发在 384×384 分辨率下继续微调得到最终检索模型。初始化检查点参数量适用场景beit3_base_patch16_224.pth276M含文本 embedding通用视觉语言预训练beit3_base_itc_patch16_224.pth222M检索微调推荐起点beit3_large_patch16_224.pth746M通用视觉语言预训练beit3_large_itc_patch16_224.pth674M检索微调推荐起点检索任务在代码中的模型入口为BEiT3ForRetrievalmodeling_finetune.py注册名称为beit3_base_patch16_384_retrieval、beit3_large_patch16_384_retrieval等modeling_finetune.py。训练与评估统一由 run_beit3_finetuning.py 驱动通过--task coco_retrieval|flickr30k区分数据集任务选择项在 run_beit3_finetuning.py 中定义。二、环境准备微调前先完成环境搭建与依赖安装。官方推荐使用如下 Docker 镜像启动交互式容器aliaswhoami | cut -d. -f2; docker run -it --rm --runtimenvidia --ipchost --privileged -v /home/${alias}:/home/${alias} pytorch/pytorch:1.8.1-cuda11.1-cudnn8-devel bash进入仓库的 beit3 目录并安装依赖README.mdgit clone https://github.com/microsoft/unilm.git cd unilm/beit3 pip install -r requirements.txtrequirements.txt 中的关键依赖包括torch、torchvision、timm0.4.12、sentencepiece、transformers、deepspeed0.4.0、torchscale0.2.0、pycocotools、pycocoevalcap等。其中torchscale提供BEiT3主干实现见 modeling_utils.pysentencepiece与transformers用于加载文本分词器pycocotools/pycocoevalcap用于 COCO 评测。文本分词器beit3.spm检索任务的文本侧统一使用 SentencePiece 模型beit3.spm分词加载方式如下该代码片段同样出现在 README.md 与检索文档中from transformers import XLMRobertaTokenizer tokenizer XLMRobertaTokenizer(/your_beit3_model_path/beit3.spm)在 run_beit3_finetuning.py 中该分词器路径通过命令行参数--sentencepiece_model传入必填项数据加载时由get_sentencepiece_model_for_beit3实例化datasets.py默认--vocab_size 64010、--num_max_bpe_tokens 64run_beit3_finetuning.py。三、COCO Retrieval 数据集准备COCO Retrieval 使用 COCO 2014 的 train/val 图像与 Karpathy split 标注。完整准备流程如下搭建环境见上文第二节。下载数据2014 训练图像train2014.zip2014 验证图像val2014.zipKarpathy split 标注caption_datasets.zip即dataset_coco.json按以下目录结构组织数据/path/to/your_data/ train2014/ COCO_train2014_000000000009.jpg ... val2014/ COCO_val2014_000000000042.jpg ... dataset_coco.json生成索引文件使用RetrievalDataset.make_coco_dataset_index把 Karpathy 标注切分为 train / val / test 三个 JSONL 索引from datasets import RetrievalDataset from transformers import XLMRobertaTokenizer tokenizer XLMRobertaTokenizer(/your_beit3_model_path/beit3.spm) RetrievalDataset.make_coco_dataset_index( data_path/path/to/your_data, tokenizertokenizer, )COCO 索引生成的源码原理从源码看该入口实际调用了三次_make_retrieval_coco_karpathy_dataset_indexdatasets.py_make_retrieval_coco_karpathy_dataset_index(data_path, tokenizer, split(train, restval), split_nametrain) _make_retrieval_coco_karpathy_dataset_index(data_path, tokenizer, split(val, ), split_nameval) _make_retrieval_coco_karpathy_dataset_index(data_path, tokenizer, split(test, ), split_nametest)其中核心逻辑datasets.py为读取dataset_coco.json按item[split]字段筛选出对应划分注意训练集把 Karpathy 的train与restval合并对每张图像的所有人工标注句子执行tokenizer.tokenizeconvert_tokens_to_ids预分词组装成{image_path, text_segment, image_id}三元组写入 JSONL。生成的索引文件名为coco_retrieval.train.jsonl/coco_retrieval.val.jsonl/coco_retrieval.test.jsonl与RetrievalDataset.get_index_files的约定一一对应datasets.py。预分词的设计值得注意训练时文本不再实时分词而是直接读取text_segment的 token id 列表再由BaseDataset._get_text_segment补齐[BOS] ... [EOS]并构造 padding maskdatasets.py这既保证了训练效率也确保了 Karpathy split 全量 5 句标注都被利用。四、Flickr30k Retrieval 数据集准备Flickr30k 的流程与 COCO 类似区别在于图像需要通过官方申请表获取。搭建环境见上文第二节。下载数据填写 Flickr images request form 申请并下载 31,000 张 Flickr30k 图像下载 Karpathy split 标注caption_datasets.zip即dataset_flickr30k.json按以下目录结构组织数据/path/to/your_data/ flickr30k-images/ 2923475135.jpg ... dataset_flickr30k.json生成索引文件from datasets import RetrievalDataset from transformers import XLMRobertaTokenizer tokenizer XLMRobertaTokenizer(/your_beit3_model_path/beit3.spm) RetrievalDataset.make_flickr30k_dataset_index( data_path/path/to/your_data, tokenizertokenizer, karpathy_path/path/to/your_data, )Flickr30k 索引生成的源码原理make_flickr30k_dataset_indexdatasets.py读取dataset_flickr30k.json中的images列表按each_item[split]train / val / test分别聚合图像路径flickr30k-images/filename、句子 token id 与自增image_id最终写出flickr30k.train.jsonl/flickr30k.val.jsonl/flickr30k.test.jsonl三个索引文件。此处karpathy_path与data_path通常指向同一目录JSON 与图像同根从参数语义上二者可以分离便于把标注文件与图像存放于不同位置。五、微调 BEiT-3 Base 模型COCO / Flickr30k官方给出的 base 档配置为16 张 V100-32GB训练输入分辨率 384×384从beit3_base_itc_patch16_224.pth初始化python -m torch.distributed.launch --nproc_per_node16 run_beit3_finetuning.py \ --model beit3_base_patch16_384 \ --input_size 384 \ --task coco_retrieval \ --batch_size 192 \ --layer_decay 0.65 \ --lr 2e-4 \ --epochs 15 \ --warmup_epochs 3 \ --drop_path 0.2 \ --sentencepiece_model /your_beit3_model_path/beit3.spm \ --finetune /your_beit3_model_path/beit3_base_itc_patch16_224.pth \ --data_path /path/to/your_data \ --output_dir /path/to/save/your_model \ --log_dir /path/to/save/your_model/log \ --weight_decay 0.05 \ --seed 42 \ --save_ckpt_freq 5 \ --enable_deepspeed \ --checkpoint_activations关键参数语义参数Base 推荐值说明--modelbeit3_base_patch16_384模型规格内部映射为beit3_base_patch16_384_retrieval--input_size384图像输入分辨率--taskcoco_retrieval/flickr30k任务与数据集选择--batch_size192每张 GPU 的 batch size--layer_decay0.65层间学习率衰减系数--lr2e-4COCO/ 1e-4Flickr30k峰值学习率--epochs15COCO/ 20Flickr30k训练轮数--warmup_epochs3COCO/ 5Flickr30k学习率预热轮数--drop_path0.2DropPath 比率--finetunebeit3_base_itc_patch16_224.pth预训练权重路径--enable_deepspeed-启用 DeepSpeed 训练--checkpoint_activations-梯度检查点节省显存关于--batch_size与有效 batch size文档明确说明--batch_size是单卡批大小有效 batch size GPU 数量 ×--batch_size×--update_freq。上述命令的有效 batch size 为192 × 16 3072。这一计算逻辑与 run_beit3_finetuning.py 中的total_batch_size args.batch_size * args.update_freq * utils.get_world_size()完全一致训练脚本会在启动时打印该数值供核对。关于--finetune指向 README.md 中提供的预训练权重。注意检索微调应使用itc 后缀的检查点beit3_base_itc_patch16_224.pth而非通用beit3_base_patch16_224.pth——ITC 检查点已做过图像文本对比中间训练是检索任务的推荐起点README.md。关于--task与模型配置脚本根据--task自动拼接模型配置名——对coco_retrieval/flickr30kmodel_config model_retrievalrun_beit3_finetuning.py从而实例化BEiT3ForRetrieval。六、微调 BEiT-3 Large 模型双节点Large 档配置为2×16 32 张 V100-32GB双节点同样 384×384 分辨率从beit3_large_itc_patch16_224.pth初始化python -m torch.distributed.launch --nproc_per_node16 --nnodes2 --node_rank$NODE_RANK \ --master_addr$MASTER_ADDR --master_port$MASTER_PORT run_beit3_finetuning.py \ --model beit3_large_patch16_384 \ --input_size 384 \ --task coco_retrieval \ --batch_size 96 \ --layer_decay 0.85 \ --lr 5e-5 \ --epochs 15 \ --warmup_epochs 3 \ --drop_path 0.2 \ --sentencepiece_model /your_beit3_model_path/beit3.spm \ --finetune /your_beit3_model_path/beit3_large_itc_patch16_224.pth \ --data_path /path/to/your_data \ --output_dir /path/to/save/your_model \ --log_dir /path/to/save/your_model/log \ --weight_decay 0.05 \ --seed 42 \ --save_ckpt_freq 5 \ --enable_deepspeed \ --checkpoint_activationsLarge 与 Base 的差异要点项BaseLarge模型结构12 层、hidden 768、12 heads24 层、hidden 1024、16 headsmodeling_utils.pyGPU 规模16 × V100-32GB32 × V100-32GB2 节点--batch_size19296有效 batch size 仍为96 × 32 3072--layer_decay0.650.85--lr2e-4COCO/ 1e-4Flickr30k5e-5--epochs15 / 2015COCO/ 20Flickr30k--warmup_epochs3 / 53COCO/ 5Flickr30k双节点场景通过--nnodes 2、--node_rank、--master_addr、--master_port完成分布式初始化。Large 模型层数更深24 层 vs 12 层因此--layer_decay 0.85意味着层间学习率衰减更平缓同时峰值学习率下调至5e-5这是大模型微调中常见的稳定训练策略。从源码看层衰减通过LayerDecayValueAssigner按layer_decay^(num_layers1-i)为每层分配学习率缩放run_beit3_finetuning.py。七、评估微调后的检索模型官方提供的微调检查点可直接单卡评估。以 base 模型 COCO 检索为例python -m torch.distributed.launch --nproc_per_node1 run_beit3_finetuning.py \ --model beit3_base_patch16_384 \ --input_size 384 \ --task coco_retrieval \ --batch_size 16 \ --sentencepiece_model /your_beit3_model_path/beit3.spm \ --finetune /your_beit3_model_path/beit3_base_patch16_384_coco_retrieval.pth \ --data_path /path/to/your_data \ --eval \ --dist_eval各任务的微调检查点对照任务Base 检查点Large 检查点COCO Retrievalbeit3_base_patch16_384_coco_retrieval.pthbeit3_large_patch16_384_coco_retrieval.pthFlickr30k Retrievalbeit3_base_patch16_384_f30k_retrieval.pthbeit3_large_patch16_384_f30k_retrieval.pth评估模式的关键开关是--eval仅推理不训练与--dist_eval分布式评估。在 run_beit3_finetuning.py 中--eval分支会加载 test split调用evaluate并打印指标后直接退出。注意评估时--task与--finetune必须匹配数据集coco_retrieval配*_coco_retrieval.pthflickr30k配*_f30k_retrieval.pth。检索指标的计算原理检索评测由RetrievalHandlerengine_for_finetuning.py完成其流程可分为三步特征抽取eval_batch对每批图像与文本分别以only_inferTrue调用模型收集归一化后的vision_cls、language_cls特征及image_idengine_for_finetuning.py。相似度矩阵after_eval将全部图像/文本特征拼接为image_cls_feats与text_cls_feats计算scores image_cls_feats text_cls_feats.t()engine_for_finetuning.py。指标统计分别沿行、列取 top-1/5/10得到TRKText Retrieval文本检索图像与IRKImage Retrieval图像检索文本六项指标并输出average_score (tr_r1 tr_r5 tr_r10 ir_r1 ir_r5 ir_r10) / 6作为汇总分数engine_for_finetuning.py。八、源码视角BEiT-3 检索模型的训练目标理解检索微调为何能工作需要看BEiT3ForRetrieval的前向逻辑modeling_finetune.py图像与文本分别独立送入 BEiT-3 主干图像分支visual_tokensimage且textual_tokensNone文本分支反之互不交叉——这是检索任务双塔式推理的前提各自取序列首位的[CLS]表示经过无偏置的vision_head/language_head线性投影再做L2 归一化F.normalize(vision_cls, dim-1)训练目标为ClipLossutils.py实现源自 open_clip以logit_scale初始化为np.log(1/0.07)缩放相似度对logits_per_image与logits_per_text两个方向的交叉熵取平均即对称的对比学习损失多卡场景下gather_features通过GatherLayerutils.py聚合所有 rank 的特征构建全局负样本label 按labels num_logits * self.rank偏移确保每个样本在全局 batch 内匹配正确的正例utils.py。这也是为什么微调命令必须配合大 batch size对比学习依赖足够大的全局batch 提供负样本官方将有效 batch size 固定为 3072并通过--enable_deepspeedZeRO与--checkpoint_activations梯度检查点在 32GB 显存上容纳这一配置。预期效果基准来自 READMEREADME.md 提供了官方微调检查点的公开指标可作为复现的对照目标数据集初始化检查点分辨率IR1TR1COCObeit3_base_itc_patch16_224384×38461.479.1COCObeit3_large_itc_patch16_224384×38463.482.1Flickr30kbeit3_base_itc_patch16_224384×38486.296.3Flickr30kbeit3_large_itc_patch16_224384×38488.197.2注意这些数字对应的微调检查点参数量COCO 检索 base 为 222M、large 为 675MREADME.md。如果你的环境与官方V100-32GB × 16/32不一致请按有效 batch size ≈ 3072的原则缩放--batch_size与--update_freq例如单机 8 卡时可用--batch_size 384或 4 卡时--batch_size 384 --update_freq 2。九、常见问题与排查建议--sentencepiece_model是必填项脚本将其声明为requiredTruerun_beit3_finetuning.py漏填会直接报错beit3.spm与预训练权重应放在同一目录。索引文件缺失报错训练/评估前必须先执行第三节、第四节的索引生成脚本因为BaseDataset.__init__会在data_path下按get_index_files的约定直接读取*.jsonldatasets.py。显存不足优先开启--checkpoint_activations梯度检查点以计算换显存与--enable_deepspeedZeRO 优化器状态切分文档对二者的定位分别是节省 GPU 内存与分布式训练必需。Flickr30k 图像版权图像需通过官方申请表获取请勿使用未授权的第三方镜像源。十、进一步阅读完整任务文档索引beit3/get_started含分类、VQA、NLVR2、Captioning 等任务的微调指南预训练模型下载与说明beit3/README.md训练/评估主入口beit3/run_beit3_finetuning.py数据集与索引生成beit3/datasets.py检索模型与损失实现beit3/modeling_finetune.py、beit3/utils.py检索任务评测逻辑beit3/engine_for_finetuning.py【免费下载链接】unilmLarge-scale Self-supervised Pre-training Across Tasks, Languages, and Modalities项目地址: https://gitcode.com/GitHub_Trending/un/unilm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考