跨模态图文检索实战：双塔共享特征空间与对比学习全流程解析

简介：2024年“泰迪杯”数据挖掘挑战赛B题跨模态图文互检模型源码，采用共享特征空间对比学习方案，适合数据挖掘、人工智能、计算机视觉方向的学习者与竞赛选手，用于理解图文语义关联和跨模态检索的实现路径。资源包共9个文件、仅10KB，以4个Python脚本与2个YAML配置为主体，辅以说明文档、依赖清单与Git忽略配置；脚本覆盖数据处理、模型设计、训练与评估流程，配置则对应训练和推理参数，结构紧凑且便于逐模块研读。目前已有68人加入学习，读者可对照完整代码梳理共享空间构建、对比学习目标设计、模型验证等关键环节，并在此基础之上复现赛题思路、调整参数或迁移到相近的图文匹配任务中。同时，项目说明与依赖清单能帮助快速搭建运行环境，节省配置与调试时间。

1. 2024 年泰迪杯 B 题：基于共享特征空间的跨模态图文互检到底在解决什么

2024年泰迪杯数据挖掘挑战赛B题的核心，是基于共享特征空间对比学习的跨模态图文互检。我拆完这份源码的第一感受是：竞赛题的难点从来不在模型结构本身，而在把对比学习这套训练范式在图文数据上完整跑通并调稳。它解决的是真实检索问题——给一张图，要从文本库里捞出匹配的描述；给一句话，要从图库里返回对应的图像，评分看的是 Recall@K 这类排序指标。源码覆盖了双塔编码、共享特征空间投影、InfoNCE 损失、负样本采样到评估的全流程。适合正在备赛的学生、想快速上手跨模态检索的工程师，以及把竞赛代码当多模态入门教材的算法新人。

2. 赛题拆解与模型选型：B 题在考什么，跨模态框架怎么定

拿到一份竞赛源码，先别急着分析训练代码，把命题意图拆清楚。B 题给的是一批成对的图文数据，模型要学的是判断“这张图和这句话是否匹配”，并基于这种匹配能力完成双向检索。用大白话讲：提交的模型要能让文本和图像在一个空间里直接比较相似度，然后在候选库里按相似度排序。一旦进入排序问题，模型的核心目标就从“分类正确”变成了“把正样本排到负样本前面”，这和对比学习的优化目标完全一致。

2.1 赛题在考什么：从图文检索指标反推技术路线

赛事评分一般用 Recall@K 和 MRR 这两类指标。Recall@K 的意思是：在返回的前 K 个结果里，是否包含正确匹配的那个样本。K 通常取 1、5、10，Recall@1 最严格，要求第一个结果就命中；Recall@10 相对宽松，只要前十个结果里出现就算得分。MRR（Mean Reciprocal Rank）则关注正确样本排在第几位，排得越靠前得分越高。

从指标反推，模型需要具备两个能力：一是相似度度量能力，匹配的图文相似度要明显高于不匹配的；二是排序稳定性，在几百上千条候选里，正确样本要稳定落在靠前位置。这两个能力正好都是对比学习的强项。数据天然以“图像—文本”正样本对的形式组织，不需要额外标注分类，两个塔各自提取特征后，直接用损失函数把正样本对拉近、负样本对推远就行。

对比学习还有一层好处，在竞赛时间有限的条件下尤其重要：图像和文本的预训练权重都能直接拿开源模型做初始化，训练时只需要微调。相比自己在单卡上从零训练一个大模型，这种做法的起步成本低很多。所以整个 B 题的默认技术路线就是：双塔结构 + 共享特征空间 + 对比损失。

2.2 双塔结构与共享特征空间：为什么检索场景默认不走单塔

双塔结构的组成很直观：图像塔用 ResNet 或 ViT，文本塔用 BERT 或 RoBERTa，两个塔各自把输入映射成特征向量。关键在后面的一层投影头（Projection Head），它通常是一到两层 MLP，把图像特征和文本特征映射到同一个维度，比如 256 维。只有映射到同一个维度之后，图像和文本才能直接算余弦相似度。

