# https://github.com/RyanCodrai/turbovec 项目说明书

生成时间：2026-06-23 00:19:15 UTC

## 目录

- [turbovec Overview & TurboQuant Algorithm](#page-1)
- [Core Rust Crate: Index Types, Encoding, and File Formats](#page-2)
- [Python Bindings & Framework Integrations](#page-3)
- [Performance, Building, Deployment & Operations](#page-4)

<a id='page-1'></a>

## turbovec Overview & TurboQuant Algorithm

### 相关页面

相关主题：[Core Rust Crate: Index Types, Encoding, and File Formats](#page-2), [Performance, Building, Deployment & Operations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/RyanCodrai/turbovec/blob/main/README.md)
- [turbovec-python/README.md](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/README.md)
- [turbovec/src/lib.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec/src/lib.rs)
- [turbovec/src/io.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec/src/io.rs)
- [turbovec-python/python/turbovec/__init__.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/__init__.py)
- [turbovec-python/python/turbovec/haystack.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/haystack.py)
- [turbovec-python/python/turbovec/langchain.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/langchain.py)
- [turbovec-python/python/turbovec/llama_index.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/llama_index.py)
- [turbovec-python/python/turbovec/agno.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/agno.py)
- [examples/downstream-smoke/src/main.rs](https://github.com/RyanCodrai/turbovec/blob/main/examples/downstream-smoke/src/main.rs)
</details>

# turbovec 概览与 TurboQuant 算法

## 1. 项目定位与核心价值

turbovec 是一个基于 Rust 实现的向量索引库，并提供 Python 绑定，底层算法来自 Google Research 提出的 **TurboQuant** —— 一种"数据无关"（data-oblivious）的量化器，能够在不进行独立训练的前提下，将高维向量压缩到每个坐标 2~4 bit，且具有接近最优的失真度。资料来源：[README.md]()、[turbovec/src/lib.rs:1-9]()。

项目的核心价值主张是极高的内存压缩比与速度优势：以 float32 存储的 1000 万条 1536 维文档语料需要约 31 GB 内存，而 turbovec 可以将其压缩到约 4 GB，并且在搜索速度上比 FAISS 更快（ARM 平台下对 FAISS `IndexPQFastScan` 领先 10%~19%，x86 平台的 4-bit 配置同样胜出）。资料来源：[README.md]()。

主要特性包括：

- **在线摄入（Online ingest）**：向量加入后立即被索引，无需训练步骤、参数调优或重建过程。资料来源：[README.md]()、[turbovec/src/lib.rs:11-31]()。
- **SIMD 加速搜索**：手写 NEON（ARM）与 AVX-512BW（x86）内核。资料来源：[README.md]()。
- **搜索时过滤**：`search()` 可接受 id 白名单或槽位位图，查询内核会直接按其过滤。资料来源：[README.md]()。
- **完全本地化**：无托管服务，数据不离开本机或 VPC。资料来源：[README.md]()。

## 2. TurboQuant 算法与文件格式

### 2.1 算法基础

TurboQuant 是 Google Research 在论文 *"TurboQuant"*（[arXiv:2504.19874](https://arxiv.org/abs/2504.19874)）中提出的量化方法。turbovec 将其工程化为可立即使用的向量索引：高维向量通过旋转矩阵降维到偶数维，再借助 Lloyd-Max 质心进行 2/3/4 bit 量化。资料来源：[turbovec/src/lib.rs:1-9]()。

代码库中关键的可调用缓存（旋转矩阵、Lloyd-Max 质心、SIMD 对齐的码字布局）通过 [`std::sync::OnceLock`] 实现**惰性初始化**：第一次调用 `search` 时支付一次性初始化成本，之后所有调用者无锁读取；用户也可以显式调用 `prepare()` 在 `add`/`load` 之后提前完成初始化。资料来源：[turbovec/src/lib.rs:33-50]()。

### 2.2 文件格式

turbovec 定义两种磁盘格式，版本均为 3（turbovec 0.6.x 引入 TQ+ per-coord 校准）：

| 格式 | 扩展名 | 魔数 | 核心负载 | 尾部附加 |
| --- | --- | --- | --- | --- |
| 量化索引 | `.tv` | `"TVPI"` | bit_width / dim / n_vectors + 打包码字 + per-vector scales | v3+ 的 TQ+ per-coord 校准 |
| 带 ID 映射的索引 | `.tvim` | `"TVIM"` | 同上 | `slot_to_id` 表（`u64` 列表） |

版本兼容策略：v2 文件透明加载，标定字段视为空；v1 文件因缺少魔数头会被拒绝并提示重建。资料来源：[turbovec/src/io.rs:1-20]()。

```mermaid
flowchart LR
    A[float32 向量] --> B[TurboQuant 编码]
    B --> C[.tv 索引文件]
    C --> D[TurboQuantIndex / IdMapIndex]
    D --> E[SIMD 距离计算]
    E --> F[Top-k 结果 + 过滤]
```

## 3. 主要组件与 API

Rust 端对外暴露的核心类型是 `TurboQuantIndex` 与 `IdMapIndex`。前者适合内部槽位编号即可满足需求的场景；后者为每个向量维护一个外部 `u64` id，支持 `remove(id)` 的 O(1) 删除与稳定的 id 映射。资料来源：[turbovec/src/lib.rs:1-31]()、[turbovec-python/README.md]()。

Python 入口从 `_turbovec` 直接导出这两个类：

```python
from turbovec import TurboQuantIndex, IdMapIndex
```

资料来源：[turbovec-python/python/turbovec/__init__.py]()。

典型用法分为三步：构造（指定 `dim` 与 `bit_width`，可选 2/4）→ 累计 `add` 向量 → 调用 `search(query, k)` 取得 `(scores, indices)`。带 id 的版本使用 `add_with_ids(vectors, ids)`，并可使用 `search(..., allowed=...)` 进行"混合检索"——即先用外部系统（SQL/BM25/ACL/时间窗口）缩小候选集合，再由 turbovec 在该集合内重排。资料来源：[turbovec-python/README.md]()。

## 4. 框架集成与生态

turbovec 提供对主流 LLM 检索框架的适配，所有适配器均通过 `IdMapIndex` 作为后端以保留稳定 id：

- **Haystack 2.x**：`TurboQuantDocumentStore` 实现 `DocumentStore` 协议，覆盖 `write/filter/delete`、`embedding_retrieval`、`save_to_disk`/`load_from_disk`、管线 `to_dict`/`from_dict`，但**未实现** BM25 稀疏检索。资料来源：[turbovec-python/python/turbovec/haystack.py:1-19]()。
- **LangChain**：`TurboQuantVectorStore` 参考 `InMemoryVectorStore` 接口，提供 `add_texts` / `aadd_texts` / `from_texts` / `afrom_texts`，并把内积相似度映射到 [0, 1] 相关性区间。资料来源：[turbovec-python/python/turbovec/langchain.py]()。
- **LlamaIndex**：将 `BaseNode` 的 `text`、`metadata`、`ref_doc_id` 与 `node_dict`（用于 `metadata_dict_to_node` 重建为完整 `BaseNode` 子类）一并存储，使检索结果可还原成 `TextNode`/`IndexNode`/`ImageNode`。资料来源：[turbovec-python/python/turbovec/llama_index.py]()。
- **Agno**：`TurboQuantVectorDb` 强制 `search_type=SearchType.vector` 与 `distance=Distance.cosine`，`bit_width` 仅接受 2 或 4，并要求 `Embedder.dimensions` 必须事先设置。资料来源：[turbovec-python/python/turbovec/agno.py]()。

在 `examples/downstream-smoke/src/main.rs` 中提供了一个端到端的最小用例：构造索引 → 写入 → 重新加载 → 搜索，作为"下游 `cargo add turbovec`"的烟雾测试，确保 build.rs 的链接指令传播正确。资料来源：[examples/downstream-smoke/src/main.rs:1-9]()。

## See Also

- 文件格式与版本迁移（见 [turbovec/src/io.rs]()）
- 框架集成（Haystack / LangChain / LlamaIndex / Agno）适配细节
- 贡献流程（见 [CONTRIBUTING.md]()）与安全策略（见 [SECURITY.md]()）

---

<a id='page-2'></a>

## Core Rust Crate: Index Types, Encoding, and File Formats

### 相关页面

相关主题：[turbovec Overview & TurboQuant Algorithm](#page-1), [Python Bindings & Framework Integrations](#page-3), [Performance, Building, Deployment & Operations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [turbovec/src/lib.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec/src/lib.rs)
- [turbovec/src/io.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec/src/io.rs)
- [turbovec/src/pack.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec/src/pack.rs)
- [turbovec/src/search.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec/src/search.rs)
- [turbovec/examples/dump_state.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec/examples/dump_state.rs)
- [turbovec-python/python/turbovec/langchain.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/langchain.py)
- [turbovec-python/python/turbovec/llama_index.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/llama_index.py)
</details>

# Core Rust Crate: Index Types, Encoding, and File Formats

## 概述

`turbovec` 是一个面向向量检索的标量量化（TurboQuant）索引库，其核心 Rust crate 同时维护两类索引对象（`TurboQuantIndex` 与 `IdMapIndex`）与两套对应的二进制文件格式（`.tv` 与 `.tvim`）。量化位宽支持 2/3/4 bits，配合 AVX-2、AVX-512BW、NEON 等 SIMD 路径实现近似最近邻（ANN）打分。Python 端的 LangChain / LlamaIndex / Haystack 等集成只持有 IdMapIndex 的二进制文件加 JSON 侧车，因此底层二进制布局存在明确的契约约束 资料来源：[turbovec/src/io.rs]()、[turbovec-python/python/turbovec/langchain.py]()。

## 索引类型

### TurboQuantIndex

`TurboQuantIndex` 是核心量化索引对象。`from_parts` 显式钉死了几条结构性不变量，例如 TQ+ 校准向量的 `shift` 与 `scale` 长度必须相等（要么为空、要么等于 `dim`），从而把"重建索引时这些字段必须自洽"提升到类型层面 资料来源：[turbovec/src/lib.rs]()。其主要字段包括：

- `bit_width: usize`：每维编码位宽（2/3/4）；
- `dim: Option<usize>`：在尚未触发编码的"懒构造"状态下可能为 `None`，落盘时记为 0；
- `n_vectors: usize`；
- `packed_codes: Vec<u8>`、`scales: Vec<f32>`；
- `tqplus_shift: Vec<f32>`、`tqplus_scale: Vec<f32>`：v3+ 引入的 per-coord 校准参数。

### IdMapIndex

`IdMapIndex` 在 `TurboQuantIndex` 之上追加一个 `slot_to_id: Vec<u64>` 表，把每个内部槽位映射回外部字符串/整数 ID，从而支撑 LangChain / LlamaIndex 集成所需的 O(1) 删除、按 `ref_doc_id` 过滤等能力 资料来源：[turbovec-python/python/turbovec/langchain.py]()、[turbovec-python/python/turbovec/llama_index.py]()。

## 编码流水线

源向量到打包字节的完整数据通路为：

1. **旋转**：使用 `rotation::make_rotation_matrix` 生成的随机正交矩阵降低各维相关性 资料来源：[turbovec/examples/dump_state.rs]()；
2. **码本**：每个维度独立的 Lloyd-Max 码本（`codebook::codebook`），共 `2^bits` 个质心 资料来源：[turbovec/examples/dump_state.rs]()；
3. **量化**：每维坐标就近映射到对应码字，得到 `bits`-wide 整数码；
4. **归一化**：每个向量维护一个 `scale`，与 `packed_codes` 一起决定最终的相似度近似；
5. **TQ+ 校准**（v3+）：按维度额外保存 shift/scale，向后兼容 v2 时该区段为空、视为恒等 资料来源：[turbovec/src/io.rs]()；
6. **打包**：`pack_blocked` 将每 `BLOCK` 个向量按字节拆成高/低半字节并以 `perm0` 交织为 FAISS 风格布局，匹配 SIMD 内核读法 资料来源：[turbovec/src/pack.rs]()；
7. **标量回退**：`deinterleave_x86_code_byte` 反向解交织，使非 x86 路径或缺少 AVX2 的虚拟机不会读到错误字节（修复 issue #106） 资料来源：[turbovec/src/pack.rs]()。

## 文件格式与持久化

### 二进制格式

库内两套格式统一由 `io.rs` 维护：

| 格式 | 承载对象 | Magic | 头/体 | 尾部 |
|------|---------|-------|-------|------|
| `.tv` | TurboQuantIndex | `TVPI` | version, bit_width, dim, n_vectors, packed_codes, scales | TQ+ shift/scale（v3+，可空） |
| `.tvim` | IdMapIndex | `TVIM` | 同 `.tv` 主体 | 追加 `slot_to_id: u64[]` |

资料来源：[turbovec/src/io.rs]()。

### 版本演进

- **v1（turbovec ≤ 0.4.3）**：无 magic，首字节即 `bit_width`，已被视为不兼容，遇到时给出"重建"提示；
- **v2（0.4.4 – 0.6.0）**：引入 magic + version；TQ+ 区段为空，按"恒等校准"透明加载，召回不变；
- **v3（0.6.x 起）**：追加 TQ+ per-coord 校准。

`dump_state` 示例工具按 `(dim, bits)` 把旋转矩阵与 Lloyd-Max 码本以裸 little-endian f32 写出（`rotation` / `boundaries` / `centroids` 三段），可被 `np.fromfile` 直接读入，用作跨实现的逐字节对照 资料来源：[turbovec/examples/dump_state.rs]()。

### Python 集成侧的侧车契约

Python 集成把"二进制 IdMapIndex + JSON 侧车"作为约定：LangChain 放在同一目录下（`index.tvim` + `docstore.json`，侧车带 `_DOCSTORE_SCHEMA_VERSION`），LlamaIndex 按用户传入的 `persist_path` 拆为 `<base>.tvim` + `<base>.nodes.json`，同样记录 `_NODES_SCHEMA_VERSION`。侧车使用纯 JSON（不依赖 pickle），因此不存在反序列化执行任意代码的风险 资料来源：[turbovec-python/python/turbovec/langchain.py]()、[turbovec-python/python/turbovec/llama_index.py]()。

### 常见失败模式

- 加载 v1 `.tv` 文件：不会崩溃，但首字节会被识别为"看起来像 v1 turbovec 文件"，并提示重建 资料来源：[turbovec/src/io.rs]()；
- `tqplus_shift.len() != tqplus_scale.len()` 或长度非 0 且非 `dim`：`from_parts` 触发断言 资料来源：[turbovec/src/lib.rs]()；
- 缺少 AVX2 的 x86 主机上若未走标量回退，会读到错误字节（issue #106），务必通过 `deinterleave_x86_code_byte` 路径解码 资料来源：[turbovec/src/pack.rs]()。

## See Also

- 仓库根 `README.md`：总体介绍与构建/基准测试说明
- `CONTRIBUTING.md`：贡献流程与集成贡献规范
- [turbovec/src/search.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec/src/search.rs)：SIMD 搜索内核与允许位掩码（`block_has_allowed`、`block_pair_has_allowed`）

---

<a id='page-3'></a>

## Python Bindings & Framework Integrations

### 相关页面

相关主题：[Core Rust Crate: Index Types, Encoding, and File Formats](#page-2), [Performance, Building, Deployment & Operations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [turbovec-python/pyproject.toml](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/pyproject.toml)
- [turbovec-python/Cargo.toml](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/Cargo.toml)
- [turbovec-python/build.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/build.rs)
- [turbovec-python/src/lib.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/src/lib.rs)
- [turbovec-python/python/turbovec/__init__.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/__init__.py)
- [turbovec-python/python/turbovec/langchain.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/langchain.py)
- [turbovec-python/python/turbovec/llama_index.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/llama_index.py)
- [turbovec-python/python/turbovec/haystack.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/haystack.py)
- [turbovec-python/python/turbovec/agno.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/agno.py)
- [turbovec-python/README.md](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/README.md)
- [README.md](https://github.com/RyanCodrai/turbovec/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/RyanCodrai/turbovec/blob/main/CONTRIBUTING.md)
</details>

# Python Bindings & Framework Integrations

## 概述与定位

turbovec 是一套基于 Rust 的在线向量量化实现（TurboQuant 论文的核心思想），通过 PyO3 暴露给 Python 作为扩展模块，并在此基础上为多个主流 LLM 编排框架提供"即插即用"的向量存储后端。其总体设计目标可以概括为三点：第一，把量化后的紧凑索引与原始文本/元数据解耦，避免反序列化代码执行风险；第二，让上层框架无需修改业务代码即可替换为量化存储；第三，对每个集成显式标注"参考实现"，确保行为一致 [README.md:1-30]()。

Python 包按可选依赖（extras）拆分为 `langchain`、`llama-index`、`haystack`、`agno` 等子模块，每个子模块对应一个独立的 VectorStore / DocumentStore 实现 [CONTRIBUTING.md:60-72]()。

## 核心绑定层：PyO3 与 Rust 端

绑定层由 `turbovec-python/src/lib.rs` 中的 `PyO3` 实现承担，对外暴露的核心类型是 `IdMapIndex`。其 `search` 方法签名采用 `#[pyo3(signature = (queries, k, *, allowlist=None))]` 形式，返回 `(scores, ids)` 二元组，分别以 `(nq, effective_k)` 形状的 `f32` 与 `uint64` 数组返回；空 allowlist 会直接抛 `ValueError`，未在索引中的 id 会抛 `KeyError` [turbovec-python/src/lib.rs:1-40]()。

`build.rs` 仅做一件关键事：调用 `pyo3_build_config::add_extension_module_link_args()`，在 macOS 上注入 `-undefined dynamic_lookup`，使得在没有 maturin 的情况下 `cargo build` 也能正确解析 `Py_True` 等解释器符号（修复 issue #92）[turbovec-python/build.rs:1-15]()。

## 框架集成层

### LangChain

`turbovec.langchain.TurboQuantVectorStore` 实现了 `langchain_core.vectorstores.VectorStore`，对外与内置的 `InMemoryVectorStore` 完全对齐：构造时可传入已有的 `IdMapIndex`，或延迟到首次 `add_texts` 时创建 [turbovec-python/python/turbovec/langchain.py:1-60]()。

搜索路径将查询嵌入到 `np.float32` 数组后走量化索引重建文档；过滤支持 dict 与 callable 两种形式，二者通过内部 `lambda` 统一求值 [turbovec-python/python/turbovec/langchain.py:120-180]()。需要特别注意的是 **MMR（最大边际相关性）搜索不被支持**，因量化后全精度向量已被丢弃，无法计算两两多样性；接口在调用时会抛出携带解释信息的 `NotImplementedError`，而不是静默退回到基类实现 [turbovec-python/python/turbovec/langchain.py:90-110]()。

### LlamaIndex

`llama_index` 模块在节点元数据上做了更细的设计：除了保留 `metadata` 与 `ref_doc_id` 用于快速过滤外，还额外存储 `node_dict`（通过 `node_to_metadata_dict` 生成的规范元数据），以便在检索时通过 `metadata_dict_to_node` 重建完整的 `BaseNode`，从而保留 `PREVIOUS` / `NEXT` / `PARENT` / `CHILD` 关系、模板字段、起止字符索引与 `mimetype` [turbovec-python/python/turbovec/llama_index.py:1-30]()。

### Haystack 与 Agno

`Haystack` 集成对照 `InMemoryDocumentStore` 校验输入形状，并把 `Document` 列表按 `DuplicatePolicy` 解析后再批量写入；持久化时把 `u64 -> doc` 字典序列化为 `[handle, data]` 对以避免 JSON 键类型损失 [turbovec-python/python/turbovec/haystack.py:1-50]()。

`Agno` 集成在语义上对齐 `LanceDb`：`upsert` 按 `content_hash` 替换整批文档；为防止"替换失败导致旧数据被销毁"（issue #89），它先捕获旧 handle、写新数据，再删除旧向量 [turbovec-python/python/turbovec/agno.py:1-50]()。

## 持久化与 Schema 版本

所有集成都遵循统一的"索引 + side-car JSON"持久化策略：`index.tvim` 由 Rust 端写入，二进制且与语言无关；`docstore.json` / `docstore.json` 之类的人类可读文件存储文档、id↔handle 映射、下一可用 `u64`、以及 `bit_width` 等元数据 [turbovec-python/python/turbovec/langchain.py:1-40]()、[turbovec-python/python/turbovec/llama_index.py:30-60]()、[turbovec-python/python/turbovec/haystack.py:30-60]()。

每个集成各自定义 `_SCHEMA_VERSION` 字段（如 LangChain 为 `1`），`load` / `from_persist_path` 在反序列化前先比对 `schema_version`，遇到未知版本立即抛 `ValueError`，从而避免向后兼容的隐式假设 [turbovec-python/python/turbovec/langchain.py:30-50]()、[turbovec-python/python/turbovec/llama_index.py:30-50]()。

## 数据流与组件关系

```mermaid
flowchart LR
    A[Python 业务代码] --> B[框架集成层<br/>langchain / llama_index / haystack / agno]
    B --> C[_dedup / _persist 工具]
    B --> D[IdMapIndex<br/>PyO3 绑定]
    D --> E[Rust 量化核心<br/>TurboQuant]
    C --> F[index.tvim]
    C --> G[docstore.json]
    F --> H[load / from_persist_path]
    G --> H
```

## 常见失败模式

| 场景 | 触发条件 | 表现 / 处理 |
|------|----------|-------------|
| 查询维度不匹配 | `queries.ncols() != index.dim` | `ValueError: query dim X does not match index dim Y` [turbovec-python/src/lib.rs:1-30]() |
| 持久化版本不兼容 | `schema_version` 不在 `_SCHEMA_COMPAT` | `ValueError: docstore.json has schema version X; this turbovec accepts ...` [turbovec-python/python/turbovec/langchain.py:30-50]() |
| 调用 MMR | `max_marginal_relevance_search` | 抛出带解释的 `NotImplementedError` [turbovec-python/python/turbovec/langchain.py:90-110]() |
| `fsspec` 文件系统 | `from_persist_path(..., fs=...)` | 显式 `NotImplementedError`（暂未支持）[turbovec-python/python/turbovec/llama_index.py:30-60]() |
| macOS 裸 `cargo build` | 缺少 `Py_True` 等符号解析 | 由 `build.rs` 注入链接参数修复（issue #92）[turbovec-python/build.rs:1-15]() |

## See Also

- [Building & Testing（构建与测试）](#)
- [Benchmarks & Methodology（基准与方法）](#)
- [Architecture Overview（架构总览）](#)

---

<a id='page-4'></a>

## Performance, Building, Deployment & Operations

### 相关页面

相关主题：[turbovec Overview & TurboQuant Algorithm](#page-1), [Core Rust Crate: Index Types, Encoding, and File Formats](#page-2), [Python Bindings & Framework Integrations](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/RyanCodrai/turbovec/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/RyanCodrai/turbovec/blob/main/CONTRIBUTING.md)
- [turbovec/src/lib.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec/src/lib.rs)
- [turbovec/src/io.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec/src/io.rs)
- [turbovec/src/search.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec/src/search.rs)
- [turbovec/build.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec/build.rs)
- [turbovec/examples/kernel_xtest.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec/examples/kernel_xtest.rs)
- [turbovec-python/README.md](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/README.md)
- [turbovec-python/build.rs](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/build.rs)
- [turbovec-python/python/turbovec/langchain.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/langchain.py)
- [turbovec-python/python/turbovec/llama_index.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/llama_index.py)
- [turbovec-python/python/turbovec/haystack.py](https://github.com/RyanCodrai/turbovec/blob/main/turbovec-python/python/turbovec/haystack.py)
</details>

# 性能、构建、部署与运维

## 概述

turbovec 是一个基于 Google Research 的 TurboQuant 算法的 Rust 向量索引实现，提供 Python 绑定并对接 LangChain、LlamaIndex、Haystack 等主流 LLM 框架。本页围绕项目的性能特征、构建流程、部署形态以及运维验证进行系统梳理，便于使用者快速完成本地构建、跨架构部署与基准回归。

## 一、性能特征

### 压缩比与召回

根据 `README.md` 的描述，1000 万文档语料在 float32 编码下占用约 31 GB 内存，turbovec 可将其压缩至约 4 GB 并保持更快搜索速度。该压缩来自 2–4 bit 每维的量化策略，体现 TurboQuant 算法 "near-optimal distortion" 的工程化结果。

### 搜索内核

在 x86_64 平台上，`turbovec/src/search.rs` 同时实现了 AVX2 与 AVX-512 两套打分内核。AVX-512 内核一次处理两个 32 字节码块，通过 `_mm512_inserti64x4` 与 `_mm512_shuffle_epi8` 在单指令对中完成查找，并通过 `FLUSH_EVERY` 间隔刷新至 f32 累加器与 top-k 堆；尾部未配对块以单次 AVX2 内层循环收尾，避免任何 masked AVX-512 逻辑。

### 基准套件

`turbovec-python/README.md` 提供了完整的基准脚本集合：

```bash
python3 benchmarks/download_data.py openai-1536   # AI 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
```

结果以 JSON 写入 `benchmarks/results/`，并可通过 `python3 benchmarks/create_diagrams.py` 重新生成图表。

## 二、构建流程

### Rust 核心库

通过 Cargo 直接构建即可：

```bash
cargo build --release
```

核心入口 `turbovec/src/lib.rs` 通过 `pub fn load` 与 `pub fn write` 完成 `.tv` 文件读写；`from_parts` 在构造时强制 `tqplus_shift.len() == tqplus_scale.len()` 的结构不变式。

### Python 绑定

`turbovec-python/build.rs` 调用 `pyo3_build_config::add_extension_module_link_args()`，在 macOS 上注入 `-undefined dynamic_lookup`，避免裸 `cargo build` 出现 "symbol(s) not found for architecture arm64" 的链接错误（issue #92）。Maturin 构建已自动注入相同参数。

### 框架集成扩展

`CONTRIBUTING.md` 指出：新增或修改 LangChain、LlamaIndex、Haystack、Agno 集成时，应在结构上与各框架内树的参考实现（`InMemoryVectorStore`、`SimpleVectorStore`、`InMemoryDocumentStore` 等）保持一致。运行对应集成测试需安装 extras：

```bash
pip install -e ".[langchain,llama-index,haystack,agno]"
```

## 三、部署形态

### 文件格式

索引持久化采用 `.tvim` 量化码本加 JSON 侧车的双文件结构。`turbovec/src/io.rs` 中 `write` 写入 `TV_MAGIC` 与版本字节 `TV_VERSION`；`load` 透明处理 v2（无 TQ+）与 v3（含 TQ+）格式，对 v1 无魔数文件以针对性错误区分。

### 集成适配

三个集成模块共享相似的持久化策略：

| 模块 | 入口文件 | 侧车文件 | 关键约束 |
| --- | --- | --- | --- |
| LangChain | `langchain.py` | `docstore.json` | 携带 `_DOCSTORE_SCHEMA_VERSION`；`bit_width` 默认 4 |
| LlamaIndex | `llama_index.py` | `{stem}.nodes.json` | 同时存储 `ref_doc_id`、`metadata`、`node_dict` |
| Haystack | `haystack.py` | `docstore.json` | 通过 `_DOCSTORE_SCHEMA_COMPAT` 支持 v1→v2 向后兼容 |

`turbovec-python/python/turbovec/langchain.py` 中的 `TurboQuantVectorStore` 提供 `add_texts`、`delete`、`from_persist_path` 等接口；`turbovec-python/python/turbovec/llama_index.py` 在存储节点时同时保留 `node_dict`，由 `metadata_dict_to_node` 重建完整的 `BaseNode`，从而保留 PREVIOUS / NEXT / PARENT / CHILD 关系以及 `start/end_char_idx` 等字段；`turbovec-python/python/turbovec/haystack.py` 镜像 `InMemoryDocumentStore` 的 `save_to_disk` / `load_from_disk` 接口，实现 Haystack 2.x `DocumentStore` 协议。

## 四、运维与验证

### 跨架构一致性

`turbovec/examples/kernel_xtest.rs` 是一个跨架构内核对齐冒烟测试。在 ARM 与 x86 上分别构建运行并对比输出文件一致性，可验证两套打分内核在相同输入下的等价性：

```bash
cargo run --release --example kernel_xtest -- <dim> <bits> <seed> > /tmp/out.txt
```

由于使用固定的 `ROTATION_SEED`，旋转计算完全确定，不引入数据集或 BLAS 后端噪声。

### 持久化安全性

三个集成模块均强调侧车文件为纯 JSON 而非 pickle，避免任意代码反序列化风险。`langchain.py` 的 `from_persist_path` 显式拒绝 `fsspec` 文件系统并提示需传入本地路径。

### 协作约定

`CONTRIBUTING.md` 明确：每个 PR 一个逻辑变更；提交信息采用短祈使句标题 + 解释 *why* 的正文；引用 issue 时使用 `Closes #N`；`Co-Authored-By:` 工具 trailer 可保留；仅维护者合并至 `main`。

## 另请参阅

- TurboQuant 论文（[arXiv:2504.19874](https://arxiv.org/abs/2504.19874)）
- RaBitQ 论文（[arXiv:2405.12497](https://arxiv.org/abs/2405.12497)）

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：RyanCodrai/turbovec

摘要：发现 20 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Proposal: official Node.js binding (turbovec-node)。

## 1. 安装坑 · 来源证据：Proposal: official Node.js binding (turbovec-node)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: official Node.js binding (turbovec-node)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/85 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：TurboVec on Snowpark Container Services (SPCS)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：TurboVec on Snowpark Container Services (SPCS)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/95 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 安全/权限坑 · 来源证据：Add insertion + removal speed benchmarks to benchmarks/suite/

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add insertion + removal speed benchmarks to benchmarks/suite/
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/65 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 安全/权限坑 · 来源证据：Public Read/Write I/O API + pub TurboQuantIndex::from_parts

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Public Read/Write I/O API + pub TurboQuantIndex::from_parts
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/70 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 安装坑 · 来源证据：Proposal: Swift / macOS binding (turbovec-swift)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: Swift / macOS binding (turbovec-swift)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/86 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 6. 安装坑 · 来源证据：TQ+ calibration: silent identity-freeze on small first add; fit from a cumulative warm-up sample

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：TQ+ calibration: silent identity-freeze on small first add; fit from a cumulative warm-up sample
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/107 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 7. 安装坑 · 来源证据：x86_64 scalar fallback (no AVX2 at runtime) returns incorrect results: reads perm0-interleaved layout as if sequential

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：x86_64 scalar fallback (no AVX2 at runtime) returns incorrect results: reads perm0-interleaved layout as if sequential
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/106 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 8. 安装坑 · 来源证据：✨ Node.js / TypeScript bindings (turbovec-node)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：✨ Node.js / TypeScript bindings (turbovec-node)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/111 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 9. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/RyanCodrai/turbovec | README/documentation is current enough for a first validation pass.

## 10. 运行坑 · 来源证据：bug: agno insert() orphans vectors on intra-batch duplicate derived doc_ids

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug: agno insert() orphans vectors on intra-batch duplicate derived doc_ids
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/104 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 11. 维护坑 · 来源证据：Docs: API reference drift around bit widths and file formats

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Docs: API reference drift around bit widths and file formats
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/101 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 12. 维护坑 · 来源证据：proposal: bindings for ruby

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：proposal: bindings for ruby
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/94 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 13. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/RyanCodrai/turbovec | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/RyanCodrai/turbovec | no_demo; severity=medium

## 15. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/RyanCodrai/turbovec | no_demo; severity=medium

## 16. 安全/权限坑 · 来源证据：Security fixes: integer overflow on .tv load + Python NaN query validation

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security fixes: integer overflow on .tv load + Python NaN query validation
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/105 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 17. 安全/权限坑 · 来源证据：ask about project

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ask about project
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/110 | 来源类型 github_issue 暴露的待验证使用条件。

## 18. 安全/权限坑 · 来源证据：can not build on mac arm when simple run cargo build

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：can not build on mac arm when simple run cargo build
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/92 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 19. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/RyanCodrai/turbovec | issue_or_pr_quality=unknown

## 20. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/RyanCodrai/turbovec | release_recency=unknown

<!-- canonical_name: RyanCodrai/turbovec; human_manual_source: deepwiki_human_wiki -->