🏠 总目录📚 本教程 10 · 向量检索 ANN ← →
📑 本页目录(点开跳转)

10 · 向量检索与 ANN

推荐算法 / 10

ANN 快了以后,究竟漏掉了什么?

先固定相似度与精确对照,再看近似索引、候选与评估协议;原图和独立 NumPy 入口保留。

能按质量、时延、内存比较索引,并明确什么才算真近邻。

⏱ 主线阅读约 20 分钟 | ⭐ 核心 | 🔨 有代码;代码实验另留时间

🎯 一句话

向量检索先定义“更相似”,再在质量、延迟和内存之间做取舍。ANN 是近似最近邻搜索:用较少搜索工作换取可能漏掉真近邻的风险;Flat 则是精确对照。

把问题具体化:已有用户向量与 1 亿个 64 维物品向量,想在 10 ms 预算内取 top-1000。这里的预算是例子,不是本章程序已经达到的性能。

先看相似度与算账;想动手可直达两个独立索引例子;已有索引但不会比较,去评估协议与独立 NumPy 入口。

查询示意:先找下一层入口,再从底层候选中取 top-k 一维节点值为A=0、C=4、F=7、H=9、J=12,距离为节点值与q=8.2之差的绝对值。上层邻接表人为设置,橙色是上层贪心移动及同ID下沉,蓝色是底层发现邻居。最终候选H、F、J,返回k=2的H、F。本例不证明近似搜索总能找到全局最近。 先找入口,再从候选里选结果 查询 q = 8.2距离 = |节点数值 − 8.2|  k = 2,底层 ef = 3 L2L1L0 ① 先沿邻边从 A 到更近的 J ② 中层从 J 到 F,再以 F 进入底层 ③ 底层沿邻边发现候选 同一个 J 同一个 F AJ AFJ ACFHJ 值 0值 4值 7值 9值 12 距离 8.2距离 4.2距离 1.2距离 0.8距离 3.8 发现过 F、C、H、J;ef = 3 最终保留 H、F、J。 C 曾进入候选,后来被更近的 J 替换;ef 不是“访问次数”。 从保留候选取 k = 2 个:H(0.8)、F(1.2)
看橙色的同名下沉,再看底层蓝色的候选发现。邻接关系是人为构造的教学示意,不是完整 HNSW 建图或性能实测;本例返回 H、F,不代表 ANN 对所有查询都保证全局 top-k。

先定相似度,再看计算成本

最大内积检索(MIPS)按原始点积取分数最大的物品,不等于必须归一化。模型若使用原始点积打分,物品向量的长度可能就是分数的一部分;改成单位向量会改变目标。只有明确要比较余弦相似度时,才把非零向量单位化后做内积检索。

单位化就是把每个向量除以自己的长度,让长度变成 1、方向不变。

同一个查询 q=(1,0):归一化可以改变赢家
物品向量原始点积余弦相似度
A=(2,2)2,原始内积赢家约 0.7071
B=(1,0)11,余弦赢家

读这个反例:单位化不是不会改变答案的“清洗”。本章后面的两个索引例子都明确选择 cosine;Faiss 通过单位化向量加 IP 实现,hnswlib 通过 cosine 空间查询。

对两个单位向量,平方 L2 距离等于 2 − 2 × 内积,所以精确排序对应;Faiss 的 L2 接口返回平方距离,越小越近,IP 越大越相似。Faiss 的距离约定。

量化重建向量未必仍是单位向量,不能把精确排序关系直接外推成 PQ 的 L2/IP 结果相同。

零向量的余弦没有定义,本章代码会明确拒绝,而不是假装归一化后就能正常比较。

暴力检索的算账:只算一遍点积,不猜墙钟时间
计算项1 亿物品、64 维时尚未包含
乘法1 亿 × 64 = 64 亿次每个点积中的求和
逐项加法1 亿 × 63 = 63 亿次top-1000 选择、访存和通信
原始向量负载1 亿 × 64 × 4 字节 = 25.6 GB索引、ID、工作区;此处 GB 为十进制

单核、SIMD、批处理、多线程、GPU 和内存带宽都会影响实际时间;不能只凭上述次数就说“几秒钟”或“快 1000 倍”。是否值得建 ANN,还要看查询次数能否摊销建库成本。

近似不是免费漏召回。ANN 可能漏掉重要候选,不承诺只漏排名靠后的物品。粗排和精排只能处理已经召回的集合,不能恢复没进入候选的物品;“损失 1–5% 换 100–1000 倍速度”不能当成通用保证。

🗺️ 四种常用检索构件:可以组合,不是四选一