这里说的“共享特征空间”不是指两个编码器参数共享，而是指两个塔输出的特征落在同一个向量坐标系里。投影头就是这个坐标系的控制器，常见实现是 Linear + 激活函数 + Linear，中间加 LayerNorm 效果更稳。投影头维度太小会丢失信息，太大又会让损失函数难以约束，128 到 512 是竞赛里比较常见的区间，源码里默认的投影维度通常也落在这个范围。

为什么不直接做一个单塔跨模态 Transformer？单塔把图像 token 和文本 token 拼成一个序列送入 Transformer，交互确实充分，但检索场景有一个致命问题：候选库里的每一条都要和 query 重新过一遍模型。库里有几万条文本，就要跑几万次前向；单塔拿到的特征无法离线缓存，线上推理时每一对都要重新计算。双塔结构可以先把整库的特征离线算好存成向量文件，线上推理时只需要算 query 这一侧的特征，再做一次矩阵乘法就能得到全库排序。

竞赛场景里数据量不大，双塔的信息融合深度完全够用，而评测时的检索效率是硬性的。源码里常见的做法是图像塔用 ResNet-50 级别的 backbone，文本塔用中文 BERT，两个塔都不大，几万图文对的训练周期能控制在可接受范围内。

2.3 对比学习目标函数：InfoNCE 与温度系数

InfoNCE 的思想可以用一句话概括：在一个 batch 内部把正样本对区分出来。假设 batch 里有 N 对图文，图像特征和文本特征相乘得到一个 N×N 的相似度矩阵，第 i 行第 j 列表示第 i 张图和第 j 句文本的相似度。正样本就在对角线上，每一行的目标是让对角线位置得分最高，其余 N-1 个位置都是负样本。

标准的对称对比损失会把这个多分类分别从两个方向各做一次：第一个方向是“图像检索文本”，每一行以文本为候选；第二个方向是“文本检索图像”，每一列以图像为候选。两个方向的交叉熵取平均，就得到最终损失。这个实现方式在 CLIP 等模型中已经成为默认配置，竞赛源码里通常也是这个结构，少数变体只是换了温度系数的放置位置。

温度系数 τ 是这里最敏感的超参数。相似度矩阵在进 softmax 之前会先除以 τ。τ 偏大时，softmax 分布变得平滑，负样本的梯度被稀释，模型收敛稳定但判别力不足；τ 偏小时，softmax 分布尖锐，模型被迫去区分最难区分的负样本，但训练过程会变得激进，容易出现震荡。常见默认值是 0.07，对应 CLIP 的原始设置。竞赛实践中先按 0.07 启动，loss 下降过慢再往 0.05 方向调，出现震荡就往 0.1 方向退。

共享特征空间不是天生对齐的，而是被这个损失函数一步一步“逼”出来的。这也解释了为什么投影头维度、温度系数、负样本策略这些细节都会直接影响最终指标——它们都在改变对特征空间的约束方式。

3. 数据预处理与负样本构建：模型没跑起来之前，一半的坑在数据侧

双塔框架定下来之后，真正费时间的其实是数据侧。跨模态任务的数据不像分类任务那样简单，它需要同时保证图像和文本两个维度的质量，还要设计正负样本的组织方式。我拆这份源码时最先做的就是数据扫描，事实证明这一步帮后面省了大量排查时间。

3.1 图文数据清洗：先保证样本对干净

竞赛数据包解压出来之后，常见脏数据有三类。第一类是图像文件损坏，下载不完整或编码异常，训练时一读到这个文件就报错；第二类是文本异常，空值、重复、超长截断；第三类是图文错标，图是这张图、文本对应另一张图，这类最隐蔽，只能靠抽样人工检查。第一类和第二类可以脚本批量处理。

from PIL import Image from pathlib import Path def scan_images(img_dir): bad_list = [] for path in Path(img_dir).rglob("*.jpg"): try: with Image.open(path) as im: im.verify() # 校验文件完整性，不触发完整解码 except Exception: bad_list.append(str(path)) return bad_list

