Faiss

—Stars

Meta Fundamental AI Research 维护的高性能向量相似度搜索与聚类库，使用 C++ 实现并提供完整 Python / NumPy 接口，支持 CPU、GPU 以及十亿级稠密向量索引。

C++ · PythonCPU · GPUBillion-scale Vector Search

VECTOR SEARCH · RESULT CONTRACT

零个数据库向量，也必须返回完整结果

空索引不是“什么都不用做”；对每个查询来说，它仍然必须写出距离哨兵值和明确的无结果标签。

EXHAUSTIVE SEARCH INPUT

Q001Q···Q1000

nq × d ≥ BLAS threshold

INDEX FLAT0database vectors · ny

BEFORE · BLAS PATHif (ny == 0) return;

D = 42I = 99

CALLER BUFFER UNTOUCHED

AFTER · EMPTY INDEX ROUTEres.sel || ny == 0 || below_threshold

TOP 1HEAPRESERVOIR

RESULT HANDLER COMPLETES

OUTPUT CONTRACT · 2 METRICS × 3 HANDLERS

L2+ FLOAT MAXlabel −1

IP− FLOAT MAXlabel −1

6 / 6 REGRESSION CASES PASS

规模分叉

空 `IndexFlat` 在小查询批次下会正确返回距离哨兵值与 `-1` 标签，但当 `nq × d` 达到 BLAS 分发阈值后，BLAS helper 会因 `ny == 0` 提前返回，结果处理器尚未初始化，调用者传入的距离与标签缓冲区可能继续保留原来的 `42` 和 `99`。

根因定位

空数据库搜索仍然是一条有明确定义的公开接口：每个查询的全部槽位都必须由对应 result handler 写成中性距离和 `-1` 标签。Top1、Heap 与 Reservoir 已经各自掌握正确的哨兵语义，因此修复不应在外层复制结果规则，而应确保空索引进入能够完整执行处理器生命周期的路径。

路径修复

在内积与 L2 两个搜索分发器中把 `ny == 0` 纳入顺序路径条件，避开 BLAS 的提前返回；回归测试强制触发原 BLAS 边界，预填输出缓冲区，并覆盖两种距离度量及 `k=1/10/150` 对应的三类 result handler。

契约覆盖

空索引无论查询规模和 `k` 如何都稳定写出完整哨兵结果，不再把未初始化的调用方数据当作搜索输出；6 组回归子测试均由失败转为通过，并完成 49 项 Python 测试、290 项 C++ 测试及 ASan / UBSan 验证，修复上游长期问题 #3830。