长上下文内存大瘦身：LARQL 四大 KV 缓存引擎原理与横向对比-平芜编程栈

【免费下载链接】larql

项目地址：https://gitcode.com/gh_mirrors/la/larql

LARQL 是一款用 Rust 编写的开源大模型推理引擎，其 KV 缓存管理模块larql-kv内置四大 KV 缓存引擎：全量 canonical 引擎、window 窗口引擎、codec 压缩引擎与 no-cache 重放模式，帮助开发者把长上下文场景的显存占用直接砍掉一半以上。本文用通俗的语言讲清四种引擎的工作原理、内存与精度取舍，并给出一份可直接上手的横向对比清单。

为什么长上下文会让内存"爆炸"？

在 Transformer 推理中，每生成一个 token，模型都会把新的 Key/Value 向量追加进KV 缓存（KV Cache）。上下文越长，缓存行越多，内存占用呈线性增长——这也是长文本推理的第一大成本项。

以仓库中的 Gemma 3 4B 为例（34 层，其中 29 层滑动窗口W=1024、5 层全局注意力，kv_dim=1024，f32 下每层每行约 8 KiB）：

场景	驻留行数	内存占用
4096 位置全量保留	139 264 行	≈ 1.06 GiB
4096 位置窗口驻留	50 176 行	≈ 0.38 GiB（−64%）

也就是说：只保留注意力真正能读到的行，比全部保留能省掉 2/3 以上的内存。LARQL 的四大 KV 缓存引擎正是围绕"保留什么、怎么压缩、要不要保留"这三个问题给出的四种答案，核心实现集中在 crates/larql-kv/src/vindex3/registry.rs。

引擎一：canonical（standard）——精确的"基准线"

机制：CanonicalKvState（身份标识canonical/v1）保存每个 token 的完整 f32 K/V 行，不做任何窗口裁剪或压缩。它是语义上的"参考实现"：仓库中的门禁测试要求它与解释器行级实现在 prefill、resume、decode 三个阶段保持逐位一致（bit-identical）。

适合谁：需要可复现、可审计结果的场景，比如正确性对比、性能基线。

larql run model.vindex3 "Hello" --engine standard

代价：内存随上下文线性增长。源码见 crates/larql-kv/src/vindex3/mod.rs。

引擎二：window——只留"注意力地平线"内的行

机制：WindowKvState（window/v1）为每一层只保留执行计划声明的注意力范围内、后续步骤还可能读到的 K/V 行。一个窗口为w的滑动层，无论对话多长都恒定只持有w行；超出范围的旧行在"排水"时直接释放其内存分配。由于行是后端自己的分配（append 时接管、不拷贝），窗口内读取与全量读取逐位相同——即"窗口内精确"。

实测效果：同样是 Gemma 3 4B @ 4096 位置，从 1.06 GiB 降到 0.38 GiB（−64%）。

larql run model.vindex3 "Hello" --continuation window/v1

源码中"释放低于地平线的行"逻辑非常直白，见 crates/larql-kv/src/vindex3/window.rs 的release_below方法。

引擎三：codec（turbo-quant）——把 K/V 压到 3~4 bit

机制：CodecKvState（codec/v1）在 window 的保留范围之上再做一层压缩：每行 K/V 按 head 为单位，用 **TurboQuant 编解码器（WHT 哈达玛旋转 + Lloyd-Max 量化）**一次性编码为 3 或 4 bit，随后丢弃原始 f32 行。读取时按层解码到一块复用的 f32 暂存区。

关键细节：

必须显式指定位宽，如bits=4；
head_dim必须是 2 的幂（旋转的硬性要求），否则构造时直接拒绝；
官方声明这是近似引擎——输出不与全量缓存逐位一致。仓库记录的实测精度为 4-bit 下逐行余弦相似度 ≈ 0.9954。

larql run model.vindex3 "Hello" --continuation codec/v1 --continuation-option bits=4

压缩实现见 crates/larql-kv/src/engines/turbo_quant/，V3 侧封装见 crates/larql-kv/src/vindex3/codec.rs。

引擎四：no-cache——不驻留、每步重算的精确模式

机制：no-cache不在步骤之间保留任何 KV 状态，每一步都把完整输入历史通过全新状态重放一遍。它只保留 token ID 序列，是内存占用最小的模式，且输出精确。

定位：它是"精确执行控制"而非性能优化——适合做正确性验证、调试对比，不适合追求速度的生产路径。

larql run model.vindex3 "Hello" --engine no-cache

💡 注意：no-cache并不注册为独立的 continuation 提供者，而是叠加在任意提供者之上的运行时重放模式，官方文档对此有明确说明，见 docs/vindex3/runtime-followups.md。

四大 KV 缓存引擎横向对比怎么选？

维度	canonical（standard）	window	codec（turbo-quant）	no-cache
身份标识	`canonical/v1`	`window/v1`	`codec/v1`	运行时模式
驻留内容	全部 f32 K/V 行	注意力地平线内的 f32 行	地平线内的 3/4-bit 压缩行	无（仅输入历史）
内存	O(序列长度)，最大	约为全量的 1/3	比 window 再低数倍	最小
精度	精确（参考基准）	窗口内精确	近似（4-bit cos≈0.9954）	精确
典型场景	基线、审计、调试	长对话、滑动窗口架构	超长上下文 + 有限显存	正确性交叉验证

选择口诀：

验证正确性、做基线 →standard/no-cache；
长对话想省内存且要求窗口内精确 →window/v1；
显存极限、能接受微小近似 →codec/v1（记得显式写bits）。

动手：安装与运行 LARQL

克隆仓库即可体验：

git clone https://gitcode.com/gh_mirrors/la/larql cd larql cargo test -p larql-kv

更多 V2 路径的引擎选择语法（--engine turbo-quant:bits=3、--engine windowed-checkpoint:window=256等）记录在 crates/larql-kv/src/engines/mod.rs 的模块文档中，其中附有 Gemma 3 4B @ 370K token 的实测内存/精度阶梯表；关于"物理容量 ≠ 逻辑驻留"的易混淆点，可阅读 docs/kv-residency-contract.md；各引擎从 V2 到 V3 的对应关系见 docs/continuation-plane-inventory.md。

总结

LARQL 的 KV 缓存设计把"保留多少行、每行占多少字节、要不要保留"拆成了四个正交的引擎选项：canonical 保精确、window 保边界、codec 压位宽、no-cache 保兜底。对新手而言，先用standard跑通、再按显存压力逐级切换到window/v1与codec/v1，就是长上下文内存优化的最短路径。