Agent 全栈实战

1.6 Context Window 与 Context Budget#

上一节咱们知道,多轮对话就是把历史一遍遍发过去。

那历史能无限发吗?

不能。

发到某一天,接口会直接报错:

text
context_length_exceeded

这一节咱们就把这堵墙量清楚:它到底限制的是什么,撞墙之前该怎么裁。

先分清两个词#

很多人把 Context Window 和 Context Budget 当成一回事。

其实不是。

Context Window(上下文窗口):模型一次请求能处理的 Token 上限。

注意,是“输入 + 输出”加起来的上限,不是只算输入。

Context Budget(上下文预算):你在调用之前,给这次请求的各个部分分配额度。

一个是模型给的硬限制,一个是你自己做的分配方案。

打个比方:

  • Window 是行李箱的最大容量;
  • Budget 是你出门前决定“衣服占多少、鞋占多少、给纪念品留多少”。

行李箱就那么大,你不分配,最后就是塞不下。

公式先摆出来#

一次请求的 Token 账,大概是这样:

text
Context Window = 输入 Token + 输出 Token + 即将生成的内容

更准确地说:

text
输入预算 = 窗口上限 - 输出预留 - 外部上下文预留

三个词解释一下:

  • 输出预留:给模型回答留的空间。不留,它答到一半就被截断。
  • 外部上下文预留:给 RAG 文档、工具描述、系统提示留的空间。
  • 输入预算:真正能装历史 + 当前问题的额度。

大多数人的第一个坑,就是只算输入、不留输出。

结果模型答到一半,finish_reason 变成 length,你拿到半句话。

实验 A:纯本地算一次预算#

代码在:

text
Node/第一章/06-context-window-demo/context-budget.js

它不调接口,纯本地算。直接跑:

bash
node context-budget.js

真实输出:

text
┌─────────────────────┬────────┐
│ 模型窗口            │ 220    │
│ 输出预留            │ 60     │
│ 外部上下文预留      │ 40     │
│ 本次输入预算        │ 120    │
│ 全部发送需要Token   │ 202    │
│ 裁剪后实际输入Token │ 107    │
│ 剩余输入预算        │ 13     │
│ 保留历史轮数        │ 1      │
│ 移出历史轮数        │ 2      │
└─────────────────────┴────────┘

这个例子里,窗口故意设得很小(220),方便观察。

算一下账:

text
220 - 60 - 40 = 120

输入预算只有 120 个 Token。

但全部消息加起来要 202 个,超了 82 个。

所以必须裁。

裁完剩 107 个,保留最近 1 轮,移出 2 轮。

注意最后一行:移出的 2 轮,内容并没有丢。

关键事实被压进了一条摘要消息里。发出去的消息列表变成:

text
system + 历史摘要 + 最近 1 轮问答 + 当前问题

这就是生产环境里“短期记忆 + 摘要”的最小实现。

代码怎么裁#

三块“必须先占”的空间(context-budget.js:2-8):

js
const MODEL_CONTEXT_LIMIT = 220
const OUTPUT_RESERVE = 60
const EXTERNAL_CONTEXT_RESERVE = 40

算出输入预算:

js
const inputBudget =
	MODEL_CONTEXT_LIMIT - OUTPUT_RESERVE - EXTERNAL_CONTEXT_RESERVE

然后估算 Token(context-budget.js:14-27):

js
function estimateTextTokens(text) {
	const chineseCharacterCount = (text.match(/[\u4e00-\u9fa5]/g) || []).length
	const otherCharacterCount = text.length - chineseCharacterCount
	return Math.ceil(chineseCharacterCount * 0.7 + otherCharacterCount / 4)
}

function estimateMessageTokens(message) {
	return estimateTextTokens(message.content) + 6
}

中文按 0.7 Token/字估,其他字符按 4 字符/Token 估,每条消息再加 6 个 Token 模拟 role、分隔符、模板开销。

这是估算,不是真分词器。

