README.md

# 🚀 KV Cache Compression — 实现代码库

**大模型 KV 缓存压缩完整实现** | 基于 DeepSeek-V2-Lite MLA 实测

## 🎯 核心成果 (L40S 实测)

| 方案 | KV/token | 压缩率 | 误差 |
|------|----------|--------|------|
| 标准 MHA | 270 KB | 1x | — |
| 吸收式 MLA | 30.4 KB | 8.9x | 0 |
| + per-channel INT8 | 15.2 KB | 17.8x | 0.011 |
| + 非对称 INT4 | **7.6 KB** | **35.6x** | 0.079 |

**单卡 L40S → 138 万 token 上下文，真实推理质量无损**

## 📦 模块

| 文件 | 功能 |
|------|------|
| `kv_cache_core.py` | 核心算法: 吸收式MLA + per-channel量化 + 分层量化 + 容量估算 |
| `agentframe_core.py` | 前缀感知缓存池 (PrefixPool + 多会话共享) |
| `agentframe_orchestrator.py` | Agent 编排层 (脑/手/记忆/循环) |
| `agentframe_hands.py` | OpenClaw 工具集 (exec/browser/文件) |
| `agentframe_quad.py` | **四层融合实现**: 认知(MetaCog) × 路由(LandmarkRouter) × 存储(AbsorbedMLA) × 物理(KVPager) |
| `agentframe_four_layer_blueprint.md` | 四层融合设计蓝图 (10.4KB) |

## 🔑 核心算法

### 1. 吸收式 MLA 缓存
标准 transformers 缓存展开后的 K/V (270KB, 浪费 MLA 架构优势)。
本实现直接缓存 576 维潜在向量 (kv_lora_rank 512 + k_pe 64)。

```python
# 缓存潜在向量, 计算时 kv_b_proj 展开
compressed_kv = kv_a_proj_with_mqa(hidden)  # [seq, 512+64]
latent, k_pe = torch.split(compressed_kv, [512, 64], dim=-1)
# → 只缓存 latent + k_pe = 30.4KB/token
```

### 2. per-channel 量化
潜在向量 outlier 按 channel 局部存在, per-tensor 被拖累 (误差 0.298),
per-channel 各自归一化后误差降 27 倍 (0.011)。

```python
# 512维分32块, 每块独立 scale
tc = tensor.view(-1, 32, 16)
scale = tc.abs().amax(dim=-1, keepdim=True) / 127
q = (tc/scale).round().clamp(-127, 127)
```

### 3. 分层量化 (Agent 专用)
按信息价值分配精度: 思考链 INT8 / 工具结果 INT4。

### 4. 前缀感知缓存池
多个 Agent 共享 System Prompt 的 KV 缓存 (只存 1 份)。

## 📊 验证数据

```
吸收式缓存 INT8 误差: 0.0050
思考链 INT8 误差:    0.0037
工具结果 INT4 误差:  0.0640
L40S 10GB → 138 万 token
```

## 🚀 快速开始

```bash
# 核心算法 (无需 GPU)
python3 kv_cache_core.py

# Agent 框架
python3 agentframe_orchestrator.py
```

## 📄 许可证

GPL-3.0 License

---

*Cloud LTE Studio · 2026-08-09*