| # AgentFrame 四层融合蓝图 |
| ## 长上下文 Agent 终极方案：认知 × 路由 × 压缩 × 分页 |
|
|
| **版本**: v1.0 |
| **日期**: 2026-08-09 |
| **状态**: 设计蓝图（待实施） |
| **许可证**: GPL-3.0 |
|
|
| --- |
|
|
| ## 1. 设计动机 |
|
|
| ### 1.1 长上下文 Agent 的四个瓶颈 |
|
|
| | 瓶颈 | 问题 | 现有方案 | 局限 | |
| |------|------|---------|------| |
| | **认知** | 不知道什么该记 | 全量塞上下文 | 上下文爆炸 | |
| | **路由** | 不知道什么该读 | 全注意力扫描 | O(N²) 计算 | |
| | **存储** | KV 存不下 | 展开存储 | 显存线性爆炸 | |
| | **物理** | 显存放不下 | 全留显存 | 容量封顶 | |
|
|
| ### 1.2 核心洞察 |
|
|
| 四个瓶颈是**正交的**——各自独立解决，可以全量叠加： |
|
|
| ``` |
| 认知层 (Cognitive Workspace 思路) → 决定"记什么" |
| 路由层 (HiLS-Attention 思路) → 决定"读什么" |
| 存储层 (吸收式 MLA + 量化, 自研) → 决定"存多小" |
| 物理层 (ICPE 思路) → 决定"放哪" |
| ``` |
|
|
| **叠加效果（理论估算）**： |
|
|
| | 层 | 贡献 | 效果 | |
| |----|------|------| |
| | 存储层 | 270KB → 7.6KB | 35.6× 存储减 | |
| | 路由层 | 只读 top-K 块 | ~13× 计算减 | |
| | 物理层 | 冷 KV 换出 | 显存占用再降 10-100× | |
| | 认知层 | 只放必要信息 | 上下文需求减 3-10× | |
|
|
| **综合：单卡 L40S 从 138 万 token → 理论 1 亿+ token 等效上下文** |
|
|
| --- |
|
|
| ## 2. 四层架构总览 |
|
|
| ``` |
| ┌─────────────────────────────────────────────────────────────┐ |
| │ Agent Loop (编排层) │ |
| │ AgentFrame Orchestrator (现有, 增强) │ |
| └──────┬──────────────────────┬──────────────────────┬────────┘ |
| │ │ │ |
| ▼ ▼ ▼ |
| ┌─────────────┐ ┌──────────────────┐ ┌─────────────────┐ |
| │ 认知层 │ │ 路由层 │ │ 存储层 │ |
| │ MetaCog │ │ LandmarkRouter │ │ AbsorbedMLA │ |
| │ 控制器 │ │ 块索引 + 分层软max│ │ 缓存 + 量化 │ |
| └──────┬──────┘ └────────┬─────────┘ └────────┬────────┘ |
| │ │ │ |
| └────────────┬───────┴──────────┬───────────┘ |
| ▼ ▼ |
| ┌──────────────────────────────────┐ |
| │ 物理层 │ |
| │ KV Pager (热/温/冷分层) │ |
| │ 显存 ↔ 内存 ↔ 磁盘 (mmap) │ |
| └──────────────────────────────────┘ |
| ``` |
|
|
| --- |
|
|
| ## 3. 层 1：认知层（MetaCog Controller） |
|
|
| ### 3.1 来源 |
| Cognitive Workspace (tao-hpu/cognitive-workspace, arXiv:2508.13171) |
|
|
| ### 3.2 职责 |
| 决定**哪些信息需要进入 KV 缓存**，模仿人类认知的元认知控制。 |
|
|
| ### 3.3 组件设计 |
|
|
| ```python |
| class MetaCogController: |
| """ |
| 认知层控制器：任务分解 + 置信度追踪 + 信息缺口分析 |
| """ |
| def __init__(self, confidence_threshold=0.7): |
| self.confidence_threshold = confidence_threshold |
| self.task_stack = [] # 任务分解栈 |
| self.info_gaps = set() # 已知信息缺口 |
| self.buffer_promotions = [] # 记忆提升记录 |
| |
| def decompose_task(self, task: str) -> list[SubTask]: |
| """ |
| 任务分解：把复杂任务拆成子任务 |
| 每个子任务标注需要的信息类型 |
| """ |
| ... |
| |
| def track_confidence(self, response) -> float: |
| """ |
| 置信度追踪：模型输出时估算置信度 |
| 低置信度 → 触发信息检索 |
| """ |
| ... |
| |
| def analyze_gap(self, task: SubTask, context) -> list[Query]: |
| """ |
| 信息缺口分析：识别完成任务还缺什么信息 |
| 返回定向检索 query（比盲目 top-k 聪明） |
| """ |
| ... |
| |
| def promote_to_longterm(self, buffer_item): |
| """ |
| 记忆提升：工作缓冲 → 情景缓冲 → 长期记忆 |
| 按 频率 + 重要性 + 关联度 打分 |
| """ |
| ... |
| ``` |
|
|
| ### 3.4 与存储层的接口 |
|
|
| ```python |
| # 认知层输出 → 存储层输入 |
| class RetrievalDirective: |
| """认知层告诉存储层：这次推理需要哪些 KV""" |
| required_chunks: list[str] # 需要的块 ID |
| priority: Literal["hot", "warm", "cold"] |
| reason: str # 为什么需要（可审计） |
| confidence: float # 认知层置信度 |
| ``` |
|
|
| --- |
|
|
| ## 4. 层 2：路由层（LandmarkRouter） |
|
|
| ### 4.1 来源 |
| HiLS-Attention (Tencent-Hunyuan/HiLS-Attention, arXiv:2607.02980) |
|
|
| ### 4.2 职责 |
| 决定**读哪些 KV 块**——用 landmark 摘要做稀疏检索，避免全量扫描。 |
|
|
| ### 4.3 组件设计 |
|
|
| ```python |
| class LandmarkRouter: |
| """ |
| 路由层：landmark 块索引 + 分层软max + 低秩校准 |
| """ |
| def __init__(self, chunk_size=64, top_k=32, num_layers=27): |
| self.chunk_size = chunk_size |
| self.top_k = top_k |
| self.num_layers = num_layers |
| # landmark token 的可学习 query (每层一个) |
| self.landmark_queries = nn.Parameter(...) # [L, d_model] |
| # 低秩校准模块 (Q-Cal, 仅 0.6% 参数) |
| self.q_cal = LowRankCalibration(r=16) |
| |
| def build_chunk_summary(self, chunk_hidden_states): |
| """ |
| 块摘要：k'c = Attn(q'c, Kc, Kc) 的加权和 |
| + 熵偏置 b'c (捕捉块内质量分布) |
| """ |
| # 一阶泰勒展开的 LogSumExp 线性化: |
| # log Σ exp(q·k/√d) ≈ (q·k'c)/√d + b'c |
| ... |
| |
| def route(self, query, chunk_summaries) -> list[ChunkSelection]: |
| """ |
| 路由：打分 top-K 块 |
| 分数 = (q̂ᵢ·k'c)/√d + b'c |
| q̂ᵢ = qᵢ + W_up W_down hᵢ (Q-Cal 校准) |
| """ |
| ... |
| |
| def hierarchical_softmax(self, query, selected_chunks): |
| """ |
| 分层软max：块内归一化 × 块间质量（可学习） |
| w_ij = [exp(s_ij)/Z_intra] × [Ẑ_chunk/Ẑ_total] |
| 使块选择端到端可训练 (LM loss 梯度直达) |
| """ |
| ... |
| ``` |
|
|
| ### 4.4 GQA 兼容 |
|
|
| ```python |
| def group_select(self, group_scores): |
| """ |
| GQA 组内取 max 聚合： |
| 组内各头归一化权重 → 取 max → top-K |
| 保证任一头觉得重要的块都不漏 |
| """ |
| group_max = np.max(group_scores, axis=0) # [num_chunks] |
| selected = np.argsort(group_max)[-self.top_k:] |
| return selected |
| ``` |
|
|
| ### 4.5 与存储层的接口 |
|
|
| ```python |
| class ChunkSelection: |
| """路由层输出：本次推理要读的块""" |
| chunk_ids: list[int] |
| retrieval_scores: list[float] |
| selected_tokens: list[int] # 展开后的 token 索引 |
| ``` |
|
|
| --- |
|
|
| ## 5. 层 3：存储层（AbsorbedMLA + 分层量化） |
|
|
| ### 5.1 来源 |
| 自研（L40S 实测：270KB → 7.6KB/token, 35.6×） |
|
|
| ### 5.2 职责 |
| 决定**KV 存多小**——吸收式 MLA 缓存潜在向量 + 分层量化。 |
|
|
| ### 5.3 组件设计（已有实现，增强） |
|
|
| ```python |
| class AbsorbedMLAEncoder: |
| """ |
| 存储层：吸收式 MLA + 分层量化（现有 agentframe_core.py 增强版） |
| """ |
| def __init__(self, kv_lora_rank=512, k_rope=64, layers=27): |
| self.kv_lora_rank = kv_lora_rank |
| self.k_rope = k_rope |
| self.layers = layers |
| self.quantizer = LayeredQuantizer() |
| |
| def encode(self, hidden_states) -> CompressedKV: |
| """ |
| 压缩：只缓存潜在向量 (576维) 而非展开 KV |
| [seq, 512+64] → 30.4KB/token (8.9×) |
| """ |
| ... |
| |
| def quantize(self, kv, kind: Literal["thought", "tool"]): |
| """ |
| 分层量化： |
| 思考链 → INT8 (误差 0.011) |
| 工具结果 → INT4 (误差 0.079) |
| per-channel 非对称 (32块, 27×精度提升) |
| """ |
| ... |
| |
| def fuse_router(self, router: LandmarkRouter): |
| """ |
| 融合点 1：路由层直接作用于压缩表示 |
| landmark 摘要基于潜在向量构建（不展开） |
| → 路由成本 O(N/S) 而非 O(N) |
| """ |
| ... |
| ``` |
|
|
| ### 5.4 与物理层的接口 |
|
|
| ```python |
| class CompressedKV: |
| """存储层输出：压缩后的 KV 块""" |
| latent: np.ndarray # [chunk, 576] 潜在向量 |
| k_pe: np.ndarray # [chunk, 64] 位置编码 |
| quant_bits: int # 16/8/4 |
| chunk_ids: list[int] |
| heat: float # 热度（物理层用） |
| last_access: float # 最后访问时间 |
| ``` |
|
|
| --- |
|
|
| ## 6. 层 4：物理层（KV Pager） |
|
|
| ### 6.1 来源 |
| ICPE (matheusdelgado/infinite-context) 思想 + 自研轻量实现 |
|
|
| ### 6.2 职责 |
| 决定 **KV 放哪**——热留显存、温放内存、冷换磁盘（mmap）。 |
|
|
| ### 6.3 组件设计 |
|
|
| ```python |
| class KVPager: |
| """ |
| 物理层：KV 换页引擎（零拷贝, mmap） |
| 显存 → 内存 → 磁盘 三级分层 |
| """ |
| def __init__(self, vram_limit_gb=10.0, ram_limit_gb=32.0): |
| self.vram = LRUCache(limit=vram_limit_gb) # 热 KV |
| self.ram = LRUCache(limit=ram_limit_gb) # 温 KV |
| self.disk = mmap_store() # 冷 KV (mmap) |
| self.predictor = PredictiveEvictor() # 预测性驱逐 |
| |
| def place(self, kv: CompressedKV): |
| """ |
| 放置：按热度决定层级 |
| heat > 0.8 → VRAM |
| 0.4 < heat < 0.8 → RAM |
| heat < 0.4 → DISK |
| """ |
| ... |
| |
| def prefetch(self, directive: RetrievalDirective): |
| """ |
| 预取：推理前纳秒级把需要的冷 KV 换回 |
| 用注意力信号预测（非简单 LRU） |
| """ |
| ... |
| |
| def evict(self, policy="predictive"): |
| """ |
| 驱逐：预测性驱逐（注意力信号驱动） |
| 优于 LRU/FIFO |
| """ |
| ... |
| ``` |
|
|
| ### 6.4 预测性驱逐算法 |
|
|
| ```python |
| class PredictiveEvictor: |
| """ |
| 预测性驱逐：用注意力分数预测未来访问 |
| 不是"最久未用"，而是"最不可能再用" |
| """ |
| def score_eviction(self, kv: CompressedKV) -> float: |
| # 特征: 注意力分数衰减率 + 访问频率 + 语义相似度 |
| attn_decay = self.attention_decay(kv) # 注意力分数随时间衰减 |
| access_freq = self.access_frequency(kv) # 历史访问频率 |
| semantic = self.semantic_relevance(kv) # 与当前任务的语义距离 |
| return 0.5*attn_decay + 0.3*access_freq + 0.2*semantic |
| ``` |
|
|
| --- |
|
|
| ## 7. 四层集成流程 |
|
|
| ### 7.1 推理前（认知 → 路由 → 物理） |
|
|
| ``` |
| Agent 收到任务 |
| │ |
| ▼ |
| [MetaCog] 分解任务 → 识别信息缺口 → 生成 RetrievalDirective |
| │ |
| ▼ |
| [KVPager] 按 directive 预取冷 KV → 换入显存/内存 |
| │ |
| ▼ |
| [LandmarkRouter] 对显存中的 KV 块构建 landmark 摘要 → 打分 top-K |
| │ |
| ▼ |
| [AbsorbedMLA] 展开选中的压缩块 → 计算注意力 |
| ``` |
|
|
| ### 7.2 推理后（存储 → 物理 → 认知） |
|
|
| ``` |
| 注意力计算完成 |
| │ |
| ▼ |
| [AbsorbedMLA] 新 KV 压缩为潜在向量 → 分层量化 |
| │ |
| ▼ |
| [KVPager] 按热度放置 (新 KV = 热 → VRAM) |
| │ |
| ▼ |
| [MetaCog] 置信度追踪 → 低置信度触发补检索 |
| 重要信息 → 提升到长期记忆 |
| ``` |
|
|
| ### 7.3 数据流伪代码 |
|
|
| ```python |
| def agent_inference(agent, task): |
| # 认知层 |
| directive = agent.metacog.decompose(task) |
| |
| # 物理层预取 |
| agent.pager.prefetch(directive) |
| |
| # 路由层 |
| selections = agent.router.route( |
| query=agent.current_query, |
| chunk_summaries=agent.store.build_summaries() |
| ) |
| |
| # 存储层 |
| kv = agent.store.gather(selections) |
| output = agent.model.forward(agent.current_query, kv) |
| |
| # 后处理 |
| agent.store.encode_new_kv(output) |
| agent.pager.place(output.new_kv) |
| agent.metacog.track_confidence(output) |
| return output |
| ``` |
|
|
| --- |
|
|
| ## 8. 实施路线图 |
|
|
| ### Phase 1：存储层强化（已有基础，2 周） |
| - [x] 吸收式 MLA 缓存（已完成, 8.9×） |
| - [x] INT8/INT4 分层量化（已完成, 35.6×） |
| - [ ] 增加块级组织（chunk 化，对齐路由层） |
|
|
| ### Phase 2：物理层（4 周） |
| - [ ] KV Pager 实现（mmap 冷存储） |
| - [ ] 热度追踪 + LRU |
| - [ ] 预测性驱逐 v1（注意力衰减） |
|
|
| ### Phase 3：路由层（6 周） |
| - [ ] Landmark 摘要构建（基于压缩潜在向量） |
| - [ ] 分层软max 前向实现 |
| - [ ] Q-Cal 低秩校准 |
| - [ ] GQA 组内 max 聚合 |
|
|
| ### Phase 4：认知层（4 周） |
| - [ ] MetaCog 控制器（任务分解 + 置信度） |
| - [ ] 信息缺口分析 |
| - [ ] 记忆提升策略 |
|
|
| ### Phase 5：集成验证（4 周） |
| - [ ] 四层端到端集成 |
| - [ ] 真实 DeepSeek-V2-Lite 加载 |
| - [ ] 长上下文基准（RULER / LongBench） |
| - [ ] 与 HiLS 对比实验 |
|
|
| **总计：约 20 周** |
|
|
| --- |
|
|
| ## 9. 风险与对策 |
|
|
| | 风险 | 等级 | 对策 | |
| |------|------|------| |
| | 四层叠加延迟累积 | 中 | 每层接口零拷贝；路由层直接在压缩表示上操作 | |
| | 路由层稀疏性导致召回下降 | 中 | GQA max 聚合 + top-K 可调 + 兜底滑窗 | |
| | 认知层误判（该记的没记） | 高 | 置信度阈值可调 + 审计日志 + 失败回退全量 | |
| | 预测性驱逐误判 | 中 | 双写（驱逐前保留磁盘副本） | |
| | 物理层 mmap 延迟 | 低 | 预取提前量可调（纳秒级 → 毫秒级） | |
|
|
| --- |
|
|
| ## 10. 预期指标 |
|
|
| | 指标 | 当前 | 四层融合后 | |
| |------|------|-----------| |
| | KV/token | 7.6 KB | 7.6 KB（存储不变, 但访问量降） | |
| | 单卡上下文 | 138 万 token | 等效 1 亿+ token（认知减负×路由稀疏） | |
| | 推理延迟 | 线性 | 亚线性（top-K 常数访问） | |
| | 显存占用 | 10 GB | 2-4 GB（冷 KV 换出） | |
| | 质量 | 无损 | 无损（分层软max 可端到端调优） | |
|
|
| --- |
|
|
| ## 11. 附录：参考项目 |
|
|
| | 项目 | 来源 | 在本蓝图的角色 | |
| |------|------|---------------| |
| | HiLS-Attention | arXiv:2607.02980 | 路由层（分层软max） | |
| | Cognitive Workspace | arXiv:2508.13171 | 认知层（元认知控制） | |
| | InfiniteVL | arXiv:2512.08829 | 参考（线性架构, 多模态扩展） | |
| | ICPE | github.com/matheusdelgado | 物理层（KV 换页思想） | |
| | 自研 (AgentFrame) | 本仓库 | 存储层（吸收式 MLA + 量化） | |
|
|
| --- |
|
|
| *Cloud LTE Studio · 2026-08-09 · GPL-3.0* |
|
|
