hnswlib / Annoy / ScaNN 向量数据库手册

适用版本：hnswlib v0.9.0（2026-03-28）/ Annoy 1.17.3（2023-06-14）/ ScaNN 1.4.2（2025-08-29，PyPI），核实于 2026-11 许可与形态：开源索引库（hnswlib / Annoy 官方 LICENSE 正文未核验、ScaNN 许可官方资料未提供，见第 11 章）；嵌入式 / 进程内索引库，不是数据库 一句话定位：三个都只负责「建索引 + 算 top-k」，持久化、并发、鉴权、CRUD、分布式、元数据过滤全部由调用方自己实现 约定：$ 普通用户、# root 或 sudo、<xxx> 为占位符；标 ⚠️ 的是高危操作。 更新时间：2026-11（版本与 API 变化快，执行前请以官方文档复核）

目录

1. 它是什么、什么时候选它
2. 版本、许可与官方入口
3. 安装与启动
4. 核心概念与数据模型
5. 快速上手：完整 CRUD 示例
6. 索引与检索进阶
7. 生产部署与运维
8. 高频故障与排障
9. 常见坑与避坑清单
10. 速查表
11. 参考与延伸

1. 它是什么、什么时候选它

1.1 三库一句话定位

1.2 核心命题：索引库不是数据库

三者都是进程内库：没有守护进程、没有网络端口、没有存储引擎、没有用户体系。你灌进去向量，它给你 top-k 的距离/相似度与下标。检索链路里它们只占中间一格：

避坑：官方资料明确的共同坑是「无网络服务、无持久化管理、无权限与并发控制」。把这三个库当数据库用，是选型阶段最该避免的错误 —— 它们甚至连「单条改完立即生效」都不保证（Annoy build 后只读，改一条要重建）。

1.3 横向对照表（一）：定位 / 维护状态 / 许可 / 平台支持 / 增量写

表中「通常可跨平台」「通常建好后以批量检索为主」为经验性表述，非官方结论；许可与 ScaNN 增量写能力见第 11 章未核实清单。

1.4 适合 / 不适合

适合：离线批量建索引与召回评测；数据量能装进单机内存且少变；作为自研检索系统的 ANN 内核；读多写少（Annoy 尤其）；需要 HNSW 增量插入与删除标记（hnswlib）；Linux x86 平台上做高精度量化检索（ScaNN）。

不适合：多进程 / 多机并发写与事务一致性；按标量字段做服务端 pre-filter；单条即时删除 / 更新且马上生效；账号、权限、审计、TLS、多租户；崩溃自动恢复、弹性扩缩容、SLA 与告警；数据量超单机内存或需要分片副本；macOS / Windows 上想用 ScaNN；依赖活跃维护与快速安全响应（Annoy 已停滞）。

1.5 规模与链路位置（经验值，非官方承诺）

三者只承担「候选召回」：离线灌 embedding，在线取 top-k 下标，再回到自己的事实源取回文本与元数据做后过滤、重排、拼 prompt。RAG 的文档管理、增量更新、权限过滤全在库之外。

⚠️ 危险：把返回的下标当业务 ID 用，一旦做过删除、重排或重建，下标会整体错位，召回会静默串到错误文档。必须维护稳定的「下标 ↔ 业务 ID」映射，并在每次重建时同步重建。

1.6 什么时候该换真数据库（选型视角判断线）

出现任意一条且无法接受自研成本，就应改用真正的向量数据库或托管服务：

2. 版本、许可与官方入口

2.1 版本状态表

版本差异：三条版本线互不相干，不要横向比大小、也不要混用「SDK / 服务端 / 格式」版本号；官方资料未提供更早的发布史。

2.2 许可与商业边界

• hnswlib / Annoy：官方 LICENSE 正文未核实（见第 11 章），许可名称与条款以官方仓库为准；ScaNN 许可官方资料未提供，同样以官方为准。
• 三者都是开源研究型 / 工具型库，无「企业版 / 商业特性」分层。真正的成本在你要自己补齐的整套数据库能力，而非授权。
• 许可变更史官方资料未提供，以官方仓库为准。

