最近我在整理自己的照片和截图时，越来越受不了两件事：
- 文件名搜索基本没用，很多图根本不记得叫什么。
- 我不想把私人相册再传到云端去换一个“智能搜索”。
所以我做了一个本地优先的开源工具：SemanticGallery。
它的目标很直接：给一个本地图片文件夹，用自然语言就能搜图；如果你手里已经有一张图，也可以继续找相似图。整个过程默认只在本机跑。
GitHub： github.com/yongyaoduan…
Demo GIF：
本文目录
- 为什么做这个工具
- 它现在能做什么
- 它底层是怎么工作的
- 怎么跑起来
- 当前限制
- 开源地址和下一步计划
为什么做这个工具
我自己的图库很混杂。
- 有手机拍的生活照片
- 有大量微信、淘宝、知乎、网页、聊天记录截图
- 还有一些“我明明记得见过，但完全不记得文件名”的图片
这类需求用传统的文件名搜索非常弱，但如果能直接搜“微信聊天截图”“健身照片”“淘宝截图”“相机拍摄的日常照片”，体验会自然很多。
另外还有一个现实问题：这类图库很多都是私人内容。我不太想为了获得“语义搜索”能力，把自己的图片先上传到某个云服务。
于是就有了 SemanticGallery 这个项目。
它现在能做什么
我现在主要拿它处理这些场景：
- 找“微信聊天截图”
- 找“知乎截图”
- 找“淘宝截图”
- 找“健身照片”
- 找“练车照片”
- 找“相机拍摄的日常照片”
- 从一张现有图片继续找相似图片
目前已经做好的能力：
- 支持自然语言搜图
- 支持上传一张图片做以图搜图
- 支持在图库里继续找相似图片
- 支持浏览器里预览大图
- 支持查看文件路径和时间元数据
- 支持批量选择和永久删除
- 默认只监听
127.0.0.1
对我来说，最有价值的不是“找到一张很好看的照片”，而是把那些本来很难找回来的截图和随手拍重新找回来。
为什么它是“本地优先”
这个项目从一开始就不是“先把图传云端，再帮你搜”。
默认情况下：
- 私有图片不会离开本地磁盘
- Web 服务只绑定
127.0.0.1 - 真正和你私人图库相关的编码、索引和检索都在本机完成
联网主要发生在首次准备环境的时候：
- 下载 Python 依赖
- 下载 MLX SigLIP2 基础模型
- 下载已发布 checkpoint
- 下载一个很小的公开参考集
换句话说，真正和你图库内容相关的部分，是本地完成的。
它底层是怎么工作的
为了让查询速度足够快，我没有走“每次搜索都全量扫图库”的路子，而是拆成了两条路径。
1. 离线路径：先把图库编码成可搜索的本地索引
- 扫描目标文件夹里的图片
- 用
SigLIP2视觉编码器把图片转成 embedding - 把 embedding、路径列表和搜索配置写到本地
- 后续查询直接在这份本地索引上完成
2. 在线路径：查询时只做一次文本或图片编码
- 文本查询时，把一句话编码成 query embedding
- 图片查询时，把上传图片编码成 query embedding
- 再和本地图库 embedding 做向量检索
- 最后在 Web UI 里返回缩略图、路径、时间等信息
运行时我选的是 Apple Silicon 上的 MLX 路线。
开发记录里，在一台 MacBook Air M4 / 32GB 上，MLX bfloat16 的部署查询平均延迟大约是 9.02 ms / query。
注：这是开发阶段的参考记录，不同机器和图库规模会不一样。
另外我还加了一步很短的 gallery-specific adaptation：
首次运行时，会从目标图库里采样最多 100 张本地图，做一次非常短的本地适配，尽量让模型更贴近你自己的图库分布，尤其是照片和截图混合的场景。
怎么跑起来
项目现在还是 source-first 方案，还没有打成现成安装包。
直接跑：
GALLERY_DIR=/absolute/path/to/gallery ./scripts/quickstart.sh
第一次运行会做这些事：
- 创建本地 Python 环境
- 下载 MLX 基础模型
- 下载已发布的 Stage 1 checkpoint
- 下载小型公开参考集
- 扫描目标图库
- 做一次短暂的本地适配
- 构建本地索引
- 启动 Web UI
默认地址：
http://127.0.0.1:36168
当前限制
- 目前只支持 Apple Silicon
- 第一次启动会下载依赖和模型，所以会慢一些
- 删除是永久删除，不是移到回收站
- 图库文件新增或变化后，需要用
FORCE=1重新构建索引 - 现在还是源码启动优先，安装体验还可以继续做
开源地址
GitHub： github.com/yongyaoduan…
如果你也有“本地照片和截图越来越多，但又不想把相册上传云端”的需求，欢迎试一下，也欢迎直接提 issue 或 PR。
如果这篇文章反馈不错，我下一步会优先补这些：
- 更好的增量索引
- 更完整的打包和安装方式
- 更稳妥的删除确认 / 恢复策略
- 更详细的实现拆解文章