这段代码的逻辑很简单，但有两个细节值得注意。im.verify()只读取文件头并校验解码信息，不会把整个图像加载进内存，扫描一个大目录时速度快得多。捕获Exception而不是只捕获OSError，是因为截断文件在 verify 阶段可能抛出多种异常类型，统一捕获更稳妥。拿到损坏列表之后，从标注文件里把这些样本整体剔除，对应的文本记录也要一起删，否则后面 Dataset 里会出现“图不存在”的索引错误。

文本清洗相对琐碎但同样必要。英文描述统一转小写、折叠多余空格、去掉 HTML 标签；中文描述没有大小写问题，但要清理控制字符和全角半角混乱。之后按 image_id 做去重，防止同一条文本被重复训练导致模型对个别样本过拟合。长度过滤也在这里做，太短的描述信息量不足，太长的描述可能包含噪声，一般设置在 2 到 64 个字符区间。

3.2 Dataset 实现：图像与文本预处理对齐

预处理的关键在于对齐。图像侧的 Resize、裁剪、归一化，文本侧的 tokenize、padding、截断，要在同一个 Dataset 里完成，保证每个 step 返回的都是严格对应的张量对。图像用 TorchVision 的 transform，文本用 HuggingFace 的 tokenizer，两边各管各的，最后在__getitem__里拼在一起返回。

from torch.utils.data import Dataset from transformers import AutoTokenizer from torchvision import transforms class ITMDataset(Dataset): def __init__(self, df, img_dir, max_len=64): self.df = df self.img_dir = img_dir self.tokenizer = AutoTokenizer.from_pretrained("bert-base-chinese") self.tf = transforms.Compose([ transforms.Resize((224, 224)), transforms.RandomResizedCrop(224, scale=(0.8, 1.0)), transforms.ToTensor(), transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]), ]) self.max_len = max_len def __getitem__(self, idx): row = self.df.iloc[idx] img = Image.open(f"{self.img_dir}/{row['image_name']}").convert("RGB") text = row["text"] tokens = self.tokenizer( text, padding="max_length", truncation=True, max_length=self.max_len, return_tensors="pt") return (self.tf(img), tokens["input_ids"].squeeze(0), tokens["attention_mask"].squeeze(0))

__getitem__返回三个张量：处理后图像、input_ids 和 attention_mask。文本侧在 tokenizer 内部已经做了 padding 到 max_length，所以 DataLoader 的默认 collate_fn 就能直接工作，不需要额外写 collate 逻辑，这一点能省掉不少初学者经常会犯的维度错误。

数据增强要克制。分类任务里常用的 ColorJitter 在图文互检里风险很高，描述里有“金黄色的麦田”时，颜色扰动直接破坏语义对应关系。我一般只保留 RandomResizedCrop 和随机水平翻转，让模型不依赖目标绝对位置，但不改动颜色信息。

3.3 负样本采样策略：in-batch 与 hard negative 并用

对比学习的负样本质量决定训练上限。in-batch negatives 是最简单的方案，batch 里 N 对图文，对每行来说其他 N-1 个样本都是负样本，不需要额外采样，计算效率高。但它的局限也很明显：batch 里大部分负样本和正样本差异巨大，模型很容易学会“图像颜色完全不同=不匹配”这种低层次判别，之后指标提升就停滞了。

常见改进做法是在 in-batch 之外追加 hard negative。所谓 hard negative，就是“很像但不对应”的负样本。对图文互检来说，两个文本描述同一类物体但对应不同图像，这两条文本互为 hard negative；两张图构图相近但物体不同，也互为 hard negative。

def sample_hard_negatives(embedding_matrix, positive_indices, k=2): sim = embedding_matrix @ embedding_matrix.T hard_pairs = [] for i in range(len(positive_indices)): sim[i, positive_indices[i]] = -float("inf") # 屏蔽正样本 hard_idx = sim[i].topk(k).indices.tolist() hard_pairs.append((i, hard_idx)) return hard_pairs