先认识各自负责什么,再谈选型
构件减少哪种成本代价与边界
① Flat:精确基线不建复杂搜索结构,直接比较全部向量搜索工作随数据量增加;小库或查询次数少时值得先试。精确近邻不等于业务推荐正确率 100%。
② IVF:聚类与倒排把物品分到桶,只访问选中的若干桶可能漏掉未访问桶里的近邻。IVF-Flat 仍存原始向量与 ID,并不自动压缩它们。
③ HNSW:分层图搜索沿邻接关系找候选,避免全库逐项比较建图有成本,图也占内存;实际召回率和延迟必须测试。
④ PQ / OPQ:量化PQ 将向量分成子空间,以码本编号存储;OPQ 先学习有利于量化的变换引入重建/距离估计误差。可与 IVF 组合为 IVF-PQ;8 字节只是此处选定配置的编码本体。

例如把 1 亿个向量分成 4096 个簇,再查若干簇,是一种 IVF 设置,并非所有规模都应使用 4096。nlist 决定桶数,nprobe 决定本次访问多少桶;桶也不保证等大。下方小例使用 64 个桶,避免直接启动百万点训练。

🕸️ HNSW:图解「多层高速公路」

上层是下层节点的稀疏子集;下沉时仍是同一个节点。高层先沿边寻找更近的入口,再在更密的层继续搜索。这个“更近”是搜索已访问邻居时的比较,不是保证找到该层全局最近点,也没有每层固定缩小一圈半径的规则。

层级身份:同一个字母,代表同一个向量 顶层2个节点、中层6个节点、底层26个节点。特别追踪T:它出现在L1和L0,没有出现在L2。虚线表示身份对应,不表示搜索路径。字母的水平间距仅用于排版,不代表向量距离。 同一个字母,代表同一个向量 上层节点必须也出现在下层;虚线只表示身份对应。 L2 · 2 个L1 · 6 个L0 · 26 个 AZ ADKPTZ ABCDEFGHIJKLMNOPQRSTUVWXYZ 例如 T:在 L1 与 L0 是同一个节点;没有进入 L2。 横向位置仅为排版;字母顺序与向量距离、查询顺序无关。
沿 T 的橙色虚线看:同一向量在多层出现,不是降层后变成另一个节点。底层 A–Z 全部画出;为聚焦身份,本图省略层内邻边,不表示空间被逐层划成更小的区域。
三个参数:建图质量与查询成本分开调
参数当前作用本章设置与边界
M控制图连接的规模示例 32;16–48 可作试验起点,不代表所有层每点实际度数恰好 M。更大的图通常更费内存。
efConstruction建图时使用的搜索候选列表规模示例 200;100–500 是可试范围,不是最大跳数。增大可能改善图质量,但也增加构建成本。
efSearch / ef查询时维护的候选列表规模示例 64,覆盖 k=10;上线后可扫这个参数观察近邻 Recall 与延迟。

增删能力要看具体库。hnswlib 支持增量插入、更新既有 ID 和标记删除;标记删除不等于立刻释放全部图内存。Faiss HNSW 的删除支持不同。不能简单概括为“所有 HNSW 都不能增删”。hnswlib 官方接口、参数解释。

🔨 动手:两个索引例子

两个索引例子都使用 12,000 × 64 的随机物品矩阵、32 个查询、k=10、固定种子与单线程;每一整块都可另存为 Python 文件独立运行。第三个代码入口在评估一节,只需 NumPy,用小数组检查评估规则。

CPU 包:Faiss 的 CPU Python 包为 faiss-cpu,是否有匹配的 wheel 取决于 Python 与平台。查看 Faiss CPU 文件。

源码编译:hnswlib 0.8.0 在 PyPI 只有源码包,Windows 安装需要合适的已有 C++ 构建环境。查看 hnswlib 文件。

没有工具链时,可先跳到NumPy 评估入口;不必为了读这一章安装编译器。

GPU 是另一个部署选择:应另查官方支持,不用 pip install faiss-gpu 作通用安装承诺。

工具 1:Faiss(Meta 开发的向量检索库)

用途:同一数据、同一 cosine 目标,对比四个独立实例,并检查保存回读。单位化后的 float32 行矩阵送入所有索引;B 和 D 各自训练自己的桶中心,D 再训练 PQ 码本。这里 M=8、nbits=8 表示 8 个子空间、每个 256 个码字,不是 HNSW 的连接数 M=32。

观察运行时打印的索引名、近邻 Recall 和第一条查询的 ID,以及回读断言是否完成。随机向量没有用户相关性标签;结果不是推荐准确率,也没有测 P99 或一亿规模。不同版本/浮点内核在边界并列处可能不同,不应把单次 ID 列表当固定教材答案。

