个人数据囤积日益严重，从硬盘到手机的分布式图像库亟需高效搜索。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。
部署参数：一步到位
- 环境：Python3，pip install numpy regex markupsafe [requests]。x86_64/AVX2/4GB+。
- 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。
- 索引：
python index.py --path /mnt/photos --android-mtp（USB 手机）。中断续传，ETA API /status。
- 启动：
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）。"