基于多模态模型与向量检索的本地图库语义搜索实战

1. 为什么我要给本地图库做语义搜索

我的图库大概是从2018年开始失控的。那会儿手机拍照越来越方便，出去旅游一趟就是几百张，加上平时工作截图、素材收集、表情包囤积，硬盘里陆陆续续堆了将近四万张图。一开始我还挺自信，按年份建文件夹，按事件建子文件夹，命名也算规整。但到了真正要找图的时候，这套体系基本等于没有——我记得有一次想找一张"傍晚的海边"的照片做封面，翻遍了"2021-青岛""2022-厦门"两个文件夹，愣是花了二十多分钟才从一堆相似的海景里挑出来。

问题出在哪？出在传统文件管理靠的是"我记得它在哪"，而不是"它长什么样"。文件名、文件夹、标签，这些都是人手动打上去的元数据，一旦数量上去了，维护成本指数级上升。更别说很多图我压根没命名，就是一堆IMG_20210815_183042.jpg。

后来我试过几种方案。最早是本地跑一个开源的以文搜图工具，效果一般，中文理解尤其差，搜"傍晚的海边"经常给我返回一堆白天的沙滩照。再后来想用云端服务，但四万张图全传上去，隐私和流量都是问题，而且很多服务按调用次数收费，长期用下来不划算。

直到我把蓝耘元生代的多模态能力接进本地图库，才算真正解决了这个问题。核心思路很简单：用多模态模型给每张图生成一段语义描述，存进本地向量库，搜索时把查询语句也转成向量，做相似度匹配。整个过程图片不出本地，只有描述文本和查询语句走模型接口，隐私和成本都可控。

这套方案适合谁？我觉得有三类人特别值得试：一是像我这样图库过万、靠文件夹已经管不过来的个人用户；二是做设计、自媒体、电商，需要频繁按"感觉"找素材的从业者；三是想入门多模态应用开发，但不想一上来就啃论文的开发者。下面我把整套流程拆开讲，包括我踩过的坑和最后跑通的配置。

2. 整体方案设计与技术选型思路

2.1 为什么是"描述生成+向量检索"而不是端到端图搜

市面上做以文搜图，主流有两条路。一条是端到端的多模态嵌入，比如CLIP这类模型，直接把图片和文本映射到同一个向量空间，搜的时候算余弦相似度。另一条是先生成描述、再对描述做文本检索，也就是我最终选的方案。

CLIP路线听起来更"原生"，但我在实际测试里发现两个问题。第一，CLIP对中文短查询的理解不够细腻，"傍晚"和"黄昏"在它眼里可能差不多，但"傍晚的海边"和"夜晚的海边"它又分不太开，返回结果的排序经常让我哭笑不得。第二，CLIP的向量维度固定，想换模型就得全量重算，四万张图重算一次成本不低。

而"描述生成+文本检索"这条路，好处是描述文本是人类可读的。我可以直接打开数据库看某张图被描述成了什么，如果描述不准，我能立刻定位是模型的问题还是图片本身的问题。这种可解释性在调试阶段太重要了。另外，文本检索这套技术栈非常成熟，向量库、全文索引、混合排序，工具链齐全，我想怎么调就怎么调。

代价是多了一步描述生成，四万张图跑一遍需要时间。但这是一次性成本，跑完之后新增图片增量处理就行，完全可以接受。

2.2 蓝耘元生代在这里扮演什么角色

蓝耘元生代提供的是多模态理解能力，通过OpenAI兼容协议暴露接口。这一点是我选它的关键原因——兼容协议意味着我可以用现成的OpenAI SDK直接调用，不用为它单独写一套客户端，代码迁移成本几乎为零。

具体到我的流程里，它承担两个任务：一是图片转描述，把每张图喂进去，让它输出一段包含主体、场景、时间、氛围、色彩的中文描述；二是查询改写，把用户输入的"傍晚的海边"这种口语化短句，扩展成更适合检索的描述性文本，比如"日落时分、海面、暖色调天空、沙滩、黄昏光线"。

为什么查询也要过一遍模型？因为用户的查询往往太短、太模糊。直接拿"傍晚的海边"去和图片描述做匹配，召回率会受影响。让模型把查询"翻译"成更丰富的语义表达，再去做检索，效果提升很明显。这一步是我实测下来最值得做的优化之一。

2.3 本地向量库怎么选

向量库我对比过几个。FAISS快，但它是库不是服务，持久化和增量更新要自己写；Chroma轻量，适合小规模，但四万条以上查询性能开始吃紧；Milvus功能全，但部署重，我一个人用没必要。