"""小 CPU cosine 检索例:四个索引、精确基线及保存回读;不是性能基准。"""
from pathlib import Path
from tempfile import TemporaryDirectory
import numpy as np
import faiss


def unit_rows(values):
    """只接受非空、有限、非零的二维向量;输出连续 float32。"""
    x = np.asarray(values, dtype=np.float64)
    if x.ndim != 2 or min(x.shape) < 1 or not np.isfinite(x).all():
        raise ValueError("向量必须是非空且有限的二维数组")
    norms = np.linalg.norm(x, axis=1, keepdims=True)
    if not np.isfinite(norms).all() or np.any(norms == 0):
        raise ValueError("cosine 不接受零向量或不可表示的范数")
    return np.ascontiguousarray(x / norms, dtype=np.float32)


def check_results(scores, ids, nq, k, catalog_size):
    """-1 表示缺邻居,不能作为物品;有效结果不得重复或越界。"""
    if scores.shape != (nq, k) or ids.shape != (nq, k):
        raise ValueError("返回数组形状不符")
    valid = ids >= 0
    if np.any(ids < -1) or np.any(ids[valid] >= catalog_size):
        raise ValueError("返回了非法物品 ID")
    if not np.isfinite(scores[valid]).all():
        raise FloatingPointError("有效候选的分数不是有限值")
    if any(len(set(row[row >= 0])) != np.count_nonzero(row >= 0) for row in ids):
        raise ValueError("同一查询返回了重复物品")


def main():
    seed, n, d, nq, k = 20260911, 12_000, 64, 32, 10
    faiss.omp_set_num_threads(1)
    rng = np.random.default_rng(seed)
    items = unit_rows(rng.normal(size=(n, d)))
    queries = unit_rows(rng.normal(size=(nq, d)))
    metric, nlist = faiss.METRIC_INNER_PRODUCT, 64

    # A:精确 cosine 基线;已单位化,IP 分数越大越相似。
    exact = faiss.IndexFlatIP(d)
    exact.add(items)

    # B:IVF-Flat;独立 coarse quantizer,不与 D 共享训练状态。
    ivf_quantizer = faiss.IndexFlatIP(d)
    ivf = faiss.IndexIVFFlat(ivf_quantizer, d, nlist, metric)
    ivf.cp.seed = seed
    ivf.train(items)
    ivf.add(items)
    ivf.nprobe = 16

    # C:HNSW;不需要聚类训练,但添加物品时需要构建图。
    hnsw = faiss.IndexHNSWFlat(d, 32, metric)
    hnsw.hnsw.efConstruction = 200
    hnsw.add(items)
    hnsw.hnsw.efSearch = 64

    # D:IVF-PQ;8 段,每段 8 bit,编码本体为 8 字节/向量。
    pq_quantizer = faiss.IndexFlatIP(d)
    pq = faiss.IndexIVFPQ(pq_quantizer, d, nlist, 8, 8, metric)
    pq.cp.seed = seed
    pq.pq.cp.seed = seed
    pq.train(items)
    pq.add(items)
    pq.nprobe = 16

    baseline_scores, baseline_ids = exact.search(queries, k)
    check_results(baseline_scores, baseline_ids, nq, k, n)
    if np.any(baseline_ids < 0):
        raise RuntimeError("精确基线必须返回 k 个有效物品")
    indexes = {"Flat": exact, "IVF-Flat": ivf, "HNSW": hnsw, "IVF-PQ": pq}
    print("NumPy:", np.__version__, "Faiss:", getattr(faiss, "__version__", "unknown"))
    print("shape:", items.shape, "queries:", nq, "k:", k, "threads: 1")

    # 每个实例分别查询和回读;临时目录退出时自动清理。
    with TemporaryDirectory(prefix="ann-demo-") as folder:
        for name, index in indexes.items():
            scores, ids = index.search(queries, k)
            check_results(scores, ids, nq, k, n)
            hits = [len(set(a[a >= 0]) & set(e)) / k
                    for a, e in zip(ids, baseline_ids)]
            print(name, "Recall@10:", float(np.mean(hits)), "Top-10 ID:", ids[0])
            path = str(Path(folder) / (name + ".index"))
            faiss.write_index(index, path)
            restored = faiss.read_index(path)
            scores2, ids2 = restored.search(queries, k)
            if not np.array_equal(ids, ids2) or not np.allclose(scores, scores2):
                raise AssertionError(name + " 保存回读结果不一致")
    print("保存回读检查结束;没有测量延迟或一亿规模性能。")


if __name__ == "__main__":
    main()

