turbovec 是用 Rust 编写的开源进程内向量索引，具有 Python 绑定。它实现了 Google Research 的 TurboQuant 方法来压缩密集向量，而无需单独的代码本训练阶段，然后使用特定于体系结构的 SIMD 内核搜索打包代码。它的实际吸引力是在线摄取、2 位或 4 位存储、持久性、稳定的外部 ID、删除支持、允许列表过滤的搜索和通用 RAG 框架的适配器的组合。
正确分类很重要。 turbovec 是一个索引库，而不是托管矢量数据库或完整的检索服务。它本身并不提供分布式复制、多节点分片、备份、身份验证、租户管理、网络 APIs、混合词法搜索、可观察性或控制平面。团队获得本地控制和内存效率，以换取拥有那些周围的关注点。
TurboQuant 压缩的工作原理
其基本原理是随机正交旋转使高维单位向量的坐标遵循可预测的分布。 turbovec 首先将每个向量的范数与其方向分开。它应用一个共享的随机旋转，然后使用预先计算的 Lloyd–Max 存储桶量化旋转坐标。两位为每个坐标提供四个值；四位提供十六个。代码是位打包的，每个向量的校正消除了量化引入的系统内积收缩。
该项目添加了 TQ+ 校准：在第一次添加时，它使用经验分位数估计每个坐标的偏移和比例，然后冻结这些值以供以后摄取。这与传统的产品量化训练不同，但第一批会影响校准。因此，一个微小的或不具代表性的首次添加可能是一个糟糕的生产初始化。用代表性样本作为索引种子并测试分布漂移。
| 舞台 | 存储或计算 | 操作后果 |
|---|---|---|
| 标准化 | 单位方向加原范数 | 在量化角度结构的同时保留幅度 |
| 随机轮换 | 共享正交变换 | 使任意输入数据的坐标分布可预测 |
| TQ+ 校准 | 第一次添加时学习的每坐标位移和比例 | 改善有限/低维行为；需要代表性初始化 |
| Lloyd–Max 量化 | 2 位或 4 位坐标代码 | 数据集相关的召回损失导致大量内存减少 |
| 长度修正 | 每个向量一个标量 | 纠正向下偏差的内积估计 |
| SIMD 搜索 | 对打包代码进行旋转查询和查找表评分 | 避免完全减压；性能取决于CPU架构 |
没有营销捷径的记忆数学
1,536 维 float32 向量使用 6,144 字节作为原始坐标。其坐标代码在元数据之前需要 2 位 384 字节或 4 位 768 字节。理论上，坐标有效负载减少了 16 倍或 8 倍。该存储库的标题称，一个包含 1000 万个文档的 float32 语料库需要大约 31 GB 的空间，大约可以容纳 4 GB 的空间；该示例反映了特定的维度和表示形式，不应推广到每个语料库。
容量规划必须添加外部 ID、每个向量校正/规范值、校准数据、对齐、分配器开销、删除的槽、应用程序元数据、查询缓冲区和原始文档存储。嵌入很少是 RAG 内存的全部。加载实际持久索引并提供并发查询后测量驻留集大小。
API 支持什么
将 numpy 导入为 np
从 turbovec 导入 IdMapIndex
索引 = IdMapIndex(dim=1536，bit_width=4)
index.add_with_ids(向量.astype(np.float32), ids.astype(np.uint64))
分数，result_ids = index.search(query.astype(np.float32), k=10)
索引.删除(document_id)
索引.write(“语料库.tvim”)
恢复 = IdMapIndex.load("corpus.tvim")Python API 故意拒绝非 float32 向量，而不是默默地转换它们。稳定的 ID 很重要，因为内部槽在删除和维护后可能会发生变化。持久性使本地重启变得可行，但应用程序仍然需要原子发布、校验和、备份/版本策略以及跨库升级的兼容性测试。
过滤检索是一个有意义的差异化因素
对于多租户、时间窗口或权限感知检索，应用程序可以首先从 SQL、BM25、ACL 服务或其他系统生成允许的 ID 集，然后要求 turbovec 仅对这些候选者进行排名。过滤发生在 SIMD 路径内部，粒度为 32 个向量块。可以跳过空块，并且在堆插入之前拒绝不允许的槽，因此选择性过滤器可以避免大量密集评分工作。
这比检索全局 top-k 并丢弃未经授权的结果要好，后者可能返回太少的有效文档并且可能泄漏排名信息。正确构建允许列表、将其绑定到经过身份验证的租户并测试空的、微小的、巨大的和快速变化的集合仍然是调用者的责任。切勿使用元数据过滤作为最终文档获取的唯一授权检查。
如何阅读已发布的基准
| 索赔 | 已发布的测试边界 | 尚待证实的是什么 |
|---|---|---|
| 回忆与 FAISS PQ 的竞争 | 100K个向量，k=64； OpenAI 尺寸 1536/3072 和 GloVe 尺寸 200；匹配比特率 | 您的嵌入模型、语料库分布、k、度量和相关性标签 |
| 在 ARM 上速度提高 10–19% | Apple M3 Max 针对存储库配置中的 FAISS IndexPQFastScan | 其他 Apple 芯片、并发、热状态和生产过滤器 |
| 有竞争力的 x86 速度 | 至强铂金 8481C； 4 位情况下报告获胜，在某些 2 位情况下略有损失 | 您的 CPU 代数、AVX 路径、内核、NUMA 和查询批处理 |
| 无需训练/重建 | 具有首次添加 TQ+ 校准和在线添加的已知分布量化器 | 不具代表性的第一批或大的分配变化的影响 |
| 过滤搜索避免过度获取 | 允许列表处理内部块评分和堆插入 | 端到端 SQL/ACL 成本和最坏情况非选择性过滤器 |
比较基线是 FAISS 指数PQ/IndexPQFastScan，不是每个 FAISS 索引类型。平面精确搜索、HNSW、IVF-PQ、GPU 索引和托管数据库解决了召回率、延迟、内存和操作曲线上的不同点。首先复制存储库基准，然后一次替换一个因素您的数据和验收目标。
有用的 RAG 评估协议
- 冻结嵌入。 使用生产计划中的精确模型、标准化、尺寸和距离约定。
- 创建基本事实。 使用可信的平面实现计算精确的前 k 个邻居，并单独维护任务相关性判断。
- 测试两个位宽。 使用 float32 或精确搜索比较 2 位和 4 位，而不仅仅是相互比较。
- 对查询进行分层。 包括常见、罕见、多语言、短、长、重复和域外案例。
- 运动摄入。 使用代表性批次进行初始化、附加后续分布、删除 ID、持久化、重新加载并验证确定性行为。
- 基准过滤器。 测量 0%、0.1%、1%、10%、50% 和 100% 覆盖率的无过滤器和允许列表，包括对抗性块布局。
- 负载测试。 记录实际并发时的 p50/p95/p99 延迟、吞吐量、CPU 利用率、常驻内存和尾部行为。
- 评估答案。 衡量检索召回、重新排序质量、引用正确性和最终答案的成功率。仅当应用程序结果存活下来时，更快的近似邻居才有价值。
决策指标
| 公制 | 定义 | 建议报告 |
|---|---|---|
| 回忆@k | 通过近似搜索恢复精确的前 k 个邻居 | 按数据集切片、位宽和过滤器选择性 |
| 任务回忆 | 检索到所需支持文档的查询 | 比单独的向量相邻重叠更有意义 |
| 每个向量的内存 | 处理 RSS 增量/加载可搜索向量 | 包括 ID、已删除的槽和元数据开销 |
| 尾部延迟 | p95/p99端到端查询时间 | 在实际并发和白名单混合情况下 |
| 更新成本 | 添加、删除、保存和重新加载的时间和峰值内存 | 包括首次添加校准和崩溃恢复 |
| 每个接受的查询的成本 | 基础设施加工程运营/正确的任务结果 | 与 FAISS 和托管替代方案进行比较 |
框架集成
该存储库记录了 LangChain、LlamaIndex、Haystack 和 Agno 的适配器，这些适配器替换了内存中的引用存储，同时保留了熟悉的界面。这可以快速进行概念验证，但“插入”指的是公共软件表面——不完全相同的评分、过滤、删除、持久性、线程或失败语义。在部署之前运行每个框架的检索测试并固定兼容版本。
替代方案
| 选项 | 更喜欢什么时候 | 权衡 |
|---|---|---|
| turbovec | 进程内本地搜索、极限压缩、在线添加和白名单过滤适合工作负载 | 您拥有服务、复制和操作控制权 |
| FAISS | 您需要成熟的精确、IVF、PQ、HNSW 或 GPU 索引选择 | 配置和培训可以更多地参与；内存因索引而异 |
| hnswlib | 高召回率和低延迟图形搜索比紧凑存储更重要 | 图形开销可能会消耗更多内存 |
| Qdrant、Weaviate 或 Milvus | 需要网络服务、元数据过滤器、复制和操作 | 比小型嵌入式库更多的基础设施和内存 |
| 托管矢量数据库 | 团队需要托管扩展、备份、身份验证和支持 | 经常性成本、数据驻留和供应商依赖性 |
| PostgreSQL 与 pgvector | 向量必须靠近关系数据和现有操作 | 可能与大规模的专门压缩索引不匹配 |
限制和生产风险
- 近似压缩可以改变最近邻顺序，特别是在激进的位宽度或低维度上。
- CPU 特定内核意味着基准测试结果不应在 ARM、AVX2 和 AVX-512 硬件之间传输。
- 首先添加校准、改变嵌入模型和语料库漂移需要显式迁移测试。
- 本地部署使向量处于您的控制之下，但不会自动添加加密、访问控制或安全备份。
- 除非刻意设计服务边界和恢复策略，否则进程内崩溃会影响主机应用程序。
- 该项目正在不断发展；引脚发布、检查变更日志/安全指南并验证持久索引兼容性。
常见问题
turbovec 是矢量数据库吗？
不，它是一个向量索引库。应用程序必须根据需要提供文档存储、网络、授权、复制、监控和生命周期操作。
是否需要离线训练步骤？
它避免了传统的码本训练并支持在线添加。 TQ+ 在第一次添加期间确实校准每个坐标值，因此初始化批处理仍然值得关注。
我应该选择 2 位还是 4 位？
当内存是绑定约束并且您测量的任务回忆仍然可以接受时，请使用 2 位。四位通常可以以大约两倍的坐标代码存储来购买更高的保真度。对两者进行基准测试。
过滤搜索是否能加强租户安全？
它可以有效地将排名限制在允许列表中。应用程序必须构建正确的列表并在返回源内容之前重新检查授权。
其 FAISS 速度声明是否通用？
不会。已发布的结果涵盖指定硬件、数据集、尺寸、位宽和 FAISS PQ/FastScan 配置。 x86 2 位结果包括 FAISS 更快的情况。
可以气隙吗？
该索引在本地运行，不需要托管服务。完整的气隙 RAG 堆栈还需要本地嵌入、文档、包/模型来源和受控更新。
主要来源
- turbovec 官方存储库和基准文档
- turbovec API 参考
- 可重复的基准测试脚本和结果
- TurboQuant 研究论文
- RaBitQ 引用长度校正的论文
- FAISS FastScan 技术参考
- turbovec Python 包
- turbovec Rust 箱子
上次审核日期为 2026 年 7 月 25 日。除非另有说明，否则性能声明的范围仅限于存储库的已发布设置。在采用之前在您的语料库、嵌入模型、硬件和过滤器分布上进行复制。
