上下文窗口是一个预算
Pi 每一轮发给模型什么、触发压缩(compaction)的算术,以及如何针对你的模型调整 reserveTokens 与 keepRecentTokens。
你正在一次重构的半路上。Pi 已经读了四十个文件,把测试套件跑了两遍,还把同一个模块重写了三次,因为每一次尝试最后都发现与上一次冲突。没什么地方出错。只是转录记录(transcript)装满了,于是它最早的那些部分不再被发给模型。
大多数人遇到它时是以一种心情的形式:Pi 在这个任务上变差了。把它当成算术来推理会容易得多。每一次模型请求都要花掉一个固定窗口中的一个固定切片,而 Pi 把这个切片花在一些有名字的地方——你可以读、可以数、可以改。
错误:“上下文窗口是一个容器。对话装在里面,模型去读这个容器。”
正确:“上下文窗口是一个预算。里面的一切都在竞争,而最早的条目先输。”
一次请求的构成
按 how-pi-works.md,一次模型请求由四部分组成:系统提示词(system prompt)、活动分支(active branch)、可用工具与模型设置。在这之上还放着技能(skill)和上下文文件。
flowchart TD
SP["系统提示词<br/>基础指令与上下文文件"] --> CTX
AB["活动分支<br/>穿过树的一条路径"] --> CTX
TL["工具声明<br/>仅针对已激活的工具"] --> CTX
SK["技能描述<br/>始终存在"] --> CTX
SI["技能指令<br/>仅在按需加载时"] --> CTX
CTX["contextTokens"] --> CMP{"过线了吗?"}
RSV["reserveTokens<br/>默认 16384"] --> CMP
CMP -->|no| REQ["已发出请求"]
CMP -->|yes| CP["压缩"]
CP --> REQ
完整的技能正文只在一个任务匹配它的描述时进入,而这正是为什么一整目录的技能在你还没有用过其中任何一个之前,不会耗费你的上下文。
有两点直接由此推出。usage.md 补充说页脚显示当前的上下文用量,而 /session 报告会话文件、它的 ID、消息条数、token 用量与费用。两者都是你的仪器。先读它们,再猜。
活动分支不是会话文件
一个会话是一棵树。每个条目有一个 id 和一个 parentId,而当前条目标识出活动分支——从根到当前叶子那条路径。只有那条路径会被发送。你通过 /tree 探索过又放弃的一切,仍然留在文件里,也仍然留在请求之外。
错误:“模型看到的是会话。”
正确:“模型看到的是活动分支。会话文件比它更大,装着你放弃过的每一个备选项。”
这是你能拿到的最便宜的上下文节省,而且它不花任何代价。当一条路子卡住了,打开 /tree,选中一条更早的用户消息,编辑它,然后提交。你会得到一条不携带那次失败尝试的新分支。
触发条件是算术,不是判断
compaction.md 把这个条件说得完全精确:
contextTokens > contextWindow - reserveTokens
reserveTokens 默认是 16384。它是留给模型自己响应的空间。settings.md 确认了这个默认值,并把这个设置称作 compaction.reserveTokens,可以在 ~/.pi/agent/settings.json 或 <project-dir>/.pi/settings.json 中配置。
Pi 在两轮之间检查它,在工具结果被追加之后、下一条助手响应之前。它也在一条新的用户提示词之前检查。所以这个阈值是对着它真正要发送的那个投影来执行的,而不是对着早先取的某个估计值。
有一处不对称值得知道。一次 provider 的上下文溢出错误,或一个早期的 stopReason: "length",可以选中一次压缩并重试的恢复尝试。那次恢复是一条修复路径,不是一种策略。message-types.md 把 "length" 列为 AssistantMessage 上的一个终局性 stopReason,与 "stop"、"toolUse"、"error"、"aborted" 和 "deferred" 并列。
一次压缩替换掉什么
压缩是一次摘要,不是一次删除。Pi 选择一个切点,把在它之前的那些消息总结,记录这条摘要以及它保留的第一个条目,然后把请求重建为摘要加上被保留的消息。原始条目仍然留在文件里。本章只需要它对预算的那个后果:一次压缩之后,请求会变小,变小的量就是摘要没有携带的那部分。
切点如何选择、为什么它从不落在一个工具结果上、摘要包含什么、以及一个扩展如何接管这条摘要,是第 23 章的主题,也是本章在此停笔的原因。
按模型调整预算
两个 token 设置都独立解析:先是模型覆盖(model override),然后是普通设置,最后是内置默认值。键是精确的、区分大小写的 provider/modelId 值。
{
"compaction": {
"enabled": true,
"reserveTokens": 16384,
"keepRecentTokens": 20000,
"modelOverrides": {
"some-provider/big-model": { "reserveTokens": 400000 }
}
}
}
对于一个有 1M 上下文窗口的模型,那个覆盖会在超过 600K token 时触发压缩,同时保留普通的 20000 个近期 token。enabled 保持全局;它不是按模型生效的。
把 "enabled": false 设上即可关掉自动压缩。/compact 仍然可用——sessions.md 说关掉自动压缩并不会关掉手动命令。
给模型一个更好的切点
/compact 接受指令。当下一阶段的工作不需要与上一阶段同样多的细节时,就用它们:
/compact Preserve the failing test names and the chosen error-handling pattern. Drop the file-listing digressions.
这是内置阈值给不了你的那个手动杠杆。自动压缩是通用的;一次手动压缩可以被瞄准。
压缩不做什么
它不会缩小系统提示词,它不总结工具声明,它也不缩短 firstKeptEntryId 之后的消息。如果你的上下文压力来自一个非常大的 AGENTS.md、来自十五个已启用的工具,或来自一种通过 bash cat 整个文件的习惯,那么压缩治的是症状。去修根源。
它同样不会抹掉任何你能找回的东西。导航到压缩条目之前的某一点,那个条目就不在路径上,于是原始消息又被发送。context_edit 的省略也是如此,session-format.md 称它是分支相对的。压缩移除的每一样东西都还在文件里,只差一次导航。
读你自己的预算
在责怪模型之前,先看一眼:
/session
比较最后一条 CompactionEntry 上的 tokensBefore 与你的窗口。如果压缩每隔几轮就落一次,那说明 keepRecentTokens 对你的工具每轮吐出多少内容来说太低了——调高它,或者减少工具吐出的内容。
运行了什么
第 4、5、23、24 章是在一段共享历史上测试的,好让它们读起来像一个主题、一段随时间的状态,而不是四个。它是持久会话中的三轮:问题 A 与它的回答;问题 B,它先做一次 bash 工具调用然后回答;问题 C 与它的回答。examples/harness/history.ts 构建它,而每一章读同一次运行的不同属性。
第 4 章的问题是什么被发送了,以及预算何时变成问题? examples/ch04-budget/ 用真实的会话回答它:
- 页脚的数字是真的:
getContextUsage()报告相对于窗口的 token 数,percent是它们的比率,而从第二轮起每个回答都让请求变大。第一次读数比第二次高,因为它包含系统提示词与工具声明,所以不要把它与后面那些相比; - 触发条件是算术。 阈值设为 3000 token 时,第一轮没有发生压缩,它前一轮处在阈值或以下,而它写下的那个条目记录了一个高于阈值的
tokensBefore; - 更大的保留区压缩得更早:同一段对话在两个保留区之下在两个不同的轮次压缩,顺序如预期;
- 一次按模型的覆盖改变了
faux/faux-1的阈值,而大小写错误的键什么也没做; enabled: false停掉了自动压缩,而手动命令仍然有效;/compact指令原样到达一个扩展的session_before_compact处理器;- 在
navigateTree()到问题 B 之后,下一条请求包含问题 A 而不包含问题 C,而文件里仍然有 C:模型看到的是活动分支,不是文件; - 只有已激活的工具被声明给模型:在
tools: ["read"]下,请求声明的正好是read。
预算一览
上面那些算术,汇到一处。每一行都是每一条请求上都要花钱的一样东西,以及一种减少它的办法——而最后一列是你为此要付的代价,这一部分是一个百分比不会告诉你的。
| 消耗方 | 每一条请求上的开销 | 如何减少它 | 减少它的代价 |
|---|---|---|---|
| 系统提示词与工具声明 | 固定的,在对话开始之前 | 更少、更窄的工具(--tools) |
更弱的能力 |
AGENTS.md 与上下文文件 |
常驻税务;压缩不会减少它 | 更短的文件;编辑后 /reload |
更窄的指令集 |
| 已加载的技能正文 | 每次触发一次 | 把细节挪到 references/,按需加载 |
需要时再读一次 |
| 工具结果 | 工具返回了多少就是多少 | 截断并指向一个文件(extensions.md) |
一次后续读取 |
| 对话历史 | 随每一轮增长 | 压缩;用 /tree 回去 |
一段摘要替代那些轮次 |
有两行值得强调,因为它们是人们会忘记的那两行。已加载的指令是一笔常驻税务:压缩改写历史而放过它们,所以一个大的 AGENTS.md 在每一条请求上永远都要付。而工具结果是大多数会话中增长最快的那一行——一个返回一千 token 的工具,也在之后每一条请求上都花掉了一千 token,这是截断大结果、并点名一个文件去读的最强论据。
下一章
一个预算只有对着某个你能回去检查的东西才有意义,而到目前为止本章的一切都是关于你打不开的内容的算术。下一章打开文件本身:磁盘上有什么、它是什么形状,以及它的哪些行模型曾经看见过。
第 5 章:会话,以及它们住在哪里。