TurboVec：基于TurboQuant的高性能向量索引库

这是什么

turbovec 是一个基于 Rust 构建的高性能向量索引库，提供 Python 和 Rust 原生绑定。其核心算法源自 Google Research 的 TurboQuant，这是一种数据无关（data-oblivious）的量化器。

该项目旨在解决大规模向量检索中的内存占用与搜索速度平衡问题。与传统的向量数据库不同，turbovec 不需要单独的“训练阶段”或代码本（codebook）训练过程。它通过数学推导预先计算量化边界，实现了在极低比特（2-bit/4-bit）下逼近香农失真下界（Shannon lower bound on distortion）的性能，同时保持极高的搜索效率。

解决的问题

1. 内存效率极低：传统 float32 格式的向量索引占用空间巨大。例如，1000 万文档的语料库在 float32 下需要 31 GB 内存，而 turbovec 仅需 4 GB。
2. 检索延迟与吞吐量瓶颈：在同等精度下，turbovec 的搜索速度优于业界主流的 FAISS（Facebook AI Similarity Search）。
3. 动态数据处理的复杂性：传统向量索引在数据增量更新时往往需要重建索引或进行复杂的参数调优。turbovec 支持在线摄入（Online ingest），添加向量即索引，无需重新训练或重建。
4. 隐私与本地化需求：对于需要完全本地部署、数据不出域（VPC）的场景，turbovec 提供纯本地解决方案，可配合任何开源嵌入模型构建完全隔离的 RAG（检索增强生成）架构。

核心功能

• TurboQuant 算法：

  • 随机旋转与校准：通过随机正交矩阵旋转向量，使坐标分布收敛至已知的高斯分布。随后使用 TQ+ 技术，在首次添加向量时拟合每个坐标的偏移和缩放参数，将经验分位数映射到标准 Beta 分布。
  • Lloyd-Max 量化：基于已知分布预先计算最优量化桶边界和质心，无需数据训练。
  • 极致压缩：支持 2-bit 和 4-bit 量化。例如，1536 维的向量从 6144 字节（FP32）压缩至 384 字节（2-bit），实现 16 倍压缩。
  • 长度归一化评分：在编码时计算并存储长度校正因子，以补偿标量量化带来的内积低估问题。

• 高性能 SIMD 内核：

  • 手写优化的 NEON（ARM）和 AVX-512BW（x86）内核，直接加速向量相似度计算。
  • 支持搜索时的实时过滤：允许传入 ID 白名单或槽位位掩码，内核在 SIMD 级别（32 向量块粒度）直接执行过滤，跳过无效块，避免过度获取（over-fetching）且不损失召回率。

• 稳定的 ID 映射（IdMapIndex）：

  • 支持外部稳定 ID（如数据库主键），支持 O(1) 复杂度的按 ID 删除操作，且删除后 ID 依然保留在映射中，确保数据一致性。

• 框架集成：

  • 提供 LangChain、LlamaIndex、Haystack 和 Agno 的 Drop-in 替换实现，保持相同的公共接口和持久化语义，只需更改导入即可无缝接入现有 RAG 管道。

亮点 / 与同类相比

• 速度优势：
  • ARM 平台：比 FAISS 的 IndexPQFastScan 快 12–20%。
  • x86 平台：在 4-bit 配置下胜出 1–6%，在 2-bit 配置下与 FAISS 持平或略优（仅在某些特定多任务配置下略慢 2–4%）。
• 精度表现：
  • 在 OpenAI 嵌入模型（d=1536/3072）上，TurboQuant 在 R@1 指标上比 FAISS PQ 高出 0.4–3.4 个百分点。
  • 在低维嵌入（如 GloVe d=200）上，4-bit 精度优于 FAISS，2-bit 精度略低但差距在 k≈16 时缩小。
• 零训练开销：
  • 与 FAISS 等需要 k-means++ 训练代码本的方案不同，turbovec 无需单独的 train 步骤，无需参数调优，无需因数据增长而重建索引。
• 内存压缩比：
  • 在保持高召回率的同时，将内存占用降低至原来的 1/8 到 1/16，显著降低硬件成本。

适合谁用 / 上手

适合人群：

• 需要构建高隐私、完全本地化 RAG 系统的开发者。
• 受限于内存资源，需要在边缘设备或低成本服务器上运行大规模向量检索的团队。
• 对搜索延迟敏感，且希望简化向量索引运维（无需训练、调参、重建）的工程团队。
• 需要支持实时数据删除和动态过滤的高级向量搜索应用。

上手指南：

1. 安装：

   pip install turbovec
   # 若需框架集成，例如 LangChain：
   pip install turbovec[langchain]
   

2. Python 基本用法：

   from turbovec import TurboQuantIndex
   
   # 创建索引，维度 1536，4-bit 量化
   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")
   

3. 支持删除与外部 ID 用法：

   import numpy as np
   from turbovec import IdMapIndex
   
   index = IdMapIndex(dim=1536, bit_width=4)
   # 添加带外部 ID 的向量
   index.add_with_ids(vectors, np.array([1001, 1002, 1003], dtype=np.uint64))
   
   # 搜索返回外部 ID
   scores, ids = index.search(query, k=10)
   
   # 按 ID 删除
   index.remove(1002)
   

4. Rust 基本用法：

   use turbovec::TurboQuantIndex;
   
   let mut index = TurboQuantIndex::new(1536, 4);
   index.add(&vectors);
   let results = index.search(&queries, 10);
   index.write("index.tv").unwrap();