2.3 官方入口表

官方资料只给出以上三个入口；官网 / 文档站 / 镜像仓库地址未提供，以官方仓库导航为准，本篇不臆造 URL。

2.4 版本识别与近两年变更

无服务端 --version。用 Python 侧自检能否 import（包名以 PyPI 为准）：

$ python -c "import hnswlib; print('hnswlib ok')"
$ python -c "import annoy; print('annoy ok')"
$ python -c "import scann; print('scann ok')"

版本差异：ScaNN 自 1.4.0 起 TensorFlow 集成需 pip install scann[tf]；ScaNN 仅 Linux manylinux_2_27 x86-64 / aarch64 wheel；Annoy 已停滞并有继任者 Voyager；hnswlib 0.10.0-rc.2 是预发布。以上均为官方资料明确事实，别照抄旧教程的「默认就带 TF 集成 / 全平台可装」。

3. 安装与启动

3.1 前置条件与形态

Python 环境；向量一般需转 float32（经验性，以各库官方文档为准）。无服务端、无端口、无守护进程，「启动」= 在进程里 import 并构造索引对象。

3.2 方式一：pip（三库分小节）

hnswlib

$ pip install hnswlib

Annoy

$ pip install annoy

ScaNN

$ pip install scann
# 1.4.0 起 TensorFlow 集成需额外装
$ pip install scann[tf]

避坑：pip install hnswlib / pip install annoy 为按包名给出的通用安装命令，包名与 wheel 可用性以 PyPI 为准。ScaNN 的 scann[tf] 是官方资料明确的可选依赖，不要与基础包混为一谈。

3.3 方式二：平台前置检查（ScaNN 必做）

ScaNN 有硬平台限制，装之前先确认，避免白装：

import sys
import platform
assert sys.version_info >= (3, 9), "ScaNN 需 Python >= 3.9"
assert platform.system() == "Linux", "ScaNN 仅提供 Linux wheel"
print("平台前置检查通过：", platform.system(), platform.machine(), sys.version.split()[0])

避坑：x86 还需 AVX+FMA，可用 grep -m1 -o -E 'avx|fma' /proc/cpuinfo 粗查（经验性，以实测为准）。hnswlib 为 header-only C++（官方资料明确），可直接包含头文件；Annoy / ScaNN 的源码构建命令官方资料未给出，以各自官方仓库为准，本篇不臆造编译参数。

3.4 目录与端口表 / 健康检查 / 生产最小配置

4. 核心概念与数据模型

4.1 术语对照表

4.2 数据模型层级

三者都没有集合 / 数据库 / 字段 / schema 层级，只有向量矩阵 + 可选下标；「表」由调用方的 records 列表或外部数据库承担。hnswlib 支持过滤，但仍是进程内能力，不等于服务端标量查询。

4.3 距离度量与方向

官方资料未给出三库距离度量的完整枚举与参数名，以下为通用原理（经验性表述），具体取值与「值越大越相似还是越小越相似」以各库官方文档为准：L2 / 欧氏类距离越小越相似；内积 / 余弦类相似度越大越相似。查询时度量必须与建索引时一致，否则结果无意义。

4.4 横向对照表（二）：许可 / 平台 / 数据模型 / 增量写 / 维护状态

4.5 写入 → 建索引 → 可检索的生命周期

避坑：Annoy 的「build 后只读」是硬约束。官方资料明确「改一条要重建」，不要指望增量更新。

5. 快速上手：完整 CRUD 示例

说明：三者都没有「连接 / 表 / CRUD」概念，且官方资料未提供三库逐字的 API 方法名与参数名。为避免臆造，本篇以一段等价的、完整可运行的 numpy brute-force 基线示范「调用方必须自己维护的胶水层」—— 索引库只替换其中「相似度检索」一步；各库具体调用以官方文档为准（见第 11 章）。

5.1 完整可运行示例：调用方胶水层基线（Python）

import numpy as np