本例一次 CPU 实跑:NumPy 2.3.5、Faiss 1.15.0;不是最优参数或性能保证
独立实例本次 Recall@10这能说明什么
Flat1.0与自身精确基线一致。
IVF-Flat0.628125只访问 16/64 个桶,此设置会漏近邻。
HNSW0.93125本次图搜索接近但没有完全找回精确集合。
IVF-PQ0.234375此随机数据、8 字节编码与搜索参数有明显损失,不应直接部署。

四个索引本次保存回读检查均完成。PQ 的低值说明压缩与搜索配置必须验证,不能用“内存省了”替代质量检查;这也不是证明所有 PQ 都只能达到这个水平。这里只运行接口演示,未测延迟、吞吐或一亿规模。

读完这一块,应该能指出四个对象分别在哪里设置参数。nprobe=16 必须在各个 IVF 实例上设置;IndexIVFPQ 的 metric 也显式传入 IP,不能依赖默认 L2。保存的是每个实例,回读后立刻查询验证;临时文件在程序结束时清理。

工具 2:hnswlib(独立的图检索小例)

用途:看清另一个库的接口,不能把 Faiss 的调用名照搬过去。本块自行创建物品、查询和 ID;knn_query 返回的是 labels 在前、distances 在后。cosine 空间的 distance 为 1−cosine,越小越近,和 Faiss IP 的分数方向相反。

"""独立 hnswlib cosine 小例;不依赖 Faiss 代码块,也不是性能基准。"""
import numpy as np
import hnswlib


def unit_rows(values):
    x = np.asarray(values, dtype=np.float64)
    if x.ndim != 2 or min(x.shape) < 1 or not np.isfinite(x).all():
        raise ValueError("向量必须是非空且有限的二维数组")
    norms = np.linalg.norm(x, axis=1, keepdims=True)
    if not np.isfinite(norms).all() or np.any(norms == 0):
        raise ValueError("cosine 不接受零向量或不可表示的范数")
    return np.ascontiguousarray(x / norms, dtype=np.float32)


def main():
    seed, n, d, nq, k = 20260911, 12_000, 64, 32, 10
    rng = np.random.default_rng(seed)
    items = unit_rows(rng.normal(size=(n, d)))
    queries = unit_rows(rng.normal(size=(nq, d)))
    ids = np.arange(n, dtype=np.int64)

    index = hnswlib.Index(space="cosine", dim=d)
    index.init_index(max_elements=n, ef_construction=200, M=32, random_seed=seed)
    index.set_num_threads(1)
    index.add_items(items, ids=ids, num_threads=1)
    index.set_ef(64)  # 搜索候选列表规模;本例 64 >= k=10。
    labels, distances = index.knn_query(queries, k=k, num_threads=1)
    if labels.shape != (nq, k) or distances.shape != (nq, k):
        raise ValueError("返回数组形状不符")
    if np.any(labels >= n) or np.any(labels < 0):
        raise ValueError("返回了非法物品 ID")
    if not np.isfinite(distances).all():
        raise FloatingPointError("距离不是有限值")
    if any(len(set(row)) != k for row in labels):
        raise ValueError("同一查询返回了重复物品")

    # hnswlib cosine 返回 1-cosine 距离,越小越近。
    # exact 使用 float32 内积;同分时以较小 ID 优先。
    exact_scores = queries @ items.T
    exact_ids = np.stack([np.lexsort((ids, -row))[:k] for row in exact_scores])
    recall = np.mean([len(set(a) & set(e)) / k for a, e in zip(labels, exact_ids)])
    print("shape:", items.shape, "queries:", nq, "k:", k, "threads: 1")
    print("Top-10 ID:", labels[0])
    print("cosine distance:", distances[0])
    print("Recall@10:", float(recall))
    print("这是固定 toy 数据的近邻重合,不是业务效果或延迟保证。")


if __name__ == "__main__":
    main()

同一组小数据在 hnswlib 0.8.0 的一次实跑得到 Recall@10=0.934375。这里以 NumPy 精确排序为参照,不能仅靠与上表的小差异就宣称哪个库更优;要固定实现、参数、数值/并列协议并做重复测量。

本例把 ef 设为 64,大于 k=10。若想支持后续物品增长,还要规划容量或扩容、删除标记、并发读写与持久化;不能把单线程演示直接当线上服务。此处的精确对照用 NumPy,严格同分按较小 ID 排前,细小浮点差异须与下面的评估协议一起理解。

工具 3:向量数据库(需要服务化能力时再考虑)