这段代码的输入是某个模态的特征矩阵，输出是每个样本最相似但不对应的 topk 索引。屏蔽正样本那一步是关键，如果不把对角线位置置为负无穷，topk 第一个选出来的往往是它自己。实际工程里不会每个 step 都重算全库特征，常见做法是每训练几个 epoch，用当前模型重新编码一次训练子集，更新 hard negative 列表。

hard negative 的比例要控制。比例太低起不到提难作用，比例太高模型会被噪声支配。常见做法是把 hard negative 控制在 batch 内负样本数量的 10% 到 20%，更新频率每隔 3 到 5 个 epoch 一次。这个参数和温度系数一样，属于最后阶段的精调对象，基础模型还没跑稳之前不建议动。

4. 训练流程与参数配置：把对比损失跑稳跑低的实操笔记

训练部分的代码是整个源码包的核心，也是调参空间最大的地方。按“损失实现→训练循环→评估脚本”的顺序拆开讲，每一段代码都是可以直接抄进工程的最小可运行版本。

4.1 InfoNCE 损失实现

对比损失的核心实现不到十行，难点在于理解它为什么这样写。图像塔输出图像特征，文本塔输出文本特征，两个特征都先做 L2 归一化，然后矩阵相乘得到相似度矩阵。除以温度系数后，对每一行做交叉熵。对称版本会再把矩阵转置算一次文本到图像方向，两个损失取平均。

import torch import torch.nn.functional as F def contrastive_loss(img_feats, txt_feats, temp=0.07): img_feats = F.normalize(img_feats, dim=-1) txt_feats = F.normalize(txt_feats, dim=-1) logits = img_feats @ txt_feats.T / temp labels = torch.arange(len(img_feats), device=img_feats.device) loss_i2t = F.cross_entropy(logits, labels) loss_t2i = F.cross_entropy(logits.T, labels) return (loss_i2t + loss_t2i) / 2

F.normalize放在矩阵相乘之前，这一步不是可选项。如果不做归一化，特征向量的模长差异会干扰温度系数的语义，logits 的绝对值尺度不稳定，调 τ 就变成了猜谜。labels 用torch.arange生成，正好对应矩阵对角线位置，每一行的正样本都是它自己。

温度系数的位置也值得注意：temp出现在矩阵相乘之后、softmax 之前。有个常见误解，有人会把temp乘到 normalize 之前，效果完全不同。除温度再 softmax 是 CLIP 的标准写法，它会等比放大所有 logits，锐化概率分布，让 loss 更关注相似度最高的那些负样本。

4.2 训练循环与优化器参数

训练循环和常规分类训练差别不大，真正的门道在梯度累积和梯度裁剪上。对比损失的梯度幅度对 batch 组成敏感，偶尔一个 hard negative 样本就能让梯度激增，所以裁剪几乎是必须的。

accum_steps = 2 # 等效大batch的累积步数 total_steps = (len(train_loader) * epochs) // accum_steps # OneCycleLR 总步数 optimizer = torch.optim.AdamW(model.parameters(), lr=5e-5, weight_decay=0.02) scheduler = torch.optim.lr_scheduler.OneCycleLR( optimizer, max_lr=5e-5, total_steps=total_steps, pct_start=0.05) for epoch in range(epochs): for step, (img, input_ids, attn_mask) in enumerate(train_loader): img, input_ids, attn_mask = img.cuda(), input_ids.cuda(), attn_mask.cuda() img_feats, txt_feats = model(img, input_ids, attn_mask) loss = contrastive_loss(img_feats, txt_feats, temp=0.07) (loss / accum_steps).backward() if (step + 1) % accum_steps == 0: torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0) optimizer.step() scheduler.step() optimizer.zero_grad()

梯度累积的实现方式是把 loss 除以 accum_steps 再 backward，这样累积 accum_steps 步之后，梯度均值等于一个大 batch 的梯度，学习率不用为小 batch 额外调整。clip_grad_norm_的 max_norm 设为 1.0，在对比学习里是很稳的选择，尤其在 hard negative 比例较高时能挡住梯度爆炸。