真实项目要么接 tokenizer 库,要么用接口返回的 usage 反推。估算偏小会超窗报 400,偏大则浪费预算。

接着,必选内容先放(context-budget.js:40-60):

js
const requiredMessages = [systemMessage, summaryMessage, userMessage]

if (requiredTokens > inputBudget) {
	throw new Error('必选内容已经超过输入预算,无法通过裁剪历史解决')
}

如果连 system + 摘要 + 当前问题都装不下,那就不是裁剪能解决的了,得换更大的窗口,或者缩短问题。

然后,从最近一轮往前装(context-budget.js:63-80):

js
for (let index = historyTurns.length - 1; index >= 0; index -= 1) {
	const turn = historyTurns[index]
	const turnTokens = estimateMessagesTokens(turn)

	if (turnTokens <= remainingBudget) {
		// 装进去
	} else {
		discardedTurns.unshift(turn)
	}
}

两个细节:

第一,从最近往前装。 新的历史更重要,旧的先丢。

第二,整轮丢,不拆半轮。 一轮是“user + assistant”,拆开会出现“有问没答”的畸形历史,模型容易误解。

实验 B:真实接口看 Token 增长#

如果你想看真实数字,用另一个脚本:

bash
node observe-context.js

它需要 Key,会连发三轮,每轮打印 usage。

我这边跑出来的记录:

轮次输入消息输入 Token输出 Token停止原因
12602stop
24882stop
3610811stop

消息数翻倍,Token 也跟着涨。

usage 里还有几个字段值得看:

  • prompt_tokens:输入用了多少;
  • completion_tokens:输出用了多少;
  • total_tokens:加起来;
  • prompt_cache_hit_tokens / prompt_cache_miss_tokens:缓存命中和未命中;
  • finish_reason:stop 是正常结束,length 是被 max_tokens 截断。

缓存命中不等于不占窗口。

缓存只影响价格,不影响“这次请求用了多少上下文”。窗口该占还是占。

一个容易忽略的点:外部上下文也吃预算#

很多人算预算,只算 messages。

但真实 Agent 一次请求里,除了对话历史,还有:

  • 工具描述(tools schema),几个工具就是几百上千 Token;
  • RAG 检索到的文档片段;
  • 系统提示里的规则、示例;
  • 结构化输出的 schema。

这些都在输入里,都吃预算。

所以公式里要留“外部上下文预留”。不留,等接了 RAG 和工具才发现超了,就得回头重构。

裁不动了怎么办#

预算不够,有三条路:

第一,裁历史。

按轮丢,或者把旧轮次压成摘要。这是最常用的。

第二,换窗口更大的模型。

128K 不够上 200K、1M。但贵,而且长上下文的效果不一定线性。

第三,把“记住”这件事外置。

历史不放在 prompt 里,放到数据库,需要时检索回来。这就是第五章 Memory 和第六章 Agentic RAG 的思路。

三种手段不互斥,生产里通常一起用。

几个容易误解的点#

PS 1:按“条”裁,不按 Token 裁,一定会翻车。

一条长消息就能把预算吃光。裁剪必须按估算 Token 算。

PS 2:finish_reason: length 不是错误。

它表示“模型还没说完,被 max_tokens 截断了”。前端看到半句话,多半是这个原因。

PS 3:摘要不是免费的。

摘要本身也要一次模型调用,也要花钱。所以别每轮都摘要,按阈值触发。

总结#

这一节咱们把上下文这笔账算清了:

  • 窗口是“输入 + 输出”的总上限;
  • 预算要先扣输出预留、外部上下文预留,剩下的才是输入;
  • 历史从最近往前装,装不下整轮丢;
  • 丢掉的旧事实,用一条摘要保住;
  • 判断是否被截断,看 finish_reason。

下一节,咱们换个角度:模型既然只是“预测下一个 Token”,那它为什么有时会一本正经地编?温度调低,是不是就不编了?