跳到正文
Ankole

上下文压缩与 compaction

面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/context-compression-and-caching/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。

随着对话轮次不断累加,任何长会话迟早都会触及大模型的上下文窗口上限。为此,AIGateway 会自动对单轮请求可见的历史上下文执行压缩(Compaction),让长会话得以跨越单次窗口限制持续推进。本页对照 ai_gateway/compaction*.ex 的实际源码说明这套机制。

先明确最核心的设计取舍:**Compaction 是刻意有损的,但绝非暗中静默丢弃。**每次执行压缩时,网关会用一份结构化摘要替换早期旧回合、原封不动保留最近几个回合,并将压缩结果本身保存为会话历史指向的一份持久化产物(Artifact)。此后早期原始回合不再进入模型上下文,而这份摘要则作为后续推理的新基准参考状态。正常续接使用这份检查点。Ankole 仍保留原始前驱记录,在 Provider 绑定变更或用户通过 /compress 恢复时,可据此重建本地检查点。

AIGateway 历史 compaction

有状态 Responses 会话的自动历史压缩由 AIGateway 全权托管,从何时触发、如何生成摘要到哪些内容原样保留,核心逻辑全部收敛在 Ankole.AIGateway.Compaction 模块中。

下文介绍默认的本地压缩。将 ai_gateway.compaction.upstream 设为 true 可在 Provider 支持时使用原生压缩,并在需要时回退本地处理,详见 AIGateway。

触发

AIGateway 以最近一次上游 Provider 报告的用量为基准,再估算新输入、工具结果、工具定义和指令增加的 Token 数。系统将预计总量与触发阈值比较,并按新增用量与压缩收益应用抑制规则,避免连续执行收益很小的压缩。各轮 Provider 用量快照不会逐轮累加。

压缩阈值通过站点级 AppConfigure 配置键 ai_gateway.compaction 统一调控:

参数 默认值 含义
threshold 0.90 触发压缩的模型输入上下文窗口占比阈值
max_threshold_tokens 400,000 计算出触发阈值后的绝对 Token 上限,避免超大窗口模型攒出过长历史
tail_rows 4 与摘要一起保留的近期历史行数偏好
user_message_budget_tokens 20,000 从被压缩区间内挑选用户原始提问逐字重放的 Token 预算

未获取到模型窗口大小时,Ankole 使用 256,000 Token。系统先扣除请求指定的输出预算,再应用 threshold 比例,并受 max_threshold_tokens 上限约束;若 64,000 Token 的下限会达到有效窗口大小,则改为在该窗口的 small_context_trigger_ratio(0.85)处触发。

Token 用量并不是唯一的触发条件。加密的推理内容和内联图片每个 Token 占用的字节很多,历史可能远在越过 Token 阈值之前就已经相当庞大。因此,当一段对话的已存历史达到单次带工具响应所能携带规模(1,024 个条目或 8 MiB)的四分之三时,AIGateway 同样会触发压缩。这一体积条件没有对应的配置项。

摘要器做什么

执行本地压缩时,AIGateway 调用 light 模型档案(未设置时回退 primary),将早期回合提炼为一份结构化摘要。压缩提示词明确将这份摘要界定为静态参考状态而非待执行指令:“切勿继续推进对话,切勿回答任何问题,仅输出结构化摘要。”摘要会重点归纳任务初衷、关键决策、踩过的报错及修复方案,同时逐字原样保留所有文件路径、函数名、报错原文、终端命令与业务 ID——因为一旦路径或错误码被同义改写,后续工具调用就会变成彻底失效的死引用。

AIGateway 将摘要与保留的用户原文、近期历史一起注入上下文,并明确将其作为背景状态,而非等待回答的一轮发言。

什么逐字存活

除了旧回合的结构化摘要,还有两类关键内容会逐字原样保留在后续上下文中:

  • 近期历史行(tail_rows,默认 4):这是保留行数的偏好值;系统会为保持工具调用与结果配对、满足上下文预算而调整边界。
  • 用户原文:CompactionRetention 在 user_message_budget_tokens 预算内重放用户文本,必要时会截断文本。被压缩的图片载荷会替换成有界占位文字,近期保留的图片仍保持完整。

这些保留内容有助于模型继续理解任务,但摘要仍会丢失早期工作的部分细节。

compaction 产物

每次压缩都会产出一份持久化的 CompactionArtifact 记录并由 AIGateway 落盘保存。此后该会话的历史链会将最近一次压缩产物作为新的起点锚点,后续回合直接从该锚点向后续接。

历史压缩与冷唤醒会话轮转的配合

ai_gateway.compaction 与 sessions.wake_recycle 分别覆盖热态连续对话与冷态唤醒恢复两类场景:

  • 热态连续对话(ai_gateway.compaction):当用户在提供商提示词缓存有效期内连续交流时,Ankole 持续沿用同一条 AIGateway 模型对话链以最大化前缀缓存命中率,仅当累计上下文越过 threshold / max_threshold_tokens,或已存历史达到上述体积条件时才触发原地压缩。
  • 冷态跨时段恢复(sessions.wake_recycle):当会话静置达到 min_cold_gap_seconds(默认 3,600 秒)且累计输入达到 min_context_tokens(默认 128,000 Token),或外部 IM 会话静置达到 im_max_idle_seconds(默认 259,200 秒 / 72 小时)后再次唤醒时,Ankole.Sessions.WakeRecycle 避免重放完整历史,转而直接终结旧模型对话、开启后继分支,并注入上限 8,000 o200k_base Token 的确定性 <wake-briefing> 摘要块;详见 Sessions。

调优

管理员可根据实际业务形态在 Console 中微调以下参数:

  • 业务以短平快对话为主、觉得压缩触发太频繁时,适当调高 threshold:默认的 0.90 偏向稳健保守,可根据成本与延迟权衡上调。
  • 发现压缩后模型容易丢掉刚做完的上一步细节时,适当调高 tail_rows:保留更多完整的近期回合,代价是留给后续增长的缓冲空间相应变小。
  • 长对话中用户前期交代的大量需求细节被截断遗漏时,适当调高 user_message_budget_tokens:为逐字重放用户原始消息留出更充裕的预算。

上述三个参数均位于 Console 的 AppConfigure 系统配置页,修改保存后将在下一次触发压缩时生效,不会影响正在执行中的当前回合。

本指南不是什么

本页讨论的并非上游厂商的前缀提示词缓存(Prompt Caching)——AIGateway 不在这一层自行实现厂商侧的 KV Cache 机制,前缀缓存由各上游 Provider 原生负责(在支持该特性的 Provider 上可通过配置 promptCacheKey 提升缓存命中率)。同时,Compaction 也绝非无损归档:早期原始回合确实会从发往模型的活动上下文中移除。最后,自动压缩也不能替代合理的任务拆分——它能兜底保障长会话不因窗口溢出而中断,但如果某个会话每隔寥寥几轮就频繁触发压缩,更合理的做法是引导开启新会话,或将重度长线工作委派给独立的后台 Agent 任务。

下一步

  • 全面了解 AIGateway 的有状态会话链与压缩触发接口,请参阅 AIGateway。