注意：预训练权重是竞赛的底线。两个塔都从开源预训练权重起步，loss 在前几个 epoch 就能掉到 1 以下；从零训练的话，几万图文对的数据量根本喂不饱 ResNet 和 BERT，效果会差一个量级。

4.3 评估脚本：Recall@K 与 MRR

评估不能在线逐条调用模型，正确做法是把验证集完整的特征先算一遍，全部收集起来，然后一次性做矩阵运算。验证集通常不会太大，一个 epoch 内存足够容纳。

def evaluate(img_feats, txt_feats, k_list=(1, 5, 10)): img_feats = F.normalize(img_feats, dim=-1) txt_feats = F.normalize(txt_feats, dim=-1) sim = txt_feats @ img_feats.T # 文本检索图像方向 for k in k_list: topk = sim.topk(k, dim=-1).indices correct = (topk == torch.arange(len(sim))[:, None]).any(dim=-1) recall = correct.float().mean().item() print(f"t2i Recall@{k}: {recall:.4f}")

sim矩阵的行是文本，列是图像，sim[i][j] 表示第 i 句文本和第 j 张图的相似度。topk取前 k 个图像的索引，当某一行的 topk 索引里包含行号本身时，说明正确样本被召回。MRR 的实现同理，找到第一个正确索引的位置后取倒数。

提示：评估脚本里的归一化和训练脚本必须逐行一致，否则相似度排序会失真。loss 曲线很漂亮但指标完全对不上，多半是这里出的问题。

有了评估脚本之后，整个训练闭环就完整了。跑通这一遍，接下来才谈得上优化指标。

5. 避坑记录：跨模态训练中五个花了不少时间才定位的翻车现场

复现这份源码的完整流程走下来，模型结构本身几乎没有卡住人，反而是各种“看似合理但实际上在跨模态场景下会出问题”的默认配置，一个接一个地消耗时间。下面五个坑都来自实际操作，每条按“现象 → 原因 → 解决”写清楚。

5.1 三个“看起来正常但指标不对”的典型

第一个坑：训练 loss 正常下降，但验证集 Recall@1 始终是 0

现象：loss 从 4.x 一路降到 1.x，曲线非常好看，跑到验证阶段却完全不行，top5 偶尔能蒙对，top1 永远命中不了。

原因：训练时contrastive_loss内部对特征做了 L2 归一化，而评估脚本直接用了模型的原始输出。两个特征空间的尺度不一致，余弦相似度的排序自然失真，正样本在原始特征空间里并没有被拉到应有的位置。

解决：评估脚本里在计算相似度矩阵之前，对两侧特征做同样的F.normalize。从那以后我养成了一个检查习惯，每次写评估脚本都会和训练函数逐行对比预处理逻辑，而不是想当然地认为模型输出可以直接用。

第二个坑：双向指标差距悬殊，text2img 远好于 img2text

现象：同一个模型、同一份特征，text2img 的 Recall@5 能到 40%，img2text 只有 20%，差距接近一倍。

原因：图像塔和文本塔的收敛速度不一致。BERT 文本塔的输出空间本身语义性强，从预训练权重起步后很快就能对齐；ResNet 图像塔的输出偏底层视觉特征，需要更多 epoch 才能被对比损失拉到语义空间。

解决：一是给图像塔的投影头输出维度从 256 提到 512，让图像特征有更多表达空间；二是加强图像侧的 RandomResizedCrop 比例，迫使图像塔关注语义主体而非背景细节。本质上是让弱的塔承担更多优化压力。

第三个坑：加了 hard negative 之后 loss 反而震荡

现象：hard negative 比例从 0 调整到 20% 之后，训练 loss 出现周期性震荡，验证指标不升反降。

