turbovec:高效向量索引工具
一个包含 1000 万文档的语料库,若以 float32 格式存储,需要 31GB 的 RAM。而 turbovec 仅用 4GB 就能容纳,并且搜索速度比 FAISS 更快。turbovec 是一个带有 Python 绑定的 Rust 向量索引,基于 Google Research 的 TurboQuant 算法构建。这是一种数据无关的量化器,能达到香农失真下限,无需码本训练,也没有单独的训练阶段。
turbovec 有哪些特性?
1. 在线摄入:添加向量后会立即进行索引,无需训练步骤、参数调整,语料库增长时也无需重建。
2. 速度更快:手写的 NEON(ARM)和 AVX - 512BW(x86)内核在 ARM 上比 FAISS IndexPQFastScan 快 12 - 20%,在 x86 上与之相当或更快。
3. 搜索时过滤:在 `search()` 函数中传入 ID 白名单(或槽位位掩码),内核会直接处理。始终能从允许的集合中获取最多 k 个结果,不会过度获取,选择性过滤时也不会降低召回率。
4. 纯本地化:无需托管服务,数据不会离开你的机器或 VPC。可与任何开源嵌入模型搭配,构建完全气隙的 RAG 堆栈。
如何安装与使用 turbovec?
Python
```python
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.tq")
loaded = TurboQuantIndex.load("my_index.tq")
```
若需要在删除操作后仍保持稳定的 ID,可使用 `IdMapIndex`:
```python
import numpy as np
from turbovec import IdMapIndex
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) # ids 是你的 uint64 外部 ID
index.remove(1002) # 按 ID 操作,时间复杂度为 O(1)
index.write("my_index.tvim")
loaded = IdMapIndex.load("my_index.tvim")
```
混合检索(过滤搜索)
可将结果限制在另一个系统(如 SQL、BM25、ACL、时间窗口等)生成的候选集内:
```python
import numpy as np
from turbovec import IdMapIndex
idx = IdMapIndex(dim=1536, bit_width=4)
idx.add_with_ids(vectors, ids)
# 阶段 1:外部系统缩小到候选 ID
allowed = np.array(db.execute("SELECT id FROM docs WHERE tenant=?", (t,)).fetchall(), dtype=np.uint64)
# 阶段 2:在候选集内进行密集重排序
scores, ids = idx.search(query, k=10, allowlist=allowed)
```
过滤操作在 SIMD 内核中以 32 向量块为粒度进行:没有允许槽位的块在进行查找表查找或评分工作之前会被短路,评分块内的单个非允许槽位在堆插入时会被丢弃。因此,选择性白名单(允许的索引占比小)可避免大部分 SIMD 成本,而不是先付出成本再丢弃结果。输出长度为 `min(k, len(allowed))`,当白名单数量小于 k 时,会得到确切的 `len(allowed)` 个结果,而不是填充的备用结果。完整参考请见 `docs/api.md`。
turbovec 如何进行框架集成?
turbovec 可作为各框架中现有向量/文档存储的直接替代品,具有相同的公共接口、持久化语义、检索器和管道连接方式,只需更改导入语句,即可保留原有管道。
- LangChain:`pip install turbovec[langchain]`,替换 `langchain_core.vectorstores.InMemoryVectorStore`
- LlamaIndex:`pip install turbovec[llama-index]`,替换 `llama_index.core.vector_stores.SimpleVectorStore`
- Haystack:`pip install turbovec[haystack]`,替换 `haystack.document_stores.in_memory.InMemoryDocumentStore`
- Agno:`pip install turbovec[agno]`,替换 `agno.vectordb.lancedb.LanceDb`
Rust
```rust
cargo add turbovec
use turbovec::TurboQuantIndex;
let mut index = TurboQuantIndex::new(1536, 4);
index.add(&vectors);
let results = index.search(&queries, 10);
index.write("index.tv").unwrap();
let loaded = TurboQuantIndex::load("index.tv").unwrap();
```
若需要在删除操作后仍保持稳定的外部 ID:
```rust
use turbovec::IdMapIndex;
let mut index = IdMapIndex::new(1536, 4);
index.add_with_ids(&vectors, &[1001, 1002, 1003]);
let (scores, ids) = index.search(&queries, 10);
index.remove(1002);
index.write("index.tvim").unwrap();
let loaded = IdMapIndex::load("index.tvim").unwrap();
```
turbovec 召回率表现如何?
与 FAISS IndexPQ(LUT256,nbits = 8)相比,在 100K 向量、k = 64 的情况下:
- 在 OpenAI 的 d = 1536 和 d = 3072 维度上,TurboQuant 在 2 位和 4 位时的 R@1 比 FAISS 高 0.4 - 3.4 个百分点,且在 k = 4 时两者都趋近于 1.0。
- GloVe d = 200 是更具挑战性的情况,在低维度下,渐近 Beta 假设更宽松。TurboQuant 在 4 位时 R@1 比 FAISS 高 0.3 个百分点,在 2 位时低 1.2 个百分点,在 k ≈ 16 时两者差距缩小。
turbovec 压缩与搜索速度怎样?
所有基准测试均基于 100K 向量、1K 查询、k = 64,取 5 次运行的中位数。
- ARM(Apple M3 Max):在 ARM 上,TurboQuant 在所有配置下都比 FAISS FastScan 快 12 - 20%。
- x86(Intel Xeon Platinum 8481C / Sapphire Rapids,8 vCPUs):在 x86 上,TurboQuant 在所有 4 位配置下快 1 - 6%,在 2 位单线程(ST)时与 FAISS 相差约 1%。2 位多线程(MT)的 d = 1536 和 d = 3072 配置略落后于 FAISS(2 - 4%),这是因为内部累加循环过短,无法通过展开摊销来匹配 FAISS 的 AVX - 512 VBMI 路径。
turbovec 工作原理是什么?
每个向量都是高维超球面上的一个方向。TurboQuant 利用一个简单的原理来压缩这些方向:应用随机旋转后,每个坐标都遵循已知的分布,与输入数据无关。
1. 归一化:去除每个向量的长度(范数),并将其存储为一个浮点数。此时每个向量都是超球面上的单位方向。
2. 随机旋转:将所有向量乘以相同的随机正交矩阵。旋转后,每个坐标独立遵循 Beta 分布,在高维情况下收敛于高斯分布 N(0, 1/d)。这种分布对任何输入数据都成立,旋转使坐标分布可预测。
3. 逐坐标校准(TQ +):步骤 2 中的 Beta 分布是渐近的,在有限维度下,单个坐标会偏离标准形状(特别是低比特和词向量风格的嵌入)。TQ + 在首次添加向量时为每个坐标拟合两个标量(偏移和缩放),将每个坐标的经验 5/95% 分位数映射到标准 Beta 边缘分布。Lloyd - Max 码本随后针对其设计的目标分布进行量化。校准在首次添加后冻结,后续添加时重用,无需重新训练、重建或单独的训练阶段。在漂移最大的单元(如 2 位的 GloVe)上,召回率增益最高可达 +1.4 个百分点。
4. Lloyd - Max 标量量化:由于分布已知,可预先计算每个坐标的最佳分桶方式。2 位时为 4 个桶,4 位时为 16 个桶。Lloyd - Max 算法找到使均方误差最小的桶边界和质心。这些是通过数学计算得出,而非从数据中计算。
5. 位打包:每个坐标现在是一个小整数(2 位时为 0 - 3,4 位时为 0 - 15),将它们紧密打包成字节。一个 1536 维的向量从 6144 字节(FP32)压缩到 384 字节(2 位),压缩比达 16 倍。
6. 长度重归一化评分:标量量化会系统性地低估内积,重建的单位方向比原始方向略短。在编码时为每个向量计算一个标量(旋转后的单位向量与其质心重建的内积),并将 `||v|| / ⟨u, x̂⟩` 与每个压缩向量一起存储。搜索内核在堆插入前将每个候选得分乘以该标量,使内积估计从有偏变为无偏,且搜索时无额外成本和存储开销。在低比特宽度下,由于量化收缩最大,召回率增益最明显。编码成本为每个向量额外进行一次 d 维点积计算 `⟨u, x̂⟩`。对于 100 万个 d = 1536 的向量,额外编码时间不到 1 秒,这是在摄入时一次性付出的代价,而非查询时。
turbovec 搜索过程是怎样的?
无需解压每个数据库向量,只需将查询旋转到相同的域,直接根据码本值进行评分。评分内核使用 SIMD 内在函数(ARM 上的 NEON,现代 x86 上的 AVX - 512BW,AVX2 作为后备)和半字节拆分查找表以实现最大吞吐量。Lloyd - Max 码本的失真率达到信息论下限(香农失真率极限)的 2.7 倍以内,长度重归一化步骤消除了 Lloyd - Max 码本在内积估计中引入的残余偏差。
如何构建 turbovec?
Python(通过 maturin)
```bash
pip install maturin
cd turbovec - python
maturin build --release
pip install target/wheels/*.whl
```
Rust
```bash
cargo build --release
```
所有 x86_64 构建目标为 x86 - 64 - v3(AVX2 基线,Haswell 2013 +),通过 `.cargo/config.toml` 配置。任何能运行 AVX2 后备内核的 CPU 都能运行整个 crate,AVX - 512 内核在运行时通过 `is_x86_feature_detected!` 进行门控,仅在支持的硬件上启用。
怎样运行 turbovec 基准测试?
```bash
# 下载数据集
python3 benchmarks/download_data.py all # 所有数据集
python3 benchmarks/download_data.py glove # GloVe d = 200
python3 benchmarks/download_data.py openai - 1536 # OpenAI DBpedia d = 1536
python3 benchmarks/download_data.py openai - 3072 # OpenAI DBpedia d = 3072
# 单独运行任何一个基准测试
python3 benchmarks/suite/speed_d1536_2bit_arm_mt.py
python3 benchmarks/suite/recall_d1536_2bit.py
python3 benchmarks/suite/compression.py
# 运行某一类别的所有基准测试
for f in benchmarks/suite/speed_*arm*.py; do python3 "$f"; done # 所有 ARM 速度测试
for f in benchmarks/suite/speed_*x86*.py; do python3 "$f"; done # 所有 x86 速度测试
for f in benchmarks/suite/recall_*.py; do python3 "$f"; done # 所有召回率测试
python3 benchmarks/suite/compression.py # 压缩测试
```
结果以 JSON 格式保存到 `benchmarks/results/`。重新生成图表:
```bash
python3 benchmarks/create_diagrams.py
```
turbovec 有哪些参考文献?
- TurboQuant: Online Vector Quantization with Near - optimal Distortion Rate (ICLR 2026) — 本项目实现的论文
- RaBitQ: Quantizing High - Dimensional Vectors with a Theoretical Error Bound for Approximate Nearest Neighbor Search (SIGMOD 2024) — 步骤 5 中采用的每个向量长度重归一化校正的来源
- FAISS Fast accumulation of PQ and AQ codes — turbovec 的 x86 SIMD 内核采用了 FastScan 的打包布局、半字节查找表评分和 u16 累加器策略
632



被折叠的 条评论
为什么被折叠?



