DSH plugin 的 Token 计量:TokenMeasurement 与上下文压力投影
“上下文快满了”这句话在 DSH plugin 里有三种含义:已发生的压力、下一次请求的预估、以及表层按路由的定价总量。 它们来自不同的字段,用错就会出现“显示还有余量,请求却被压缩”的错位。先把计量快照读明白,再谈阈值。 DSH插件 想在状态栏显示压力可以,但别把显示值当成门控依据。
计量是快照,不是实时累计
TokenMeasurement 是一份在某个日志修订上的分离不可变快照。(来源)
它不是一个会自己长大的计数器。logRevision 表示生成该计量中每个字段时消费的持久事件数量,等于下一个未读事件序号。快照不可变,也不会随底层回放折叠推进而增长——想要新数据,就再调一次 measure()。
这条设计对插件很重要:你可以安全地把一份计量挂到消息上、放进缓存、或者跨异步边界传下去,不用担心它在背后被改写。反过来,也不要长期缓存它当“当前压力”,因为它只描述生成那一刻。
六个字段分别回答什么
每个字段对应一个不同的问题,混用就会得到错误结论。(来源)
| 字段 | 回答什么 |
|---|---|
logRevision | 这份快照基于多少条持久事件 |
baseline | 这次计量用了哪种锚点 |
surfaceDeltaTokens | 表层内容相对锚点的带符号重定价 |
totalTokens | 当前请求与响应的非负压力 |
surfaceTokens | 表层的路由定价总量 |
nodes | 当前表层节点,按位置从头到尾 |
surfaceDeltaTokens 是唯一允许为负的字段:它保留相对于匹配锚点的增长与缩减,且两侧按同一路由重新定价。surfaceTokens 等于所有节点价格之和,这一点在排查“为什么两个数对不上”时最有用——先把节点价加一遍。
nodes 的顺序是表层顺序,不是 seq 顺序。表层顺序具有权威性:替换节点的持久 seq 可能高于位置排在其后的节点,所以不要按 seq 排序后再计价。
baseline 是锚点,estimated 是兜底
能复用提供方 usage 就复用,不能就整份重估。(来源)
每次计量都会通过 ctx.llm 把生效信封的路由 provider/model 解析为该路由声明的请求图片定价。因此图片出现处按“请求实际发送的视觉 token + 模型可见文本”计价;未声明定价的路由与组合保持固定启发式规则。
baseline.kind === 'usage' 的条件很严:最近一次成功的提供方调用具有相同的规范请求 envelope,且该调用的总量不低于其完整路由定价锚点。两个条件缺一不可,后者是为了保守——不能拿一个更小的 usage 去压低当前压力。
estimated 表示不存在可复用的保守 usage 锚点,服务自行对完整信封与表层定价。后续成功请求会替换早先的锚点。这条替换语义解释了一个现象:连续几次请求后,totalTokens 会跳一下,因为锚点换了,不是内容突然变多。
TokenSurfaceNode:节点价与影子价
一个节点有两个价:按路由的请求价,和与路由无关的启发式价。(来源)
TokenSurfaceNode 只有三个字段:seq、tokens、heuristicTokens。
tokens 是在被测路由下,该节点投影出的确切消息的请求压力 token:图片出现处若路由适配器声明了视觉定价,就按声明计价,否则用固定启发式。触发、保留与范围选择都读这个价。
heuristicTokens 是同一消息的固定启发式 token,与任何路由无关。它存在的理由是影子价协议:替换用这个值计价,使 O(1) 的投影折叠与它自己的追加保持一致。换句话说,tokens 服务“这次请求要花多少”,heuristicTokens 服务“折叠内部怎么算才自洽”。
这也意味着你不能用 heuristicTokens 做预算判断,也不该用 tokens 做跨路由比较。前者与路由无关,后者与路由强绑定。
ContextPressureProjection:给显示用,不给门控
三个字段不是一次原子观测,而是不同时刻的最后值。(来源)
ctx.tokenMeter.contextPressure(session) 同步读取最新记录的 pressureTokens 与 contextWindow;客户端投影还根据表层变化派生 projectedTokens。
pressureTokens— 最近一次请求的提供方 prompt 大小:未缓存输入加缓存读写,不含输出,因此不会随当前轮次流式输出增长;在提供方报告 usage 之前缺失。projectedTokens— 下一次请求的 prompt 成本:pressureTokens加上表层自此样本以来增减的启发式重估。只估算增量,所以既锚定提供方,又能在压缩遮蔽一段时立刻反应——pressureTokens单独做不到,因为压缩本身不上报 usage。contextWindow— 最新记录的路由容量,没有适配器声明时缺失。
官方特意写明:这些字段不是一次原子请求观测,切换模型时可能把新容量与上一条路由的压力配在一起,直到下一次请求报告 usage。这是有意的取舍,它是面向用户的参考值,不是计费或门控输入。
所以状态栏可以用它,做硬门控不行。要判断“下一次请求会不会爆”,应当自己调 measure()。
measure 与 contextPressure 不能互相替代
显示值不为新请求计价,请求计价只认 measure()。(来源)
measure(session, requestHeader?) 通过持久尾部重放计量当前请求压力与表层。requestHeader 会替换最近记录的 envelope 用于压力与节点计价,但节点集合始终描述当前会话表层。每次调用都会克隆这些位置节点,所以开销是 O(surface)。
这解释了两条使用建议:频繁轮询状态用 contextPressure(),它只读已记录值;准备发请求或做压缩决策用 measure(),它才会按新 envelope 重算。需要给单条消息估个价时,用 estimateMessage(message),它返回固定服务启发式下的内容与角色框定 token。
还有一条容易踩的边界:measure() 的锚点包含 assistant 消息之前的所有表层节点,包括 step/start 之后准入的输入。你在请求前临时注入内容,它会计入压力。
验证:接近上限时的压力与压缩触发
验证要同时看“显示值”“请求计价”和“压缩后的变化”,三处对齐才算通过。(来源) 六步:
- 构造一个未报告 usage 的会话,断言
contextPressure()的pressureTokens缺失,而measure()仍返回可用计量。 - 让一次请求成功上报 usage,断言
pressureTokens出现,且baseline.kind为usage。 - 追加几条长消息,断言
projectedTokens上升而pressureTokens不变。 - 触发一次压缩,断言
projectedTokens立即下降,pressureTokens仍停在旧样本。 - 把节点价逐个相加,断言等于
surfaceTokens;确认顺序按表层而非 seq。 - 换一个声明了图片定价的路由再
measure(),断言同一图片节点的tokens变化而heuristicTokens不变。
如果第 4 步没有下降,先确认压缩是否真的遮蔽了表层区间——projectedTokens 只看增量,不推测未发生的替换。
压缩产物侧的字段与边界,可以对照压缩产物与剪枝;引用预算的截断规则见会话引用预算。
一句话收束: 计量是不可变快照,六个字段分工不同,tokens 看路由、heuristicTokens 看折叠,显示值不做门控,请求计价只认 measure()。
常见问题
不会,DSH plugin 的计量是一份分离不可变的快照。DSH plugin 用 logRevision 记录生成各字段时消费的持久事件数,快照本身不会随底层回放折叠推进而变大。
不是,DSH plugin 把两者分开定义。DSH plugin 的 totalTokens 是非负的请求与响应压力,surfaceTokens 是表层按路由计价的总量,等于所有节点价格之和。
不建议,DSH plugin 明确说它是面向用户的参考值。DSH plugin 的三个字段分别是不同时刻的最后值,切换模型时可能把新容量与旧路由压力配在一起,不适合计费或门控。
因为 DSH plugin 只估算增量。DSH plugin 用最近一次请求的压力加表层增减的启发式重估,压缩遮蔽一段表层时增量会立即反映,而单纯的 pressureTokens 做不到这一点。
相关术语
- TokenMeasurement
- TokenMeasurement 是在某个已消费日志修订上的分离不可变请求压力与表层快照,含六个只读字段。— packages/llm/token-meter/src/types.ts
- logRevision
- logRevision 是生成该计量中每个字段时消费的持久事件数量,等于下一个未读事件序号。— packages/llm/token-meter/src/types.ts
- TokenSurfaceNode
- TokenSurfaceNode 是当前有序表层里的一个计价节点,含事件 seq、请求压力 tokens 与路由无关的 heuristicTokens。— packages/llm/token-meter/src/types.ts
- ContextPressureProjection
- ContextPressureProjection 是面向状态显示的压力近似值,含 pressureTokens、projectedTokens 与 contextWindow。— packages/llm/token-meter/src/projection.ts
来源
- DeepSeek Harness 官方参考 - Token 计量· deepseek-ai
- packages/llm/token-meter/src/types.ts· deepseek-ai