原因：hard negative 列表是用上一个 epoch 的特征采样出来的，而特征空间本身在训练中持续移动，等到当前 epoch 真正用到这些负样本时，监督信号已经部分失效。模型面对的是一批“旧空间里的难样本”，强行拟合只会引入噪声。

解决：降低更新频率，每 5 个 epoch 重采样一次 hard negative，并把比例控制在 10% 左右。如果仍然震荡，说明是难负样本的噪声在主导梯度，继续下调比例，或者对 hard negative 样本的 loss 降权处理。

5.2 两个“一改就崩”的参数陷阱

第四个坑：显存不够，把 batch size 从 128 降到 32，指标全面下滑

现象：loss 变大，验证指标掉了 5 个点以上，而且不只是 Recall@1，所有 K 值都在掉。

原因：对比学习对 batch 内负样本数量有硬依赖。batch 越小负样本越少，模型每个 step 能看到的信息量大幅缩水，梯度估计的方差也会变大。这不是学习率没调的问题，是方法本身的约束。

解决：不要直接缩小 batch，用梯度累积模拟大 batch。实测用 batch=32 加 accum=4，等效于 128 的 batch，指标能拉回九成。但这里还有一个隐藏问题：如果 backbone 带 BatchNorm，梯度累积不会改变 BatchNorm 统计量的计算方式，它仍然只基于 32 个样本更新统计量，需要换成 SyncBN 才能在等效大 batch 下正常工作。

第五个坑：复现结果不稳定，同样的参数跑两次差几个点

现象：同样的代码、同样的参数，连续跑两次验证集指标波动超过 3 个百分点，有时候波动大到影响超参数判断。

原因：直接原因是随机种子没有固定，数据加载顺序和图像增强的随机性没有被约束；更深层的原因是对比学习对负样本分布极其敏感，shuffle 顺序不同导致每个 batch 的负样本构成不同，模型在每个 step 接收的监督信号就有差异。

解决：固定 torch、numpy、random 三个库的随机种子，并且给 DataLoader 传worker_init_fn，保证数据加载线程的随机性也可控。固定种子之后，实验方差能压到 1 个点以内，扫描超参数才有可比性。

6. 进阶用法：用消融实验把“玄学”变成可复现的参数

baseline 跑通之后，拉开差距的是消融实验。对比学习在竞赛里常被说成玄学，但把几个关键参数分开扫一遍，它其实每个参数的影响都可解释。我通常把温度系数、投影头维度、hard negative 比例作为三个扫描变量，其他配置保持不变。

{ "temp": 0.07, "proj_dim": 256, "hard_neg_ratio": 0.1, "lr": 5e-5, "batch_size": 64 }

for t in 0.03 0.07 0.1; do python train.py --temp $t --proj_dim 256 --hard_neg_ratio 0.1 done

每一组实验的验证结果都要单独记录，不要只看最优值。温度从 0.07 降到 0.05 时，如果 Recall@1 上升但 Recall@5 下滑，说明模型把注意力过度集中在难负样本上，排序前几位变准但整体排序变毛糙了。投影头维度从 256 加到 512 时，如果 text2img 方向的提升明显大于 img2text，说明图像塔还在学习阶段，投影头多出来的维度给了它追赶的空间。

验证阶段除了算指标，拆这份源码时我习惯把验证集特征保存成 npy 文件，写一个最近邻检索脚本，人工抽查 top10 检索结果。典型 query 分三类：描述物体位置的、描述颜色的、描述动作的。如果“穿红色外套的男人”检索结果里出现“黑色外套的女人”，颜色语义没有对齐；如果出现构图相似但物体完全不同的图，说明视觉底层特征在主导排序，文本语义没有真正参与。

从那以后，我每次拿到竞赛源码，都强制自己先把最小配置跑干净，确认 loss 和验证指标能对齐，再动任何超参数。宁可多花半天把数据清洗和评估脚本做严格，也不要在训练跑完一轮之后才发现评估有 bug。对比学习的每个参数都有迹可循，前提是你给它一个可复现的评测环境。希望帮到你。

本文还有配套的精品资源，点击获取