保留工具地图,但不把产品名当性能结论
工具可以关注的能力先确认的条件
Milvus / Zilliz CloudMilvus 是开源向量数据库;Zilliz Cloud 提供托管服务过滤、索引类型、部署和运维方式;两者不能都笼统称作开源项目。
QdrantRust 实现,提供向量与载荷过滤等服务能力用自己的过滤条件和查询负载比较,不用“轻量快”替代测量。
Weaviate可集成外部 API 或自托管 embedding 模型集成接口不等于数据库无条件内置所有模型权重;留意推理服务依赖。
pgvector在 PostgreSQL 中保存和检索向量已有 Postgres 时值得先试;容量、索引、过滤和服务负载仍须评估。

Milvus 的过滤执行与Weaviate 的模型集成说明了“数据库能力”和“算法本身”是不同层次。

  • 小于 10 万:可以先试 Flat;不是超过这个数字就一定不能用精确检索。
  • 10 万到 1000 万、内存较充裕:HNSW 可列入候选;还要看构建时间、查询次数、更新与过滤。
  • 超过 1000 万、内存吃紧:可测试 IVF-PQ;先算完整索引账,再验证压缩后的近邻质量。
  • 需要过滤、分布式或托管服务:比较数据库;仅需保存文件时,Faiss 自己已能保存/加载。
  • 已有 Postgres:先评估 pgvector 能否满足目标,避免仅为固定数量阈值更换技术栈。

🎛️ 怎么评估:先固定“什么算对”

ANN Recall@K 是近邻集合的重合率,不是用户相关性 Recall。对同一查询,以相同 metric、相同预处理、相同合法物品集合上的精确 top-k 为参照,算 ANN 找回其中多少个。然后再与延迟、吞吐、内存和更新成本一起看。

三块是独立入口:Faiss 以自己的 FlatIP 为 exact;hnswlib 例用 float32 点积、严格同分时小 ID 优先;下方评估例用 float64 cosine、同样以小 ID 处理严格同分。不同精度与库的边界结果不必相同;横向比较前,应先统一一个 exact 实现和并列协议。

  1. 固定合法库与 k:此处要求 1 ≤ k ≤ 合法库大小;exact 必须返回 k 个不同的合法 ID。
  2. 保持查询顺序一致。ANN 缺邻居可用 −1 占位,但 −1 不算物品,分母仍为 k。
  3. 本例采用严格 ID 重合;精确分数相同,较小 ID 排前。另一种同距并列结果可能被计为 miss,这不等于距离质量变差。
  4. 空查询、不同形状、重复有效 ID、非法 ID 和非法 k 明确报错。函数只能检查数组,不能替你证明两个结果来自同一过滤条件或同一查询。

下方第一条查询中 ID 10 与 11 是完全相同的向量。程序同时展示普通缺邻居和边界并列,人为 ANN 数组只是评估函数的测试夹具,不是某个索引真的返回的结果。本块不依赖另外两个代码入口。

"""独立 NumPy 评估入口:固定合法库、固定 k、严格 ID 重合协议。"""
import numpy as np


def validate_catalog(catalog_ids, k):
    ids = np.asarray(catalog_ids)
    if ids.ndim != 1 or not np.issubdtype(ids.dtype, np.integer):
        raise ValueError("catalog_ids 必须是一维整数数组")
    if np.any(ids < 0) or len(np.unique(ids)) != len(ids):
        raise ValueError("合法库 ID 必须非负且唯一")
    if isinstance(k, (bool, np.bool_)) or not isinstance(k, (int, np.integer)):
        raise ValueError("k 必须是整数")
    if not 1 <= k <= len(ids):
        raise ValueError("本协议要求 1 <= k <= 合法库物品数")
    return ids


def exact_cosine(items, queries, catalog_ids, k):
    """全部输入行属于同一个合法库;按分数降序、ID 升序消除严格同分。"""
    ids = validate_catalog(catalog_ids, k)
    x, q = np.asarray(items, dtype=np.float64), np.asarray(queries, dtype=np.float64)
    if x.ndim != 2 or q.ndim != 2 or x.shape[0] != len(ids):
        raise ValueError("物品/查询须为二维,物品行数须匹配 ID")
    if x.shape[1] < 1 or q.shape[1] != x.shape[1] or q.shape[0] == 0:
        raise ValueError("维度不一致或查询为空")
    if not np.isfinite(x).all() or not np.isfinite(q).all():
        raise ValueError("输入必须有限")
    xn, qn = np.linalg.norm(x, axis=1), np.linalg.norm(q, axis=1)
    if np.any(xn == 0) or np.any(qn == 0) or not np.isfinite(xn).all() or not np.isfinite(qn).all():
        raise ValueError("cosine 要求非零且范数有限")
    scores = (q / qn[:, None]) @ (x / xn[:, None]).T
    return np.stack([ids[np.lexsort((ids, -row))[:k]] for row in scores])


