Hotdry.
归档
ai-systems

Hachi 自托管图像搜索引擎：嵌入相似检索、自定义索引与 web 查询接口

剖析 Hachi 自托管图像搜索的核心：CLIP 嵌入向量分片索引、RetinaFace 面部聚类、Nim 元索引，附 Docker 部署、阈值调优与性能监控清单。

个人数据囤积日益严重，从硬盘到手机的分布式图像库亟需高效搜索。Hachi（github.com/eagledot/hachi）作为开源自托管搜索引擎，正好填补空白。它专注图像相似检索，使用 CLIP ViT-B/32 生成语义嵌入，支持自然语言 / 文本 / 图像查询，未来扩展视频 / 音频。核心优势：零数据复制，仅索引路径 / 嵌入，隐私本地运行，轻量依赖（numpy/regex），跨 Windows/Linux，支持单板机。[1]

架构剖析：双索引 + ML 管道

Hachi 分 Meta-Index（Nim 列式 DB）和 Vector-Index（NumPy 分片）。

  • Meta-Index：单线程 JSON 接口，支持 string/int32/float32/bool/array。提取 EXIF / 大小 / 路径 / Mount，无 schema 变更重索引成本。辅助索引加速列查询，未来多线程 / SIMD。
  • Vector-Index：嵌入分片（float32 张量），查询 np.dot (BLAS) top-k。分片调 RAM：低端 1K，高 4K 向量 / 分片。
  • ML 管道：异步批处理融合预处理（resize/BGR/normalize），stb_image/libwebp 生成 256x256 预览。RetinaFace 一体检测面 / 地标，HOG 过滤模糊 / 眼镜 / 侧脸（像素比 > 0.7），嵌入聚类（余弦 > 0.85，主嵌入稳定簇）。[2]

索引 500k 图（180GB Pexels）基准 i5-8300H/8GB：>1000 文件 / 秒，查询 < 100ms。HN 社区反馈：响应如商用，易 hack。

部署参数：一步到位

  1. 环境：Python3，pip install numpy regex markupsafe [requests]。x86_64/AVX2/4GB+。
  2. Docker（推荐）： 
    git clone https://github.com/eagledot/hachi
cd hachi
docker build -t hachi .
docker run -p 5000:5000 -v /data/images:/data hachi index --path /data
    卷挂载数据，--batch=64 CPU 饱和，--preview=256。
  3. 索引：python index.py --path /mnt/photos --android-mtp（USB 手机）。中断续传，ETA API /status。
  4. 启动：python server.py，web http://localhost:5000，支持分页 / 取消。

阈值清单：

参数 默认 调优建议 场景
分片大小 2048 低 RAM:1024，高：4096 平衡延迟 / RAM
面检阈值 0.5 >0.6 严谨 模糊环境
聚类相似 0.85 0.8-0.9 簇纯度
top-k 50 20-100 召回 / 精度
HOG 滤波 0.7 0.6 宽松 眼镜 / 侧脸

查询接口：多模融合

Web UI：拖图 / 文本 “beach sunset”，融合向量 top-k + 元过滤（日期 / 人）。面搜索：personML（ML 簇）/person（用户编辑），回滚 immutable。扩展：/ext/android/setup MTP。

性能监控：

  • 指标：/metrics（Prometheus）：线程饱和、IO bps、查询 p95<200ms、RAM<80%。
  • 警报：索引卡顿 > 1min 重启，OOM 日志 debug。
  • 基准：10M 图单节点，SSD 加速分片载入。

风险与回滚

  • 风险：大库 OOM（>50GB RAM），分批 --max-batch=32；ARM float16 未优（Intel BLAS 90% 峰值）。
  • 回滚：reset_meta --field=embeddings，重聚类无损原图。
  • 扩展：PQ 量化检索，线性微调 CLIP（OpenAI cookbook），分片集群手机。

Hachi 诠释最小主义 AI 系统：~3 依赖，纯源无 Docker 强制，hackable（Nimpy 桥）。对比 HomeGallery（浏览器端 TFJS），Hachi 服务端高效，语义强。落地摄影师 / 设计师，参数调优即产出。

资料来源： [1] eagledot.xyz/hachi.md.html：详细管道 / 哲学。 [2] HN：news.ycombinator.com/item?id=...（Hachi 帖，10+ points）。"

查看归档