turboquant
0xSero/turboquant加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
2026 年，随着 Qwen3.5-27B、DeepSeek-V3 等百亿参数大模型成为主流 AI 应用的中坚力量，一个尖锐的矛盾浮出水面：用户想要在消费级 GPU 上运行超长上下文的推理，但 KV Cache 吃掉了太多显存。
一个典型场景：你在 RTX 5090（32GB）上跑 Qwen3.5-27B，当上下文长度达到 131K tokens 时，KV Cache 直接占满 30GB GPU 显存，最大 token 容量只有 45 万个。更糟的是，很多企业只有 8 张 RTX 3090（每张 24GB），想在多卡环境下跑满 131K 上下文几乎不可能。
TurboQuant 就是来解决这个问题的——在不显著损失模型质量的前提下，把 KV Cache 压缩到原来的 1/4 到 1/5，让同样的硬件能跑更长的上下文，或者同样的上下文只需要更少的 GPU。
TurboQuant 并非凭空诞生，它的理论基础来自 Zandieh 等人在 ICLR 2026 发表的论文（arXiv:2504.19874）。作者 0xSero 将论文中的理论算法工程化，做出了一个可以实际集成到 vLLM 生产环境的 KV Cache 量化系统。
这个项目的核心创新在于：用 3-bit 表示 Key，2-bit 表示 Value，配合 Triton 融合内核实现零感知延迟的推理加速。在 RTX 5090 单卡上，开启 TurboQuant 后 Prefill 吞吐量甚至还提升了 5.7%（从 1,804 提升到 1,907 tok/s），Decode 吞吐量提升 3.1%，同时 KV Cache 占用的显存从 30GB 降到了 0。
TurboQuant 的核心压缩流程分为五步：
第一步：随机正交旋转（Random Orthogonal Rotation）。对每个 Key 向量乘以一个随机正交矩阵 R，把信息均匀分散到所有维度上。这一步听起来玄学，背后却有严格的数学保证——旋转后向量服从 Beta 分布，可以用更少的比特精确量化。
第二步：Lloyd-Max 最优标量量化（Codebook）。旋转后的值服从 Beta 分布，TurboQuant 为 head_dim=128 和 256 两种情况分别预先生成了 2-bit、3-bit、4-bit 的码本（Codebook）。量化时，查表找到最接近的码字（Codeword），将浮点向量压缩为整数索引。
第三步：QJL 投影（Query JL Projection）。对于 Key 的残差部分（量化误差），用一个 d×d 的随机投影矩阵 S 做投影，把 sign bits 压缩到 1 bit。这实际上是经典的 Johnson-Lindenstrauss 引理在注意力场景的应用。
第四步：Value 的分组量化（Group Quantization）。Value 不走旋转路线，直接按组（默认每 32 个元素一组）做对称量化，记录 scale 和 zero-point，然后用 2-bit 或 4-bit 紧凑存储。
第五步：比特打包（Bit-packing）。2-bit 量化时每 4 个值打包成 1 个字节，4-bit 量化时每 2 个值打包成 1 个字节，最大化存储效率。
这套方案最优雅的地方在于无偏估计（Unbiased Estimator）：压缩后的注意力分数在数学期望上等于原始分数，这意味着理论上模型输出不会因量化而整体偏移。
TurboQuant 的代码组织非常清晰，核心模块如下：
turboquant/
├── codebook.py # Lloyd-Max 码本生成与查询
├── rotation.py # 正交旋转矩阵 & QJL 投影矩阵生成
├── quantizer.py # TurboQuantMSE + TurboQuantProd 核心量化算法
├── kv_cache.py # KV 缓存管理器，含 Value 打包/解包
├── capture.py # 模块化 KV 捕获钩子
├── store.py # 压缩 KV 存储（量化 + 追加 + 扁平缓存）
├── score.py # 从压缩 Key 计算注意力分数
├── integration/vllm.py # vLLM 集成适配器（monkey-patch 方式）
├── triton_kernels.py # 3 个 Triton 融合内核
└── vllm_attn_backend.py# vLLM attention backend shim（向后兼容）
整体采用分层设计：最底层是纯数学的量化算法（quantizer、rotation、codebook），中间层是存储和计算抽象（store、score、capture），最上层通过 monkey-patch 方式无缝注入 vLLM。这样做的好处是核心算法完全不依赖 vLLM，理论上可以移植到其他推理引擎。
TurboQuant 为 vLLM 提供了四种工作模式，按侵入程度从低到高：
使用方式极其简单，三行代码即可开启：
from turboquant.vllm_attn_backend import install_turboquant_hooks, set_mode
set_mode("active") # 切换到 hybrid 模式
install_turboquant_hooks(
model_runner,
key_bits=3, # Key 用 3-bit 量化
value_bits=2, # Value 用 2-bit 量化
buffer_size=128, # 最近 128 token 保留全精度
initial_layers_count=4, # 前 4 层开启 TQ
)
TurboQuant 在真实硬件上做了详尽的基准测试，部分结果摘录如下：
在 RTX 5090 单卡（32GB）+ Qwen3.5-27B-AWQ（4-bit 权重，TP=1）配置下，开启 3-bit Key / 2-bit Value 量化后：
在 8×RTX 3090（24GB）× Qwen3.5-35B-A3B MoE，TP=8 配置下，131K 上下文时：
需要注意的是：30.9% 的压缩率是针对 MoE 模型（线性注意力层不可压缩）的结果。对于纯 Dense Transformer 模型，理论压缩率可达 77%（4.4 倍），因为所有层的 KV 都可以被量化。
TurboQuant 提供了详尽的量化质量分析（代码中 audit_claims.py 就是一份坦诚的"对账"）。最关键的发现：
| 量化配置 | 余弦相似度 | 评价 |
|---|---|---|
| Key 3-bit | 1.000000 | 几乎无损 |
| Key 4-bit | 1.000000 | 几乎无损 |
| Value 2-bit | 0.940 | 质量瓶颈 |
| Value 4-bit | 0.997 | 推荐 |
| 3b Key + 2b Value 组合 | 0.940 | 值量化主导降质 |
核心结论：Key 量化几乎无损，但 Value 2-bit 量化是质量的主要瓶颈。如果对输出质量敏感，建议改用 Value 4-bit 量化（cos_sim=0.997，接近无损）。
多针（Needle）检索测试表明：单针（512-131K tokens）全部通过，5 针近最大上下文场景下 5/5 全部检索成功，3 针多事实连贯性测试也全部通过。不过论文也坦诚指出："Needle 检索通过是 trivial 的"——因为测试中 query 就是 key 的直接复制，而真实 LLM 查询和 key 之间往往有语义差异，难度不可同日而语。
TurboQuant 的 README 中有一节 Limitations，写得非常坦诚，这是科研型项目少有的诚实态度，值得尊敬。具体局限如下：
Prefill 阶段 KV Cache 仍需分配。TQ 在 prefill 时无法做到零分配，KV Cache 在引擎初始化时就已经分配好了，TQ 只能在 prefill 完成后释放它。要实现真正的零分配，需要更深入的 vLLM 内部集成。
线性注意力层不可压缩。Mamba、线性注意力类模型的状态无法被 TurboQuant 压缩，所以 MoE 模型中线性注意力层占比越高，TQ 的整体压缩收益越小。
Value 2-bit 量化的质量损失。cos_sim=0.94 对于质量敏感场景不可接受，如代码生成、数学推理等场景，建议使用 4-bit Value。
Hybrid Decode 需要反量化回 float32。虽然论文设计了融合 Triton 内核来避免这一步，但当前实现的 hybrid 路径仍会将所有压缩 token 反量化到 float32 再计算。
TurboQuant 最适合以下场景：
不太适合的场景：
# 安装
pip install -e .
# 验证算法正确性（CPU，无需 GPU）
python validate_paper.py
# 运行对抗性审计（同样 CPU）
python audit_claims.py
# pytest 测试套件
python -m pytest test_modular.py -v
# 真实 benchmark（需 4×RTX 3090 + Qwen3.5-27B-AWQ）
CUDA_VISIBLE_DEVICES=0,1,4,6 python proof.py
依赖环境：Python ≥ 3.10、torch ≥ 2.1、vllm ≥ 0.16、triton ≥ 3.0，CUDA 12.x，GPU 显存 ≥ 24GB。
TurboQuant 的出现，折射出一个正在加速的趋势：大模型推理正在从"能用"走向"用得起"。
2024-2025 年，FP8/AWQ/Q4 权重量化解决了模型"装不进去"的问题；但上下文越来越长后，运行时 KV Cache 成了新的显存杀手。TurboQuant 从算法层面给出了答案——不是卸载到 CPU/SSD（那样延迟爆炸），而是用有数学保障的量化方案，在 GPU 显存内解决。
从技术演进角度看，这个方向还有很大空间：当前 vLLM 集成还是 monkey-patch 方式（侵入性强），full_tq 模式未实现，Triton 融合内核的性能优势也还未完全兑现。可以预期，随着 vLLM 官方 attention backend API 的开放，TurboQuant 这类方案的集成深度会越来越高，最终成为推理引擎的标配功能。
项目信息：GPL-3.0 开源协议，Python 实现，GitHub 1720 ⭐，Star 增长稳健。如果你正在为长上下文推理的显存瓶颈头疼，这个项目值得 clone 下来跑一跑 proof.py。