简介本资源面向计算机、人工智能、通信工程等专业的在校学生与教师提供一份基于Flickr30k数据集的图像—文本跨模态检索课程设计完整方案可用于媒体计算实践作业、毕业设计或项目初期立项演示。压缩包共35个文件约1.13MB以22个Python源码为核心辅以6个pyc编译文件、3个Markdown说明文档、1个shell脚本及少量图片与许可证文件覆盖数据预处理、模型训练、评估与测试界面等模块。项目包含训练集、测试集、验证集划分脚本短边缩放至256的图像预处理流程以及分阶段训练与检索评估代码并配有QueryApp测试界面便于直观验证图文匹配效果。目前已有586人学习下载代码经测试运行成功答辩评审平均分达96分适合基础尚可的学习者在此基础上修改扩展实现更多检索功能。1. 从一次课程设计翻车说起Flickr30k 跨模态搜索到底在做什么你可能遇到过这种场景课程设计选题拿到「基于 Flickr30k 实现图像文本跨模态搜索」第一反应是——不就是以图搜图、以文搜图吗然后打开搜索引擎一查发现满屏都是 CLIP、BLIP 这些大模型动辄要几十 GB 显存本地根本跑不动。更尴尬的是老师要求交源码、数据集、测试界面和项目说明而你连 Flickr30k 长什么样都没见过。这个标题真正要落地的东西其实是一套轻量级、可复现、能在普通笔记本上跑通的图文互检系统用 Python 把 Flickr30k 的图片和五句英文描述分别编码到同一个向量空间然后通过余弦相似度实现「输入一句话返回最匹配的图」和「输入一张图返回最匹配的描述」。它不需要你训练一个百亿参数模型核心工作量在数据预处理、特征提取、索引构建和界面串联上。适合正在做课程设计、想拿高分又不想被大模型劝退的本科生也适合想快速理解跨模态检索链路的 Python 入门者。下面我按自己踩过的坑把整条路径拆开讲清楚。2. Flickr30k 数据集怎么读从压缩包到可检索的图文对2.1 数据集目录结构与两个必须搞清的文件Flickr30k 原始包解压后通常长这样一个flickr30k-images/文件夹存放 31783 张 jpg 图片一个results_20130124.token或dataset_flickr30k.json存放标注。很多人第一次翻车就翻在这里——直接拿results.csv当输入结果发现每张图对应五条描述格式是image_name#0.jpg这种带序号的后缀和图片文件夹里的image_name.jpg对不上。我一般会先写一个解析脚本把标注统一成{图片文件名: [描述1, 描述2, ...]}的字典。如果是.token格式每行是文件名#序号\t描述如果是.json格式结构是{images: [{filename: ..., sentences: [{raw: ...}]}]}。两种都要能处理因为不同来源的 Flickr30k 包格式不一样。import json import os from collections import defaultdict def load_flickr30k_annotations(ann_path): 支持 .token 和 .json 两种 Flickr30k 标注格式 返回: {image_filename: [caption1, caption2, ...]} ann_dict defaultdict(list) if ann_path.endswith(.json): with open(ann_path, r, encodingutf-8) as f: data json.load(f) for item in data[images]: fname item[filename] for sent in item[sentences]: ann_dict[fname].append(sent[raw].strip()) else: # .token 格式: 1000092795.jpg#0\tTwo young guys ... with open(ann_path, r, encodingutf-8) as f: for line in f: line line.strip() if not line: continue key, caption line.split(\t, 1) fname key.split(#)[0] # 去掉 #0 后缀 ann_dict[fname].append(caption.strip()) return dict(ann_dict) # 使用示例 ann load_flickr30k_annotations(dataset_flickr30k.json) print(f共加载 {len(ann)} 张图片的标注) print(f第一张图的描述: {list(ann.values())[0]})这段代码的关键点有三个第一用defaultdict(list)保证同一张图的五条描述都收进去第二.token格式必须用split(#)[0]把序号剥掉否则后面按文件名找图会全部失败第三编码统一用utf-8Flickr30k 的描述里有不少非 ASCII 字符用默认编码在 Windows 上会直接报UnicodeDecodeError。2.2 图片路径校验与缺失样本过滤解析完标注不等于能直接用。Flickr30k 的图片文件名和标注文件名偶尔会有大小写差异或者某些图片在传输过程中损坏。我习惯在构建索引前先做一轮校验遍历标注字典的 key检查images_dir/fname是否存在且能被 PIL 打开。打不开的直接从字典里剔除同时记录日志。from PIL import Image import os def validate_images(ann_dict, images_dir): valid {} missing [] for fname, captions in ann_dict.items(): img_path os.path.join(images_dir, fname) if not os.path.exists(img_path): missing.append(fname) continue try: with Image.open(img_path) as im: im.verify() # 不加载像素只校验文件完整性 valid[fname] captions except Exception as e: missing.append(fname) print(f有效图片: {len(valid)}, 缺失/损坏: {len(missing)}) return valid, missing valid_ann, missing validate_images(ann, flickr30k-images)im.verify()是个容易被忽略的细节——它只检查文件头不真正解码像素所以速度很快。如果你用im.load()做校验3 万张图跑下来要多花好几分钟。校验完把valid_ann存成 pickle后续所有步骤都读这个缓存避免每次重新解析。提示Flickr30k 完整图片约 4.5 GB标注文件几百 KB。如果磁盘紧张可以只保留测试集对应的 1000 张图先跑通流程但课程设计报告里要说明这是子集实验。3. 用 CLIP 做图文特征提取模型选型与批量推理参数3.1 为什么选 CLIP 而不是自己训一个双塔跨模态搜索的核心是「把图和文映射到同一个向量空间」。自己训双塔需要大量图文对和 GPU 时间课程设计周期内基本不现实。CLIP 的优势在于它已经在 4 亿图文对上预训练过图像编码器和文本编码器输出的向量天然对齐直接拿来算余弦相似度就能用。常见做法是选ViT-B/32这个规格模型权重约 350 MBCPU 上单张图推理约 0.3 秒3 万张图大概 2.5 小时如果有 GPU几分钟就能跑完。选型时要注意CLIP 的文本编码器对英文描述效果最好Flickr30k 正好是英文标注匹配度高。如果你非要用中文查询得额外接一个翻译层或者换用支持中文的 Chinese-CLIP但那就偏离标题了。3.2 批量提取图像特征的完整脚本下面这段是我实际用的图像特征提取代码核心是torch.no_grad()关闭梯度、DataLoader做批处理、特征归一化后存成 numpy 数组。import torch import clip import numpy as np from PIL import Image from torch.utils.data import Dataset, DataLoader import os device cuda if torch.cuda.is_available() else cpu model, preprocess clip.load(ViT-B/32, devicedevice) model.eval() class FlickrImageDataset(Dataset): def __init__(self, ann_dict, images_dir, preprocess): self.fnames list(ann_dict.keys()) self.images_dir images_dir self.preprocess preprocess def __len__(self): return len(self.fnames) def __getitem__(self, idx): fname self.fnames[idx] img Image.open(os.path.join(self.images_dir, fname)).convert(RGB) return self.preprocess(img), fname def extract_image_features(ann_dict, images_dir, batch_size64): ds FlickrImageDataset(ann_dict, images_dir, preprocess) loader DataLoader(ds, batch_sizebatch_size, num_workers4, shuffleFalse) all_feats, all_names [], [] with torch.no_grad(): for imgs, fnames in loader: imgs imgs.to(device) feats model.encode_image(imgs) feats feats / feats.norm(dim-1, keepdimTrue) # L2 归一化 all_feats.append(feats.cpu().numpy().astype(float32)) all_names.extend(fnames) return np.concatenate(all_feats, axis0), all_names img_feats, img_names extract_image_features(valid_ann, flickr30k-images) np.save(image_feats.npy, img_feats) with open(image_names.txt, w) as f: f.write(\n.join(img_names))参数说明batch_size64在 8 GB 显存的 GPU 上比较稳CPU 上建议降到 16 否则内存吃紧num_workers4是数据加载进程数Windows 下如果报错就改成 0feats.norm(dim-1, keepdimTrue)这步 L2 归一化不能省否则余弦相似度计算会退化成点积检索结果会偏向向量模长大的样本。3.3 文本特征提取与「五条描述取平均」的取舍Flickr30k 每张图有五条描述构建文本索引时有两种做法一是把五条描述都编码检索时取最高分二是把五条描述编码后取平均每张图只保留一个文本向量。我一般选后者因为索引体积小五倍检索速度更快而且平均后的向量更稳定不会因为某一条描述写得偏而拉低整体匹配度。def extract_text_features(ann_dict, img_names): text_feats [] with torch.no_grad(): for fname in img_names: captions ann_dict[fname] tokens clip.tokenize(captions).to(device) feats model.encode_text(tokens) feats feats / feats.norm(dim-1, keepdimTrue) avg_feat feats.mean(dim0) avg_feat avg_feat / avg_feat.norm() # 平均后再归一化 text_feats.append(avg_feat.cpu().numpy()) return np.array(text_feats, dtypefloat32) text_feats extract_text_features(valid_ann, img_names) np.save(text_feats.npy, text_feats)注意img_names的顺序必须和图像特征提取时完全一致否则图和文对不上检索结果会变成玄学。我习惯在保存image_names.txt后文本提取直接读这个文件来保证顺序。4. 检索索引与相似度计算让以文搜图真正跑起来4.1 余弦相似度矩阵与 Top-K 检索有了归一化后的图像特征矩阵img_feats形状N x 512和文本特征矩阵text_feats形状N x 512检索就变成矩阵乘法查询文本编码成1 x 512向量后和img_feats做点积得到1 x N的相似度数组取 Top-K 即可。def search_by_text(query, model, img_feats, img_names, top_k5): with torch.no_grad(): tokens clip.tokenize([query]).to(device) q_feat model.encode_text(tokens) q_feat q_feat / q_feat.norm(dim-1, keepdimTrue) sims (q_feat.cpu().numpy() img_feats.T)[0] # (N,) top_idx np.argsort(-sims)[:top_k] return [(img_names[i], float(sims[i])) for i in top_idx] results search_by_text(a dog running on the grass, model, img_feats, img_names) for name, score in results: print(f{name}\t{score:.4f})np.argsort(-sims)是降序取索引的惯用写法比np.argsort(sims)[::-1]更直观。返回的分数在 0.2 到 0.4 之间通常就是比较靠谱的匹配低于 0.15 的基本可以认为是噪声。以图搜文同理把查询换成图像特征和text_feats做点积即可。4.2 用 FAISS 加速3 万条以上才值得上如果只是 3 万张图numpy 矩阵乘法一次查询大概 10 毫秒完全够用。但如果你的课程设计要扩展到更大规模或者老师要求体现「工程优化」可以引入 FAISS 建索引。import faiss index faiss.IndexFlatIP(512) # 内积索引特征已归一化等价于余弦 index.add(img_feats) faiss.write_index(index, flickr30k.index) # 查询 D, I index.search(q_feat.cpu().numpy(), top_k)IndexFlatIP是精确检索不会损失精度。如果追求速度可以换IndexIVFFlat但需要额外训练聚类中心课程设计里用IndexFlatIP就够别为了炫技引入不必要的复杂度。4.3 测试界面Gradio 三行代码搭一个能演示的 Web UI课程设计要交「测试界面」用 Gradio 是最省事的方案不用写前端Python 脚本直接起服务。import gradio as gr def text_search(query): results search_by_text(query, model, img_feats, img_names, top_k5) return [os.path.join(flickr30k-images, name) for name, _ in results] demo gr.Interface( fntext_search, inputsgr.Textbox(label输入英文描述), outputsgr.Gallery(label匹配结果), titleFlickr30k 跨模态搜索 ) demo.launch()gr.Gallery会自动把返回的图片路径列表渲染成网格。启动后浏览器打开http://127.0.0.1:7860就能演示。注意 Gradio 默认只允许本地访问答辩时如果要在别的机器上展示加server_name0.0.0.0参数。5. 避坑与排查那些让我重跑一整天的细节5.1 现象检索结果全是同一张图原因图像特征没有做 L2 归一化或者归一化时用了feats.norm(dim0)而不是dim-1。dim0是对 batch 维度归一化完全错了。解决检查feats / feats.norm(dim-1, keepdimTrue)这行确保dim-1。可以在归一化后打印feats.norm(dim-1)看是否全为 1。5.2 现象文本检索报RuntimeError: expected scalar type Half but found Float原因CLIP 模型在 GPU 上默认用 fp16 推理但你的输入张量是 fp32。或者反过来模型被转成 fp32 但输入是 fp16。解决统一用model.float()把模型转成 fp32或者输入时加.half()。我一般直接model.float()牺牲一点速度换稳定。5.3 现象DataLoader 在 Windows 上卡死或报BrokenPipeError原因Windows 的num_workers 0需要if __name__ __main__:保护否则子进程会重新导入主模块导致递归。解决把提取特征的代码包在if __name__ __main__:里或者直接把num_workers设为 0。后者慢一点但省心。5.4 现象中文查询返回的结果完全不相关原因CLIP 的文本编码器只在英文上训练过中文输入会被 tokenizer 拆成无意义的子词。解决在检索前加一层翻译或者明确在界面上限制「请输入英文描述」。课程设计报告里要写清楚这个边界别让答辩老师以为你的系统支持中文。5.5 现象np.save保存的特征文件加载后形状不对原因保存时用了np.save(feats.npy, feats)加载时用np.load(feats.npy)没问题但如果保存时文件名没加.npynumpy 会自动补上加载时却按原名找就会报FileNotFoundError。解决保存和加载用同一个变量存文件名别手写字符串两次。6. 把检索精度再提一截重排序与阈值过滤的实战技巧跑通基础流程后你可能会发现 Top-1 的准确率大概在 30% 到 40% 之间——这是 CLIP 零样本检索的正常水平。如果课程设计想拿更高分有两个不增加训练成本的办法。第一个是查询扩展把用户输入的一句话用简单的模板生成三到五条变体比如原句是a dog running变体可以是a dog is running、running dog、dog on grass。分别编码后取平均向量再检索。我实测在 Flickr30k 测试集上这一招能把 Top-1 提升 3 到 5 个百分点。代码就是在search_by_text里把clip.tokenize([query])换成clip.tokenize([query, query outdoors, query.replace( , a )])这种然后对多个查询向量取平均。第二个是相似度阈值过滤在界面上只展示分数高于 0.22 的结果低于这个值的直接显示「未找到匹配」。这样虽然召回率降了但用户看到的每一条都靠谱答辩演示时观感好很多。阈值不要拍脑袋定在测试集上跑一遍画个分数分布直方图取正负样本分界点。def search_with_expansion(query, model, img_feats, img_names, top_k5, threshold0.22): variants [query, query outdoors, a photo of query] with torch.no_grad(): tokens clip.tokenize(variants).to(device) feats model.encode_text(tokens) feats feats / feats.norm(dim-1, keepdimTrue) q_feat feats.mean(dim0) q_feat q_feat / q_feat.norm() sims (q_feat.cpu().numpy() img_feats.T)[0] top_idx np.argsort(-sims)[:top_k] return [(img_names[i], float(sims[i])) for i in top_idx if sims[i] threshold]最后说个我自己的习惯每次改完特征提取或检索逻辑一定先拿五条固定查询跑一遍把返回的图片文件名和分数打印出来存成日志。这样一旦后面结果变差能立刻定位是哪一步改坏了。跨模态检索这玩意儿没有后悔药只有日志。希望帮到你。本文还有配套的精品资源点击获取
