update kvcache blog

Author: gushiqiao

_articles/Kvcache.md

@@ -0,0 +1,337 @@
+---
+layout: post
+title: "让自回归视频模型更省显存：LightX2V KV Cache 管理与优化解析"
+author: "LightX2V Team"
+date: 2026-05-13
+tags: [KV Cache, Autoregressive Video, Consumer GPU, Inference Optimization]
+---
+
+在视频生成模型里，显存压力并不只来自模型权重。对于自回归视频生成、实时世界模型和长序列视频生成这类任务，**KV Cache** 会随着生成长度、帧数、分辨率和 Transformer 层数持续增长。权重可以通过 offload 暂时放到 CPU 或磁盘，但 KV Cache 是推理过程中动态产生、持续读取、反复参与 attention 的状态，因此需要单独的管理策略。
+
+LightX2V 将多个自回归视频 / 世界模型统一到同一套 KV Cache 管理路径上，并提供 rolling window、KV quantization、KV offload 等多种策略。它们可以单独使用，也可以和 weight offload 组合，帮助更大的模型运行在 RTX 3060、RTX 4090、RTX 5090 等消费级显卡上。
+
+这篇文章重点解释：
+
+- 为什么 KV Cache 会成为自回归视频模型的显存瓶颈；
+- KV Cache 管理和 weight offload 有什么区别；
+- LightX2V 如何组织 KV Cache 的生命周期；
+- rolling、quantization、offload 分别解决什么问题；
+- 面向不同显卡时应该如何选择策略。
+
+**目录：**
+
+- [为什么 KV Cache 是自回归视频生成的核心瓶颈](#为什么-kv-cache-是自回归视频生成的核心瓶颈)
+- [LightX2V KV Cache 的设计目标](#lightx2v-kv-cache-的设计目标)
+- [KV Cache 和 Weight Offload 的区别](#kv-cache-和-weight-offload-的区别)
+- [LightX2V KV Cache 的核心路径](#lightx2v-kv-cache-的核心路径)
+- [三类 KV Cache 策略](#三类-kv-cache-策略)
+- [KV Quantization 后端](#kv-quantization-后端)
+- [KV Offload 的执行时序](#kv-offload-的执行时序)
+- [推荐使用策略](#推荐使用策略)
+- [结论](#结论)
+
+---
+
+## 为什么 KV Cache 是自回归视频生成的核心瓶颈
+
+在普通 diffusion 视频生成里，模型大部分显存压力来自权重、激活和中间 feature；但在自回归视频生成或实时世界模型里，推理过程还会引入一个不断增长的历史状态：KV Cache。
+
+可以把自回归视频生成理解成下面的过程：
+
+```text
+已生成上下文  ->  当前 step / frame block  ->  生成新的 K/V  ->  写入 KV Cache
+                    ↑                                  ↓
+              attention 读取历史 KV  <------------------
+```
+
+KV Cache 的作用是避免每次都重新计算历史 token / frame 的 Key 和 Value。它用更多缓存换取更少重复计算。问题是，在视频模型里，这个缓存不是少量文本 token，而是和帧数、空间分辨率、head 数、head dim、层数相关的高维张量。
+
+KV Cache 的显存占用通常和以下因素相关：
+
+```text
+num_layers × cache_length × num_heads × head_dim × 2(K/V) × dtype_size
+```
+
+对于长视频或自回归世界模型来说，即使权重已经通过 offload 降下来了，KV Cache 仍然可能成为新的显存墙。尤其是在 14B 级模型、较高分辨率或更长上下文场景下，KV Cache 的大小会直接影响模型能否在消费级显卡上跑通。
+
+---
+
+## LightX2V KV Cache 的设计目标
+
+LightX2V 的 KV Cache 管理不是单个模型的临时逻辑，而是面向多个自回归模型的统一资源管理层。它主要有三个目标。
+
+**第一，统一入口。**  
+不同自回归视频模型都可以通过统一的 KV Cache Manager 创建、初始化和更新 KV Cache。这样可以减少每个模型各自维护一套 cache 逻辑带来的复杂度，也方便后续接入新的自回归视频或世界模型。
+
+**第二，多策略组合。**  
+KV Cache 可以选择普通 fp16 / bf16 存储，也可以启用 SageQuant、KIVI、TurboQuant 等量化后端；同时还可以选择是否启用 `kv_offload`。这些策略并不是互斥的：rolling window 负责控制历史长度，quantization 负责降低单个 cache entry 的存储成本，offload 负责把部分 KV 状态放到 CPU 侧。
+
+**第三，面向消费级显卡。**  
+KV Cache 量化减少单个 KV entry 的显存占用，KV Cache offload 把部分 KV 从 GPU 搬到 CPU，二者还可以和 weight offload 组合使用。目标是在尽量保持生成质量的前提下，让更大的自回归视频模型落到 4090 / 5090 / 3060 等设备上。
+
+---
+
+## KV Cache 和 Weight Offload 的区别
+
+Weight offload 和 KV Cache 管理都和显存优化有关，但它们处理的是完全不同的数据。
+
+| 对比项 | Weight Offload | KV Cache Management |
+|---|---|---|
+| 数据来源 | 模型加载时已有 | 推理过程中动态生成 |
+| 生命周期 | 整个推理过程基本固定 | 随生成 step 不断增长或滚动 |
+| 访问模式 | 按 block / phase 计算时读取 | 每层 attention 反复读取历史 K/V |
+| 是否会被写入 | 通常不写回 | 每个 step 都会写入新 K/V |
+| 优化重点 | 权重驻留位置与加载时机 | 容量、压缩、滚动窗口、读写和 offload |
+| 主要风险 | 加载慢导致吞吐下降 | 显存增长、读写开销、解量化开销、同步开销 |
+
+一句话概括：**weight offload 解决“模型太大放不下”的问题；KV Cache 管理解决“生成过程中历史状态越来越大”的问题。**
+
+这也是为什么二者经常需要组合使用。对于大模型，weight offload 可以降低静态权重的显存压力；对于长序列自回归推理，KV quantization 和 KV offload 则负责控制动态历史状态。
+
+---
+
+## LightX2V KV Cache 的核心路径
+
+LightX2V 的 KV Cache Manager 会根据输入 latent shape、patch size、输出帧数、local attention 配置等信息计算 cache size。随后它会创建 self-attention KV cache 和 cross-attention KV cache，并初始化对应 buffer。
+
+整体流程可以概括为：
+
+```text
+输入 latent shape
+        ↓
+计算 frame_seq_length / output frames
+        ↓
+计算 kv_size / max_attention_size / local_attn_size
+        ↓
+创建 self-attn KV cache
+        ↓
+创建 cross-attn KV cache
+        ↓
+初始化 KV buffer
+```
+
+其中 self-attention KV cache 是主要优化对象，因为它会随着自回归生成持续扩展；cross-attention KV cache 更偏静态，通常用于文本或条件上下文。
+
+在世界模型场景中，条件输入也可能拥有自己的 KV cache。例如 keyboard action 和 mouse action 可以分别维护 cache。对于带空间维度的条件，例如鼠标动作，还可以使用带额外空间维的 rolling cache，让同一套窗口管理逻辑适配 `[S, N, H, D]` 这类形状。
+
+![LightX2V KV Cache Management Overview]({{ site.baseurl }}/assets/kvcache-blog/kv_fig1.png)
+*图 1：LightX2V KV Cache 管理总览。KVCacheManager 负责统一创建 self-attention / cross-attention cache，并在 rolling、quantization、offload 等策略之间组织运行时路径。*
+
+---
+
+## 三类 KV Cache 策略
+
+LightX2V 的 KV Cache 优化可以按三类策略理解：rolling、quantization、offload。
+
+### Rolling KV Cache：控制历史窗口
+
+最基础的策略是 rolling cache。它的核心思想是：不是无限保存所有历史 KV，而是在一定窗口内滚动维护历史上下文。对于视频自回归，这通常和 local attention、sink token / sink frame、最大 attention size 等概念相关。
+
+```text
+[ sink context ] [ rolling local window ]
+       ↑                  ↑
+  长期保留           随生成向前滚动
+```
+
+这类策略适合控制 KV Cache 的上限，避免生成长度越长显存越无限增长。它的关键不是压缩单个 KV entry，而是决定哪些历史上下文必须保留、哪些可以随着窗口前移被淘汰。
+
+### KV Quantization：降低单个 KV entry 的存储成本
+
+第二类策略是量化。KV quantization 的目标是降低每个 K/V 元素的存储成本。例如原始 KV 使用 fp16 时，每个元素通常占 2 bytes；如果使用 int8 或 int4，就可以显著降低缓存占用。
+
+LightX2V 支持多种 KV quant 后端：
+
+| 后端 | 核心思路 | 适合场景 |
+|---|---|---|
+| SageQuant | K int8，V fp8 / fp16，并配合 SageAttention 使用 | 工程上较稳，适合通用压缩 |
+| KIVI | K/V int2、int4、int8 | 更激进的低 bit 压缩 |
+| TurboQuant | key/value compression + codebook | 更复杂的压缩策略，适合进一步压缩 KV |
+
+这里需要特别说明 SageQuant。它通常不是单独使用的 KV 存储格式，而是和 SageAttention 后端配合使用：KV Cache 以 SageAttention 能直接消费的低精度格式保存，attention kernel 在计算时直接读取对应格式，因此不需要先把 KV 显式反量化回 fp16 / bf16 再做 attention。这也是 SageQuant 相对适合工程落地的原因之一，它减少了显存占用，同时避免了一部分反量化带来的额外开销。
+
+量化的收益很直观：更低 bit 数通常意味着更低显存。代价也需要分情况看：如果 attention 后端不能直接消费量化格式，读取时可能需要反量化；写入 KV 时也有量化成本，并且不同 bit 数会影响质量稳定性。
+
+![LightX2V KV Quantization Details]({{ site.baseurl }}/assets/kvcache-blog/kv_fig2.png)
+*图 2：LightX2V KV quantization 后端对比。SageQuant 的优势在于可以配合 SageAttention 直接消费量化 KV；TurboQuant 和 KIVI 更强调压缩率，但读取路径通常需要重建、解量化或 unpack。*
+
+### KV Offload：把部分 KV 放到 CPU
+
+第三类策略是 KV offload。它和 weight offload 的思路相似，但对象是动态 KV Cache。
+
+KV offload 的基本流程可以理解为：
+
+```text
+当前 layer 需要 KV
+        ↓
+begin_layer：确保该 layer 的 KV 在当前 GPU buffer
+        ↓
+attention 读取 / 更新 KV
+        ↓
+end_layer：必要时写回 dirty range
+        ↓
+预取下一 layer KV 到另一个 buffer
+        ↓
+切换 GPU buffer
+```
+
+这里的关键点是：KV Cache 不只是读，还会写。每个自回归 step 产生的新 K/V 都要写入 cache。如果当前 GPU buffer 中的 KV 被更新，就需要标记 dirty range，并在合适时机写回 CPU 侧。
+
+---
+
+## KV Quantization 后端
+
+### SageQuant：工程上偏稳的 KV 压缩
+
+SageQuant 可以理解成和 SageAttention 深度配合的 KV 压缩方案。LightX2V 中常见配置是 K 使用 int8，V 使用 fp8 / fp16；这些低精度 KV 不是先反量化回 fp16 / bf16 再交给普通 attention，而是直接交给 SageAttention 后端消费。这样既能降低 KV Cache 的显存占用，也能避免显式反量化带来的额外开销。
+
+优势：
+
+- 相比 fp16 KV，显存下降明显；
+- K / V 可以使用不同类型，兼顾 attention 的数值敏感性；
+- SageAttention 可以直接消费对应低精度格式，减少反量化开销；
+- 适合作为中等规模模型或通用场景的默认尝试。
+
+潜在代价：
+
+- 需要配合 SageAttention 后端使用，普通 attention 后端不一定能直接消费该格式；
+- V 使用 fp8 时需要关注 GPU 对 fp8 的支持；
+- scale 选择会影响稳定性；
+- 极低显存场景下，压缩率可能不如 int4 / int2 激进方案。
+
+### KIVI：低 bit KV Cache 压缩
+
+KIVI 的特点是更激进，可以做到 int2、int4、int8。它适合显存非常紧张、希望最大程度压低 KV Cache 的场景。
+
+KIVI 更适合下面这些情况：
+
+- 显存非常紧张；
+- 希望最大程度压低 KV Cache；
+- 可以接受一定的量化 / 解量化开销；
+- 需要更激进的长上下文压缩。
+
+需要注意的是，更低 bit 并不总是更好。它会带来更大的数值误差和潜在质量波动，因此通常需要结合具体模型、分辨率和生成长度做验证。
+
+### TurboQuant：更复杂的 key/value compression
+
+TurboQuant 的定位更偏“压缩系统”。它包含 key bits、value bits、codebook 等配置项，可以做更细粒度的 key/value compression。
+
+它的价值在于：
+
+- 可以把 key/value 做更细粒度压缩；
+- 支持 codebook 思路；
+- 对长序列、长视频场景可能更有压缩潜力。
+
+但它也更复杂：
+
+- codebook 管理更重要；
+- 首次运行可能有额外准备成本；
+- 不同模型、分辨率、帧数下需要独立验证质量和稳定性。
+
+---
+
+## KV Offload 的执行时序
+
+KV offload 的核心是双缓冲：当前 GPU buffer 供 attention 计算使用，另一个 GPU buffer 同时准备下一层需要的 KV，CPU pinned memory 则作为 GPU 之外的 KV 存储区域。
+
+![LightX2V KV Cache Offload Inference]({{ site.baseurl }}/assets/kvcache-blog/kv_fig3.png)
+*图 3：KV offload 的双缓冲执行时序。当前层使用一个 GPU buffer 计算 attention，另一个 buffer 负责预取下一层 KV 或写回 dirty range，从而尽量减少等待时间。*
+
+和 weight offload 类似，这里也不是保证所有 copy 都能完全被计算隐藏，而是通过 pipeline 尽量减少 GPU 等待时间。KV offload 的关键点有三个。
+
+**第一，读写都是动态的。**  
+KV Cache 不仅要加载历史 KV，还会写入新的 K/V。如果当前 buffer 被更新，就需要标记 dirty range 并在合适时机写回。
+
+**第二，双缓冲避免互相阻塞。**  
+一个 buffer 供当前 layer 使用，另一个 buffer 可以进行预取或写回，下一层再切换。
+
+**第三，事件同步保证正确性。**  
+offload 需要在 load、compute、writeback 之间建立清晰的同步关系。当前层必须等自己的 KV 加载完成才能计算；被修改的 KV 必须在 buffer 复用前完成写回。
+
+---
+
+## 推荐使用策略
+
+可以按显卡显存和模型规模来选择 KV Cache 策略。
+
+### RTX 5090 / 4090D：优先量化，必要时再 KV offload
+
+这类显卡显存相对充足。建议优先尝试：
+
+```text
+weight offload + KV quantization
+```
+
+如果高分辨率或长上下文仍然接近显存上限，再打开：
+
+```text
+weight offload + KV quantization + KV offload
+```
+
+在这个档位上，KV quantization 通常比 KV offload 更值得优先尝试，因为量化可以直接降低 GPU 上的 KV 占用，而不会引入太多 CPU/GPU 传输。
+
+### RTX 4060 / 3060：KV quant + KV offload 更关键
+
+对于 8 GB / 12 GB 显存设备，KV Cache 很容易成为主要瓶颈。建议组合使用：
+
+```text
+更低 bit KV quant
++ KV offload
++ weight offload
++ 降低分辨率 / 帧数 / window size
+```
+
+这类设备的目标通常不是极限速度，而是先保证可运行，再通过量化后端、local attention、offload 策略逐步优化速度。
+
+### 数据中心 GPU：KV Cache 仍然有价值
+
+即使在 A100 / H100 / H200 上，KV Cache 管理也有意义。它可以用于：
+
+- 提升单卡可处理的视频长度；
+- 支持更多并发请求；
+- 降低服务化部署的峰值显存；
+- 和 sequence parallel / tensor parallel 组合，提高长序列吞吐。
+
+---
+
+## Lingbot World Fast 性能对比表
+
+下面的表格预留给 Lingbot World Fast 的实测对比。建议固定同一组输入条件，例如相同分辨率、帧数、prompt、seed、GPU 和推理配置，然后分别记录显存、时间和生成视频，方便观察不同 KV Cache 策略的收益和代价。
+
+### 基线对比
+
+| 方案 | KV Quant | KV Offload | Weight Offload | 峰值显存 | 总耗时 | 平均 iter 时间 | 视频 / 结果 |
+|---|---|---|---|---:|---:|---:|---|
+| Lingbot 原始实现 | - | - | - |  |  |  |  |
+| LightX2V | - | - | - |  |  |  |  |
+
+### KV Quantization 对比
+
+| 方案 | KV Quant | KV Offload | Weight Offload | 峰值显存 | 总耗时 | 平均 iter 时间 | 视频 / 结果 |
+|---|---|---|---|---:|---:|---:|---|
+| LightX2V + SageQuant | SageQuant | - | - |  |  |  |  |
+| LightX2V + KIVI | KIVI | - | - |  |  |  |  |
+| LightX2V + TurboQuant | TurboQuant | - | - |  |  |  |  |
+
+### Offload 组合对比
+
+| 方案 | KV Quant | KV Offload | Weight Offload | 峰值显存 | 总耗时 | 平均 iter 时间 | 视频 / 结果 |
+|---|---|---|---|---:|---:|---:|---|
+| LightX2V + KV Offload | - | 开启 | - |  |  |  |  |
+| LightX2V + KV Offload + Weight Offload | - | 开启 | 开启 |  |  |  |  |
+| LightX2V + SageQuant + KV Offload + Weight Offload | SageQuant | 开启 | 开启 |  |  |  |  |
+
+---
+
+## 结论
+
+LightX2V 的 KV Cache 管理可以概括为一句话：
+
+> 对自回归视频模型来说，显存优化不能只看权重，还必须管理不断增长的历史 KV 状态。
+
+从工程角度看，LightX2V 做了三层抽象：
+
+1. 用 **KV Cache Manager** 统一不同自回归模型的 KV Cache 创建、初始化和生命周期；
+2. 用 **Rolling / Local Attention** 控制历史窗口，避免 KV 无限增长；
+3. 用 **KV Quantization + KV Offload** 降低 KV Cache 的显存占用，并通过双缓冲和异步 stream 尽量减少搬运开销。
+
+随着自回归视频生成和实时世界模型的发展，KV Cache 会越来越成为推理系统的重要组成部分。对于消费级显卡来说，weight offload 解决的是静态权重显存压力，而 KV Cache 管理解决的是动态历史状态显存压力。只有二者结合，才能让更大的长序列视频模型真正落到本地设备上。