【免费下载链接】turboquant_plus项目地址https://gitcode.com/gh_mirrors/tu/turboquant_plus点击查看免费下载本文以仓库根目录的 PLAN.md 实施计划为主体结合 turboquant/ 包的完整源码、tests/ 测试与 benchmarks/ 演示脚本系统讲解如何从零实现 ICLR 2026 论文 TurboQuant 的 KV Cache 压缩包括随机旋转、PolarQuant 标量量化、QJL 残差纠偏、畸变界验证、KV 张量集成与性能优化。读完你不仅能复现论文的压缩流程还能直接在本仓库的 Python/NumPy 参考实现上做二次研究与集成实验。一、论文背景与项目定位TurboQuant 是 Google Research 提出的在线向量量化Online Vector Quantization方案论文信息如下内容来自 PLAN.md标题TurboQuant: Online Vector Quantization with Near-optimal Distortion Rate作者Amir Zandieh, Majid Daliri, Majid Hadian, Vahab Mirrokni会议ICLR 2026arXiv 编号2504.19874本仓库turboquant_plus的目标非常明确不依赖任何推理引擎用纯 Python/NumPy 从零实现 TurboQuant 的量化与反量化使其能够对 KV cache 张量进行压缩与解压对照论文给出的畸变界distortion bounds验证正确性为后续接入 llama.cpp 或 MLX 等推理引擎提供参考实现。按 README.md 的说明该仓库是 TurboQuant 研究的研究大本营research homePython 参考实现、验证文档与基准数据都存放在这里验证成熟的部分会以小补丁形式逐步合入上游引擎。阅读本文时你可以同时对照 README.md 中的架构图与 docs/papers 下的系列实验论文形成计划 → 实现 → 验证 → 上游化的完整闭环。二、总体架构三个算法如何组合成一个压缩器TurboQuant 本质上是三个算法的叠加随机旋转 最优标量量化PolarQuant 1-bit Johnson-Lindenstrauss 变换QJL。PLAN.md 给出的数据流如下Input vector x ∈ R^d │ ▼ ┌─────────────────┐ │ PolarQuant │ Random rotation → Beta-distributed coordinates │ (b-1 bits) │ → optimal scalar quantization per coordinate └────────┬────────┘ │ quantized residual ▼ ┌─────────────────┐ │ QJL │ 1-bit sign quantization of residual │ (1 bit) │ via Johnson-Lindenstrauss Transform └────────┬────────┘ │ ▼ TurboQuant output: (indices, qjl_signs, residual_norm) Total: b bits per coordinate理解这条流水线的关键随机旋转将一个任意方向的向量旋转到各坐标独立、分布已知的坐标系使每个坐标可以独立做最优标量量化PolarQuantb-1 bit负责主压缩追求 MSE 最优QJL1 bit对残差做符号量化负责消除 PolarQuant 重建的偏置bias让内积估计保持无偏。合计 b bits/坐标。对应到源码三个算法分别落在 turboquant/rotation.py、turboquant/polar_quant.py、turboquant/qjl.py并在 turboquant/turboquant.py 中组装成完整流水线。一个必须了解的仓库事实QJL 在生产中的取舍需要提前说明的是README.md 明确记录了一个关键实验结论生产环境最终丢弃了 QJLK 和 V 都不再用。原因是 QJL 消除重建偏置的同时放大了方差而 softmax 会把这种方差放大成注意力噪声README 记载了五个独立团队buun、scos-lab、Arclabs001 等的一致验证结果详见 docs/papers/turbo4-resurrection.md。因此仓库中QJL与TurboQuant带 QJL 的完整版两个类被定位为论文复现与研究用途而生产/集成侧推荐使用TurboQuantMSEV cache或在 K 上直接用 48 bit 的 PolarQuant。本文仍以 PLAN.md 的完整算法为主线因为它要求实现论文全貌但会在相应小节如实标注这一仓库结论避免读者把研究实现误当生产最佳实践。三、Phase 1核心算法实现NumPy这是 PLAN.md 的主体共 5 个任务。以下每个任务都先讲计划要求再落到仓库源码。Task 1.1 — 随机旋转矩阵生成计划要求PLAN.md生成正交随机旋转矩阵 Π ∈ R^(d×d)用随机高斯矩阵的 QR 分解获得 Haar 分布旋转给定种子必须确定可复现大 d 时考虑结构化旋转Hadamard 随机符号翻转把复杂度从 O(d²) 降到 O(d log d)。仓库实现位于 turboquant/rotation.py提供两套旋转稠密 Haar 旋转random_rotation_dense生成标准高斯矩阵 Gnp.linalg.qr(G)取正交因子 Q再用np.sign(np.diag(R))修正列符号使其服从 Haar 分布最后用np.linalg.slogdet检查行列式并把 det 修正为 1保证是旋转而非反射。注意它用slogdet而非det是因为大 d 下行列式会溢出。import numpy as np from turboquant.rotation import random_rotation_dense rng np.random.default_rng(42) Pi random_rotation_dense(d128, rngrng) # 正交阵det 1快速结构化旋转random_rotation_fast生成两组随机符号向量 signs1/signs2并把维度补齐到 2 的幂padded_d旋转等价于D2 H D1 x其中 H 是归一化 Hadamard 矩阵。应用时用 fast_walsh_hadamard_transformO(d log d) 蝶形运算而不是稠密矩阵乘apply_fast_rotation_batch 提供批量版本的向量化蝶形实现。这正是 PLAN.md 中 Phase 4 Task 4.1 的提前落地。Task 1.2 — PolarQuant 码本构造计划要求PLAN.md对位宽 b 计算 2^b 个 MSE 最优质心论文对高维给出闭式解b1 质心为±√(2/πd)b2 为{±0.453/√d, ±1.51/√d}一般 b 用 Lloyd 算法迭代求解大 d 可用高斯近似质心存为有序数组以支持快速最近邻查找。原理随机旋转后每个坐标服从 Beta(d/2, d/2)[-1/√d, 1/√d] 上大 d 时收敛到 N(0, 1/d)因此可以对每个坐标独立做最优标量量化。仓库实现位于 turboquant/codebook.pyoptimal_centroidsb1、b2 直接用论文闭式解b≥3 走 _lloyds_gaussian对 N(0, 1/d) 做 100 轮 Lloyd 迭代区间条件期望用解析公式更新nearest_centroid_indices对有序质心取相邻质心中点作为边界用np.searchsorted做向量化最近邻查找复杂度 O(n log k) 而非 O(n·k)。from turboquant.codebook import optimal_centroids, nearest_centroid_indices centroids optimal_centroids(bit_width3, d128) # 8 个有序质心 idx nearest_centroid_indices(y, centroids) # 逐坐标最近质心索引Task 1.3 — MSE 最优 TurboQuantAlgorithm 1计划给出的算法PLAN.mdquantize_mse(x, Π, codebook)y Π x→ 每个坐标取最近质心 → 返回 b-bit 索引dequantize_mse(idx, Π, codebook)索引查质心 →x̃ Π.T ỹ。仓库中该算法由 turboquant/polar_quant.py 的PolarQuant类实现且做了两个重要扩展扩展一范数提取与重标定polar_quant.py。论文第 5 页明确要求以浮点精度存储 L2 范数并在反量化时重标定因为真实 KV cache 向量不是单位范数而码本是按单位范数向量校准的。实现流程提取范数 → 归一化 → 旋转 → 量化反量化时逆旋转后乘回原范数。扩展二范数修正norm correctionpolar_quant.py。量化会在旋转域中压缩重建向量的范数norm_correctionTrue时先把旋转域重建向量重归一化到单位范数再逆旋转从而消除这一系统性偏差。测试 tests/test_turboquant.py 专门验证了开启/关闭该修正会得到不同重建结果但索引与范数一致。from turboquant.polar_quant import PolarQuant pq PolarQuant(d128, bit_width2, seed42, norm_correctionTrue) indices, norms pq.quantize(x) # x: (d,) 或 (batch, d) x_hat pq.dequantize(indices, norms) # 重建形状与输入一致类中还提供 quantize_and_residual一次性返回索引、范数与残差r x - dequantize(indices, norms)这正是完整 TurboQuant 第二级 QJL 的输入。Task 1.4 — QJL量化 Johnson-Lindenstrauss 变换计划要求PLAN.md生成随机投影矩阵 S ∈ R^(d×d)元素 ~ N(0,1)量化qjl sign(S r)→ {1, -1}^d反量化x̃_qjl √(π/2) / d * gamma * S.T qjlgamma ||r||₂ 作为元数据存储。仓库实现位于 turboquant/qjl.py有两处与计划草稿不同的工程化处理以实际代码为准正交化投影矩阵qjl.pyQR 分解后按np.sign(np.diag(R))修正符号得到正交 S并断言||S Sᵀ − I||_F 1e-10。正交性是无偏估计E[⟨x̂, y⟩] ⟨x, y⟩与E[||x̂||²] (π/2)·||x||²成立的前提论文 Theorem 2缩放系数按 √d 而非 dqjl.py实际反量化为x̂ √(π/2)/√d · ||r|| · Sᵀ · signs与 PLAN.md 草稿中的1/d不同源码注释给出了完整推导。此外 QJL 反量化还暴露了一个shrinkage参数默认1.0是论文的无偏估计量2/np.pi ≈ 0.6366是 MMSE 最优的收缩系数推导见 qjl.py它带来偏置但显著降低 MSE适合对 MSE 敏感的注意力分数修正场景。from turboquant.qjl import QJL qjl QJL(d128, seed42) signs, residual_norm qjl.quantize(r) # signs: int8 {1, -1} r_hat qjl.dequantize(signs, residual_norm) # 默认无偏估计 r_hat_mmse qjl.dequantize(signs, residual_norm, shrinkage2/np.pi)Task 1.5 — 完整 TurboQuantAlgorithm 2组合两者计划给出的两阶段流程PLAN.mdquantizeMSE 量化 (b-1) bit → 残差r x - dequantize_mse(idx)→ QJL 量化残差 → 存残差范数dequantizeMSE 重建 QJL 残差重建 → 求和。仓库实现在 turboquant/turboquant.py 的TurboQuant类docstring 明确标注为Algorithm 2 from the paper — Inner Product TurboQuantfrom turboquant.turboquant import TurboQuant tq TurboQuant(d128, bit_width3, seed42) # b 21-bit PolarQuant 1-bit QJL compressed tq.quantize(x) # CompressedVector x_hat tq.dequantize(compressed)几个实现细节值得注意位宽约束bit_width 2直接抛ValueErrorturboquant.py因为 1 bit 给 PolarQuant 后 QJL 就没有余量了——1-bit 场景应直接用 QJL种子分工PolarQuant 用seedQJL 用seed 1000turboquant.py保证两级随机矩阵独立输出容器CompressedVectordataclassturboquant.py打包 mse 索引、(b-1) bit、原始范数、QJL 符号与残差范数、总位宽内存与压缩比核算compressed_size_bits 按d*b 32bits/向量 估算32 bit 是 float32 残差范数compression_ratio 相对原始 fp16 计算压缩倍数。配套的TurboQuantMSE类turboquant.py是不带 QJL 的 Algorithm 1 纯 MSE 版用于 V cache所有 b 个 bit 全部投入 MSE 量化存储开销更小无需 QJL 符号位。四、Phase 2验证与基准Task 2.1 — 单元测试与畸变界验证计划要求PLAN.md往返测试测 MSE对照论文 Table 2 的畸变界验证内积保持|⟨x, y⟩ - ⟨x̃, ỹ⟩|在 d {128, 256, 1536, 3072} 上用随机单位向量测试。仓库在 tests/test_distortion.py 中把论文 Table 2 的界直接写成常量test_distortion.pyb期望 MSE期望内积畸变10.361.57/d20.1170.56/d30.030.18/d40.0090.047/d同时定义了理论下界因子√(3π)/2 ≈ 2.7test_distortion.py——TurboQuant 的畸变在最优的 2.7 倍以内。测试逻辑要点PolarQuant MSEtest_distortion.py对 d∈{128,256,512}、b∈{1..4} 各取 1000 个随机单位向量断言平均 MSE 低于论文界 × 3论文界是 d→∞ 的渐近值有限 d 留 3 倍余量单侧内积畸变test_distortion.py只量化 x、保留精确 y按论文 Theorem 2 的界√(3π²)/d · 1/4^b检查允许 5 倍余量并断言位宽越高误差严格越低test_distortion.pyTurboQuant 相对 PolarQuant 的增益test_distortion.py同一 b 下比较两者内积误差验证 QJL 残差纠偏的意义该测试仅打印对比不断言作为研究数据留档。完整性测试在 tests/test_turboquant.py往返 MSE 在论文界 ×3 内test_turboquant.py、内积保持test_turboquant.py、位宽 2 抛错、零向量稳定性、种子确定性、批量与单条结果一致批量必须与逐条量化完全一致test_turboquant.py。Task 2.2 — 量化速度基准计划要求PLAN.md论文称 d3072 约 0.002s需验证同数量级在 d {200, 1536, 3072} 上做基准并与朴素乘积量化对比。仓库提供了开箱即用的演示基准 benchmarks/demo.py运行方式来自 README.mdgit clone https://github.com/TheTom/turboquant_plus.git # 若从源码开始 cd turboquant_plus python3 -m venv .venv source .venv/bin/activate pip install -e .[dev] python3 -m pytest tests/ -v # 验证测试套件通过 python3 benchmarks/demo.py # 免模型的压缩演示demo.py 会对 d128 的单个注意力头向量在 2/3/4-bit 下分别打印 MSE、余弦相似度、压缩比与量/反量化耗时demo_inner_product 对 1000 对随机单位向量做单侧量化的内积误差统计demo_kv_cache 直接模拟 (4 层, 8 头, 512 长度, 128 维) 的 KV cache 输出整体压缩比与耗时。注意论文的 0.002s 是论文方在特定硬件上的报告值本仓库不做背书。基准的意义在于同数量级验证 相对比较如不同位宽、不同 d 的伸缩性实际性能请以自己硬件上运行benchmarks/demo.py的结果为准。Task 2.3 — 压缩比验证计划要求PLAN.md输入 fp16 KV cache16 bits/值3-bit 输出应约 5.3×16/34-bit 输出应约 4×16/4计入元数据开销旋转矩阵、码本、残差范数。仓库中 tests/test_turboquant.py 验证3-bit 时compression_ratio()落在 (4.0, 6.0) 区间d128 时约 4.92因为每向量多 32 bit 范数摊薄了比例4-bit 落在 (3.0, 5.0)。更精细的内存核算在 turboquant/utils.py 的memory_footprint_bytes把 MSE 索引b-1 bit、QJL 符号1 bit与范数float32/向量逐项拆开与原始 fp16 字节数比较得出真实压缩比。五、Phase 3KV Cache 集成Task 3.1 — KV 张量的批量量化计划要求PLAN.mdKV cache 形状为(num_layers, num_heads, seq_len, head_dim)沿 head_dim 逐向量独立量化支持流式逐 token 在线量化。仓库实现在 turboquant/kv_cache.pyCompressedKVCachekv_cache.py按每层每头组织压缩结果KVCacheCompressor.compresskv_cache.py对每层每头把(seq_len, head_dim)整体批量量化KVCacheCompressor.decompresskv_cache.py还原为原形状张量memory_statskv_cache.py直接给出 original_mb / compressed_mb / compression_ratio 与 K、V 各自的每值位数。Task 3.2 — 非整数位宽的外点通道策略计划要求PLAN.md实现论文的 2.5-bit 与 3.5-bit 外点拆分2.5-bit32 个外点通道 3-bit 96 个通道 2-bit3.5-bit类似拆分外点用 4-bit按幅值逐层校准识别外点通道。仓库除 turboquant/outlier.py 提供实现外还在 benchmarks/test_outlier_comparison.py 中提供了外点策略对比实验。这一机制的意义在于KV 张量存在少量幅值极大的外点通道把它们单独分配更高位宽可以显著改善低 bit 下的量化质量。Task 3.3 — 压缩 KV 上的注意力计算计划要求PLAN.md计算softmax(Q K_compressed.T / √d) V_compressedK cache 用内积版 TurboQuantAlgorithm 2V cache 用 MSE 版 TurboQuantAlgorithm 1验证注意力输出与全精度在容差内一致。这一分工的设计动机在 kv_cache.py 的类注释中讲得很清楚K 参与内积计算Q·Kᵀ内积保真度决定注意力路由质量所以用带 QJL 的 Algorithm 2V 参与加权求和重建MSE 更重要所以用 Algorithm 1。这与 README.md 记录的关键发现V 压缩几乎免费、所有质量损失来自 K 压缩互为印证也呼应了仓库后续的非对称 K/V结论见 docs/papers/asymmetric-kv-compression.md。六、Phase 4性能优化Task 4.1 — 结构化随机旋转快速 Walsh-Hadamard计划要求PLAN.md用 Hadamard 随机符号翻转替代稠密 ΠO(d log d) 旋转实时 KV 压缩的关键。已在 Task 1.1 介绍random_rotation_fastfast_walsh_hadamard_transform 批量蝶形apply_fast_rotation_batch都在 turboquant/rotation.py 落地。这也正是 README 中llama.cpp 上游已合并 Hadamard KV 旋转README.md所对应的核心思想。Task 4.2 — 向量化量化计划要求PLAN.md用 NumPy 广播做批量量化避免逐坐标 Python 循环目标 d3072 时 1000 向量 10ms。nearest_centroid_indices的searchsorted方案、PolarQuant.quantize的批量归一化/旋转(rotation x.T).T、QJL.quantize的批量符号投影全部是向量化实现tests/test_turboquant.py 还保证批量结果与逐条调用严格一致。10ms 目标属于计划期许实际数字请以本机基准为准。Task 4.3 — 内存高效存储计划要求PLAN.md把 b-bit 索引打包进 uint8/uint16而非每索引一个 int把 QJL 符号位打包成 uint8 位域每字节 8 符号核算实际内存占用与理论值。仓库在 turboquant/utils.py 提供pack_bits/unpack_bitsutils.py{1,-1} 符号 ↔ uint8 位域8 符号/字节用np.packbits/np.unpackbits实现pack_indicesutils.py1-4 bit 索引压缩到字节内5-8 bit 直接用 uint8memory_footprint_bytesutils.py分项核算 MSE 索引、QJL 符号、范数三者字节数并与 fp16 原始大小对比。七、Phase 5集成目标未来工作PLAN.md 规划了三类集成目标仓库现状如下以仓库实际内容为准Task 5.1 — PyTorch 封装计划做成torch.nn.Module的即插即用 KV cache 替换、支持 autograd为潜在微调实验。仓库中该封装尚未实现社区有独立实现 turboquant-pytorch 采用了本仓库的 layer-adaptive 压缩与 Sparse V 结论Task 5.2 — llama.cpp C 实现计划移植核心算法到 C、对接 ggml_backend。按 README.md 的状态上游 llama.cpp 已合并 Hadamard KV 旋转与快速 WHT 内核完整 PolarQuant 编解码器位于 llama-cpp-turboquant、docs/turbo-speed-investigation.md 记录了构建与优化细节Task 5.3 — MLX 实现计划移植到 MLX 并用 Metal shader 加速。仓库的 docs/mlx-port.md 记录了 MLX Python 移植TurboKVCache即插即用另有 Swift 侧协作mlx-swift-lm在进行中README.md。八、关键数学常量速查PLAN.md 给出的常量仓库中均已落地为实际代码对照验证import numpy as np # 高维最优质心b1 / b2来自论文闭式解 CENTROIDS_1BIT lambda d: np.array([-np.sqrt(2 / (np.pi * d)), np.sqrt(2 / (np.pi * d))]) CENTROIDS_2BIT lambda d: np.array([-1.51/np.sqrt(d), -0.453/np.sqrt(d), 0.453/np.sqrt(d), 1.51/np.sqrt(d)]) # QJL 反量化常数qjl.py 中的 QJL_CONST QJL_CONST np.sqrt(np.pi / 2) # 理论畸变界因子TurboQuant 在最优的 √(3π)/2 ≈ 2.7 倍以内 BOUND_FACTOR np.sqrt(3 * np.pi) / 2对应源码CENTROIDS_1BIT/2BIT的实现见 codebook.pyQJL_CONST见 qjl.pyBOUND_FACTOR见 test_distortion.py。前两个质心公式都按1/√d缩放因此在实例化时必须传入维度 d。九、文件结构从计划到仓库的映射PLAN.md 规划的文件结构在当前仓库中已全部落地各文件路径以仓库根目录为基准turboquant/ ├── __init__.py # 包导出PolarQuant / QJL / TurboQuant / TurboQuantMSE / KVCacheCompressor ├── polar_quant.py # PolarQuant随机旋转 标量量化 范数提取/修正 ├── qjl.py # QJL1-bit Johnson-Lindenstrauss论文复现用 ├── turboquant.py # 完整 TurboQuantAlgorithm 2 TurboQuantMSEAlgorithm 1 ├── codebook.py # 码本构造闭式解 Lloyd 迭代 searchsorted 最近邻 ├── rotation.py # 稠密 Haar 旋转 快速 Walsh-Hadamard 结构化旋转 ├── kv_cache.py # KV cache 集成层K 用 TurboQuant、V 用 TurboQuantMSE ├── outlier.py # 外点通道策略2.5-bit / 3.5-bit └── utils.py # 位打包与内存核算 tests/ ├── test_polar_quant.py ├── test_qjl.py ├── test_turboquant.py # 完整算法往返、压缩比、批量一致性 ├── test_distortion.py # 对照论文 Table 2 的畸变界 └── test_kv_cache.py benchmarks/ ├── demo.py # 免模型快速演示单向量 / KV cache / 内积保持 ├── run_benchmark.py ├── test_outlier_comparison.py # 外点策略对比 └── validate_real_model.py # 真实模型 KV 张量验证需 transformers/torch此外 README.md 还列出了lloyd_max.py、isoquant.py、rotorquant.py等扩展模块与 14 个测试文件pyproject.toml中注明turboquant包为研究专用dev-only不随 refract wheel 发布pyproject.toml这进一步印证了其论文复现参考实现的定位。十、验收标准与迭代方向PLAN.md 给出四条成功标准仓库均有对应验证手段正确性d ≥ 128 时 MSE 畸变在论文报告界的 10% 以内 → 由 tests/test_distortion.py 的 Table 2 对照测试把关有限 d 下留 3 倍余量速度d3072 量化 10ms论文报 0.002s→ 由 benchmarks/demo.py 与 benchmarks/run_benchmark.py 测量实际值以本机为准压缩实际内存接近理论值b bits/坐标 元数据开销 5%→ 由compression_ratio与 utils.py 的分项核算验证往返1000 对随机向量的内积保持误差低于论文界 → 由 tests/test_turboquant.py 的test_inner_product_preservation验证。最后给研究者的两点仓库级提示论文复现 vs 生产部署如果你要复现论文或研究 K 侧 8-bit 以下压缩直接用QJL/TurboQuant类如果目标是集成到推理引擎请按 README.md 的建议使用TurboQuantMSE或纯 PolarQuant并参考 docs/turboquant-recommendations.md 的实测配置矩阵非对称 K/V、Boundary V 等做模型级验证延伸资料质量与速度数据见 docs/benchmarks.md旋转/码本/范数修正等机制深挖见 docs/papers/turbo4-resurrection.md 与 docs/papers/asymmetric-kv-compression.md可作为理解计划内算法与生产演化之间关系的实证材料。赞分享【免费下载链接】turboquant_plus项目地址https://gitcode.com/gh_mirrors/tu/turboquant_plus点击查看免费下载相关推荐TurboQuant 实战指南基于 PolarQuant 与 Walsh-Hadamard 旋转的 KV Cache 压缩原理、配置与落地TurboQuant 实战指南基于 PolarQuant 与 Walsh Hadamard 旋转的 KV Cache 压缩原理、配置与落地 本文以仓库根目录LMDeploy KV Cache 量化实战INT4/INT8 在线量化与 TurboQuant 深入解析LMDeploy KV Cache 量化实战INT4/INT8 在线量化与 TurboQuant 深入解析 本篇技术指南以 LMDeploy 的 KV Cac人工智能大模型模型推理服务推理引擎本地部署模型量化LMDeploy KV Cache 量化实战INT4/INT8 在线量化与 TurboQuant 原理、配置与性能分析LMDeploy KV Cache 量化实战INT4/INT8 在线量化与 TurboQuant 原理、配置与性能分析 KV Cache 量化是降低 LLM人工智能大模型模型推理服务推理引擎本地部署模型量化上一篇ESLint 文件忽略完整指南flat config 下的 globalIgnores、--ignore-pattern 与 .gitignore 集成下一篇Refine v5 Ant Design CloneButton 完整指南从列表一键跳转克隆创建页创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/9 2:36:21 · 阅读 1.2k 从零实现 TurboQuant：基于 PolarQuant + QJL 的 KV Cache 在线向量量化落地指南（turboquant_plus）
【免费下载链接】turboquant_plus项目地址https://gitcode.com/gh_mirrors/tu/turboquant_plus点击查看免费下载本文以仓库根目录的 PLAN.md 实施计划为主体结合 turboquant/ 包的完整源码、tests/ 测试与 benchmarks/ 演示脚本系统讲解如何从零实现 ICLR 2026 论文 TurboQuant 的 KV Cache 压缩包括随机旋转、PolarQuant 标量量化、QJL 残差纠偏、畸变界验证、KV 张量集成与性能优化。读完你不仅能复现论文的压缩流程还能直接在本仓库的 Python/NumPy 参考实现上做二次研究与集成实验。一、论文背景与项目定位TurboQuant 是 Google Research 提出的在线向量量化Online Vector Quantization方案论文信息如下内容来自 PLAN.md标题TurboQuant: Online Vector Quantization with Near-optimal Distortion Rate作者Amir Zandieh, Majid Daliri, Majid Hadian, Vahab Mirrokni会议ICLR 2026arXiv 编号2504.19874本仓库turboquant_plus的目标非常明确不依赖任何推理引擎用纯 Python/NumPy 从零实现 TurboQuant 的量化与反量化使其能够对 KV cache 张量进行压缩与解压对照论文给出的畸变界distortion bounds验证正确性为后续接入 llama.cpp 或 MLX 等推理引擎提供参考实现。按 README.md 的说明该仓库是 TurboQuant 研究的研究大本营research homePython 参考实现、验证文档与基准数据都存放在这里验证成熟的部分会以小补丁形式逐步合入上游引擎。阅读本文时你可以同时对照 README.md 中的架构图与 docs/papers 下的系列实验论文形成计划 → 实现 → 验证 → 上游化的完整闭环。二、总体架构三个算法如何组合成一个压缩器TurboQuant 本质上是三个算法的叠加随机旋转 最优标量量化PolarQuant 1-bit Johnson-Lindenstrauss 变换QJL。PLAN.md 给出的数据流如下Input vector x ∈ R^d │ ▼ ┌─────────────────┐ │ PolarQuant │ Random rotation → Beta-distributed coordinates │ (b-1 bits) │ → optimal scalar quantization per coordinate └────────┬────────┘ │ quantized residual ▼ ┌─────────────────┐ │ QJL │ 1-bit sign quantization of residual │ (1 bit) │ via Johnson-Lindenstrauss Transform └────────┬────────┘ │ ▼ TurboQuant output: (indices, qjl_signs, residual_norm) Total: b bits per coordinate理解这条流水线的关键随机旋转将一个任意方向的向量旋转到各坐标独立、分布已知的坐标系使每个坐标可以独立做最优标量量化PolarQuantb-1 bit负责主压缩追求 MSE 最优QJL1 bit对残差做符号量化负责消除 PolarQuant 重建的偏置bias让内积估计保持无偏。合计 b bits/坐标。对应到源码三个算法分别落在 turboquant/rotation.py、turboquant/polar_quant.py、turboquant/qjl.py并在 turboquant/turboquant.py 中组装成完整流水线。一个必须了解的仓库事实QJL 在生产中的取舍需要提前说明的是README.md 明确记录了一个关键实验结论生产环境最终丢弃了 QJLK 和 V 都不再用。原因是 QJL 消除重建偏置的同时放大了方差而 softmax 会把这种方差放大成注意力噪声README 记载了五个独立团队buun、scos-lab、Arclabs001 等的一致验证结果详见 docs/papers/turbo4-resurrection.md。因此仓库中QJL与TurboQuant带 QJL 的完整版两个类被定位为论文复现与研究用途而生产/集成侧推荐使用TurboQuantMSEV cache或在 K 上直接用 48 bit 的 PolarQuant。本文仍以 PLAN.md 的完整算法为主线因为它要求实现论文全貌但会在相应小节如实标注这一仓库结论避免读者把研究实现误当生产最佳实践。三、Phase 1核心算法实现NumPy这是 PLAN.md 的主体共 5 个任务。以下每个任务都先讲计划要求再落到仓库源码。Task 1.1 — 随机旋转矩阵生成计划要求PLAN.md生成正交随机旋转矩阵 Π ∈ R^(d×d)用随机高斯矩阵的 QR 分解获得 Haar 分布旋转给定种子必须确定可复现大 d 时考虑结构化旋转Hadamard 随机符号翻转把复杂度从 O(d²) 降到 O(d log d)。仓库实现位于 turboquant/rotation.py提供两套旋转稠密 Haar 旋转random_rotation_dense生成标准高斯矩阵 Gnp.linalg.qr(G)取正交因子 Q再用np.sign(np.diag(R))修正列符号使其服从 Haar 分布最后用np.linalg.slogdet检查行列式并把 det 修正为 1保证是旋转而非反射。注意它用slogdet而非det是因为大 d 下行列式会溢出。import numpy as np from turboquant.rotation import random_rotation_dense rng np.random.default_rng(42) Pi random_rotation_dense(d128, rngrng) # 正交阵det 1快速结构化旋转random_rotation_fast生成两组随机符号向量 signs1/signs2并把维度补齐到 2 的幂padded_d旋转等价于D2 H D1 x其中 H 是归一化 Hadamard 矩阵。应用时用 fast_walsh_hadamard_transformO(d log d) 蝶形运算而不是稠密矩阵乘apply_fast_rotation_batch 提供批量版本的向量化蝶形实现。这正是 PLAN.md 中 Phase 4 Task 4.1 的提前落地。Task 1.2 — PolarQuant 码本构造计划要求PLAN.md对位宽 b 计算 2^b 个 MSE 最优质心论文对高维给出闭式解b1 质心为±√(2/πd)b2 为{±0.453/√d, ±1.51/√d}一般 b 用 Lloyd 算法迭代求解大 d 可用高斯近似质心存为有序数组以支持快速最近邻查找。原理随机旋转后每个坐标服从 Beta(d/2, d/2)[-1/√d, 1/√d] 上大 d 时收敛到 N(0, 1/d)因此可以对每个坐标独立做最优标量量化。仓库实现位于 turboquant/codebook.pyoptimal_centroidsb1、b2 直接用论文闭式解b≥3 走 _lloyds_gaussian对 N(0, 1/d) 做 100 轮 Lloyd 迭代区间条件期望用解析公式更新nearest_centroid_indices对有序质心取相邻质心中点作为边界用np.searchsorted做向量化最近邻查找复杂度 O(n log k) 而非 O(n·k)。from turboquant.codebook import optimal_centroids, nearest_centroid_indices centroids optimal_centroids(bit_width3, d128) # 8 个有序质心 idx nearest_centroid_indices(y, centroids) # 逐坐标最近质心索引Task 1.3 — MSE 最优 TurboQuantAlgorithm 1计划给出的算法PLAN.mdquantize_mse(x, Π, codebook)y Π x→ 每个坐标取最近质心 → 返回 b-bit 索引dequantize_mse(idx, Π, codebook)索引查质心 →x̃ Π.T ỹ。仓库中该算法由 turboquant/polar_quant.py 的PolarQuant类实现且做了两个重要扩展扩展一范数提取与重标定polar_quant.py。论文第 5 页明确要求以浮点精度存储 L2 范数并在反量化时重标定因为真实 KV cache 向量不是单位范数而码本是按单位范数向量校准的。实现流程提取范数 → 归一化 → 旋转 → 量化反量化时逆旋转后乘回原范数。扩展二范数修正norm correctionpolar_quant.py。量化会在旋转域中压缩重建向量的范数norm_correctionTrue时先把旋转域重建向量重归一化到单位范数再逆旋转从而消除这一系统性偏差。测试 tests/test_turboquant.py 专门验证了开启/关闭该修正会得到不同重建结果但索引与范数一致。from turboquant.polar_quant import PolarQuant pq PolarQuant(d128, bit_width2, seed42, norm_correctionTrue) indices, norms pq.quantize(x) # x: (d,) 或 (batch, d) x_hat pq.dequantize(indices, norms) # 重建形状与输入一致类中还提供 quantize_and_residual一次性返回索引、范数与残差r x - dequantize(indices, norms)这正是完整 TurboQuant 第二级 QJL 的输入。Task 1.4 — QJL量化 Johnson-Lindenstrauss 变换计划要求PLAN.md生成随机投影矩阵 S ∈ R^(d×d)元素 ~ N(0,1)量化qjl sign(S r)→ {1, -1}^d反量化x̃_qjl √(π/2) / d * gamma * S.T qjlgamma ||r||₂ 作为元数据存储。仓库实现位于 turboquant/qjl.py有两处与计划草稿不同的工程化处理以实际代码为准正交化投影矩阵qjl.pyQR 分解后按np.sign(np.diag(R))修正符号得到正交 S并断言||S Sᵀ − I||_F 1e-10。正交性是无偏估计E[⟨x̂, y⟩] ⟨x, y⟩与E[||x̂||²] (π/2)·||x||²成立的前提论文 Theorem 2缩放系数按 √d 而非 dqjl.py实际反量化为x̂ √(π/2)/√d · ||r|| · Sᵀ · signs与 PLAN.md 草稿中的1/d不同源码注释给出了完整推导。此外 QJL 反量化还暴露了一个shrinkage参数默认1.0是论文的无偏估计量2/np.pi ≈ 0.6366是 MMSE 最优的收缩系数推导见 qjl.py它带来偏置但显著降低 MSE适合对 MSE 敏感的注意力分数修正场景。from turboquant.qjl import QJL qjl QJL(d128, seed42) signs, residual_norm qjl.quantize(r) # signs: int8 {1, -1} r_hat qjl.dequantize(signs, residual_norm) # 默认无偏估计 r_hat_mmse qjl.dequantize(signs, residual_norm, shrinkage2/np.pi)Task 1.5 — 完整 TurboQuantAlgorithm 2组合两者计划给出的两阶段流程PLAN.mdquantizeMSE 量化 (b-1) bit → 残差r x - dequantize_mse(idx)→ QJL 量化残差 → 存残差范数dequantizeMSE 重建 QJL 残差重建 → 求和。仓库实现在 turboquant/turboquant.py 的TurboQuant类docstring 明确标注为Algorithm 2 from the paper — Inner Product TurboQuantfrom turboquant.turboquant import TurboQuant tq TurboQuant(d128, bit_width3, seed42) # b 21-bit PolarQuant 1-bit QJL compressed tq.quantize(x) # CompressedVector x_hat tq.dequantize(compressed)几个实现细节值得注意位宽约束bit_width 2直接抛ValueErrorturboquant.py因为 1 bit 给 PolarQuant 后 QJL 就没有余量了——1-bit 场景应直接用 QJL种子分工PolarQuant 用seedQJL 用seed 1000turboquant.py保证两级随机矩阵独立输出容器CompressedVectordataclassturboquant.py打包 mse 索引、(b-1) bit、原始范数、QJL 符号与残差范数、总位宽内存与压缩比核算compressed_size_bits 按d*b 32bits/向量 估算32 bit 是 float32 残差范数compression_ratio 相对原始 fp16 计算压缩倍数。配套的TurboQuantMSE类turboquant.py是不带 QJL 的 Algorithm 1 纯 MSE 版用于 V cache所有 b 个 bit 全部投入 MSE 量化存储开销更小无需 QJL 符号位。四、Phase 2验证与基准Task 2.1 — 单元测试与畸变界验证计划要求PLAN.md往返测试测 MSE对照论文 Table 2 的畸变界验证内积保持|⟨x, y⟩ - ⟨x̃, ỹ⟩|在 d {128, 256, 1536, 3072} 上用随机单位向量测试。仓库在 tests/test_distortion.py 中把论文 Table 2 的界直接写成常量test_distortion.pyb期望 MSE期望内积畸变10.361.57/d20.1170.56/d30.030.18/d40.0090.047/d同时定义了理论下界因子√(3π)/2 ≈ 2.7test_distortion.py——TurboQuant 的畸变在最优的 2.7 倍以内。测试逻辑要点PolarQuant MSEtest_distortion.py对 d∈{128,256,512}、b∈{1..4} 各取 1000 个随机单位向量断言平均 MSE 低于论文界 × 3论文界是 d→∞ 的渐近值有限 d 留 3 倍余量单侧内积畸变test_distortion.py只量化 x、保留精确 y按论文 Theorem 2 的界√(3π²)/d · 1/4^b检查允许 5 倍余量并断言位宽越高误差严格越低test_distortion.pyTurboQuant 相对 PolarQuant 的增益test_distortion.py同一 b 下比较两者内积误差验证 QJL 残差纠偏的意义该测试仅打印对比不断言作为研究数据留档。完整性测试在 tests/test_turboquant.py往返 MSE 在论文界 ×3 内test_turboquant.py、内积保持test_turboquant.py、位宽 2 抛错、零向量稳定性、种子确定性、批量与单条结果一致批量必须与逐条量化完全一致test_turboquant.py。Task 2.2 — 量化速度基准计划要求PLAN.md论文称 d3072 约 0.002s需验证同数量级在 d {200, 1536, 3072} 上做基准并与朴素乘积量化对比。仓库提供了开箱即用的演示基准 benchmarks/demo.py运行方式来自 README.mdgit clone https://github.com/TheTom/turboquant_plus.git # 若从源码开始 cd turboquant_plus python3 -m venv .venv source .venv/bin/activate pip install -e .[dev] python3 -m pytest tests/ -v # 验证测试套件通过 python3 benchmarks/demo.py # 免模型的压缩演示demo.py 会对 d128 的单个注意力头向量在 2/3/4-bit 下分别打印 MSE、余弦相似度、压缩比与量/反量化耗时demo_inner_product 对 1000 对随机单位向量做单侧量化的内积误差统计demo_kv_cache 直接模拟 (4 层, 8 头, 512 长度, 128 维) 的 KV cache 输出整体压缩比与耗时。注意论文的 0.002s 是论文方在特定硬件上的报告值本仓库不做背书。基准的意义在于同数量级验证 相对比较如不同位宽、不同 d 的伸缩性实际性能请以自己硬件上运行benchmarks/demo.py的结果为准。Task 2.3 — 压缩比验证计划要求PLAN.md输入 fp16 KV cache16 bits/值3-bit 输出应约 5.3×16/34-bit 输出应约 4×16/4计入元数据开销旋转矩阵、码本、残差范数。仓库中 tests/test_turboquant.py 验证3-bit 时compression_ratio()落在 (4.0, 6.0) 区间d128 时约 4.92因为每向量多 32 bit 范数摊薄了比例4-bit 落在 (3.0, 5.0)。更精细的内存核算在 turboquant/utils.py 的memory_footprint_bytes把 MSE 索引b-1 bit、QJL 符号1 bit与范数float32/向量逐项拆开与原始 fp16 字节数比较得出真实压缩比。五、Phase 3KV Cache 集成Task 3.1 — KV 张量的批量量化计划要求PLAN.mdKV cache 形状为(num_layers, num_heads, seq_len, head_dim)沿 head_dim 逐向量独立量化支持流式逐 token 在线量化。仓库实现在 turboquant/kv_cache.pyCompressedKVCachekv_cache.py按每层每头组织压缩结果KVCacheCompressor.compresskv_cache.py对每层每头把(seq_len, head_dim)整体批量量化KVCacheCompressor.decompresskv_cache.py还原为原形状张量memory_statskv_cache.py直接给出 original_mb / compressed_mb / compression_ratio 与 K、V 各自的每值位数。Task 3.2 — 非整数位宽的外点通道策略计划要求PLAN.md实现论文的 2.5-bit 与 3.5-bit 外点拆分2.5-bit32 个外点通道 3-bit 96 个通道 2-bit3.5-bit类似拆分外点用 4-bit按幅值逐层校准识别外点通道。仓库除 turboquant/outlier.py 提供实现外还在 benchmarks/test_outlier_comparison.py 中提供了外点策略对比实验。这一机制的意义在于KV 张量存在少量幅值极大的外点通道把它们单独分配更高位宽可以显著改善低 bit 下的量化质量。Task 3.3 — 压缩 KV 上的注意力计算计划要求PLAN.md计算softmax(Q K_compressed.T / √d) V_compressedK cache 用内积版 TurboQuantAlgorithm 2V cache 用 MSE 版 TurboQuantAlgorithm 1验证注意力输出与全精度在容差内一致。这一分工的设计动机在 kv_cache.py 的类注释中讲得很清楚K 参与内积计算Q·Kᵀ内积保真度决定注意力路由质量所以用带 QJL 的 Algorithm 2V 参与加权求和重建MSE 更重要所以用 Algorithm 1。这与 README.md 记录的关键发现V 压缩几乎免费、所有质量损失来自 K 压缩互为印证也呼应了仓库后续的非对称 K/V结论见 docs/papers/asymmetric-kv-compression.md。六、Phase 4性能优化Task 4.1 — 结构化随机旋转快速 Walsh-Hadamard计划要求PLAN.md用 Hadamard 随机符号翻转替代稠密 ΠO(d log d) 旋转实时 KV 压缩的关键。已在 Task 1.1 介绍random_rotation_fastfast_walsh_hadamard_transform 批量蝶形apply_fast_rotation_batch都在 turboquant/rotation.py 落地。这也正是 README 中llama.cpp 上游已合并 Hadamard KV 旋转README.md所对应的核心思想。Task 4.2 — 向量化量化计划要求PLAN.md用 NumPy 广播做批量量化避免逐坐标 Python 循环目标 d3072 时 1000 向量 10ms。nearest_centroid_indices的searchsorted方案、PolarQuant.quantize的批量归一化/旋转(rotation x.T).T、QJL.quantize的批量符号投影全部是向量化实现tests/test_turboquant.py 还保证批量结果与逐条调用严格一致。10ms 目标属于计划期许实际数字请以本机基准为准。Task 4.3 — 内存高效存储计划要求PLAN.md把 b-bit 索引打包进 uint8/uint16而非每索引一个 int把 QJL 符号位打包成 uint8 位域每字节 8 符号核算实际内存占用与理论值。仓库在 turboquant/utils.py 提供pack_bits/unpack_bitsutils.py{1,-1} 符号 ↔ uint8 位域8 符号/字节用np.packbits/np.unpackbits实现pack_indicesutils.py1-4 bit 索引压缩到字节内5-8 bit 直接用 uint8memory_footprint_bytesutils.py分项核算 MSE 索引、QJL 符号、范数三者字节数并与 fp16 原始大小对比。七、Phase 5集成目标未来工作PLAN.md 规划了三类集成目标仓库现状如下以仓库实际内容为准Task 5.1 — PyTorch 封装计划做成torch.nn.Module的即插即用 KV cache 替换、支持 autograd为潜在微调实验。仓库中该封装尚未实现社区有独立实现 turboquant-pytorch 采用了本仓库的 layer-adaptive 压缩与 Sparse V 结论Task 5.2 — llama.cpp C 实现计划移植核心算法到 C、对接 ggml_backend。按 README.md 的状态上游 llama.cpp 已合并 Hadamard KV 旋转与快速 WHT 内核完整 PolarQuant 编解码器位于 llama-cpp-turboquant、docs/turbo-speed-investigation.md 记录了构建与优化细节Task 5.3 — MLX 实现计划移植到 MLX 并用 Metal shader 加速。仓库的 docs/mlx-port.md 记录了 MLX Python 移植TurboKVCache即插即用另有 Swift 侧协作mlx-swift-lm在进行中README.md。八、关键数学常量速查PLAN.md 给出的常量仓库中均已落地为实际代码对照验证import numpy as np # 高维最优质心b1 / b2来自论文闭式解 CENTROIDS_1BIT lambda d: np.array([-np.sqrt(2 / (np.pi * d)), np.sqrt(2 / (np.pi * d))]) CENTROIDS_2BIT lambda d: np.array([-1.51/np.sqrt(d), -0.453/np.sqrt(d), 0.453/np.sqrt(d), 1.51/np.sqrt(d)]) # QJL 反量化常数qjl.py 中的 QJL_CONST QJL_CONST np.sqrt(np.pi / 2) # 理论畸变界因子TurboQuant 在最优的 √(3π)/2 ≈ 2.7 倍以内 BOUND_FACTOR np.sqrt(3 * np.pi) / 2对应源码CENTROIDS_1BIT/2BIT的实现见 codebook.pyQJL_CONST见 qjl.pyBOUND_FACTOR见 test_distortion.py。前两个质心公式都按1/√d缩放因此在实例化时必须传入维度 d。九、文件结构从计划到仓库的映射PLAN.md 规划的文件结构在当前仓库中已全部落地各文件路径以仓库根目录为基准turboquant/ ├── __init__.py # 包导出PolarQuant / QJL / TurboQuant / TurboQuantMSE / KVCacheCompressor ├── polar_quant.py # PolarQuant随机旋转 标量量化 范数提取/修正 ├── qjl.py # QJL1-bit Johnson-Lindenstrauss论文复现用 ├── turboquant.py # 完整 TurboQuantAlgorithm 2 TurboQuantMSEAlgorithm 1 ├── codebook.py # 码本构造闭式解 Lloyd 迭代 searchsorted 最近邻 ├── rotation.py # 稠密 Haar 旋转 快速 Walsh-Hadamard 结构化旋转 ├── kv_cache.py # KV cache 集成层K 用 TurboQuant、V 用 TurboQuantMSE ├── outlier.py # 外点通道策略2.5-bit / 3.5-bit └── utils.py # 位打包与内存核算 tests/ ├── test_polar_quant.py ├── test_qjl.py ├── test_turboquant.py # 完整算法往返、压缩比、批量一致性 ├── test_distortion.py # 对照论文 Table 2 的畸变界 └── test_kv_cache.py benchmarks/ ├── demo.py # 免模型快速演示单向量 / KV cache / 内积保持 ├── run_benchmark.py ├── test_outlier_comparison.py # 外点策略对比 └── validate_real_model.py # 真实模型 KV 张量验证需 transformers/torch此外 README.md 还列出了lloyd_max.py、isoquant.py、rotorquant.py等扩展模块与 14 个测试文件pyproject.toml中注明turboquant包为研究专用dev-only不随 refract wheel 发布pyproject.toml这进一步印证了其论文复现参考实现的定位。十、验收标准与迭代方向PLAN.md 给出四条成功标准仓库均有对应验证手段正确性d ≥ 128 时 MSE 畸变在论文报告界的 10% 以内 → 由 tests/test_distortion.py 的 Table 2 对照测试把关有限 d 下留 3 倍余量速度d3072 量化 10ms论文报 0.002s→ 由 benchmarks/demo.py 与 benchmarks/run_benchmark.py 测量实际值以本机为准压缩实际内存接近理论值b bits/坐标 元数据开销 5%→ 由compression_ratio与 utils.py 的分项核算验证往返1000 对随机向量的内积保持误差低于论文界 → 由 tests/test_turboquant.py 的test_inner_product_preservation验证。最后给研究者的两点仓库级提示论文复现 vs 生产部署如果你要复现论文或研究 K 侧 8-bit 以下压缩直接用QJL/TurboQuant类如果目标是集成到推理引擎请按 README.md 的建议使用TurboQuantMSE或纯 PolarQuant并参考 docs/turboquant-recommendations.md 的实测配置矩阵非对称 K/V、Boundary V 等做模型级验证延伸资料质量与速度数据见 docs/benchmarks.md旋转/码本/范数修正等机制深挖见 docs/papers/turbo4-resurrection.md 与 docs/papers/asymmetric-kv-compression.md可作为理解计划内算法与生产演化之间关系的实证材料。赞分享【免费下载链接】turboquant_plus项目地址https://gitcode.com/gh_mirrors/tu/turboquant_plus点击查看免费下载相关推荐TurboQuant 实战指南基于 PolarQuant 与 Walsh-Hadamard 旋转的 KV Cache 压缩原理、配置与落地TurboQuant 实战指南基于 PolarQuant 与 Walsh Hadamard 旋转的 KV Cache 压缩原理、配置与落地 本文以仓库根目录LMDeploy KV Cache 量化实战INT4/INT8 在线量化与 TurboQuant 深入解析LMDeploy KV Cache 量化实战INT4/INT8 在线量化与 TurboQuant 深入解析 本篇技术指南以 LMDeploy 的 KV Cac人工智能大模型模型推理服务推理引擎本地部署模型量化LMDeploy KV Cache 量化实战INT4/INT8 在线量化与 TurboQuant 原理、配置与性能分析LMDeploy KV Cache 量化实战INT4/INT8 在线量化与 TurboQuant 原理、配置与性能分析 KV Cache 量化是降低 LLM人工智能大模型模型推理服务推理引擎本地部署模型量化上一篇ESLint 文件忽略完整指南flat config 下的 globalIgnores、--ignore-pattern 与 .gitignore 集成下一篇Refine v5 Ant Design CloneButton 完整指南从列表一键跳转克隆创建页创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考