turboquant.cpp 是 TurboQuant 算法的开源 C++ 实现，TurboQuant 是一种接近最优的在线向量量化算法。其理论基础为论文《TurboQuant: Online Vector Quantization with Near-optimal Distortion Rate》。该库的目标是在无需预处理、训练或码本学习的条件下，将高维浮点向量压缩为低位宽整数（每个坐标 1-4 比特），并尽可能保留内积和距离信息。向量在到达时独立量化，适合流式或在线场景。
主要能力方面，turboquant.cpp 提供两种量化器。QuantizerMSE 最小化重建误差（均方误差）；QuantizerProd 提供低方差的无偏内积估计。两者均能达到信息论下界常数因子（约 2.7 倍）以内的失真。对于单位范数向量，当比特宽度为 b 时，理论保证有所描述，但资料未给出具体失真数值公式。压缩比方面，以 fp32 大小对比比特打包后的线格式（索引加范数元数据），在 Apple M4 Max 单线程环境下，使用 Bazel 构建优化版运行基准测试，可观察覆盖维度 d=256/768/1536 和比特宽度 b=1-4 的完整扫描。吞吐量受限于稠密的 d×d 旋转矩阵乘法，因此复杂度为 O(d^2) 且几乎与比特宽度无关。
使用方式上，项目使用 Bazel 构建，依赖 Eigen 3.4，通过 Bazel 中央注册表自动解析，无需手动安装。运行示例可通过 bazel run -c opt //:turboquant_benchmark 执行基准测试。若要在其他 Bazel 项目中使用 turboquant，需在 MODULE.bazel 中添加依赖，并使用 @turboquant 作为依赖项。
可重现性方面，使用相同（维度、比特宽度、种子）构建的量化器在所有支持的平台上产生相同的编码。旋转和 QJL 投影通过可移植的 Box-Muller 采样器在 std::mt19937 的整数上生成，而非使用 std::normal_distribution，因为后者算法在 C++ 标准中未指定（libc++ 和 libstdc++ 从同一引擎返回不同序列）。tests/determinism_test.cpp 用黄金哈希固定输出，并在 Linux 和 macOS 的 CI 上运行。turboquant::kAlgorithmVersion 会在输出变化时更改。如果持久化编码，应连同（维度、比特宽度、种子）一起记录版本，并拒绝来自其他版本的编码。
限制包括：仅支持比特宽度 1-4（预计算码本），扩展到更高比特宽度需要针对 Beta 分布解决 Lloyd-Max 优化；内存中存储完整的 d×d 旋转矩阵，大维度下可能占用较多内存，随机 Hadamard 变换可将其降至 O(d log d)；尚无 SIMD 优化，量化循环可用 AVX2/AVX-512 向量化。