def recall_at_k(ann_ids, exact_ids, catalog_ids, k):
    """调用方必须保证同一查询顺序、metric、过滤集合与 exact 同分协议。"""
    catalog = validate_catalog(catalog_ids, k)
    ann, exact = np.asarray(ann_ids), np.asarray(exact_ids)
    if ann.ndim != 2 or exact.shape != ann.shape or ann.shape[1] != k or ann.shape[0] == 0:
        raise ValueError("双方必须是相同的非空 (查询数, k) 数组")
    if not np.issubdtype(ann.dtype, np.integer) or not np.issubdtype(exact.dtype, np.integer):
        raise ValueError("结果 ID 必须是整数")
    if not np.isin(exact, catalog).all():
        raise ValueError("exact 必须含 k 个合法物品,不能带 -1")
    if not (np.isin(ann, catalog) | (ann == -1)).all():
        raise ValueError("ANN 仅允许合法 ID 或缺邻居哨兵 -1")
    per_query = []
    for a, e in zip(ann, exact):
        valid_a = a[a != -1]
        if len(np.unique(e)) != k or len(np.unique(valid_a)) != len(valid_a):
            raise ValueError("同一查询的有效 ID 不得重复")
        per_query.append(len(set(valid_a) & set(e)) / k)
    return float(np.mean(per_query))


def main():
    # 指定小数组用于测试评估函数;ann 是人为夹具,不是 ANN 模型输出。
    catalog = np.array([10, 11, 12, 13])
    items = np.array([[1., 0.], [1., 0.], [0., 1.], [-1., 0.]])
    queries = np.array([[1., 0.], [0., 1.]])
    exact = exact_cosine(items, queries, catalog, k=2)
    ann = np.array([[10, 12], [12, -1]])
    value = recall_at_k(ann, exact, catalog, k=2)
    assert value == 0.5
    print("exact ID:", exact.tolist(), "fixture Recall@2:", value)

    # ID 10/11 完全同分,本协议指定小 ID 优先;另一种合法距离并列算 miss。
    tied_exact = exact_cosine(items, queries[:1], catalog, k=1)
    tie_value = recall_at_k(np.array([[11]]), tied_exact, catalog, k=1)
    assert tie_value == 0.0
    print("strict-ID tie example:", tie_value, "(不代表距离质量变差)")

    bad_calls = [
        lambda: recall_at_k(ann, exact, catalog, 0),
        lambda: recall_at_k(ann, exact, catalog, 5),
        lambda: recall_at_k(np.empty((0, 2), dtype=int), np.empty((0, 2), dtype=int), catalog, 2),
        lambda: recall_at_k(ann[:1], exact, catalog, 2),
        lambda: recall_at_k(np.array([[10, 10]]), exact[:1], catalog, 2),
        lambda: recall_at_k(np.array([[10, 99]]), exact[:1], catalog, 2),
        lambda: recall_at_k(ann, np.array([[10, -1], [12, 10]]), catalog, 2),
        lambda: exact_cosine(items, np.array([[0., 0.]]), catalog, 2),
    ]
    for call in bad_calls:
        try:
            call()
        except ValueError:
            continue
        raise AssertionError("非法输入未被拒绝")
    print("rejected invalid cases:", len(bad_calls))


if __name__ == "__main__":
    main()

本块可观察到:精确 ID 为 [[10,11],[12,10]],指定夹具的 Recall@2 为 0.5;严格 ID 并列例为 0.0,并拒绝 8 类非法调用。这些数字只检查评估协议,不证明任何索引快慢或质量。

生产测量还需固定硬件、线程、并发/批量、预热与查询数。例子目标“Recall@100 ≥ 0.95,P99 ≤ 10 ms”可以作为某次实验预算,不是所有业务的标准。若采用同距容差协议或不同分母,必须另行命名并在对比中保持一致。

  1. 固定索引类型与数据,分别扫 efSearch 或 nprobe,记录每个点的 Recall 与延迟分位。
  2. 在同一个延迟统计量的预算内,选择达到质量要求的配置;同时检查内存、吞吐和有效返回数。
  3. 达不到目标,再比较索引、编码、过滤方案或算力。不能预设每次加参数都按同样幅度改善。
