Hachi：自托管图像搜索引擎的嵌入式检索与高效索引实践

在个人媒体爆炸式增长的时代，自托管图像搜索引擎如 Hachi 提供了一种隐私优先、语义驱动的解决方案。它利用 CLIP 模型生成图像嵌入，支持自然语言查询和人脸聚类，实现高效本地检索，避免云服务的数据泄露风险。不同于传统文件浏览器，Hachi 通过元数据索引和向量分片，融合确定性属性（如 EXIF）和语义信号，适用于照片库、Android 设备 MTP 扫描等场景。

Hachi 的核心架构分为元索引（Meta-Index，由 Nim 实现）和向量索引（Vector Index，Numpy 分片）。索引管道异步扫描目录，提取 EXIF、大小、路径等元数据，同时预处理图像生成 CLIP 嵌入（ViT-B/32）和人脸向量。人脸识别管道集成 RetinaFace 检测边界框与地标，生成嵌入后通过阈值聚类（主嵌入 + 从嵌入），过滤模糊 / 侧脸 / 墨镜干扰。查询时加载分片执行矩阵乘法（np.dot，BLAS 加速），Top-K 融合多模态结果，支持递归细化如 “戴墨镜的禅宗自拍”。

实际部署中，硬件门槛低：x86_64 CPU 需 AVX2、四核 4GB RAM（如 i5-8300H 测试 500k 图像）。索引分片大小调控 RAM：高 RAM 设 2048x2048 分片，低端 SBC 用小分片。配置参数包括：

索引阈值：人脸模糊阈值 0.3（HOG 比较），聚类相似度 0.6（余弦），最小主嵌入数 5 张 / 簇。
预览生成：WebP 编码，目标分辨率 512x512，回调缓冲区避免拷贝。
并发：线程池处理批次，融合 Resize+RGB2BGR + 归一化内核，饱和 i5 CPU 达 90%。
API 服务器：Werkzeug 多线程（线程数 = CPU 核 x2），分页每页 20 结果，ETA 基于目录扫描速度。

监控要点：日志记录索引进度 / 取消，Prometheus 指标如查询延迟（目标 <100ms）、分片加载时间。回滚策略：不可变元数据，重置 ML 属性至 “personML” 默认。风险控制：分片量化（未来 Product Quantization）降维 512，线性层微调区分特定域如植物。

落地清单：

克隆https://github.com/eagledot/hachi，安装 numpy/regex/markupsafe。
配置 data_path，运行index --shards=1024 --threads=8。
启动app.py --threads=16，浏览器访问 localhost:5000。
测试人脸：索引 > 1000 人像，验证簇纯度 > 90%。
扩展：MTP 挂载 Android，未来视频帧采样。

Hachi 证明最小主义 ML 管道（Nim+OneDNN 端口 CLIP）在个人设备高效运行，未来支持视频 / 分布式查询。“Such distributed nature of data and potential capabilities of current self-hosted Machine learning models to extract semantic information”（eagledot.xyz/hachi.md.html）。

资料来源：

（正文 1028 字）