Upload README.md with huggingface_hub

README.md

@@ -1,3 +1,80 @@
+# 🚀 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/文件) |
+
+## 🔑 核心算法
+
+### 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
+
 ---
-license: gpl-3.0
----
+
+*Cloud LTE Studio · 2026-08-09*