人为教学数据、非实测:在示例10毫秒P99预算内选择候选配置 横轴为示意P99延迟,单位毫秒,线性范围0到20;纵轴为同一k下的Recall@k,线性范围0.5到1.0。人为点A为1和0.60,B为2和0.72,C为5和0.88,D为10和0.95,E为20和0.98。示例预算10毫秒以内D的Recall最高;E超预算。连线只引导读数,不是拟合、基准结果或通用最佳参数。 先画预算线,再比较线左边的候选 人为教学数据 · 非实测 · 五种配置沿用同一个 k Recall@k本例预算:P99 ≤ 10 ms 1.000.900.800.700.600.50 05101520 ABCDE 示意 P99 延迟(ms)· 线性横轴,越左越快 A (1, 0.60) B (2, 0.72) C (5, 0.88) D (10, 0.95) E (20, 0.98) 给定这五点,预算内选 D;E 更准,但超出 10 ms。
看 10 ms 预算线:在给定的五个人为候选点中,D 是预算内 Recall@k 最高的配置。两轴线性,纵轴从 0.50 起;连线只引导读数。这不是实测 P99,也不是所有系统的通用最优点。

从单索引到分片:查询必须说明本次合法库、编码器/预处理、metric与版本。把同一查询发到各分片(fan-out),再按同一分数协议归并候选,才谈全局top-k;多路召回并集不等于这个分片协议。

可跳过:两分片归并与更新清单

手设统一为“分数越大越好”,严格同分时小ID在前,物品ID全局唯一。分片A返回 ID10:0.90、ID12:0.60;分片B返回 ID11:0.95、ID13:0.70。合并后全局top-2是11、10。若各片在同一合法快照上都返回精确局部top-k,候选足以归并同一协议的全局top-k;局部ANN若漏掉11,后续排序无法把它补回。这是手设候选,不是索引库实测。

  • 分数能否比较:统一metric方向、归一化、模型/特征与过滤语义;独立训练的强压缩索引可能使近似距离难比较,需统一训练或回到一致表示重打分。并列、缺候选、重复ID也要定义。
  • 分片与副本不同:分片拆分物品集合;副本保存同一分片,用于可用性或读扩展。说明每片由哪个版本的副本响应;缺片/超时应标记partial,不能冒称全库足量结果。
  • 新增、删除与切换:更新要带模型/索引代际与稳定业务ID;删除或墓碑应在合法库及所有相关副本生效,不能只删一个列表。索引的删除能力与ID重排取决于具体实现。
  • 整版发布:先构建并校验所有分片、向量/码本和ID映射,待路由与副本就绪后按一致版本协议切换;记录失败/回滚与读取快照。不能把混合版本结果默认为同一个语义空间,也不能把Python归并当分布式原子发布。

已有本节exact与Recall@K协议继续复用;更新的模型兼容性见原更新段。完整快照的SQLite教学例只作协议参照,不是多节点切换实测。官方依据:Faiss多机器训练/IndexShards及距离比较限制、各类索引操作。

⚠️ 工业落地的四个真实问题

① 向量多久更新?先看哪些输入会变化

更新频率来自时效要求,不是固定日历。“物品天级全量重建 + 分钟级增量”是一种部署例子;新品可按需加入,量化训练或模型换版则可能需要重建评估。

用户向量可以每请求计算、按事件刷新、缓存或预计算。若用户塔依赖最新行为,缓存会有时效损失;若只查静态 user-ID embedding,就不必每请求重新跑模型。

无论多久刷新,用户塔与物品塔的模型/特征版本、归一化、metric 和索引向量必须兼容。同为 64 维不代表同一个语义坐标系。更换编码器也可能使旧量化训练分布失效。

② 带条件检索:把合法集合放进评估定义

例如只推近 30 天、类目为数码的物品。精确参照也必须来自这个集合,不能用全库 top-k 来评判过滤后的返回。

过滤顺序不同,漏项和返回数量也不同
方案怎么做边界
Pre-filter先限定合法子集,再检索可用精确或受过滤约束的 ANN,不等于只能暴力;小子集精确扫描可能合适。
Post-filter先取一批候选,例如 top-1000,再过滤可能不足 k,甚至为空;多取些候选是缓解,不是补齐或 Recall 保证。
分区索引按类目或其他低基数条件维护分区条件组合多时分区会膨胀;还要处理跨区查询与更新。
原生过滤数据库/索引把过滤条件纳入执行计划可能先过滤或迭代过滤,不统一等于“图遍历时带条件”。

小反例:全库前两项都不是数码,后过滤便为空,即使第 3、4 项都是合法物品。过滤顺序会改变实际候选覆盖,不能只比较未过滤索引的 Recall。

③ 内存怎么算:编码、ID 与图分别列账

