turbovec：基于 TurboQuant 的进程内向量索引

工具定位

turbovec 是一个可供 Python 和 Rust 调用的进程内（in-process）向量索引库，不是网络服务。它以 2 位或 4 位每维的精度压缩存储向量，并利用 SIMD 内核直接在压缩形式上完成检索。README 称其实现了 Google Research 的 TurboQuant 方法。

原文给出的使用方式

Python 端通过 pip install turbovec 安装后，可构造 TurboQuantIndex(dim=..., bit_width=4)，用 add() 加入向量、search() 检索、sync(path) 增量持久化、load() 载入。IdMapIndex 支持以自定义 uint64 id 管理条目，并提供 add_with_ids、remove，以及带 allowlist（id 白名单）的过滤检索。输入要求是形状为 (n, dim) 的二维 float32 数组，其他类型会报错；返回的分数是内积，若要余弦相似度需自行归一化向量。Rust 端 API 与 Python 对应。

原文还列出 LangChain、LlamaIndex、Haystack、Agno 的集成文档与对应可选依赖，但具体接入细节需查阅各集成文档。

原文引用的对比数据

以下数值均来自 README 所述测试条件：100K 条 OpenAI embeddings（d=1536 与 d=3072）及 GloVe（d=200），k=64，1K 条查询，5 次运行取中位数，在 GCP ARM 与 x86 机器上，对比同比特率的 FAISS。

• 搜索速度：4 位时各测试组合为 FAISS 的 3.8–5.1 倍（ARM 4.0×、x86 4.9×）；2 位时为 1.8–2.5 倍。
• 内存：d=1536 下 4 位约 75 MB、2 位约 38 MB，对比 float32 的 586 MB，即 7.8× / 15.5×。
• Recall@1：OpenAI 语料 4 位为 0.959 / 0.981，2 位为 0.901 / 0.931；FAISS 对应为 0.966 / 0.971 与 0.876 / 0.911。GloVe d=200 为 0.860（4 位）与 0.572（2 位），FAISS 为 0.842 与 0.565。
• 增删：单次 add() 耗时 7.9–21.7 µs；remove(id) 为 1.4–5.8 µs，而 FAISS 每次需重排全部编码。
• 整文件保存比 FAISS 慢 1.0–1.4 倍；加载到首次搜索慢 1.0–1.5 倍。

README 称在 OpenAI 语料上前 8 个结果内总能包含真实最近邻。原文提醒：上述结论因语料和机器而异，应自行在样本上验证召回。

原文说明的适用边界

• 该库采用全量扫描，查询开销随语料线性增长；对于规模达数亿且延迟要求严格的场景，原文建议使用 HNSW 或 IVF 类图或倒排索引，而 turbovec 本身不属于此类。
• 量化是有损的，需要精确浮点结果的场景不适用；低维向量（如 GloVe d=200）召回损失更大。
• 它没有网络 API、复制或多租户服务能力。
• 维度需为 8 的倍数且不超过 16,384；比特宽度仅支持 2 和 4。

原理概述

turbovec 先记录向量长度并归一化，再用同一个随机正交矩阵旋转全部向量，使各坐标服从已知分布；随后按该分布用 Lloyd-Max 码本量化（2 位 4 级、4 位 16 级）并位打包。检索时查询只旋转一次，用 SIMD 查表打分，并以编码时固定的每向量标量修正内积偏差。对偏离渐近分布的数据，可用一次性的 calibrate(sample) 拟合每坐标的两个标量。