智能令牌压缩
TokenJuice 会在冗长的工具输出进入模型上下文前进行压缩,同时保留可恢复的完整原始内容。
LLM 令牌要花钱,而冗长的工具输出会浪费掉其中大部分。A git status 在一个繁忙的仓库里, cargo build 日志、一个 600 条消息的邮件线程和一个 docker ps -a 与真实集群对比时,任何一个都可能几乎不提供任何信息,却占满上下文窗口。
OpenHuman 随附 TokenJuice,这是 agent 工具执行路径中的一个压缩路由器。在工具结果到达模型之前,编译后的 TinyJuice 模块会对其进行分类,选择压缩器,在需要时将可恢复的原始内容存入其 CCR 缓存,并返回压缩后的结果。该模块负责压缩、CCR 检索与查询、HTML 提取,以及以下中的 schema 和请求/结果类型 tinyjuice-bus。OpenHuman 提供配置、文件系统授权、按回合限制的模型调用以及节省归因。命令和日志规则来自 vincentkoc/tokenjuice.
流水线
每个工具结果都会通过 TinyJuice 模块的路由器走相同的路径:
原始工具结果
│
▼
1. 大小门槛 路由器已启用?输入 ≥ min_bytes_to_compress(2 KB)?
│ 是
▼
2. 检测类型 Json · Diff · Html · Search · Code · Log · PlainText
│
▼
3. 选择压缩器 每种类型一个专用压缩器(+ 每种类型开关)
│
▼
4. 压缩 运行它;如果它拒绝或使输出变大,则回退/直接透传
│
▼
5. CCR 资格 有损 AND ≥ ccr_min_tokens(约 500)?→ 将原始内容卸载到缓存
│
▼
6. 附加标记 ⟦tj:<hash>⟧ 页脚,以便 agent 可以取回完整原文
│
▼
7. 记录节省 按模型和压缩器记录节省的令牌 + 成本
│
▼
压缩后的文本 → LLM 上下文大小门槛。 如果路由器关闭,或者输入低于
min_bytes_to_compress(默认 2048 字节),则会原样透传。太小的输出不值得压缩。内容检测 (
detect/kind.rs)。结果会被分类为七种类型之一。优先级顺序是:显式提示,其次是 MIME 或扩展名标记,然后是按工具的先验(例如grep表示 Search,git_operations表示 Diff,run_tests表示 Log),然后是廉价的结构启发式(JSON、Diff、HTML、Search、Code、Log、PlainText)。热路径上没有正则。压缩器选择。 每种类型都会进入自己的压缩器,并遵守按类型的开关(
search_enabled,code_enabled,html_enabled).压缩。 压缩器运行。如果它拒绝,或者其输出不比输入更小,TokenJuice 就会回退到通用压缩器,或者直接透传原文。它绝不会让内容变得更大。
CCR 卸载。 当压缩是有损的,而且原文足够大(
ccr_min_tokens,默认约 500 个令牌)时,完整原文会进入 Compress-Cache-Retrieve(CCR)存储,因此不会永久丢失。恢复标记。 会附加一个带有标记
⟦tj:<hash>⟧的页脚。它会告诉 agent 这个视图只是部分内容,以及如何获取剩余部分。节省记账。 按模型和压缩器记录已节省的令牌数和估算节省成本。
这些压缩器
每种内容类型都有一个专用压缩器(vendor/tinyjuice/src/compressors/):
SmartCrusher
JSON
将对象数组重新渲染为紧凑表格。超过大约 40 行后,会保留开头、结尾、错误行和数值异常值。
Code
Code
保留签名和导入,并将深层函数体折叠为 { … N 行 … } (可用时使用 tree-sitter,否则使用大括号深度启发式)。保留 TODO, FIXME, error, panic 和 unsafe 标记。
Log
Log
对于命令输出,使用 JSON 规则引擎(见下文)。对于其他日志,则保留错误、警告、堆栈跟踪和摘要,并丢弃噪声。
Search
Search
将 grep 和 ripgrep path:line:body 命中按文件分组,按查询词密度排序,保留每个文件的最佳匹配,并统计 [+N more].
Diff
Diff
保留变更行和 hunk 标头,并将很长的未变更片段折叠为锚点。锁文件的 hunk 会缩成一行 +A/-B 摘要。
Html
HTML
去除标记,转换为可读文本,采用合理的块边界换行和实体解码(占用少,且不构建 DOM)。
TextCrusher
PlainText
确定性的显著性压缩,保留句子和段落边界。
通用
回退
适用于没有任何特定规则匹配的命令输出的首尾摘要。对于结构化结果它会拒绝,以便保留原样。
多字节文本(CJK、emoji、组合标记)会按字素逐个处理,绝不会在字符中间拆分。
句柄预览和 juice 工具(默认)
默认启用压缩。对于至少 ccr_min_tokens的结果,该模块会将原文存入其 CCR 缓存,并向模型显示一个小预览,而不是压成一个整体:
一行统计描述其形状(估算令牌数、字节数、行数、JSON 键,或 Markdown 大纲;绝不包含值),
前 500 个字符,
一个抽取式大纲,以及
一个标注句柄(CCR 令牌)的页脚。
然后,模型通过三个只读工具查询已存储的原文,这些工具都不会调用模型:
juice_find
文本, grep, 正则, 排序 (BM25), sed, awk 和 jq 对输出进行操作,并带有类似 Python 的 作用域 切片。
juice_extract
HTML 或 Markdown 输出中的链接或标题。
juice_summarize
大小、大纲或 JSON 结构,然后是开头和结尾,或者与某个 提示.
答案有大小上限,未知或已被驱逐的句柄会报错。 juice_retrieve 仍然会返回完整原文。句柄预览是在不调用模型的情况下构建的,因此对于大到足以生成摘要的结果,它也会替代 LLM 摘要。缓慢的摘要器不会阻塞当前回合。这三个只读工具由 tinyjuice-bus 声明,并在该模式开启时为新会话注册;已恢复的会话会保留其转录中记录的声明。它们的宿主适配器会向模块发送类型化查询;不会读取模块缓存,也不会在本地重复其查询算法。对于工件路径,OpenHuman 会先应用其常规路径和大小检查,然后在不发送路径的情况下,将已授权内容发送给模块。
每次对话都会记录模型的工具目录,并在该线程恢复时保持冻结。如果转录中包含 Juice 工具,OpenHuman 会恢复其记录的名称和 schema,即使当前设置本不会创建新句柄。恢复后的工具仍使用当前宿主路径授权和模块策略。被禁用或不可用的模块对查询会返回明确的不可用结果;OpenHuman 不会用本地 CCR 存储或查询实现替代它。可选的输出压缩会保持其既有的 fail-open 行为:当模块无法压缩时,会返回未修改的结果。
要关闭整个功能,请设置 context.compaction_enabled = false 或者 OPENHUMAN_COMPACTION=0。要保留压缩但回到单块压缩和 juice_retrieve,请设置 tokenjuice.repl_handle_enabled = false (OPENHUMAN_TOKENJUICE_REPL_HANDLE_ENABLED=0).
不会丢失任何内容:CCR 缓存
有损压缩通常会丢弃数据。TinyJuice 则会把完整原文存入模块拥有的 CCR 存储,并留下一个线索。
内存层 (始终开启):模块的存储以 SHA-256 哈希为键,并受条目数(
max_cache_entries,默认 256)和总字节数(max_cache_bytes,默认 64 MiB)限制,并采用 FIFO 淘汰。磁盘层 (可选):
<workspace>/.tokenjuice/ccr/,通过ccr_disk_enabled启用。它可在内存淘汰后继续保留。可通过ccr_ttl_secs.标记: 压缩后的输出以如下页脚结尾
[compacted tool output: PARTIAL view; full original available via juice_retrieve with token "…"]携带⟦tj:<hash>⟧令牌。检索工具: agent 使用只读的
juice_retrieve带着该令牌调用该工具(可选地附带字节或行范围)即可获取完整原文或其切片。该令牌是不可猜测的 SHA-256 摘要。
默认情况下,agent 先获得廉价的压缩视图,只有在需要时才会放大查看完整文本。
节省跟踪
OpenHuman 的节省回调会对每次压缩进行计量(crates/openhuman-core/src/inference/tokenjuice/savings.rs)。TokenJuice 会报告事件和令牌差值。OpenHuman 会应用已配置的默认模型输入定价,汇总 总计, 按模型 和 按压缩器,而模块会将统计信息保存到其 juice.savings 存储文档中(旧的 <workspace>/state/tokenjuice_savings.json 仅会导入一次)。
可通过 RPC 读取它们: openhuman.tokenjuice_savings_stats;可通过以下命令清除它们: openhuman.tokenjuice_savings_reset.
规则覆盖层(命令和日志输出)
一个三层 JSON 规则覆盖层驱动日志和命令压缩器。规则按顺序合并,后面的层会覆盖前面的层:
内置
随二进制一起提供
大约 96 条随附规则,适用于 git、npm、cargo、docker、kubectl、ls 等
用户
~/.config/tokenjuice/rules/
适用于所有位置的个人覆盖
项目
.tokenjuice/rules/
特定仓库的覆盖,已提交并与团队共享
每条规则都会命名一个命令或工具模式,以及一种缩减策略:跳过并保留过滤器、诸如 strip-ANSI 和 dedupe 的转换、首尾摘要、命名计数器和预设消息。规则是 JSON。添加一条即可生效,无需重新编译。
配置、RPC 和工具
所有内容都位于 [tokenjuice] 配置块中(crates/openhuman-core/src/config/schema/tokenjuice.rs),并且可以实时更改。
总开关:
context.compaction_enabled(默认true;OPENHUMAN_COMPACTION=0表示选择退出)以及router_enabled(默认true).句柄预览:
repl_handle_enabled(默认true).阈值:
min_bytes_to_compress和ccr_min_tokens.CCR:
ccr_enabled,ccr_disk_enabled,max_cache_entries,max_cache_bytes和ccr_ttl_secs.按类型:
search_enabled,code_enabled,html_enabled.RPC(
openhuman.tokenjuice_*):detect,compress(对流水线做 dry-run),settings_get和settings_update(在线部分补丁),cache_stats,retrieve,savings_stats和savings_reset.Agent 工具:
juice_retrieve恢复整个已存储的原文。juice_find,juice_extract和juice_summarize按句柄查询一个。全部都是只读。调试:用以下命令启动 core
RUST_LOG=openhuman_core::inference::tokenjuice=debug即可查看检测、匹配,以及每个结果被裁掉了多少。
这为何重要
agent 的上下文预算就是它的上限。一次工作会话可能会扩展到几十次工具调用:grep、build、测试运行、 git 输出和大量 网页抓取 结果。TokenJuice 会在每个结果进入上下文之前先对其压缩,因此 agent 可以扫过嘈杂仓库或长网页,而不会填满窗口。一次会话中的节省会不断累积,并以美元计量(见 计费、成本和用量).
TokenJuice 运行在 agent 的工具结果上,而不是运行在 内存 摄取上。源同步会自己转换文档,不会把负载通过 TokenJuice 路由。
另见
最后更新于