本地图库这件事几乎每个做视觉、做内容、做电商的人最后都会走到同一个死胡同硬盘里躺着几万张图文件夹按日期分了一堆真要用的时候还是靠肉眼一张张翻。文件名是IMG_20240815_183022.jpg这种标签系统建了又懒得维护最后搜索能力约等于零。我自己的图库大概四万多张之前试过用文件名规则、试过用系统自带的相册分类都不太顶用——因为我想搜的是傍晚的海边这种语义层面的东西而不是包含海字的文件。这篇就聊聊我最近折腾的一套方案把本地图库接上一个多模态语义搜索服务用自然语言直接搜图。核心思路是用多模态模型把图片转成向量存进本地向量库查询时把文本也转成向量做相似度匹配。服务端我接的是蓝耘元生代它提供OpenAI兼容协议所以客户端代码基本可以复用现成的OpenAI SDK写法迁移成本很低。整套东西跑通之后傍晚的海边确实能搜出那张在青岛拍的、文件名毫无信息量的照片体验提升是断崖式的。适合谁来参考有一定Python基础、手里有本地图库、想自己搭一套语义搜索但不想从零训模型的同学。如果你只是想找个现成App那这篇可能偏重了但如果你想搞清楚图片是怎么变成可搜索的向量这件事并且想自己掌控数据和流程那往下看。1. 为什么传统图库搜索在傍晚的海边面前彻底失效1.1 文件名和文件夹体系的先天缺陷先说说为什么老办法不行。绝大多数人的图库组织方式无非两种按时间分文件夹或者按事件分文件夹。前者的问题是时间跟内容没关系你记得那张照片是傍晚拍的但你不记得是哪天后者的问题是事件粒度太粗2024青岛行这个文件夹里可能有两百张图你还是得翻。文件名就更不用说了。相机和手机默认生成的文件名是时间戳加序号没有任何语义信息。有些人会手动改名但四万张图你改到什么时候我试过一段时间坚持给重要照片改名坚持了两周就放弃了因为改名的成本远高于偶尔翻找的成本——直到图库规模大到偶尔翻找变成经常翻找这个账才算不过来。标签系统理论上能解决但它有个致命问题标签是离散的、需要预先定义的。你得先想好有哪些标签然后一张张打。而人的记忆是连续的、模糊的。傍晚的海边这个查询里傍晚是时间光线属性海边是场景属性这两个维度在传统标签体系里往往是分开的你很难用一个标签组合精确命中。1.2 语义搜索到底在搜什么语义搜索的本质是把内容映射到一个高维空间里的点然后在这个空间里算距离。图片和文本被映射到同一个空间所以傍晚的海边这句话对应的向量会和那张傍晚海边照片对应的向量靠得很近。这里的关键是多模态模型。传统的图像模型只能做分类这是猫、那是狗输出的是一堆概率值没法跟自然语言对齐。多模态模型比如CLIP这类对比学习架构在训练时就是把图片和它的文字描述拉到同一个向量空间里所以它天生就支持用文字搜图。理解这一点很重要因为它决定了你后面所有的工程选择你不需要自己训模型你需要的是一个能把图片编码成向量的服务以及一个能存向量、算相似度的数据库。剩下的都是胶水代码。1.3 为什么选蓝耘元生代而不是本地跑模型理论上你可以在本地跑一个开源的多模态模型用transformers加载然后自己写推理。我一开始就是这么干的但很快遇到几个现实问题。第一是显存。多模态模型的视觉编码器参数量不小要在本地跑得动要么降精度要么用很小的模型而小模型的语义理解能力会明显下降傍晚和清晨这种细微差别它分不出来。第二是速度。四万张图要全部编码一遍本地跑可能要几个小时甚至更久而且这还只是首次建库后续新增图片还得持续编码。第三是维护成本模型版本更新、依赖冲突这些事很烦。接蓝耘元生代的好处是它提供OpenAI兼容协议。这意味着我不需要学一套新的SDK直接用openai这个Python包把base_url指过去就行。对于已经用过OpenAI接口的人来说迁移成本几乎为零。而且编码这件事交给服务端本地只负责发请求和存结果对机器要求低很多。提示选服务端方案的核心考量不是能不能跑而是长期维护成本。本地跑模型短期爽长期是负担服务端方案短期要配置长期省心。2. 把图片变成向量编码环节的工程细节2.1 图片预处理尺寸、格式与批量策略多模态模型的输入对图片尺寸是有要求的。太大的图直接传会浪费带宽和时间太小的图又会丢失细节。我的做法是统一缩放到长边不超过1024像素保持宽高比格式统一转成JPEG质量85。这个尺寸对语义理解足够了因为模型关心的是画面里有什么不是像素级细节。批量策略上有个坑不要一次性把几百张图塞进一个请求。服务端一般有单次请求的图片数量或体积限制而且一旦失败整批都要重来。我的做法是每批10张失败重试3次每次重试间隔递增。这样即使某张图有问题也只影响这一批不会拖垮整个建库流程。from PIL import Image import io def preprocess_image(path, max_side1024, quality85): img Image.open(path).convert(RGB) w, h img.size scale max_side / max(w, h) if scale 1: img img.resize((int(w * scale), int(h * scale)), Image.LANCZOS) buf io.BytesIO() img.save(buf, formatJPEG, qualityquality) return buf.getvalue()这段代码看着简单但Image.LANCZOS这个重采样算法值得说一下。默认的NEAREST会出锯齿BILINEAR会糊LANCZOS在缩小图片时质量最好代价是稍慢一点。对于建库这种一次性任务慢一点无所谓质量优先。2.2 调用兼容接口base_url与鉴权的正确姿势用OpenAI兼容协议调蓝耘元生代核心就是三行配置api_key、base_url、model。这里最容易踩的坑是base_url的写法——有些服务要求带/v1后缀有些不带写错了会直接404。我的经验是先看服务商文档给的示例然后拿一个最简单的请求去试通了再往下写。from openai import OpenAI client OpenAI( api_key你的密钥, base_urlhttps://你的服务地址/v1 ) def encode_image(image_bytes): import base64 b64 base64.b64encode(image_bytes).decode(utf-8) resp client.embeddings.create( model多模态嵌入模型名, input[{type: image_url, image_url: {url: fdata:image/jpeg;base64,{b64}}}] ) return resp.data[0].embedding注意input的格式。文本嵌入直接传字符串但图片嵌入要传一个结构化的对象里面用data:image/jpeg;base64,这种data URL的形式。这个格式跟OpenAI的视觉接口是一致的所以如果你之前调过GPT-4V那类接口这里会很熟悉。注意密钥不要硬编码在代码里用环境变量或者配置文件。我见过太多人把密钥提交到Git仓库然后被扫出来盗刷这个坑真的没必要踩。2.3 向量维度与存储格式的选择编码出来的向量是一个浮点数数组维度取决于模型常见的是768、1024、1536这几种。存储的时候有两个选择存原始float32数组或者存量化后的int8。float32精度高但占空间int8省空间但会损失一点精度。我的建议是首次建库用float32因为图库规模在十万以内时存储成本完全可以接受。算一下1536维的float32向量一张图占1536×46144字节约6KB。四万张图就是240MB对现在的硬盘来说不值一提。等规模上到百万级再考虑量化。存储格式上我推荐用numpy的.npy文件或者向量数据库。如果图库不大几万张直接用numpy存一个矩阵查询时算余弦相似度简单粗暴且够快。如果图库很大或者要频繁增删那就上专门的向量库比如FAISS、Milvus这些。方案适用规模优点缺点numpy矩阵十万以内零依赖、简单增删麻烦、全量加载FAISS百万级快、支持索引需要额外学习Milvus千万级功能全、支持分布式部署重我自己的图库四万多张用的就是numpy方案查询延迟在几十毫秒级别完全够用。3. 查询链路从一句话到一组图3.1 文本编码必须和图片编码用同一个模型这是整个方案里最容易被忽略、后果最严重的一个点。图片和文本必须在同一个向量空间里才能算相似度。如果你用A模型编码图片用B模型编码文本那算出来的相似度是完全没有意义的搜出来的结果会乱七八糟。所以查询时的文本编码必须调用和建库时完全相同的模型。这一点在代码里要写死不能图省事换个模型。我一开始就犯过这个错建库用了一个模型查询时随手换了个更便宜的结果搜海边出来一堆室内照片排查了半天才发现是模型不一致。def encode_text(text): resp client.embeddings.create( model多模态嵌入模型名, # 必须和图片编码一致 input[{type: text, text: text}] ) return resp.data[0].embedding3.2 相似度计算余弦相似度为什么是首选向量相似度有好几种算法欧氏距离、点积、余弦相似度。多模态嵌入向量通常用余弦相似度因为它只关心方向不关心长度而嵌入向量的长度往往跟内容强度有关不是我们想要的信号。余弦相似度的公式是两向量点积除以模长乘积取值范围-1到1越接近1越相似。用numpy实现的话把库里的向量矩阵归一化之后查询向量也归一化然后直接做矩阵乘法一次就能算出跟所有图片的相似度速度非常快。import numpy as np def search(query_vec, db_matrix, top_k20): q query_vec / np.linalg.norm(query_vec) db_norm db_matrix / np.linalg.norm(db_matrix, axis1, keepdimsTrue) scores db_norm q idx np.argsort(-scores)[:top_k] return idx, scores[idx]这段代码里np.argsort(-scores)取的是相似度最高的top_k个。注意是负号因为argsort默认升序取负号就变成降序了。3.3 结果排序与阈值过滤的实战调参光有top_k还不够还得有个相似度阈值。因为不管你的查询多离谱top_k总会返回k个结果哪怕这k个都跟查询没关系。比如你搜傍晚的海边图库里根本没有海边照片它也会硬凑出20张最像的可能是傍晚的街道、可能是白天的海边这些结果会误导你。我的做法是设一个阈值比如0.25具体值要实测低于这个值的直接不返回。这样搜不到就是搜不到比返回一堆垃圾结果要好。阈值怎么定拿几个你确定能搜到的查询试看正确结果的相似度大概在什么区间然后取一个略低于最低值的数。另外排序也值得调。默认按相似度降序就行但如果你有额外的元数据比如拍摄时间、文件路径可以做个加权。比如你搜傍晚的海边如果同时想优先看最近拍的可以把时间作为一个微调因子。不过这个属于进阶玩法先把基础跑通再说。4. 建库流程的完整落地与增量更新4.1 首次全量建库遍历、去重与断点续传首次建库要遍历整个图库这一步的工程细节最多。首先是遍历用os.walk递归扫过滤掉非图片文件。其次是去重同一个文件可能在多个文件夹里有副本可以用文件内容的MD5做去重避免重复编码浪费额度。最重要的是断点续传。四万张图编码可能要跑一两个小时中间网络抖动、服务限流都可能中断。如果每次中断都从头来那太痛苦了。我的做法是每处理完一张图就把它的路径和向量追加写到一个临时文件里重启时先读这个文件跳过已经处理过的。import os, hashlib, json def file_md5(path): h hashlib.md5() with open(path, rb) as f: for chunk in iter(lambda: f.read(8192), b): h.update(chunk) return h.hexdigest() def build_index(root, done_filedone.jsonl): done set() if os.path.exists(done_file): with open(done_file) as f: for line in f: done.add(json.loads(line)[path]) for dirpath, _, files in os.walk(root): for name in files: if not name.lower().endswith((.jpg, .jpeg, .png)): continue path os.path.join(dirpath, name) if path in done: continue # 编码并追加写入 done_file ...这个模式看着土但极其可靠。我建库过程中断过三次每次都从断点接着跑没有浪费任何已完成的编码。4.2 增量更新新照片怎么进库图库是活的每天都有新照片进来。全量重建不现实得支持增量。增量的逻辑很简单定期扫一遍图库找出不在已建库列表里的新文件编码后追加到向量矩阵和路径列表里。这里有个细节numpy矩阵追加不如列表灵活。我的做法是内存里维护一个列表定期比如每100张把列表转成矩阵存盘。这样既避免了频繁的磁盘IO又保证了数据不会丢太多。提示增量更新最好做成定时任务比如每天凌晨跑一次。手动触发容易忘忘了图库就越来越旧搜索体验会下降。4.3 元数据管理路径、时间与向量的对应关系向量本身没有意义必须和图片路径对应起来。我维护两个平行的结构一个是向量矩阵N×D一个是路径列表长度N第i行向量对应第i个路径。这个对应关系一旦错位整个搜索就废了所以每次增删都要保证两个结构同步更新。除了路径我还存了拍摄时间从EXIF读和文件大小。这些元数据在结果展示时有用比如搜出来之后按时间排序或者显示这张是2023年拍的。EXIF读取用PIL的_getexif()就行注意有些图没有EXIF要做异常处理。5. 实测效果与几个反直觉的发现5.1 傍晚的海边实测命中率与失败案例分析拿我自己的图库实测搜傍晚的海边top 20里命中了7张真正的傍晚海边照片另外有几张是傍晚的湖面、清晨的海边这个算半对。命中率大概七成对于自然语言查询来说我觉得可以接受。失败案例里最有意思的是**傍晚和清晨的混淆**。这两个时段的光线特征确实很像都是低角度、暖色调模型有时候分不清。我试过加限定词比如日落时的海边命中率会高一些因为日落比傍晚更具体。另一个发现是抽象词效果差。搜孤独的海边基本搜不出什么因为孤独是个情绪词多模态模型对情绪的理解有限。这类查询还是得靠人脑机器帮不上忙。5.2 中文查询的坑分词、同义词与表达习惯中文查询有个隐形的坑同义词。你搜海边能搜到搜海滩可能结果就不一样虽然在人看来这俩是一回事。这是因为模型训练时的语料里这两个词的分布不完全重合。应对办法是查询扩展把用户的查询词做同义词替换生成多个查询分别编码后取并集。比如海边扩展成[海边, 海滩, 海岸]三个查询的结果合并去重。这会增加一点计算量但召回率明显提升。还有个坑是表达习惯。中文里傍晚的海边和海边的傍晚语义一样但向量可能不同。这个目前没有特别好的解法只能靠多试。我的经验是把核心名词放前面海边 傍晚这种写法有时候比完整句子效果更好。5.3 性能实测四万张图的查询延迟四万张图1536维向量numpy矩阵大小约240MB。查询时归一化矩阵乘法在普通笔记本上实测延迟30到50毫秒完全感觉不到卡顿。这个性能对于个人使用绰绰有余。建库速度方面受限于服务端的编码速度四万张图大概跑了两个多小时平均每张不到0.2秒。这个速度我觉得可以接受毕竟是一次性任务。增量更新每天几十张几秒钟就完事。指标实测值图库规模约40000张向量维度1536矩阵大小约240MB查询延迟30-50ms全量建库耗时约2小时增量更新100张约20秒6. 踩过的坑与排查思路6.1 编码模型不一致导致的搜啥都不对这个前面提过但值得单独说因为它太隐蔽了。症状是搜索能返回结果但结果跟查询明显不相关而且不管搜什么都差不多。排查方法是拿一张已知的图片用它的向量去搜它自己如果相似度不是接近1那说明编码链路有问题。具体排查步骤先确认建库时用的模型名再确认查询时用的模型名两者必须一字不差。然后拿同一张图编码两次看向量是否一致应该完全一致除非服务端有随机性。最后拿图片向量搜文本这张图里有什么看相似度是否合理。6.2 base_url写错引发的404与超时base_url的坑在于它有时候带/v1有时候不带而且不同服务商的约定不一样。症状是请求直接报404或者连接超时。排查很简单用curl手动发一个请求看返回什么。如果404就试试加或去掉/v1如果超时检查网络和地址拼写。curl -X POST https://你的服务地址/v1/embeddings \ -H Authorization: Bearer 你的密钥 \ -H Content-Type: application/json \ -d {model:模型名,input:[{type:text,text:test}]}这个curl能通代码就一定能通。反之如果curl都不通那问题在配置不在代码。6.3 大批量请求被限流的应对策略服务端一般都有速率限制短时间内发太多请求会被限流表现为返回429状态码。应对策略有三层降低并发、加重试、加退避。降低并发就是别开太多线程同时发请求我一般控制在4到8个并发。加重试就是遇到429自动重试重试次数设3到5次。加退避就是每次重试的间隔递增比如1秒、2秒、4秒、8秒给服务端喘息的时间。import time def encode_with_retry(image_bytes, max_retry5): for i in range(max_retry): try: return encode_image(image_bytes) except Exception as e: if 429 in str(e) and i max_retry - 1: time.sleep(2 ** i) continue raise这个指数退避的模式是处理限流的标准做法几乎适用于所有API。6.4 向量矩阵与路径列表错位的灾难性后果这个坑的后果是搜索结果张冠李戴搜出来的图跟你点开的图不是同一张。原因是向量矩阵和路径列表的顺序不一致了比如你删了矩阵的第5行但没删路径列表的第5个。预防办法是把两个结构绑在一起操作增删都写成一个函数内部保证同步。另外每次启动时做个校验检查矩阵行数和路径列表长度是否相等不等就报警。assert len(paths) db_matrix.shape[0], 向量与路径数量不一致这行断言看着简单但能救命。我建议放在程序启动的必经之路上。7. 后续可以怎么扩展7.1 以图搜图同一套向量换个查询入口既然图片已经编码成向量了那以图搜图就是顺手的事把查询图片编码成向量然后走同样的相似度计算流程。不需要任何额外的基础设施只是查询入口从文本换成图片而已。这个功能找相似构图、找同一场景的不同角度特别有用。7.2 结合元数据的混合检索纯语义检索有时候不够精确比如你想找2023年夏天在海边拍的语义部分只能处理海边时间部分得靠元数据过滤。做法是先按时间范围筛出候选集再在候选集里做语义排序。这种混合检索能显著提升精确查询的体验。7.3 本地缓存与离线降级方案服务端方案有个天然风险网络不通或者服务不可用时搜索就废了。一个务实的做法是缓存最近的查询结果网络断了还能看历史。更彻底的做法是本地也部署一个小模型做降级虽然效果差一点但至少能用。这个属于锦上添花看个人需求。我自己在实际操作中的体会是这套方案最大的价值不在于技术多先进而在于它把图库从一个被动的存储变成了一个主动可查询的知识库。以前找图是我记得有那么一张现在是我描述一下它帮我找。这个转变一旦体验过就回不去了。最后分享一个小技巧建库的时候顺便把图片的EXIF时间也存下来搜索时按时间倒序展示这样最近拍的照片会优先出现符合大多数人的使用直觉。