d = 4  # 示例用 4 维，实际常见 768 / 1024 / 1536
records = [
    {"id": "doc-0", "text": "三国演义", "category": "history", "vec": [0.1, 0.2, 0.3, 0.4]},
    {"id": "doc-1", "text": "红楼梦",   "category": "history", "vec": [0.1, 0.2, 0.3, 0.5]},
    {"id": "doc-2", "text": "三体",     "category": "scifi",   "vec": [0.9, 0.1, 0.2, 0.1]},
    {"id": "doc-3", "text": "流浪地球", "category": "scifi",   "vec": [0.8, 0.1, 0.2, 0.2]},
]

def build_matrix(rows):
    """C = 建集合 / U = 插入：索引库只吃数值矩阵，业务字段自己留着"""
    return np.asarray([r["vec"] for r in rows], dtype="float32")

def brute_topk(xb, query_vec, k):
    """R：精确 top-k 基线（hnswlib 自带 brute-force；另两库把这里换成自己的索引）"""
    xq = np.asarray(query_vec, dtype="float32")
    dist = np.sum((xb - xq) ** 2, axis=1)   # 平方 L2，越小越相似
    return [(int(i), float(dist[i])) for i in np.argsort(dist)[:k]]

def search_with_filter(xb, rows, query_vec, category, k):
    """带标量过滤检索：取回候选后自己按元数据后过滤"""
    return [(rows[i]["id"], rows[i]["text"], dist)
            for i, dist in brute_topk(xb, query_vec, k)
            if rows[i]["category"] == category]
xb = build_matrix(records)                       # 连接（无）+ 创建集合 + 插入
print("已灌入行数 =", len(records))
print("R 精确 top-2 =", brute_topk(xb, [0.1, 0.2, 0.3, 0.45], 2))
print("过滤 history =", search_with_filter(xb, records, [0.1, 0.2, 0.3, 0.45], "history", 4))
# U：更新（无行级 update，改事实源后重建矩阵；Annoy 还要重建整个索引）
records[1].update(text="红楼梦（修订）", vec=[0.1, 0.2, 0.3, 0.55])
xb = build_matrix(records)
print("更新后检索 =", search_with_filter(xb, records, [0.1, 0.2, 0.3, 0.55], "history", 2))
# D：删除（从事实源移除，再整表重建；hnswlib 的删除标记不是物理删除）
records = [r for r in records if r["id"] != "doc-3"]
xb = build_matrix(records)
print("删除后剩余行数 =", len(records))
# 清理 / 持久化：三库都不托管，Annoy 只有 mmap 静态文件，其余由调用方导出
np.save("vectors.npy", xb)
print("已写出 vectors.npy；索引文件与事实源必须一起备份")

5.2 输出怎么读

R 精确 top-2 的 i 是 add 矩阵行下标（不是业务 ID），dist 是平方 L2、越小越像；过滤 history 是后过滤结果 (业务ID, 文本, 平方L2)；删除后剩余行数 是事实源行数，重建后旧下标全部失效。

避坑：把下标当业务主键是三库通用的错。Annoy 只有 mmap 静态索引文件、hnswlib / ScaNN 无持久化管理，业务字段永远在你自己的事实源里。

5.3 按子产品分小节：接入生命周期

5.3.1 hnswlib：header-only C++/Python，只做 HNSW + brute-force；支持增量插入 / 删除标记 / 过滤，是三者中唯一明确可增量写的。适合需要在进程内持续追加数据的场景。删除是标记而非物理删除，需自己管标记集合与重建时机。

5.3.2 Annoy：Spotify 随机投影树，mmap 只读静态索引，读多写少。逐条加入后 build，build 之后只读；官方资料明确「改一条要重建」。适合索引基本不变、靠 mmap 低内存加载的离线召回。

5.3.3 ScaNN：Google Research，各向异性量化 + 分区树 + 精确重排；仅 Linux manylinux_2_27 x86-64 / aarch64 wheel（x86 需 AVX+FMA），Python ≥3.9，1.4.0 起 TF 集成需 pip install scann[tf]。平台前置检查见第 3.3 节。官方资料未提供官方 Python 最小接入代码，逐字 API 以官方文档为准（见第 11 章）。

