turbovec —— 基于TurboQuant的向量索引引擎，用Rust编写并提供Python绑定

这是什么

turbovec 是一个基于 Rust 构建的高性能向量索引库，提供 Python 绑定。它核心采用 Google Research 提出的 TurboQuant 算法——一种数据无关的量化器，能够在无需独立训练阶段的情况下实现接近最优的失真率。turbovec 专为大规模向量检索场景设计，在内存占用和搜索速度上均显著优于传统方案（如 FAISS）。

解决的问题

传统向量索引（如 FAISS 的 IndexPQ）在处理大规模语料时面临两个核心痛点：

1. 内存爆炸：一个 1000 万文档的浮点向量（float32）需要约 31 GB 内存，部署成本高昂。
2. 训练与调参成本：FAISS 等索引通常需要离线训练码本、调节参数，且当语料持续增长时需重新构建索引，难以支持在线增量更新。

turbovec 通过 TurboQuant 算法将同样 1000 万文档的向量压缩至 4 GB 内存（16 倍压缩率），同时保持甚至超越 FAISS 的搜索速度。其数据无关的量化策略消除了训练步骤，支持在线即时添加向量，无需任何参数调优或重建。

核心功能

• 在线增量摄取：调用 add() 即可将新向量实时加入索引，无需训练、调参或重建。索引随语料增长自动适配。
• SIMD 加速搜索：手写 NEON（ARM）和 AVX-512BW（x86）内核，实现极速搜索。ARM 上比 FAISS IndexPQFastScan 快 10–19%；x86 上 4-bit 配置领先，2-bit 配置略逊但差距很小（如 d=1536 单线程约 8%）。
• 搜索时过滤（allowlist）：支持通过 ID 白名单或槽位掩码直接过滤结果。SIMD 内核在 32 向量块粒度上短路未匹配的块，避免无谓计算；仅当允许集的向量比例很小时，过滤开销几乎为零。输出结果精确为 min(k, len(allowed))，不会填充无效结果。
• 纯本地部署：无需托管服务，数据不离开机器或 VPC。可搭配任意开源 embedding 模型构建完全离线的 RAG 堆栈。
• 持久化与加载：支持 write() / load() 序列化索引到磁盘文件。
• 稳定外部 ID 支持：IdMapIndex 允许用户指定 uint64 外部 ID，支持 O(1) 删除，ID 在删除后仍保持稳定。

亮点 / 与同类相比

| 对比维度 | turbovec | FAISS IndexPQ | |----------|----------|---------------| | 训练阶段 | 无，数据无关量化 | 需要离线训练码本（k-means++） | | 内存占用 | 16 倍压缩（1536 维向量 2-bit 仅 384 字节） | 典型 8-bit 压缩，内存占用更高 | | 在线增量 | 支持，即时添加，无需重建 | 不支持，增量需重建索引 | | 搜索速度 | ARM 上快 10–19%；x86 4-bit 配置领先 | 2-bit 配置上 AVX-512 VBMI 路径有优势 | | 过滤机制 | SIMD 内核级短路，零额外开销 | 需后过滤，可能过取或降低召回 | | 精度 | 与 FAISS 持平或略优于 FAISS（R@1 高 0.2–1.9 点） | 经典 PQ 基线，高维表现良好 |

核心技术亮点：TurboQuant 通过随机旋转将任意分布的向量坐标映射到已知的 Beta 分布（高维趋近高斯），从而无需数据即可预计算 Lloyd-Max 量化桶。其增强版 TQ+ 在首次添加时对每个坐标拟合两个标量（shift 和 scale），将经验分布 5%/95% 分位数对齐到理论 Beta 边缘，进一步提升低维或低比特场景下的召回率（最高 +1.4 点 R@1）。

适合谁用 / 上手

适用人群：

• 构建 RAG 系统且对隐私、内存或延迟敏感的开发者和架构师。
• 需要在受限硬件（如边缘设备、AI PC）上运行大规模向量搜索的团队。
• 希望替换现有框架（LangChain、LlamaIndex、Haystack、Agno）中内存向量存储的用户——turbovec 提供一键替换的集成包。

上手示例：

pip install turbovec
from turbovec import TurboQuantIndex

index = TurboQuantIndex(dim=1536, bit_width=4)
index.add(vectors)                # 在线添加
index.add(more_vectors)
scores, indices = index.search(query, k=10)
index.write("my_index.tv")        # 持久化
loaded = TurboQuantIndex.load("my_index.tv")

如需稳定外部 ID 和删除功能：

from turbovec import IdMapIndex
import numpy as np

index = IdMapIndex(dim=1536, bit_width=4)
index.add_with_ids(vectors, np.array([1001, 1002, 1003], dtype=np.uint64))
scores, ids = index.search(query, k=10)
index.remove(1002)
index.write("my_index.tvim")

框架集成示例（LangChain）：

pip install turbovec[langchain]

然后在代码中将 langchain_core.vectorstores.InMemoryVectorStore 替换为 turbovec.langchain.VectorStore 即可。