一亿个 64 维向量,十进制 GB;不是进程峰值内存
部分计算约占用
原始 float32 向量1 亿 × 64 × 4 字节25.6 GB
HNSW 底层边槽示例M=32、容量约 2M、32 位邻居编号:1 亿 × 64 × 4 字节另约 25.6 GB;与向量合计约 51.2 GB,尚未计上层/元数据
PQ 编码本体M=8、nbits=8:1 亿 × 8 字节0.8 GB,编码负载相对 256 字节压缩 32 倍
IVF-PQ 编码 + 64 位 ID1 亿 × (8 + 8) 字节至少 1.6 GB,另有码本、倒排管理和可能的预计算表

0.8 GB 不能写成完整 IVF-PQ 部署占用。输入数组、建库工作区、查询工作区和业务元数据也需要内存。原先“约 50 GB”的 HNSW 估算可以理解为上述 M=32 示例的数量级,不是每个实现的固定值。Faiss 索引的逐项存储组成。

④ 多路召回怎么合并:先候选并集,再统一评判

假设 20 路召回各返回一批,不同路的分数不一定可直接比较。

  • 配额:每路取 top-200,不直接比较分数;合并去重后最多 4000 个,也可能更少。
  • 分数处理:可校准或规范化再融合,但简单缩放不自动保证不同路的分数含义一致。
  • 统一粗排:对候选并集重新打分;它仍不能找回所有路都没有召回的物品。

🧩 向量检索不只用于召回

  • 相似物品:在“相关推荐”位置寻找语义或行为向量近邻。
  • 去重:检索相似内容候选,再按业务规则核验;近邻本身不是重复的证明。
  • 冷启动:用新物品内容 embedding 找相似旧物品,将其统计作为参考特征;不把旧物品标签无条件复制成新物品事实。
  • RAG / 搜索:可以复用向量索引环节;文本切分、混合召回、权限过滤、重排与生成仍有自己的设计,不是完整技术栈毫无区别。

🔗 这一章连到哪里

去哪为什么
数学原理 05理解某些高维分布下距离集中及索引效率的困难;这不证明精确检索不可能。Flat 仍是精确基线。
ML 基础 06IVF 的桶来自聚类,PQ 的子空间码本也通过聚类学习;“分桶”和“压缩”要分开。
智能体 11把向量检索作为 RAG 的一个组件,继续看文本、过滤与生成如何接起来。

✅ 检查点

  1. 为什么可以考虑 ANN?后续粗排/精排能自动补回所有漏召回吗?
  2. HNSW 的核心关系是什么?线上哪个参数控制搜索候选规模?
  3. 最大内积检索是否必须 L2 归一化?本章 cosine 小例为什么要单位化?
  4. 1000 万向量、内存充裕、追求低延迟,可以先测试什么索引?还缺哪些判断条件?
  5. ANN Recall@K 的参照与分母是什么?−1、过滤和同分边界怎么处理?
  6. 用户和物品向量一定按固定频率更新吗?同为 64 维就能混用吗?
👀 答案
  1. ANN 以可能漏真近邻为代价减少搜索工作,是否值得要结合质量、资源与业务评估。后续排序只能重排已有候选,不能自动补回未召回物品。
  2. 上层是下层的稀疏节点子集,同一节点可跨层出现;高层找入口,底层继续搜索。查询时调 efSearch(hnswlib 叫 ef),它是候选列表规模,不是最大跳数。
  3. 不必须。原始 MIPS 可利用物品范数;单位化可能改变赢家。本章主动选择 cosine,因此对非零有限向量单位化,再以 IP 检索;零向量必须单独处理。
  4. HNSW 是值得先试的候选,不是数量阈值决定的唯一答案。还需测召回、延迟/吞吐、建库/更新、过滤、内存与查询次数;小批量任务也可能更适合 Flat。
  5. 参照为同一查询、metric、预处理和合法库上的 exact top-k;本协议 k 不超过合法库大小,分母固定 k。−1 不算命中;非法形状/ID/空查询拒绝。严格同分按 ID 排序,另一种同距结果可能算 miss,因此必须标明协议。
  6. 不一定。可按请求、事件、缓存或批次刷新,取决于输入变化和时效预算。模型/特征、归一化、metric 与索引版本要兼容;维度相同不代表语义坐标一致。

本节回顾

⚡ 走神救援

先记住这几件事

  • ANN 在搜索质量、延迟和内存之间取舍,先建立精确检索基线。
  • 固定数据与指标,画出检索质量随搜索成本变化的曲线。
  • 过滤条件、向量更新与多路分数尺度都可能改变实际返回结果。

下一节 👉 11 · 重排与多样性

打卡记录保存在你的浏览器里,首页能看到总进度