避坑：官方资料未提供三库逐字的 API 方法名与参数名，本篇不臆造。上面第 5.1 节的 numpy 基线是可运行的等价实现；上线前请把「相似度检索」一步替换为对应库的官方调用，并以官方 README / 文档核对参数。

6. 索引与检索进阶

6.1 横向对照表（三）：调优 / 平台 / 增量写 / 维护状态

6.2 索引参数调优表（概念层）

官方资料未给出三库逐字的参数名、默认值与推荐范围，本表为概念性经验表述，不是官方结论；具体参数以各库官方文档为准（见第 11 章）。

6.3 召回 / 延迟 / 过滤 / 混合检索

• 候选规模调大 → recall 上升、延迟上升；建图 / 建树规模调大 → 召回上升、内存与构建时间上升。没有统一最优值，必须用自己的数据压测 recall@k 与 p99。
• 三者都没有服务端标量过滤：hnswlib 的过滤是进程内能力，Annoy / ScaNN 更需调用方自己后过滤（第 5.1 节演示）。

⚠️ 危险：后过滤会让返回条数变少。k 取小、过滤条件又很 Selective 时可能一条不剩。生产上要么放大 k 再截断，要么换支持 pre-filter 的向量数据库。

• BM25 + 稠密混合、RRF 融合、稀疏向量、重排都要在外部自己实现 —— 同样是「索引库不是数据库」的直接后果。

6.4 量化与压缩

ScaNN 的核心就是各向异性量化 + 分区树 + 精确重排（官方资料明确）：用量化压缩候选、再用精确计算重排补回精度。Annoy 的 mmap 静态索引走的是随机投影树 + 只读内存映射。hnswlib 以 HNSW 图为主、另有 brute-force 基线。量化必然有召回损失，上线前必须用精确基线（第 5.1 节）算 recall@k。

6.5 内存与磁盘容量估算

• 原始向量矩阵：n × d × 4 字节（float32 每元素 4 字节），再加索引结构开销。例：1,000,000 × 768 × 4 ≈ 2.86 GiB，这只是原始向量，HNSW 图 / 投影森林 / 量化码字另算。
• Annoy 的 mmap 静态文件常可只读映射、按需换页，进程常驻内存可低于文件尺寸（经验性，以实测为准）。
• 三者都无增量落盘、无 WAL，每次导出都是整份快照。以上为经验估算，以产物大小与 free -m 实测为准。

7. 生产部署与运维

7.1 把边界再讲透：三库不负责什么

⚠️ 危险：多进程同时导出 / 覆盖同一索引文件会互相写坏。落盘要「写临时文件 → 原子改名」，并保留上一版可回滚。

高可用 / 集群 / 分片 / 副本三者原生都不提供，可行做法都是调用方自建：多副本各持只读索引、前置负载均衡、定期全量重建后滚动替换。这与「托管服务买的是运维责任转移」形成鲜明对比 —— 这里责任全在你（对比见 04 分册）。

7.2 什么时候该换真数据库（运维视角判断线）

第 1.6 节是选型视角，这里是上线前自检：任一问答「是」就别硬撑索引库。

7.3 备份与恢复（索引是否需要重建）

避坑：不要只备份索引文件。没有事实源，你无法把返回下标还原成业务记录，等于数据丢了。

7.4 监控指标与告警阈值建议 / 容量与升级

三者无 /metrics 端点，需在服务层埋点：

按第 6.5 节公式估算内存并预留索引结构与峰值余量；扩缩容 = 重建索引 + 换机器 / 换副本，无在线弹性。升级：固定 pip 版本，升级前用同一份数据跑 recall 对比；索引文件跨版本兼容性官方资料未提供说明，稳妥做法是升级后用事实源重建索引；ScaNN 升级还要核对 Linux wheel 与 AVX/FMA 依赖。