最后我选了Qdrant，理由是它单机部署简单，Docker一条命令起来，支持持久化、支持增量写入、支持过滤条件（比如按拍摄年份筛），而且Python客户端用起来很顺手。四万条向量对它来说毫无压力，查询基本在毫秒级。

维度方面，我用的是文本嵌入模型输出的768维向量。这里有个细节：描述生成用的多模态模型和文本嵌入模型是两回事。前者负责"看图说话"，后者负责"把话变成向量"。我文本嵌入用的是本地部署的中文优化模型，这样查询和描述都在本地转向量，只有描述生成那一步走蓝耘元生代接口。

2.4 整体数据流

把上面几块串起来，完整流程是这样的：

1. 扫描本地图库目录，收集所有图片路径
2. 对每张图，调用蓝耘元生代生成中文描述
3. 把描述文本用本地嵌入模型转成向量
4. 向量+描述+图片路径+元数据（拍摄时间、尺寸等）一起写入Qdrant
5. 用户输入查询，先经模型改写，再转向量
6. 在Qdrant里做相似度检索，返回Top-K图片
7. 可选：对结果做一次重排序，提升精度

这个架构的好处是每一层都可以单独替换和调优。描述生成不满意，换模型；嵌入效果不好，换嵌入模型；检索排序不理想，加个重排。模块化带来的灵活性，是端到端方案给不了的。

3. 核心细节解析与实操要点

3.1 描述生成的提示词设计

这一步是整个方案的地基。描述生成得好不好，直接决定后面检索的上限。我前后改了七八版提示词，总结出几个关键点。

第一，要求模型输出结构化但自然的描述。太结构化（比如纯JSON字段）会丢失语义连贯性，检索时匹配效果反而差；太自由又容易漏掉关键信息。我最后用的提示词大意是：请用一段话描述这张图片，包含主体、场景、时间氛围、色彩基调、可能的拍摄视角，语言自然，控制在80字以内。

第二，强制包含时间与光线信息。这是"傍晚的海边"能搜到的关键。很多模型默认描述会忽略光线，只说"海边有沙滩和海水"。我在提示词里明确要求描述时间氛围和光线，比如"黄昏""暖光""逆光""室内冷光"。

第三，避免主观臆断。早期我让模型"描述图片讲述的故事"，结果它开始编，把一张普通街景描述成"忙碌的上班族赶着回家"。这种幻觉会污染检索。后来改成只描述可见内容，不推测意图。

提示：描述长度控制在60到100字之间比较合适。太短信息不足，太长会稀释关键词权重，检索时反而不精准。

3.2 批量处理的并发与限流

四万张图，如果一张一张串行调用，按每张两秒算，得跑二十多个小时。这显然不行。我做了并发，但并发不是越高越好。

我一开始把并发开到20，结果接口开始返回超时和限流错误，而且部分请求失败了还没重试，导致有几百张图描述为空。后来改成并发8，配合指数退避重试，稳定多了。实测下来，四万张图大概跑了三个多小时，可以接受。

这里有个经验：一定要做断点续传。我维护了一个处理状态表，记录每张图的处理状态（待处理/成功/失败）。程序中断后重启，只处理待处理和失败的，不用从头再来。这个设计在我调试阶段救了我无数次。

另外，失败重试要区分错误类型。网络超时值得重试，但如果是图片本身损坏或者格式不支持，重试多少次都没用，直接标记跳过，避免死循环。

3.3 图片预处理不能省

直接拿原图去调接口，有两个问题。一是大图传输慢，二是很多接口对图片尺寸有限制。我在调用前统一做了预处理：长边缩放到1024像素，保持宽高比，转成JPEG，质量85。

这个尺寸是权衡的结果。太小（比如512）会丢失细节，模型看不清远处的东西；太大没必要，1024对语义理解已经足够，而且传输快。质量85在肉眼几乎无损的前提下，文件体积能压到原来的三分之一左右。

还有个细节：EXIF方向要处理。手机拍的照片很多带旋转信息，如果不校正，模型看到的可能是躺着的图，描述就会出错。我用Pillow的ImageOps.exif_transpose统一校正，这一步千万别省。

3.4 向量库的Schema设计

Qdrant里的每条记录，我存了这些字段：

shot_time这个字段特别有用。有时候我明确知道要找某年拍的照片，就可以在检索时加时间过滤，把范围缩小，精度和速度都提升。Qdrant支持在payload上建索引做过滤，查询时带上条件即可。

注意：向量维度一旦确定，后续所有写入和查询必须一致。换嵌入模型时维度可能变，这时候要么重建集合，要么做维度对齐，别混着写。

3.5 查询改写的分寸

