SAMcache: 面向多模态智能体推理的 Token 压缩与 Cache 复用联合优化系统

第三届全国研究生操作系统开源大赛 | 武汉大学 · SuperAgentMaker

Smart Agent Memory Cache — 让多模态智能体的每一次推理都更快、更省

📋 目录

背景与动机
核心创新
系统架构
快速开始
性能评估
项目结构
与现有工作的关系
团队成员

🎯 背景与动机

多模态智能体（VLM-based Agent）在”规划-执行-反思”的长生命周期推理中，面临两大核心矛盾：

矛盾一：跨轮次上下文回顾导致的重复计算 智能体反复回顾历史多模态上下文时，相同图像被重复编码（ViT）+ 重复 Prefill，造成极大的算力浪费。

矛盾二：视觉 Token 急剧膨胀 高分辨率图像产生成百上千的视觉 Token，挤占显存并带来注意力机制的二次方计算开销。

我们的破局思路：复用 — 压缩 — 重算三者联合优化

💡 核心创新

创新 1：基于内容哈希的跨轮次多模态缓存复用

借鉴 VLCache 的位置无关 KV Cache 复用思想，但引入请求级全局哈希 + 图像级独立哈希双重寻址机制：

首次出现：全量计算 ViT + Prefill，在 RoPE 应用前存储 KV Cache
再次命中：直接复用 ViT 输出和图像 KV Cache，跳过 90%+ 冗余计算
硬件友好：将稀疏注意力转化为连续 Block Sparse Attention

创新 2：MoE 路由驱动的视觉 Token 多阶段压缩

不同于传统方法（附加评分网络或注意力图 Top-K 裁剪），我们复用 VLM-MoE 内部的 Router Logits 作为低成本高鲁棒的重要性信号：

在预设解码层（如第 2/6/15 层）触发多阶段锚点选择
综合考虑路由置信度、主导专家类别、概率分布多样性
未保留 Token 加权聚合到锚点而非简单丢弃

创新 3：低代价高保真的两步重计算与误差修正（核心融合创新）

针对 Cache 复用与 Token 裁剪叠加引入的双重偏差，提出双轨重计算策略：

轨道 1（头部截断）：重算序列前端 ~10% Token，稳固 Attention Sink 骨架，阻断误差传播链
轨道 2（语义关键）：基于 MoE 路由置信度重算与当前 Prompt 高度相关的关键语义 Token
层感知预算分配：离线构建层敏感度曲线，在单调非递增约束下贪心求解各层最优重算率
**总重算率仅 2%~5%**，即可恢复到近无损精度

创新 4：智能体分支推理的内存共享

针对智能体多路径决策场景，维护分支上下文树并实现 Copy-on-Write 机制，避免分支推理时的显存爆炸。同时探索 GPU 显存、主存与外部存储之间的分层冷热数据迁移。

🏗 系统架构

┌─────────────────────────────────────────────────────────────┐
│                     多模态智能体请求                          │
└──────────────────┬──────────────────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────────────┐
│  ① 内容寻址层                                                │
│  ┌──────────────────────────────────────────────┐           │
│  │  全局哈希  ←  图像像素值                      │           │
│  │  图像级哈希 ←  逐图像独立哈希                  │           │
│  │  → 命中判定 → 未命中 → 正常 ViT + Prefill    │           │
│  │            → 命中   → 跳过 ViT，复用缓存      │           │
│  └──────────────────────────────────────────────┘           │
└──────────────────┬──────────────────────────────────────────┘
                   ▼
┌──────────────────────────────────────────────────────────────┐
│  ② MoE 路由压缩层                                            │
│  ┌──────────────────────────────────────────────┐           │
│  │  Forward Hook → 采集 Router Logits           │           │
│  │  锚点选择 → 路由置信度 + 专家多样性 + 分布相似性│          │
│  │  Token 合并 → 加权聚合到锚点                  │           │
│  │  状态同步 → 更新 mask / position_ids / RoPE  │           │
│  └──────────────────────────────────────────────┘           │
└──────────────────┬──────────────────────────────────────────┘
                   ▼
┌──────────────────────────────────────────────────────────────┐
│  ③ 动态重计算层                                              │
│  ┌──────────────────────────────────────────────┐           │
│  │  层敏感度评估 → 离线探针测试                   │           │
│  │  预算分配 → 受限贪心（单调非递增约束）          │           │
│  │  双轨重算 → 头部截断 + 语义关键 Token          │           │
│  └──────────────────────────────────────────────┘           │
└──────────────────┬──────────────────────────────────────────┘
                   ▼