版本差异：ScaNN 1.4.0 起 TF 集成需 scann[tf]；hnswlib 0.10.0-rc.2 是预发布；Annoy 已停滞并有继任者 Voyager。别照抄旧教程的默认行为。

7.5 安全基线与日志

无自带日志，统一打到业务服务日志。系统级服务管理（systemd / 防火墙等）属通用运维，见根目录手册，本篇不重复。

8. 高频故障与排障

9. 常见坑与避坑清单

1. 现象：把三者当数据库，直接拿返回下标当业务主键。原因：返回的是 add 矩阵行下标。怎么做：自己维护「下标 ↔ 业务 ID」映射，删改后同步重建。
2. 现象：Annoy 改一条数据后结果不变。原因：build 后只读，改一条要重建。怎么做：全量重建 + 原子替换，别做增量幻想。
3. 现象：macOS / Windows 上 pip install scann 失败。原因：仅 Linux manylinux_2_27 x86-64 / aarch64 wheel。怎么做：第 3.3 节先查平台，或换跨平台库。
4. 现象：ScaNN 在老 x86 CPU 上崩或报指令错。原因：x86 需 AVX+FMA。怎么做：查 /proc/cpuinfo，换满足指令集的机器。
5. 现象：ScaNN 的 TensorFlow 集成用不了。原因：1.4.0 起需 pip install scann[tf]。怎么做：补装可选依赖，别照抄旧教程「装了就有」。
6. 现象：hnswlib 删除后旧向量仍被召回。原因：是删除标记，非物理删除。怎么做：自己维护标记并在结果层过滤，累积后重建。
7. 现象：照旧教程以为有服务端 / /health。原因：三者无网络服务、无权限与并发控制。怎么做：服务层自建健康检查与鉴权。
8. 现象：以为索引会自动持久化、崩溃能恢复。原因：Annoy 只有 mmap 静态文件，另两库无持久化管理。怎么做：自己导出 + 版本化 + 备份，且事实源一起备。
9. 现象：只备份索引文件，恢复后拿不回文档。原因：业务字段本就不在库里。怎么做：索引文件与事实源一起备份，否则等于数据丢失。
10. 现象：上了量化后召回明显掉。原因：量化是有损的。怎么做：用第 5.1 节精确基线算 recall@k，调候选规模 / 重排后再上线。
11. 现象：带 category 过滤后一条不返回。原因：无服务端标量过滤，只能取回 top-k 后自己后过滤。怎么做：放大 k 再截断；高选择性过滤换 pre-filter 库。
12. 现象：多进程同时导出把索引文件写坏。原因：无 WAL、无文件锁、整份覆盖写。怎么做：⚠️ 写临时文件 → 原子改名，保留上一版可回滚。

⚠️ 危险：第 9、12 条可能导致线上数据丢失；第 1、6 条会产生长期静默的错误召回结果，上线前必须做恢复演练与 recall 回归。

10. 速查表

10.1 横向对照表（四）：速查版

10.2 操作速查表

常用端口与路径小表

11. 参考与延伸

11.1 官方文档链接清单

官网 / 文档站 / 镜像仓库地址官方资料未提供，以官方仓库导航为准，本篇不臆造 URL。

11.2 与本册其他产品的关系

• 同属「向量索引库（不是数据库）」：Faiss.md，四库选型对照见两篇的横向对照表。
• 出现第 1.6 / 7.2 节任一判断线时，改用真向量数据库：Milvus / Qdrant / Weaviate / pgvector（见对应分册）。
• 想买「运维责任转移」而非自建，见 04 分册：Pinecone.md、Zilliz-Cloud.md、国内云向量数据库.md。

11.3 进阶阅读方向

HNSW / 随机投影树 / 各向异性量化的原理与召回-延迟取舍；以精确基线为 ground truth 的 recall@k 评测方法学；mmap 静态索引的只读发布与原子替换；从索引库迁移到支持 pre-filter / 删除 / 分布式向量库的改造路径；Annoy 继任者 Voyager 的评估。

11.4 本篇「未核实 / 以官方为准」事项