简介一套基于Chinese-CLIP的图文检索系统课程设计资料包面向人工智能、通信工程、自动化、电子信息、物联网等计算机相关专业的在校学生与教师可支撑课程设计、毕业设计、项目立项演示及进阶学习。资源围绕“文本—图像”跨模态检索完整流程覆盖预处理、模型训练、评估与部署等环节代码经测试运行成功功能可靠。包内共60个文件以40个Python源文件为代码主体辅以9个JSON数据配置、7个pyc编译文件、2个txt文本、1个png图片与1个md说明文档压缩包大小仅544KB轻量且目录规范便于按模块阅读。入口与推理脚本可直接运行结合预处理、训练、部署、评估等目录模块能快速复现实验效果也方便对照流程做调试或二次开发。内含详细文档与全部资料源自高分课程设计并通过答辩评审具备较强参考价值。目前已有216人学习下载适合想深入NLP与视觉融合应用的读者既可作为系统的入门指南也能为后续算法改进与界面优化提供基础。1. 课程设计抽到“基于Chinese-CLIP的图文检索”这个题目到底在考什么答辩现场老师问的第一句话通常是“你这系统和你自己训的模型有什么区别”如果只回答“我调了个包”基本就告别高分了。这门课设真正想让你做的是理解一个完整图文检索系统的数据流图片和文字如何被编码、映射到同一个向量空间、再通过相似度排序返回结果——Chinese-CLIP恰好是把这条路走通的最省力起点因为它在中文语料上预训练好了你不需要造轮子但必须清楚轮子为什么能转。这篇文章只聊一件事拿到“基于Chinese-CLIP的图文检索系统”这个课设题目后从数据准备、离线特征提取、后端接口到课程文档怎么一步步把它做成一个能演示、能讲清、能被老师追问不慌的系统。新手能照着跑熟手能直接抄参数和踩坑清单。目录结构那个zip包里有什么其实不重要重要的是你自己能把这一套从头到尾复现一遍。2. 从 CLIP 到 Chinese-CLIP为什么图文检索课设绕不开对比学习2.1 图文检索的两条老路为什么撑不住课设演示图文检索不是新东西。传统方案里图像侧用 CNN 提特征文本侧用 TF-IDF 或 Word2Vec 提特征然后想办法做“对齐”。问题在于CNN 的 ImageNet 分类特征和 Word2Vec 的语义向量根本不在同一个空间里硬算余弦相似度搜出来的结果毫无可解释性。另一条路是训练一个多标签分类器把图片分类成若干语义标签再拿标签去匹配文本——这等于把开放域检索退化成了有限类别匹配课设演示时换个没见过的词就翻车。这两条路的共同问题是模型只学了“图像是什么”或“文本说什么”没学“图和文之间怎么对应”。而图文检索要的是跨模态匹配这恰恰是需要专门训练的。2.2 对比学习把图和文拉进同一个向量空间CLIP 的思路一句话就能讲完训练一个双塔网络图像塔负责把图片编码成向量文本塔负责把句子编码成向量然后用对比损失让“匹配的图文对”在向量空间里靠近“不匹配的”互相远离。关键在损失函数。给定一个 batch 里的 N 个图文对对每张图片来说它对应的文本是正样本batch 里其余 N-1 条文本都是负样本文本侧同理。模型要做的是让正样本对的余弦相似度尽量大、负样本对的尽量小。训练完成后整个模型变成了一个“映射函数”任意图片和任意文本都被压进同一个向量空间检索时直接算相似度排序就行。这个设计的好处是图搜文和文搜图不需要两套系统。把图片特征矩阵存下来拿一条文本向量去点积就是文搜图把文本特征矩阵存下来拿一张图片向量去点积就是图搜文。方向只是矩阵乘法的转置问题。这也是为什么课设里你只需要写一个相似度计算函数就能覆盖两个检索方向。顺着这个思路往后延伸视觉大语言模型里常见的图文对齐模块底层用的也是同一套对比学习逻辑。理解 CLIP后续看任何多模态模型都轻松得多。2.3 Chinese-CLIP 的模型组成与选型base 还是 largeChinese-CLIP 是 CLIP 的中文版本解决的是英文 CLIP 在中文场景下表现差的问题。它用 Wukong、LAION 等中文图文对数据重新预训练效果比直接拿英文 CLIP 翻译要靠谱得多。模型结构上没有惊天动地的改动依然是双塔图像塔ViT-B/16把图片切成 16×16 的 patch 序列过 Transformer 编码文本塔RoBERTa-wwm-ext针对中文优化过的 BERT 变体投影层两个塔各自输出后都会过一层投影把特征压到同一个维度空间做对比课程设计选 base 就够。large 模型检索质量的提升幅度对于一两千张图的课设 demo 来说几乎看不出来但显存占用和推理时间翻倍。我一般直接用OFA-Sys/chinese-clip-vit-base-patch16这个权重推理时用 transformers 加载from transformers import ChineseCLIPProcessor, ChineseCLIPModel model ChineseCLIPModel.from_pretrained(OFA-Sys/chinese-clip-vit-base-patch16) processor ChineseCLIPProcessor.from_pretrained(OFA-Sys/chinese-clip-vit-base-patch16) model.eval()逻辑说明from_pretrained会自动下载模型权重和 processor 配置。eval()一定要加否则模型里的 dropout 和 layernorm 在推理时行为不一致检索结果会随机抖动。参数说明OFA-Sys是作者组织名chinese-clip-vit-base-patch16表示图像塔用的是 ViT-B/16。如果显存紧张可以换成-patch14或移动端小模型但检索精度会下降课设阶段不建议折腾。3. 搭一个能跑的图文检索数据组织、特征提取与相似度计算3.1 数据准备用 Flickr30K-CN 子集还是自建数据课设的数据集选择有个原则越小越可控。公开中文图文数据集里Flickr30K-CN 和 COCO-CN 都可以直接下载但完整数据集动辄几万张图跑一遍特征提取上小时起步。我习惯只抽一个子集比如 Flickr30K-CN 里抽 2000 个图文对每张图带 5 条参考描述——这个配置刚好够算 Recall 指标。数据目录组织建议长这样dataset/ ├── images/ # 图像文件夹统一 jpg 格式 └── captions.json # 标注文件captions.json的结构我一般设计成{ img_0001.jpg: { file: img_0001.jpg, captions: [一只猫坐在窗台上, 白猫望着窗外, ...] } }关键点每张图保留多条 caption。这不仅是为了检索时能返回多条结果更重要的是后面评估 RecallK 时一个 query 的 ground truth 是一个集合命中任意一条就算对。没有多条 captionRecall 指标根本没法算。JSON 格式还有个好处跟 Flask 接口的交互几乎零成本。前端传回来的结果列表可以直接按 key 取图片路径不需要额外的数据库。3.2 离线提取图库特征归一化比想象中重要特征提取是整个系统的核心耗时环节一定放到检索前面做。我一般写一个脚本一次性把图库里所有图片的特征提取完存成.npy文件之后 Flask 启动时直接np.load加载几秒钟搞定不用每次请求都过模型。import json import numpy as np import torch from pathlib import Path from PIL import Image from transformers import ChineseCLIPProcessor, ChineseCLIPModel model ChineseCLIPModel.from_pretrained(OFA-Sys/chinese-clip-vit-base-patch16) processor ChineseCLIPProcessor.from_pretrained(OFA-Sys/chinese-clip-vit-base-patch16) model.eval() images_dir Path(dataset/images) anns json.load(open(dataset/captions.json, encodingutf-8)) img_ids list(anns.keys()) feats [] batch [] batch_ids [] batch_size 32 # 显存小就改成 16 for idx, img_id in enumerate(img_ids): img Image.open(images_dir / anns[img_id][file]).convert(RGB) batch.append(img) batch_ids.append(img_id) if len(batch) batch_size or idx len(img_ids) - 1: inputs processor(imagesbatch, return_tensorspt) with torch.no_grad(): embeds model.get_image_features(**inputs) # L2 归一化检索相似度等价于余弦相似度 embeds embeds / embeds.norm(dim-1, keepdimTrue) feats.append(embeds.cpu().numpy()) batch.clear() batch_ids.clear() feats np.concatenate(feats, axis0) np.save(dataset/image_embeds.npy, feats) np.save(dataset/image_ids.npy, np.array(img_ids))逻辑说明get_image_features提取图像特征后必须手动归一化。这一步不做后面算相似度时数据分布会受特征模长干扰看起来结果也能出但排序不稳定换一张 query 图排名就乱跳。参数说明batch_size32在普通 8GB 显存的 GPU 上没问题CPU 环境建议降到 4~8且不要开 fp16。.convert(RGB)是必须的否则遇到 RGBA 或灰度模式的图片会直接让 processor 报错或形状不匹配。3.3 文搜图与图搜文一次矩阵乘法的两个方向图库特征存好了检索就变成一个纯矩阵运算逻辑。文搜图的实现如下def text_search(query, top_k10): inputs processor(text[query], return_tensorspt) with torch.no_grad(): text_emb model.get_text_features(**inputs) text_emb text_emb / text_emb.norm(dim-1, keepdimTrue) # feats 是 (N, dim) 的图库特征矩阵已经被 L2 归一化 sims text_emb.cpu().numpy() feats.T # (1, N) idx np.argsort(-sims[0])[:top_k] return [{img_id: img_ids[i], score: float(sims[0][i])} for i in idx]逻辑说明一句话查询变成向量后和整个图库特征矩阵做矩阵乘法得到的(1, N)向量就是这条 query 与每张图的相似度。argsort(-sims[0])取相似度最高的前 K 个索引。图搜文更简单只需事先把每一张图的 5 条 caption 也过一遍文本塔存成dataset/text_embeds.npy和对应的文本 id 列表。查询时把输入图片过get_image_features归一化后直接和文本特征矩阵点积。两个方向的代码几乎一样区别只在“query 走图像塔还是文本塔”。这里有个容易被忽略的点文本侧每条 caption 单独编码而不是把 5 条拼成一段。因为模型训练时一条文本 token 序列对应一张图拼接会让语义浑浊检索精度明显下降。4. 把检索结果变成能交差的系统Flask 接口、页面与课程文档怎么组织4.1 系统功能与接口设计先定交互再写代码课设系统不需要花哨但一定要“完整”。说得直白点老师打开你的系统应该能完成三个动作输入文字搜图片、上传图片搜文本、看一眼结果页觉得像那么回事。我建议先画两个接口再动手POST /api/search_text— 请求参数{query: 一只猫在窗台上}返回图片 id 相似度列表POST /api/search_image— 请求参数为 multipart 上传的图片文件返回文本描述列表Claude 出的方案经常喜欢给一堆接口但课设场景做多就是给自己找事。两个接口一个网页前后端打通就是完整闭环。4.2 Flask 后端与检索页面最小实现from flask import Flask, request, jsonify, render_template import numpy as np import torch from PIL import Image from transformers import ChineseCLIPProcessor, ChineseCLIPModel app Flask(__name__) model ChineseCLIPModel.from_pretrained(OFA-Sys/chinese-clip-vit-base-patch16) processor ChineseCLIPProcessor.from_pretrained(OFA-Sys/chinese-clip-vit-base-patch16) model.eval() image_embeds np.load(dataset/image_embeds.npy) image_ids np.load(dataset/image_ids.npy) app.route(/api/search_text, methods[POST]) def search_text(): query request.get_json()[query] inputs processor(text[query], return_tensorspt) with torch.no_grad(): text_emb model.get_text_features(**inputs) text_emb text_emb / text_emb.norm(dim-1, keepdimTrue) sims text_emb.cpu().numpy() image_embeds.T topk np.argsort(-sims[0])[:12] results [{img_id: image_ids[i], score: float(sims[0][i])} for i in topk] return jsonify({results: results}) app.route(/api/search_image, methods[POST]) def search_image(): file request.files[image] img Image.open(file.stream).convert(RGB) inputs processor(images[img], return_tensorspt) with torch.no_grad(): img_emb model.get_image_features(**inputs) img_emb img_emb / img_emb.norm(dim-1, keepdimTrue) text_embeds np.load(dataset/text_embeds.npy) # 启动时加载更好这里只是演示 sims img_emb.cpu().numpy() text_embeds.T topk np.argsort(-sims[0])[:5] results [{caption: text_ids[i], score: float(sims[0][i])} for i in topk] return jsonify({results: results}) app.route(/) def index(): return render_template(index.html) if __name__ __main__: app.run(debugTrue, port5000)逻辑说明模型在模块加载时就初始化避免每个请求重新载入。图库特征也提前加载成全局变量。text_embeds.npy在图搜文接口里每次请求都 load 一次正式代码应该和 image 特征一样在启动时加载这里写成演示逻辑是为了强调它的存在。前端页面建议直接用原生 HTML JavaScript fetch不要引 Vue 或 React课设不需要前端工程化。页面里一个文本框、一个上传按钮、一个结果网格区约 80 行代码就够。4.3 课程设计文档怎么写让老师相信你“做完了”而不是“跑通了”“详细文档 全部资料 优秀项目”这个后缀说明这门课设的评分重点很大程度在文档上。我评审过几届课程设计最常见的通病是代码能跑但文档只有环境安装步骤和代码贴图没有任何设计过程。一份合格的课程设计文档至少要有这几部分需求分析说明系统解决什么问题用户是谁核心功能是什么方案选型为什么选 Chinese-CLIP 而不是 ResNet BERT要有对比系统设计数据流图、模块划分、接口定义核心算法对比学习原理、特征归一化、相似度计算要写出公式测试与评估RecallK 指标、检索示例、失败案例分析总结做了什么、没做什么、如果重做会怎么改如果你的文档里能写清楚“为什么每张图保留 5 条 caption 才能算 RecallK”这个深度已经超过九成同学了。这个 zip 包里哪怕自带优秀模板也建议自己按上述结构重写一份答辩时被追问“这文档是你写的吗”照稿念和临场答完全是两个印象分。5. Chinese-CLIP 图文检索踩坑实录维度、显存和玄学检索质量5.1 显存总是在特征提取时爆炸现象一张图一张图过模型没问题但为了提高速度把 batch_size 调到 64直接 OOM。原因get_image_features虽然只提取图像特征但模型的前向传播会同时构建图像和文本两个塔的计算图实际显存占用比单塔翻倍。而且很多人忘了在eval()模式下仍然开着梯度torch.no_grad()没包住 forward额外多占一份显存。解决推理时务必用with torch.no_grad():包住前向计算batch_size 从 32 降到 16显存占用直接砍半。如果还是不够再把模型的torch_dtype切到torch.float16但注意 fp16 下如果出现 NaN优先怀疑 LayerNorm 精度问题这时候改回 fp32 比调任何参数都管用。5.2 相似度全挤在 0.7 到 0.8排序没区分度现象检索结果里所有分数都接近第一名和第十名只差 0.02看起来像随机排序。原因特征没有做 L2 归一化。CLIP 类模型的输出特征模长分布很宽不归一化直接点积相似度会被大模长的维度主导导致分数挤在一起。解决特征提取和 query 编码时都执行embeds embeds / embeds.norm(dim-1, keepdimTrue)。归一化之后相似度范围在 [-1, 1]排序间隔拉开阈值过滤才有意义。这是最容易被忽略但影响最大的一步。5.3 长中文描述检索效果明显变差现象输入“一只橘色的猫趴在窗台上晒太阳”能搜对输入一小段场景描述反而返回一堆无关图。原因Chinese-CLIP 预训练时文本侧有最大长度限制默认配置下超过 52 个 token 的内容会被截断。课设里大家写的 query 往往不是短语而是完整句子后半句的关键信息被截掉特征自然不对。解决明确传processor(text[query], max_length64, truncationTrue)同时检查input_ids的真实长度。如果序列被截断要么精简 query 表达要么调大max_length但注意模型位置编码有上限不是越大越好。5.4 同一张图换一种预处理方式检索结果就变现象你用 PIL 打开图片直接送进模型和用 OpenCV 读图再送进去前几名结果不一样。原因PIL 和 OpenCV 的颜色通道顺序不同模型花在识别颜色属性上的特征被扰动。顺手一点的是 processor 内部已经做了 resize、center crop 和归一化只要输入是 RGB 模式且图像尺寸大于等于 224×224问题不大但如果你在传图前自己 resize 或裁剪过模型看到的分布就和预训练不一致。解决所有图片统一走 processor 处理不要在外部手写 resize。遇到尺寸很小的图先补边到 224×224 再送处理器而不是直接拉伸。拉伸会让宽高比畸变ViT 切 patch 时位置信息被破坏检索质量断崖式下降。5.5 检索结果“感觉不对”CLIP 的语义粒度到底有多细现象搜“高楼大厦”返回了山峰的图搜“厨房”返回了餐桌的图你觉得它理解错了但它评分确实最高。原因CLIP 学到的是“概念级”对齐不是“属性级”对齐。“高楼大厦”和“山峰”在视觉特征上有共同点——竖直方向大面积连续纹理这在向量空间里确实近。这是模型本身的语义粒度边界参数上无解。解决接受这个边界然后在产品层面处理。一是给检索结果加阈值过滤低于阈值的直接不展示二是做后处理重排比如对返回候选集做一个基于颜色直方图的微调把明显不符合的排下去。后者能让课设答辩的演示效果好一大截原理也讲得通很加分。6. 把检索系统从“能跑”拉到“能答辩”的三个进阶动作6.1 用 faiss 把检索从 numpy 点积换成索引查询课设图库只有几千张图时numpy 矩阵乘法完全够用延迟在毫秒级。但如果你的数据集抽到 10 万张以上或者答辩时老师问“你这检索怎么支撑更大规模数据”答案不能是“换一台更大的机器”。用 faiss 做向量索引是标准解法。特征已经 L2 归一化的情况下用内积索引就能精确复现 numpy 的排序结果import faiss dim image_embeds.shape[1] index faiss.IndexFlatIP(dim) # 内积等价于归一化后的余弦 index.add(image_embeds.astype(float32)) D, I index.search(query_emb.astype(float32), top_k)参数说明IndexFlatIP是暴力精确检索不牺牲精度适合百万级以下的数据。再往上可以换IndexIVFFlat但那要调 nlist 和 nprobe课设阶段写了反而容易被追问细节。一句话带过“后续可以换 IVF 近似索引”就够了。6.2 算 RecallK图文检索系统好不好的硬指标演示效果可以“看起来不错”但文档里的评估必须有数值。图文检索的标准指标是 RecallK对每个 query取检索结果前 K 个看 ground truth 是否在其中。K 通常取 1、5、10。两个方向分开算文搜图的 RecallK 和图搜文的 RecallK。def recall_at_k(sim_matrix, ground_truth, k): hits 0 for i, gt in enumerate(ground_truth): topk np.argsort(-sim_matrix[i])[:k] if any(g in topk for g in gt): hits 1 return hits / len(ground_truth)注意 ground_truth 是一个列表集合不是单个 id。因为每张图有多条相关描述命中任意一条就算一次命中。这个细节写进文档老师一眼就知道你真的动手算过指标而不是抄了个数字。6.3 答辩演示前必做的三张对比图我自己的习惯是答辩前一晚必然跑三组固定的检索样例截图存下来。第一组是常见场景的成功检索证明系统基本能力第二组是相似语义的不同表达比如“小猫”和“幼猫”搜出的结果对比证明模型学到了语义对齐第三组是故意失败的案例并准备一段解释“为什么失败”——这比全是成功截图更有说服力因为老师知道 CLIP 有语义粒度边界你能主动说清边界就说明你是真的理解模型而不是调参碰运气。做这个项目最大的教训是检索系统的好坏不是“看起来像”而是“算得出”。下次再碰多模态项目我会在第一天就把特征归一化、RecallK、faiss 索引这三件事放进技术方案里而不是等到答辩前一周才补。希望这篇笔记能帮你少走一次我当时走过的弯路。本文还有配套的精品资源点击获取