查询改写能提升召回，但改过头会引入噪声。我试过让模型把"傍晚的海边"扩展成一大段，结果检索时把很多不相关的海边图也拉进来了，因为扩展文本里出现了"沙滩""度假""旅行"这些泛化词。

后来我把改写策略调整为适度扩展，保留原词。具体做法是：改写结果里必须包含原始查询词，再补充同义或相关的时间、光线、场景词。比如"傍晚的海边"改写成"傍晚 黄昏 日落 海边 海面 沙滩 暖色调光线"。这样既丰富了语义，又不会跑偏。

实测下来，改写后的召回率比不改写提升了大概三成，而精度基本没掉。这个投入产出比很划算。

4. 实操过程与核心环节实现

4.1 环境准备与依赖安装

我的运行环境是Ubuntu 22.04，Python 3.10。核心依赖就几个：

pip install openai qdrant-client pillow sentence-transformers tqdm

• openai：调用蓝耘元生代的兼容接口
• qdrant-client：操作向量库
• pillow：图片预处理
• sentence-transformers：本地文本嵌入
• tqdm：进度条，处理几万张图时看着进度心里有底

Qdrant用Docker起：

docker run -d --name qdrant -p 6333:6333 -v $(pwd)/qdrant_data:/qdrant/storage qdrant/qdrant

-v把数据挂到本地目录，容器删了数据还在，这点很重要。

4.2 调用蓝耘元生代生成描述

因为走的是OpenAI兼容协议，代码和调OpenAI几乎一样，只是base_url和api_key换成蓝耘的。下面是我实际用的核心函数，做了简化：

