Turboquant Rs

TurboQuant RS

Google的Rust实现 涡轮量化 用于压缩高维嵌入向量的算法。实现 6.2倍压缩 384维，无需校准，近乎最佳的失真保证。

use turboquant::{TurboIndex, SearchResult};

let mut index = TurboIndex::create("./my_index", 384, 42, 99)?;
index.insert(0, &embedding)?;

let results: Vec = index.search(&query, 10);

运作原理

TurboQuant分三步压缩向量：

Input vector (384 × f32 = 1,536 bytes)
    │
    ▼
┌───────────────────────────────────────┐
│  Step 1: Random Orthogonal Rotation   │  Spreads energy evenly — each
│  Q × x (deterministic from seed)      │  coordinate → N(0, 1/√d)
└───────────────────┬───────────────────┘
                    │
                    ▼
┌───────────────────────────────────────┐
│  Step 2: Lloyd-Max Scalar Quantize    │  MSE-optimal centroids for
│  b bits per dimension (default b=4)   │  the Gaussian distribution
└───────────────────┬───────────────────┘
                    │ residual = rotated − reconstructed
                    ▼
┌───────────────────────────────────────┐
│  Step 3: QJL Residual Correction      │  sign(S × residual)
│  1-bit sign per dimension             │  → unbiased IP estimator
└───────────────────┬───────────────────┘
                    │
                    ▼
Output: 248 bytes (6.2x compression, 5.17 bits/dim)

旋转解相关坐标，因此每个坐标都遵循一个已知的高斯分布。Lloyd-Max找到了该分布的可证明最优量化质心（在信息理论下限的2.7倍以内）。QJL校正残差，使内积估计器 无偏见的.

交互式演示： 打开 docs/turbo-quant-visualizer.html 在浏览器中查看算法在3D矢量上的动画效果——通过旋转、量化和QJL校正以及轨道控制。

压缩数

在384个暗随机单位向量上测量（来自 cargo test --test compression_claims):

对于384维的10000个嵌入件：

• 生浮子32： 15.0毫巴
• TurboQuant 4位： 2.4 MB

快速开始

作为依赖

[dependencies]
turboquant = { git = "https://github.com/coderjack/turboquant-rs" }

高级：TurboIndex

创建索引，插入向量，搜索：

use turboquant::{TurboIndex, SearchResult};

// Create a persistent index on disk (default: 4-bit Lloyd-Max)
let mut index = TurboIndex::create(
    "./my_index",
    384,  // embedding dimension
    42,   // rotation seed (any u64, deterministic)
    99,   // QJL seed (any u64, deterministic)
)?;

// Or choose a specific bit width: 1–8
let mut index = TurboIndex::create_with_bits("./my_index", 384, 42, 99, 3)?;

// Insert embeddings with unique IDs
index.insert(0, &embedding_vec)?;
index.insert(1, &another_vec)?;

// Search: returns top-k by approximate inner product
let results: Vec = index.search(&query_vec, 10);
for r in &results {
    println!("id={} score={:.4}", r.id, r.score);
}

// Maintenance
index.delete(1)?;     // soft-delete
index.compact()?;      // rebuild without deleted vectors

// Re-open from disk in another process
let index = TurboIndex::open("./my_index")?;

低液位：LloydMax压缩机

无需索引即可直接访问压缩：

use turboquant::{LloydMaxCompressor, PreparedQuery};

let compressor = LloydMaxCompressor::new(
    384,  // dimension
    42,   // rotation seed
    99,   // QJL seed
    4,    // bits per dimension
);

// Compress a vector
let compressed = compressor.compress(&vector);
println!("{} bytes", compressed.byte_size()); // 248

// Decompress (Lloyd-Max reconstruction, no QJL)
let reconstructed = compressor.decompress(&compressed);

// Similarity search: prepare query once, score many candidates
let prepared: PreparedQuery = compressor.prepare_query(&query);
let score = compressor.similarity_prepared(&prepared, &compressed);

prepare_query 进行一次O（d^2）旋转+QJL投影。每 similarity_prepared 呼叫仅为O（d）。

例子

基本指标（无外部存款）

cargo run -p turboquant --example basic_index

使用合成向量创建索引，从磁盘插入、搜索、删除、压缩和重新打开。

使用本地ONNX模型进行语义搜索

使用端到端语义搜索 全迷你LM-L6-v2 （384昏暗）：

# 1. Export the model to ONNX (one-time)
pip install optimum[exporters]
optimum-cli export onnx \
    --model sentence-transformers/all-MiniLM-L6-v2 \
    models/all-MiniLM-L6-v2

# 2. Run the example
cargo run -p turboquant --example semantic_search -- \
    --model-dir models/all-MiniLM-L6-v2

建筑

turboquant-rs/
  crates/
    turboquant/          Core compression library
      src/
        compression/
          rotation.rs      Step 1: Random orthogonal rotation (Gram-Schmidt)
          lloyd_max.rs     Step 2: Lloyd-Max scalar quantization (default)
          polarquant.rs    Step 2 alt: Polar coordinate quantization
          qjl.rs           Step 3: QJL 1-bit residual correction
        turboquant.rs      Pipeline composition (LloydMaxCompressor + TurboQuantCompressor)
        index.rs           TurboIndex: insert, delete, search, compact
        storage.rs         File-based vector storage
        lib.rs             Public API re-exports
      examples/
        basic_index.rs     Minimal usage example
        semantic_search.rs End-to-end with ONNX embedding model
      tests/
        compression_claims.rs  Property tests + baseline comparisons
        head_to_head.rs        Lloyd-Max vs PolarQuant benchmark

依赖项

核心图书馆有 零ML依赖 --纯数学+压缩：

• ndarray --矩阵运算
• rand, rand_chacha, rand_distr --确定性RNG
• serde, bincode --序列化
• thiserror --错误类型

ONNX运行时和令牌化器仅是开发依赖项，由 semantic_search 例子。

运行测试

# All tests
cargo test -p turboquant

# With verbose output (shows compression tables, recall numbers)
cargo test -p turboquant --test compression_claims -- --nocapture

# Lloyd-Max vs PolarQuant comparison
cargo test -p turboquant --test head_to_head -- --nocapture

参考文献

该项目实现了以下算法：

@article{zandieh2025turboquant,
  title={TurboQuant: Online Vector Quantization with Near-optimal Distortion Rate},
  author={Zandieh, Amir and Daliri, Majid and Hadian, Majid and Mirrokni, Vahab},
  journal={arXiv preprint arXiv:2504.19874},
  year={2025}
}

@article{zandieh2024qjl,
  title={QJL: 1-Bit Quantized JL Transform for KV Cache Quantization with Zero Overhead},
  author={Zandieh, Amir and Daliri, Majid and Han, Insu},
  journal={arXiv preprint arXiv:2406.03482},
  year={2024}
}

@article{han2025polarquant,
  title={PolarQuant},
  author={Han, Insu and Kacham, Praneeth and Karbasi, Amin and Mirrokni, Vahab and Zandieh, Amir},
  journal={arXiv preprint arXiv:2502.02617},
  year={2025}
}

谷歌研究博客文章： TurboQuant：用极端压缩重新定义AI效率

许可证

根据以下任一方式获得许可

• Apache许可证，版本2.0(特许通行证 或 )
• MIT许可证(许可证-麻省理工学院 或 )

由您选择。