┌──────────────────────────────────────────────────────────────┐
│  ④ 智能体上下文管理层                                        │
│  ┌──────────────────────────────────────────────┐           │
│  │  分支上下文树 → 多路径决策追踪                │           │
│  │  Copy-on-Write → 分支内存共享                │           │
│  │  分层存储 → GPU 显存 / 主存 / 外存冷热迁移    │           │
│  └──────────────────────────────────────────────┘           │
└──────────────────────────────────────────────────────────────┘

🚀 快速开始

环境要求

Python ≥ 3.10
CUDA ≥ 12.1（推荐）
至少 1 张 NVIDIA GPU（A100 80G 推荐）
基于 openEuler / openKylin / OpenHarmony 等 Linux 发行版（也支持 Ubuntu 22.04+）

安装

# 1. 克隆仓库
git clone https://github.com/SuperAgentMaker/SAMcache.git
cd SAMcache

# 2. 安装依赖
pip install -r requirements.txt

# 3. 安装 samcache 包
pip install -e .

# 4. 准备 VLCache（SGLang 后端）
# 参考 third_party/VLCache 的 README 安装 SGLang

快速示例

from samcache import SAMcacheEngine

# 初始化引擎
engine = SAMcacheEngine(
    model_path="OpenGVLab/InternVL3-8B",
    cache_enabled=True,
    compression_enabled=True,
    recompute_ratio=0.05,
)

# 多轮对话（相同图片复用缓存）
response1 = engine.chat(
    images=["diagram.png"],
    prompt="请解释这张系统架构图",
)

response2 = engine.chat(
    images=["diagram.png"],
    prompt="图中的数据流向是怎样的？",  # 复用 diagram.png 的 ViT 和 KV Cache
)

运行基准测试

# 运行标准 benchmark
bash scripts/run_benchmark.sh --model InternVL3-8B --benchmark mmmu

# 使用 VLMEvalKit 评估
bash scripts/evaluate.sh --model InternVL3-8B --benchmark MMMU

📊 性能评估

实验环境

配置	详情
GPU	NVIDIA A100 80GB × 1
CPU	Intel Xeon Platinum 8467C
内存	512 GB
操作系统	Ubuntu 22.04 LTS
推理框架	SGLang v0.5.3rc2 (VLCache)
模型	InternVL3-8B / InternVL3.5-30B-A3B

主要结果

指标	效果	说明
MMMU 精度	≤1% 跌幅	与全量推理几乎持平
显存占用	↓ XX%	长序列场景优势更明显
TTFT	↑ X 倍	缓存命中场景最高提升
重算率	2%~5%	仅极低额外计算开销

详细实验结果见 docs/design.md

📁 项目结构

SAMcache/
├── samcache/                        # 核心 Python 包
│   ├── core/                        # 核心引擎与配置
│   ├── cache/                       # 多模态缓存管理器
│   ├── compression/                 # MoE 路由压缩器
│   ├── recompute/                   # 动态重计算引擎
│   ├── agent/                       # 智能体上下文管理器
│   └── models/                      # 模型适配
├── docs/                            # 文档
├── scripts/                         # 实用脚本
├── benchmarks/                      # 基准测试
├── examples/                        # 使用示例
├── tests/                           # 单元测试
├── patches/                         # 对 VLCache/SGLang 的补丁
└── third_party/                     # 第三方依赖链接
    ├── VLCache →                    # 指向 VLCache (SGLang fork)
    └── VLMEvalKit →                 # 指向 VLMEvalKit

🔗 与现有工作的关系

项目	关系	在本项目中的角色
VLCache	核心参考	提供位置无关 KV Cache 复用基础能力；我们在此基础上增加层感知重算与压缩协同
SlimMoE-VLM	核心参考	提供 MoE 路由驱动的视觉 Token 压缩方法论；我们将其与缓存复用联合优化
SGLang	底层框架	VLCache 基于 SGLang v0.5.3rc2；我们的插件通过 SGLang 的 hook 机制集成
VLMEvalKit	评估工具	用于在 MMMU 等基准上验证精度

我们的独特贡献：

首次将 缓存复用 与 Token 压缩 联合优化，而非单独使用
提出 双轨重计算 策略，以极低开销消除叠加误差
设计 层感知预算分配 算法，突破统一重算率的次优限制
面向 完整智能体工作流（多轮/分支/工具调用），而非单轮推理

👥 团队成员

武汉大学 · SuperAgentMaker

成员	角色	方向
陆冕	队长	系统架构、缓存复用
汪晓阳	核心开发	MoE 路由压缩、算法实现
庞力诚	核心开发	重计算引擎、性能优化

📄 许可证

本项目基于 Apache License 2.0 开源。

_{第三届全国研究生操作系统开源大赛 · 初赛作品}