在数字化时代，个人图像收藏迅速膨胀，从手机相册到硬盘备份，用户常常面对海量图片却难以高效检索。传统文件夹分类或云服务搜索依赖手动标签或外部API，不仅隐私风险高，还受网络延迟和厂商政策制约。自托管图像检索引擎如 Hachi 提供了解决方案：完全本地运行，利用机器学习嵌入（embedding）相似度匹配，实现语义级搜索，无需上传数据，保障隐私并支持自定义扩展。这不仅是技术创新，更是回归用户数据主权的实践。
Hachi 的核心在于 embedding-based indexing，利用预训练模型如 CLIP（ViT B/32 变体）将图像转换为高维向量嵌入，这些嵌入捕捉语义特征（如“海滩日落”或“家庭聚会”），而非像素级哈希。索引过程从指定目录递归扫描图像，提取元数据（EXIF、大小、路径）和语义嵌入，同时生成预览缩略图。Meta-Index（用 Nim 语言实现的列式数据库）存储结构化元数据，支持字符串、整数、浮点、布尔和数组类型查询；Vector Index 将嵌入分片存储为 NumPy float32 张量（shard-size 可调），查询时加载分片，使用 np.dot（BLAS 加速）计算余弦相似度或内积，融合 top-k 结果与元数据过滤。该设计避免数据复制，仅索引元信息，原图位置不变，支持分布式扩展（如未来手机集群）。“Hachi 通过 RetinaFace 模型同时预测人脸边界框和地标，实现 25ms 延迟的面部嵌入生成，并经 HOG 特征过滤聚类。” 聚类采用主从嵌入机制：筛选清晰、正脸嵌入为主（过滤模糊、侧脸、墨镜），阈值比较分配从嵌入，支持用户重命名（如 personML → person），处理顺序依赖通过多轮迭代缓解。
此机制高效处理 500k 张 Pexels 数据集，测试于 i5-8300H（8GB RAM），索引异步多线程融合操作（如预处理内核：resize + BGR 转换 + 归一化），减少 I/O。查询支持分页、自然语言（CLIP 文本嵌入匹配）、面部 ID、多属性组合（如“2023 海滩 person:Alice”），前端 HTML/JS 多页应用提供递归细化、ETA 显示、任务取消。后端 Python（Werkzeug）+ Nim 桥接（nimpy），最小依赖（numpy、regex、markupsafe），无 Docker/GIL 瓶颈。
落地部署简单，聚焦 embedding 索引调优：
1. 环境准备（x64 Windows/Linux，支持 Fedora 42+）：
- 安装 Python 3.x，pip install numpy regex markupsafe（可选 requests）。
- 下载二进制：GitHub releases（eagledot/hachi），解压 hachi.exe（Windows）或 hachi（Linux，libc 2.27+）。
- C 编译器（zig-cc 跨编译可选），无 GPU 需求，但 AVX2+ 推荐。
2. 快速启动：
./hachi index --path /photos --shard-size 2048 # 索引目录，分片大小（RAM 调优：低配 1024，高配 4096）
./hachi serve --port 8080 # 启动 API+Web，访问 localhost:8080
- Android MTP 索引：连接设备，UI 选择路径，支持多设备。
3. 参数调优清单：
| 参数 |
默认 |
建议 |
作用 |
| shard-size |
2048 |
低 RAM:1024; 高:8192 |
平衡加载延迟与内存，测试 2048x2048 matmul 基准设备容量 |
| face-threshold |
0.6 |
0.5-0.7 |
聚类相似度，迭代调优个人数据集 |
| blur-score |
50 |
30-70 |
过滤模糊脸，HOG + 地标对齐 |
| top-k |
50 |
20-100 |
初始召回，元数据后滤 |
| preprocess-kernel |
fused |
- |
启用融合（resize+norm），加速 20-30% |
4. 监控与回滚：
- UI 日志：扫描进度、ETA、错误（e.g., 权限/损坏文件）。
- 指标：查询延迟（<100ms/查询）、索引吞吐（GB/h，根据 CPU）。
- 回滚：
hachi reset --schema，重置不可变 ML 属性（personML 等）。
- 风险：硬件限（<4GB RAM 分片溢出），阈值主观（多数据集验证）；本地模型无云 SOTA，但隐私优先，可 fine-tune 线性层（e.g., 植物区分）。
扩展：未来 shards 分布式（手机分担 matmul），产品量化（PQ）加速亿级向量。Hachi 证明最小主义自托管可媲美商用，适用于摄影师、家庭相册、安防本地库。
资料来源：