from openai import OpenAI import base64 client = OpenAI( api_key="你的API_KEY", base_url="蓝耘元生代的兼容接口地址" ) def image_to_description(image_path): with open(image_path, "rb") as f: img_b64 = base64.b64encode(f.read()).decode("utf-8") prompt = ( "请用一段自然的中文描述这张图片，包含：主体内容、场景环境、" "时间氛围与光线、色彩基调、拍摄视角。控制在80字以内，" "只描述可见内容，不要推测意图或编造故事。" ) resp = client.chat.completions.create( model="多模态模型名称", messages=[{ "role": "user", "content": [ {"type": "text", "text": prompt}, {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{img_b64}"}} ] }], max_tokens=200, temperature=0.3 ) return resp.choices[0].message.content.strip()

几个参数说明一下。temperature设0.3，是为了让描述稳定，不要每次都不一样。max_tokens给200足够，描述本身不长。图片用base64内联传，省去上传步骤。

提示：base64编码后体积会增大约三分之一，所以预处理压缩图片这一步对传输效率影响很大，别跳过。

4.3 本地嵌入与写入向量库

描述拿到后，用本地嵌入模型转向量。我用的是中文语义优化过的sentence-transformers模型，768维：

from sentence_transformers import SentenceTransformer from qdrant_client import QdrantClient from qdrant_client.models import PointStruct, VectorParams, Distance embedder = SentenceTransformer("你的本地嵌入模型路径") qdrant = QdrantClient(host="localhost", port=6333) # 建集合，只需执行一次 qdrant.recreate_collection( collection_name="my_gallery", vectors_config=VectorParams(size=768, distance=Distance.COSINE) ) def index_image(img_id, path, description, shot_time): vec = embedder.encode(description, normalize_embeddings=True).tolist() qdrant.upsert( collection_name="my_gallery", points=[PointStruct( id=img_id, vector=vec, payload={ "path": path, "description": description, "shot_time": shot_time } )] )

normalize_embeddings=True很重要，归一化后余弦相似度计算更稳定。距离度量用COSINE，和归一化配套。

4.4 批量处理的完整流程

把上面几步串起来，加上并发控制和断点续传，就是主处理脚本。我用concurrent.futures的线程池，因为主要瓶颈在网络IO，多线程足够：

from concurrent.futures import ThreadPoolExecutor, as_completed from tqdm import tqdm import sqlite3, hashlib, os def process_one(path): try: img_id = int(hashlib.md5(path.encode()).hexdigest()[:15], 16) # 检查是否已处理 if is_done(img_id): return "skip" desc = image_to_description(preprocess(path)) index_image(img_id, path, desc, get_shot_time(path)) mark_done(img_id) return "ok" except Exception as e: mark_failed(img_id, str(e)) return "fail" paths = scan_gallery("/path/to/gallery") with ThreadPoolExecutor(max_workers=8) as pool: futures = [pool.submit(process_one, p) for p in paths] for f in tqdm(as_completed(futures), total=len(futures)): f.result()

状态用SQLite存，轻量又可靠。is_done和mark_done就是简单的查表和更新。这套跑下来，四万张图三个多小时处理完，失败率不到千分之三，失败的重新跑一遍基本都能过。

4.5 查询接口的实现

查询分两步：改写和检索。

def search(query, top_k=20, year=None): # 第一步：改写 rewritten = rewrite_query(query) # 第二步：转向量 qvec = embedder.encode(rewritten, normalize_embeddings=True).tolist() # 第三步：检索，可带时间过滤 flt = None if year: flt = Filter(must=[FieldCondition( key="shot_time", range=Range(gte=year_start(year), lt=year_end(year)) )]) hits = qdrant.search( collection_name="my_gallery", query_vector=qvec, limit=top_k, query_filter=flt ) return [(h.payload["path"], h.payload["description"], h.score) for h in hits]

rewrite_query就是调模型把短查询扩展成描述性文本。返回结果里带上score，方便我判断哪些是强相关、哪些是勉强沾边。

4.6 效果验证：搜"傍晚的海边"

跑通之后我做了个对比测试。同一批图，分别用文件名搜索、纯CLIP方案、我的方案搜"傍晚的海边"，看前20个结果里真正符合的有几个。

文件名搜索直接挂零，因为没人的文件名叫这个。CLIP能搜到一些，但把白天的海景也混进来了。我的方案命中17个，剩下3个是光线接近但场景略有偏差的，可以接受。耗时上因为多了改写这一步，慢了几百毫秒，但换来精度提升，我觉得值。

5. 常见问题与排查技巧实录

5.1 描述生成质量不稳定的排查

现象：同一张图，有时候描述很准，有时候漏掉关键信息。

排查思路：先看是不是temperature设高了。我早期设0.7，描述每次都不一样，后来降到0.3稳定多了。如果还不行，检查提示词是不是太笼统，把要求拆细，明确列出必须包含的维度。

另一个坑：图片本身质量差。模糊、过暗、过曝的图，模型也看不清，描述自然差。这类图我建议单独标记，检索时降权或者直接排除。

5.2 检索结果不相关的处理

现象：搜"傍晚的海边"，返回一堆"清晨的山"。

排查思路：先看描述文本。如果描述里压根没提"傍晚"和"海边"，那是描述生成的问题，回去调提示词。如果描述里有，但检索还是不准，那是嵌入模型的问题，考虑换一个中文语义更强的嵌入模型。

我踩过的坑：嵌入模型和描述语言不匹配。我一开始用了个英文为主的嵌入模型，中文描述转出来的向量区分度很差。换成中文优化的模型后，效果立竿见影。

5.3 处理中断与数据一致性

现象：程序跑到一半崩了，重启后不知道哪些处理过。

解决：状态表是必须的。我用SQLite记录每张图的img_id和status，重启后先查状态，跳过已成功的。另外，写入Qdrant和更新状态表要尽量保证原子性，我的做法是先写向量库，成功后再更新状态，这样即使中间崩了，最多是重复处理，不会丢数据。

5.4 常见问题速查表

5.5 几个独家避坑技巧

第一，先小批量验证再全量跑。我一开始直接上全量，跑到一半发现提示词有问题，白跑了两小时。后来改成先拿200张图试，确认描述质量和检索效果都OK，再全量。

第二，保留原始描述文本。向量库里的描述别只存向量，原文一定要留着。调试时直接看描述，比看向量直观一万倍。

第三，定期备份向量库。Qdrant的数据目录定期打包备份，万一集合损坏，重建的成本很高。我吃过一次亏，后来养成了每周备份的习惯。

第四，给检索加个重排序。如果对精度要求高，可以在向量检索返回Top-50后，再用一个交叉编码器做精排，取Top-10。这一步能再提升一截精度，代价是查询慢一点。我平时不开，做重要检索时才开。

6. 后续可扩展的方向

这套跑通之后，我又顺手做了几个扩展。一个是按图搜图，把某张图当查询，找相似的图，原理一样，只是查询向量换成图片描述向量。另一个是自动打标签，从描述里抽关键词，生成标签云，方便快速浏览。

还有个我觉得挺有意思的方向：结合拍摄时间做时间线检索。比如"去年夏天在海边拍的"，查询里带时间范围，配合语义检索，能精准定位。这个我还在调，主要是时间解析那部分需要处理各种口语化表达。

如果你也想给自己的图库做一套，我的建议是先跑通最小闭环：拿100张图，走完描述生成、向量写入、查询检索全流程，确认效果符合预期，再考虑全量和优化。别一上来就追求完美架构，容易卡在半路。这套方案的门槛其实不高，核心代码加起来也就两三百行，难的是把每个环节的细节调到位。